chore(doc): Add comments and derive attributes

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "uniswap-sdk-core"
-version = "0.20.1"
+version = "0.22.0"
 edition = "2021"
 authors = ["malik <aremumalik05@gmail.com>", "Shuhui Luo <twitter.com/aureliano_law>"]
 description = "The Uniswap SDK Core in Rust provides essential functionality for interacting with the Uniswap decentralized exchange"
@@ -13,10 +13,8 @@ eth_checksum = { version = "0.1.2", optional = true }
 lazy_static = "1.4"
 num-bigint = "0.4.4"
 num-integer = "0.1.45"
-num-rational = "0.4.1"
 num-traits = "0.2.17"
 regex = { version = "1.10", optional = true }
-syn = "2.0"
 thiserror = "1.0"
 
 [features]

README.md

@@ -17,7 +17,7 @@ Add this to your Cargo.toml
 
 ```
 [dependencies]
-uniswap-sdk-core = "0.20.0";
+uniswap-sdk-core = "0.22.0";
 ```
 
 And this to your code:

src/addresses.rs

@@ -4,7 +4,13 @@ type AddressMap = HashMap<u64, Address>;
 type ChainMap = HashMap<u64, ChainAddresses>;
 type ChainAddress = HashMap<u64, Address>;
 
-#[derive(Clone, Copy)]
+#[derive(Clone, Copy, Debug)]
+
+/// Represents the addresses of various contracts on a network.
+///
+/// This struct holds the addresses for various Uniswap contracts such as the
+/// core factory, multicall, quoter, migrator, and others. Each field in the struct
+/// corresponds to a specific contract and its address on the network.
 pub struct ChainAddresses {
     v3_core_factory_address: Address,
     multicall_address: Address,
@@ -16,6 +22,10 @@ pub struct ChainAddresses {
     v1_mixed_route_quoter_address: Option<Address>,
 }
 
+/// The default networks that are supported by the Uniswap SDK Core.
+///
+/// This constant defines the default networks that the SDK will interact with.
+/// It includes the mainnet, Goerli, and Sepolia networks.
 pub const DEFAULT_NETWORKS: [ChainId; 3] = [ChainId::MAINNET, ChainId::GOERLI, ChainId::SEPOLIA];
 
 /// returns a hashmap of key pair input of chainid to address
@@ -38,6 +48,11 @@ pub fn construct_same_address_map(address: Address, additional_networks: &[Chain
 }
 
 lazy_static! {
+    /// The UNI_ADDRESSES struct holds a map of addresses for the UNI token on various networks.
+    ///
+    /// This map is constructed using the `construct_same_address_map` function, which takes an address
+    /// and a list of additional networks, and returns a map where each network ID is associated
+    /// with the provided address. The default networks include Mainnet, Goerli, and Sepolia.
     #[derive(Debug, Clone, Copy)]
     pub static ref UNI_ADDRESSES: AddressMap = construct_same_address_map(
         address!("1f9840a85d5aF5bf1D1762F925BDADdC4201F984"),
@@ -51,12 +66,19 @@ lazy_static! {
     );
 }
 
+/// The address for the Uniswap NFT airdrop claim contract.
 pub const UNISWAP_NFT_AIRDROP_CLAIM_ADDRESS: Address =
     address!("8B799381ac40b838BBA4131ffB26197C432AFe78");
 
+/// The address for the Uniswap V2 Factory Address claim contract.
 pub const V2_FACTORY_ADDRESS: Address = address!("5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f");
 
 lazy_static! {
+    /// A map of Uniswap V2 Factory addresses for various networks.
+    ///
+    /// This map is used to look up the address of the Uniswap V2 Factory contract
+    /// for a given network. The keys in the map are the network IDs, and the values
+    /// are the corresponding contract addresses.
     pub static ref V2_FACTORY_ADDRESSES: HashMap<u64, Address> = {
         let mut m = HashMap::new();
         m.insert(ChainId::MAINNET as u64, V2_FACTORY_ADDRESS);
@@ -97,9 +119,15 @@ lazy_static! {
     };
 }
 
+/// The address for the Uniswap V2 Router Address claim contract.
 pub const V2_ROUTER_ADDRESS: Address = address!("7a250d5630B4cF539739dF2C5dAcb4c659F2488D");
 
 lazy_static! {
+    /// A map of Uniswap V2 Router addresses for various networks.
+    ///
+    /// This map is used to look up the address of the Uniswap V2 Router contract
+    /// for a given network. The keys in the map are the network IDs, and the values
+    /// are the corresponding contract addresses.
     pub static ref V2_ROUTER_ADDRESSES: HashMap<u64, Address> = {
         let mut m = HashMap::new();
         m.insert(ChainId::MAINNET as u64, V2_ROUTER_ADDRESS);
@@ -152,6 +180,10 @@ impl Default for ChainAddresses {
 }
 
 lazy_static! {
+    /// The `MAINNET_ADDRESSES` struct holds the Uniswap contract addresses for the Ethereum Mainnet.
+    ///
+    /// This includes the addresses for the core factory, multicall, quoter, migrator, and other contracts.
+    /// Each field in the struct corresponds to a specific contract and its address on the Mainnet.
     pub static ref MAINNET_ADDRESSES: ChainAddresses = {
         ChainAddresses {
             v1_mixed_route_quoter_address: Some(address!(
@@ -163,6 +195,10 @@ lazy_static! {
 }
 
 lazy_static! {
+    /// The `MAINNET_ADDRESSES` struct holds the Uniswap contract addresses for the Goerli Testnet.
+    ///
+    /// This includes the addresses for the core factory, multicall, quoter, migrator, and other contracts.
+    /// Each field in the struct corresponds to a specific contract and its address on the Mainnet.
     pub static ref GOERLI_ADDRESSES: ChainAddresses = {
         ChainAddresses {
             v1_mixed_route_quoter_address: Some(address!(
@@ -174,10 +210,18 @@ lazy_static! {
 }
 
 lazy_static! {
+    /// The `OPTIMISM_ADDRESSES` struct holds the Uniswap contract addresses for the Optimism network.
+    ///
+    /// This includes the addresses for the core factory, multicall, quoter, migrator, and other contracts.
+    /// Each field in the struct corresponds to a specific contract and its address on the Optimism network.
     pub static ref OPTIMISM_ADDRESSES: ChainAddresses = ChainAddresses::default();
 }
 
 lazy_static! {
+    /// The `ARBITRUM_ONE_ADDRESSES` struct holds the Uniswap contract addresses for the Arbitrum One network.
+    ///
+    /// This includes the addresses for the core factory, multicall, quoter, migrator, and other contracts.
+    /// Each field in the struct corresponds to a specific contract and its address on the Arbitrum One network.
     pub static ref ARBITUM_ONE_ADDRESSES: ChainAddresses = {
         ChainAddresses {
             multicall_address: address!("adF885960B47eA2CD9B55E6DAc6B42b7Cb2806dB"),
@@ -187,6 +231,10 @@ lazy_static! {
     };
 }
 lazy_static! {
+    /// The `POLYGON_ADDRESSES` struct holds the Uniswap contract addresses for the Polygon network.
+    ///
+    /// This includes the addresses for the core factory, multicall, quoter, migrator, and other contracts.
+    /// Each field in the struct corresponds to a specific contract and its address on the Polygon network.
     pub static ref POLYGON_ADDRESSES: ChainAddresses = ChainAddresses::default();
 }
 
@@ -373,6 +421,11 @@ pub const ROOTSTOCK_ADDRESSES: ChainAddresses = ChainAddresses {
 };
 
 lazy_static! {
+    /// A map of chain IDs to their corresponding Uniswap contract addresses.
+    ///
+    /// This map is used to look up the addresses of various Uniswap contracts
+    /// for a given network. The keys in the map are the network IDs, and the values
+    /// are the corresponding contract addresses.
     pub static ref CHAIN_TO_ADDRESSES_MAP: ChainMap = {
         let mut new_map = ChainMap::new();
         new_map.insert(ChainId::BNB as u64, BNB_ADDRESSES);
@@ -485,11 +538,19 @@ pub static ref GOVERNANCE_BRAVO_ADDRESSES: AddressMap = {
 }
 
 lazy_static! {
+    /// The `TIMELOCK_ADDRESSES` struct holds the timelock contract addresses for various networks.
+    ///
+    /// This includes the addresses for the timelock contract on different networks.
+    /// Each field in the struct corresponds to a specific contract and its address on the network.
     pub static ref TIMELOCK_ADDRESSES: AddressMap =
         construct_same_address_map(address!("1a9C8182C09F50C8318d769245beA52c32BE35BC"), &[]);
 }
 
 lazy_static! {
+    /// The `MERKLE_DISTRIBUTOR_ADDRESS` struct holds the merkle distributor contract address for the mainnet.
+    ///
+    /// This includes the address for the merkle distributor contract on the mainnet.
+    /// Each field in the struct corresponds to a specific contract and its address on the network.
     pub static ref MERKLE_DISTRIBUTOR_ADDRESS: AddressMap = {
         let mut new_map = AddressMap::new();
         new_map.insert(
@@ -501,6 +562,10 @@ lazy_static! {
 }
 
 lazy_static! {
+    /// The `ARGENT_WALLET_DETECTOR_ADDRESS` struct holds the Argent Wallet Detector contract address for the mainnet.
+    ///
+    /// This includes the address for the Argent Wallet Detector contract on the mainnet.
+    /// Each field in the struct corresponds to a specific contract and its address on the network.
     pub static ref ARGENT_WALLET_DETECTOR_ADDRESS: AddressMap = {
         let mut new_map = AddressMap::new();
         new_map.insert(
@@ -512,6 +577,10 @@ lazy_static! {
 }
 
 lazy_static! {
+    /// The `QUOTER_ADDRESSES` struct holds the quoter contract addresses for various networks.
+    ///
+    /// This includes the addresses for the quoter contract on different networks.
+    /// Each field in the struct corresponds to a specific contract and its address on the network
     pub static ref QUOTER_ADDRESSES: ChainAddress = {
         let mut chain_add = ChainAddress::new();
         for chain_id in SUPPORTED_CHAINS {
@@ -528,6 +597,10 @@ lazy_static! {
 }
 
 lazy_static! {
+    /// The `NONFUNGIBLE_POSITION_MANAGER_ADDRESSES` struct holds the non-fungible position manager contract addresses for various networks.
+    ///
+    /// This includes the addresses for the non-fungible position manager contract on different networks.
+    /// Each field in the struct corresponds to a specific contract and its address on the network.
     pub static ref NONFUNGIBLE_POSITION_MANAGER_ADDRESSES: ChainAddress = {
         let mut chain_add = ChainAddress::new();
         for chain_id in SUPPORTED_CHAINS {
@@ -552,11 +625,19 @@ lazy_static! {
 }
 
 lazy_static! {
+    /// The `ENS_REGISTRAR_ADDRESSES` struct holds the ENS Registrar contract addresses for various networks.
+    ///
+    /// This includes the addresses for the ENS Registrar contract on different networks.
+    /// Each field in the struct corresponds to a specific contract and its address on the network.
     pub static ref ENS_REGISTRAR_ADDRESSES: AddressMap =
         construct_same_address_map(address!("00000000000C2E074eC69A0dFb2997BA6C7d2e1e"), &[]);
 }
 
 lazy_static! {
+    /// The `SOCKS_CONTROLLER_ADDRESSES` struct holds the SOCKS Controller contract addresses for various networks.
+    ///
+    /// This includes the addresses for the SOCKS Controller contract on different networks.
+    /// Each field in the struct corresponds to a specific contract and its address on the network.
     pub static ref SOCKS_CONTROLLER_ADDRESSES: AddressMap = {
         let mut new_map = AddressMap::new();
         new_map.insert(
@@ -568,6 +649,10 @@ lazy_static! {
 }
 
 lazy_static! {
+    /// The `TICK_LENS_ADDRESSES` struct holds the tick lens contract addresses for various networks.
+    ///
+    /// This includes the addresses for the tick lens contract on different networks.
+    /// Each field in the struct corresponds to a specific contract and its address on the network.
     pub static ref TICK_LENS_ADDRESSES: ChainAddress = {
         let mut chain_add = ChainAddress::new();
         for chain_id in SUPPORTED_CHAINS {
@@ -592,6 +677,10 @@ lazy_static! {
 }
 
 lazy_static! {
+    /// The `MIXED_ROUTE_QUOTER_V1_ADDRESSES` struct holds the mixed route quoter contract addresses for various networks.
+    ///
+    /// This includes the addresses for the mixed route quoter contract on different networks.
+    /// Each field in the struct corresponds to a specific contract and its address on the network.
     pub static ref MIXED_ROUTE_QUOTER_V1_ADDRESSES: ChainAddress = {
         let mut chain_add = ChainAddress::new();
         for chain_id in SUPPORTED_CHAINS {
@@ -615,6 +704,18 @@ lazy_static! {
     };
 }
 
+/// Returns the address of the Uniswap V2 Router contract for the specified chain.
+///
+/// If the chain ID is not found in the `CHAIN_TO_ADDRESSES_MAP`, it defaults to the
+/// address of the router contract on the Ethereum mainnet.
+///
+/// # Arguments
+///
+/// * `chain_id` - The ID of the chain for which to retrieve the router address.
+///
+/// # Returns
+///
+/// * `Address` - The address of the Uniswap V2 Router contract for the specified chain.
 pub fn swap_router02_address(chain_id: u64) -> Address {
     if CHAIN_TO_ADDRESSES_MAP.contains_key(&chain_id)
         && CHAIN_TO_ADDRESSES_MAP

src/chains.rs

@@ -1,29 +1,58 @@
 #[derive(Debug, Clone, Copy)]
+/// Represents the unique identifier for different blockchain networks supported by the Uniswap SDK.
+///
+/// Each variant corresponds to a specific blockchain network, identified by its unique chain ID.
 pub enum ChainId {
+    /// The Ethereum Mainnet.
     MAINNET = 1,
+    /// The Goerli Testnet.
     GOERLI = 5,
+    /// The Sepolia Testnet.
     SEPOLIA = 11155111,
+    /// The Optimism network.
     OPTIMISM = 10,
+    /// The Optimism Goerli Testnet.
     OPTIMISMGOERLI = 420,
+    /// The Optimism Sepolia Testnet.
     OPTIMISMSEPOLIA = 11155420,
+    /// The Arbitrum One network.
     ARBITRUMONE = 42161,
+    /// The Arbitrum Goerli Testnet.
     ARBITRUMGOERLI = 421613,
+    /// The Arbitrum Sepolia Testnet.
     ARBITRUMSEPOLIA = 421614,
+    /// The Polygon network.
     POLYGON = 137,
+    /// The Polygon Mumbai Testnet.
     POLYGONMUMBAI = 80001,
+    /// The Celo network.
     CELO = 42220,
+    /// The Celo Alfajores Testnet.
     CELOALFAJORES = 44787,
+    /// The Gnosis network.
     GNOSIS = 100,
+    /// The Moonbeam network.
     MOONBEAM = 1284,
+    /// The Binance Smart Chain (BSC).
     BNB = 56,
+    /// The Avalanche network.
     AVALANCHE = 43114,
+    /// The Base network.
     BASEGOERLI = 84531,
+    /// The Base Goerli Testnet.
     BASE = 8453,
+    /// The Zora network.
     ZORA = 7777777,
+    /// The Zora Sepolia Testnet.
     ZORASEPOLIA = 999999999,
+    /// The Rootstock network.
     ROOTSTOCK = 30,
 }
 
+/// A list of `ChainId` constants representing the blockchain networks supported by the Uniswap SDK.
+///
+/// This array includes all the `ChainId` variants that are supported by the SDK, making it easy to
+/// iterate over or check for supported chains.
 pub const SUPPORTED_CHAINS: [ChainId; 20] = [
     ChainId::MAINNET,
     ChainId::OPTIMISM,
@@ -47,13 +76,25 @@ pub const SUPPORTED_CHAINS: [ChainId; 20] = [
     ChainId::ROOTSTOCK,
 ];
 
+#[derive(Debug, Clone, Copy)]
+/// Represents the names of native currencies supported by the Uniswap SDK.
+///
+/// Each variant corresponds to a specific native currency name.
 pub enum NativeCurrencyName {
+    /// Ethereum's native currency.
     ETHER,
+    /// Polygon's native currency.
     MATIC,
+    /// Celo's native currency.
     CELO,
+    /// Gnosis's native currency.
     GNOSIS,
+    /// Moonbeam's native currency.
     MOONBEAM,
+    /// Binance Smart Chain's native currency.
     BNB,
+    /// Avalanche's native currency.
     AVAX,
+    /// Rootstock's native currency.
     ROOTSTOCK,
 }