# Dependency Documentation
This document explains the rationale behind all dependencies in the odos-sdk crate, their purpose, and version choices.
## Philosophy
The odos-sdk follows these dependency management principles:
1. **Minimal footprint**: Only include dependencies that are absolutely necessary
2. **Stable ecosystem**: Prefer well-maintained crates with strong community support
3. **Version alignment**: Keep related dependencies (e.g., alloy-*) at compatible versions
4. **Security first**: Regular audits and prompt updates for security advisories
5. **Zero unnecessary transitive deps**: Don't explicitly declare dependencies that are already pulled in transitively
## Core Dependencies
### Alloy Ecosystem (Ethereum Interactions)
The SDK heavily relies on the [Alloy](https://github.com/alloy-rs/alloy) suite of crates for type-safe Ethereum interactions.
#### alloy-chains (0.2.x)
- **Purpose**: Chain ID definitions and type-safe chain support
- **Why this version**: alloy-chains is in a separate repository (github.com/alloy-rs/chains) with its own versioning - 0.2.x is the latest stable series and is fully compatible with alloy 1.x
- **Current version**: 0.2.25 (latest)
- **Usage**: Provides `NamedChain` enum and chain-specific configurations
- **Note**: Despite different major version numbers, alloy-chains 0.2.x is designed to work with alloy 1.x
#### alloy-primitives (1.5.x)
- **Purpose**: Core Ethereum types (`Address`, `U256`, `Bytes`, etc.)
- **Features enabled**:
- `std`: Standard library support
- `rlp`: RLP encoding/decoding for Ethereum data structures
- **Why this version**: Latest stable release with excellent performance and ergonomics
- **Usage**: All address handling, amount calculations, and hex encoding
#### alloy-contract (1.3.x)
- **Purpose**: Contract interaction abstractions
- **Features**: `default-features = false` for fine-grained control
- **Usage**: Used for contract bindings and transaction assembly
#### alloy-sol-types (1.5.x)
- **Purpose**: Solidity type definitions and ABI encoding/decoding
- **Features enabled**: `json` for ABI JSON support
- **Usage**: V2/V3 router contract ABIs and transaction encoding
#### alloy-sol-type-parser (1.5.x)
- **Purpose**: Parsing Solidity type strings at compile time
- **Usage**: Contract macro expansion for type-safe ABI bindings
#### alloy-provider (1.3.x)
- **Purpose**: RPC provider abstractions for Ethereum node communication
- **Features enabled**:
- `anvil-node`: Local testing support
- `reqwest`: HTTP transport via reqwest
- **Usage**: Transaction simulation and submission
#### alloy-signer (1.3.x), alloy-signer-local (1.3.x)
- **Purpose**: Transaction signing abstractions and local wallet support
- **Features**: `default-features = false` to avoid unnecessary dependencies
- **Usage**: Transaction signing for swap execution
#### alloy-network (1.3.x)
- **Purpose**: Network-level abstractions (mainnet, testnet, etc.)
- **Features**: `default-features = false`
- **Usage**: Network-aware transaction building
#### alloy-rpc-* crates (1.3.x)
- **alloy-rpc-client**: Low-level RPC client
- **alloy-rpc-types**: RPC type definitions
- **alloy-json-rpc**: JSON-RPC protocol support
- **Purpose**: HTTP communication with Ethereum nodes and services
- **Usage**: Contract calls and transaction submission
#### alloy-transport (1.3.x), alloy-transport-http (1.3.x)
- **Purpose**: Transport layer for RPC communications
- **Features**: `reqwest` for HTTP support
- **Usage**: HTTP communication layer
**Version Strategy**: The alloy ecosystem consists of two repositories:
1. **alloy-rs/alloy** (1.x): Main alloy crates for Ethereum interactions
2. **alloy-rs/chains** (0.2.x): Chain definitions maintained separately
Both are fully compatible despite different version numbers. We use the latest stable from each repository.
### HTTP Client
#### reqwest (0.12.x)
- **Purpose**: Async HTTP client for Odos API communication
- **Features enabled**: `json` for automatic JSON serialization
- **Why this crate**: Industry standard, excellent async support, built on hyper
- **Usage**: All HTTP requests to Odos API endpoints
- **Note**: Reqwest pulls in `tower` and `tower-http` as transitive dependencies for middleware support
### Retry Logic
#### backon (1.6.x)
- **Purpose**: Exponential backoff algorithm for retries
- **Why this crate**: Actively maintained alternative to the unmaintained `backoff` crate
- **Migration**: Migrated from `backoff` 0.4.x (unmaintained, RUSTSEC-2025-0012)
- **Features**: Iterator-based backoff API with configurable min/max delays
- **Usage**: Retry logic in `OdosHttpClient::execute_with_retry` for transient failures
- **API differences**: Uses `BackoffBuilder` trait and iterator pattern instead of mutable state
### Serialization
#### serde (1.0.x)
- **Purpose**: Serialization/deserialization framework
- **Features enabled**: `derive` for automatic derive macros
- **Why this crate**: De facto standard for Rust serialization
- **Usage**: All API request/response structures
#### serde_json (1.0.x)
- **Purpose**: JSON implementation for serde
- **Why this crate**: Fast, reliable, standard JSON support
- **Usage**: JSON encoding/decoding for Odos API
### Error Handling
#### thiserror (2.0.x)
- **Purpose**: Ergonomic error type derivation
- **Why this crate**: Best-in-class error handling macros
- **Usage**: `OdosError` enum and all error types throughout the SDK
### Async Runtime
#### tokio (1.0.x)
- **Purpose**: Async runtime for async/await support
- **Features enabled**:
- `time`: Timer support for timeout and retry logic
- `rt`: Runtime support
- **Why this crate**: Industry standard async runtime
- **Usage**: Async operations, timeouts, sleep in retry logic
- **Note**: Minimal feature set - we don't need `macros`, `fs`, or `net`
### Ergonomics
#### bon (3.x)
- **Purpose**: Builder pattern macro for ergonomic APIs
- **Why this crate**: Type-safe builders with excellent compile-time checking
- **Usage**: `QuoteRequest`, `SwapContext`, and other builder APIs
- **Alternative considered**: `derive_builder`, but `bon` has better ergonomics
### Observability
#### tracing (0.1.x)
- **Purpose**: Structured logging and instrumentation
- **Why this crate**: Standard for Rust observability
- **Usage**: Instrumentation throughout the SDK for debugging and monitoring
- **Future**: Will be made optional via feature flag in 1.0.0
### Utilities
#### url (2.5.x)
- **Purpose**: URL parsing and manipulation
- **Why this crate**: Standard URL handling
- **Usage**: API endpoint construction and validation
#### uuid (1.x)
- **Purpose**: UUID generation and handling
- **Features enabled**:
- `serde`: Serialization support
- `v4`: Random UUID generation
- **Usage**: Request tracking and correlation IDs
## Dev Dependencies
### wiremock (0.6.x)
- **Purpose**: HTTP mocking for tests
- **Why this crate**: Best mock server library for Rust
- **Usage**: All integration tests mock Odos API responses
### tokio-test (0.4.x)
- **Purpose**: Testing utilities for async code
- **Why this crate**: Official tokio test utilities
- **Usage**: Async test helpers and assertions
### http (1.3.x)
- **Purpose**: HTTP types and abstractions
- **Why this crate**: Standard HTTP types used by test utilities
- **Usage**: Test request/response construction
## Removed Dependencies
### Tower/Tower-HTTP (Previously Explicit, Now Transitive Only)
- **Removed in**: 1.0.0
- **Rationale**: These were explicitly declared but never used directly in our code
- `tower` is pulled in by `reqwest`, `alloy-rpc-client`, and `alloy-transport`
- `tower-http` is pulled in by `reqwest`
- We don't use any tower middleware or services directly
- **Impact**: None - still available transitively
## Transitive Dependencies of Note
These are NOT explicitly declared but come from our direct dependencies:
### derivative (via ruint/ark-ff) - **[UNMAINTAINED]**
- **Advisory**: RUSTSEC-2024-0388
- **Status**: Pulled in by alloy's `ruint` dependency
- **Action**: No action needed - this is a proc macro crate with minimal runtime impact
- **Tracking**: Monitor alloy ecosystem for migration to maintained alternative
### instant **[REMOVED]**
- **Previously**: Transitive dependency via unmaintained `backoff` crate
- **Status**: Removed as part of migration from `backoff` to `backon`
- **Advisory**: RUSTSEC-2024-0384 (no longer applicable)
### paste (via syn-solidity) - **[UNMAINTAINED]**
- **Advisory**: RUSTSEC-2024-0436
- **Status**: Pulled in by alloy's Solidity parsing crates
- **Action**: No action needed - this is a proc macro crate
- **Note**: Despite "unmaintained" status, `paste` is feature-complete and widely used
## Dependency Update Policy
### Regular Updates
- **Frequency**: Weekly dependency checks via Dependabot
- **Security**: Immediate updates for security advisories
- **Major versions**: Careful evaluation with changelog review
### Breaking Changes
- **Pre-1.0**: Breaking dependency updates are acceptable
- **Post-1.0**: Breaking dependency updates require major version bump
- **Notification**: CHANGELOG will document all significant dependency changes
### CI Enforcement
- `cargo audit` runs on every PR - fails on vulnerabilities
- `cargo deny` checks licenses and advisories
- `cargo outdated` runs weekly to check for updates
## Future Improvements (Post-1.0 Roadmap)
1. **Feature Flags** (1.0.0):
- Make `tracing` optional
- Make `alloy-provider` optional for users who only want quote fetching
- Add `full` feature for all functionality
2. **Dependency Reduction** (Completed in 1.0.0):
- ✅ Replaced `backoff` with `backon`
- ✅ Removed `anyhow` compatibility shim
- ✅ Removed unused `tower`/`tower-http` explicit dependencies
- Evaluate if `uuid` is strictly necessary or if we can use simpler correlation IDs
3. **Performance**:
- Consider `simd-json` for faster JSON parsing (feature-gated)
- Evaluate `rustls` vs `native-tls` for better performance
4. **Observability**:
- Optional `metrics` crate integration
- Optional `opentelemetry` integration
## License Compatibility
All dependencies are compatible with the project's Apache-2.0 license:
- Most are dual-licensed MIT/Apache-2.0
- None have copyleft licenses (GPL, LGPL, etc.)
- CI enforces license compatibility via `cargo-deny`
## Acknowledgments
This project builds on the excellent work of the Rust and Ethereum communities, particularly:
- The [Alloy](https://github.com/alloy-rs/alloy) project for type-safe Ethereum interactions
- The Tokio project for async runtime
- The Serde project for serialization
---
**Last Updated**: 2026-01-12 (Version 2.0.0)
**Next Review**: Before 2.1.0 release