Crate odos_sdk

Expand description

§Odos SDK

A production-ready Rust SDK for the Odos protocol - a decentralized exchange aggregator that provides optimal routing for token swaps across multiple EVM chains.

§Features

Multi-chain Support: 16+ EVM chains including Ethereum, Arbitrum, Optimism, Polygon, Base, etc.
Type-safe: Leverages Rust’s type system with Alloy primitives for addresses, chain IDs, and amounts
Production-ready: Built-in retry logic, circuit breakers, timeouts, and error handling
Builder Pattern: Ergonomic API using the bon crate for request building
Comprehensive Error Handling: Detailed error types for different failure scenarios

§Quick Start

use odos_sdk::*;
use alloy_primitives::{Address, U256};
use std::str::FromStr;

// Create a client
let client = OdosSorV2::new()?;

// Build a quote request
let quote_request = QuoteRequest::builder()
    .chain_id(1) // Ethereum mainnet
    .input_tokens(vec![(
        Address::from_str("0xA0b86a33E6441d35a6b083d5b02a8e3F6CE21a2E")?, // WETH
        U256::from(1000000000000000000u64) // 1 ETH
    ).into()])
    .output_tokens(vec![(
        Address::from_str("0xA0b86a33E6441d35a6b083d5b02a8e3F6CE21a2E")?, // USDC
        1
    ).into()])
    .slippage_limit_percent(1.0)
    .user_addr("0x742d35Cc6634C0532925a3b8D35f3e7a5edD29c0".to_string())
    .compact(false)
    .simple(false)
    .referral_code(0)
    .disable_rfqs(false)
    .build();

// Get a quote
let quote = client.get_swap_quote(&quote_request).await?;

// Build transaction data
let swap_context = SwapContext::builder()
    .chain(alloy_chains::NamedChain::Mainnet)
    .router_address(alloy_chains::NamedChain::Mainnet.v2_router_address()?)
    .signer_address(Address::from_str("0x742d35Cc6634C0532925a3b8D35f3e7a5edD29c0")?)
    .output_recipient(Address::from_str("0x742d35Cc6634C0532925a3b8D35f3e7a5edD29c0")?)
    .token_address(Address::from_str("0xA0b86a33E6441d35a6b083d5b02a8e3F6CE21a2E")?)
    .token_amount(U256::from(1000000000000000000u64))
    .path_id(quote.path_id().to_string())
    .build();

let transaction = client.build_base_transaction(&swap_context).await?;

§Configuration

The SDK supports extensive configuration for production use:

use odos_sdk::*;
use std::time::Duration;

let config = ClientConfig {
    timeout: Duration::from_secs(30),
    connect_timeout: Duration::from_secs(10),
    max_retries: 3,
    initial_retry_delay: Duration::from_millis(100),
    max_retry_delay: Duration::from_secs(5),
    circuit_breaker_threshold: 5,
    circuit_breaker_reset_timeout: Duration::from_secs(60),
    max_connections: 20,
    pool_idle_timeout: Duration::from_secs(90),
};

let client = OdosSorV2::with_config(config)?;

§Error Handling

The SDK provides comprehensive error types for different failure scenarios:

use odos_sdk::*;

match client.get_swap_quote(&quote_request).await {
    Ok(quote) => {
        // Handle successful quote
        println!("Got quote with path ID: {}", quote.path_id());
    }
    Err(OdosError::Api { status, message }) => {
        // Handle API errors
        eprintln!("API error {}: {}", status, message);
    }
    Err(OdosError::Timeout(msg)) => {
        // Handle timeout errors (retryable)
        eprintln!("Request timed out: {}", msg);
    }
    Err(OdosError::RateLimit(msg)) => {
        // Handle rate limiting (retryable)
        eprintln!("Rate limited: {}", msg);
    }
    Err(OdosError::CircuitBreakerOpen(msg)) => {
        // Handle circuit breaker
        eprintln!("Circuit breaker open: {}", msg);
    }
    Err(err) => {
        // Handle other errors
        eprintln!("Error: {}", err);
    }
}

Modules§

OdosLimitOrderRouter: Module containing a contract’s types and functions.
OdosLimitOrderV2: Generated by the following Solidity interface…
OdosRouterV2: Module containing a contract’s types and functions.
OdosV2Router: Generated by the following Solidity interface…
SignatureValidator: Module containing a contract’s types and functions.

Structs§

AssembleRequest: Request to the Odos Assemble API: https://docs.odos.xyz/build/api-docs
AssemblyResponse: Response from the Odos Assemble API: https://docs.odos.xyz/build/api-docs
ClientConfig: Configuration for the HTTP client
InputToken: Input token for the Odos quote API
LimitOrderV2: The Limit Order Router contract.
OdosHttpClient: Enhanced HTTP client with retry logic, timeouts, and circuit breaker
OdosSorV2: The Odos Smart Order Routing V2 API client
OutputToken: Output token for the Odos quote API
QuoteRequest: Request to the Odos quote API: https://docs.odos.xyz/build/api-docs
QuoteRequestBuilder: Use builder syntax to set the inputs and finish with build().
Simulation: Simulation from the Odos Assemble API: https://docs.odos.xyz/build/api-docs
SimulationError: Simulation error from the Odos Assemble API: https://docs.odos.xyz/build/api-docs
SingleQuoteResponse: Single quote response from the Odos quote API: https://docs.odos.xyz/build/api-docs
SwapContext: A token swap.
SwapContextBuilder: Use builder syntax to set the inputs and finish with build().
SwapInputs: Swap inputs for the Odos assemble API
TransactionData: Transaction data from the Odos Assemble API: https://docs.odos.xyz/build/api-docs
TransferRouterFunds: A transfer of a token from one address to another.
TransferRouterFundsBuilder: Use builder syntax to set the inputs and finish with build().
V2Router: The V2 SOR Router contract.

Enums§

OdosChainError: Errors that can occur when working with Odos chains
OdosError: Comprehensive error types for the Odos SDK

Constants§

ASSEMBLE_URL: The URL for the Odos Assemble API
ODOS_V3: Odos V3 Router - Next-generation router contract
ODOS_V2_ARBITRUM_ROUTER: Arbitrum One - V2 Router contract address
ODOS_V2_AVALANCHE_ROUTER: Avalanche C-Chain - V2 Router contract address
ODOS_V2_BASE_ROUTER: Base - V2 Router contract address
ODOS_V2_BSC_ROUTER: BNB Smart Chain - V2 Router contract address
ODOS_V2_ETHEREUM_ROUTER: Ethereum Mainnet - V2 Router contract address
ODOS_V2_FANTOM_ROUTER: Fantom - V2 Router contract address
ODOS_V2_FRAXTAL_ROUTER: Fraxtal - V2 Router contract address
ODOS_V2_LINEA_ROUTER: Linea - V2 Router contract address
ODOS_V2_MANTLE_ROUTER: Mantle - V2 Router contract address
ODOS_V2_MODE_ROUTER: Mode - V2 Router contract address
ODOS_V2_OP_ROUTER: Optimism - V2 Router contract address
ODOS_V2_POLYGON_ROUTER: Polygon - V2 Router contract address
ODOS_V2_SCROLL_ROUTER: Scroll - V2 Router contract address
ODOS_V2_SONIC_ROUTER: Sonic - V2 Router contract address
ODOS_V2_UNICHAIN_ROUTER: Unichain - V2 Router contract address
ODOS_V2_ZKSYNC_ROUTER: zkSync Era - V2 Router contract address

Traits§

OdosChain: Trait for chains that support Odos protocol
OdosRouterSelection: Extension trait for easy router selection

Functions§

get_both_router_addresses: Check if both V2 and V3 are supported on a given chain
get_supported_chains: Get all supported chain IDs
get_supported_v2_chains: Legacy alias for backward compatibility
get_supported_v3_chains: Legacy alias for backward compatibility
get_v2_router_by_chain_id: Get the V2 router address for a specific chain ID
get_v3_router_by_chain_id: Get the V3 router address for a specific chain ID
parse_value

Type Aliases§

OdosChainResult: Result type for Odos chain operations
Result: Result type alias for Odos SDK operations

Crate odos_sdkCopy item path