@sodax/sdk 0.0.1-rc.9 → 1.0.0-rc.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) [2024] [Balanced Network]
+Copyright (c) [2025] [Sodax]
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -4,27 +4,45 @@ The Sodax SDK provides a comprehensive interface for interacting with the Sodax
 
 ## Features
 
-### Swaps (Solver / Intents)
-  - EVM (Arbitrum, Avalanche, Base, BSC, Optimism, Polygon) ✅
+### Swaps (Solver / Intents) [📖](./docs/SOLVER.md)
+  - EVM (Arbitrum, Avalanche, Base, BSC, Optimism, Polygon, Sonic, HyperEVM❌, Lightlink) ✅
   - Sui ✅
   - Stellar ✅
   - ICON ✅
-  - Solana ❌ Coming soon
-  - Injective ❌ Coming soon
-  - Havah ❌ Coming soon
+  - Solana ✅
+  - Injective ✅
 
-### Lend and Borrow (Money Market)
-  - EVM (Arbitrum, Avalanche, Base, BSC, Optimism, Polygon) ✅
+### Lend and Borrow (Money Market) [📖](./docs/MONEY_MARKET.md)
+  - EVM (Arbitrum, Avalanche, Base, BSC, Optimism, Polygon, Sonic, HyperEVM, Lightlink) ✅
   - Sui ✅
   - Stellar ✅
   - ICON ✅
-  - Solana ❌ Coming soon
-  - Injective ❌ Coming soon
-  - Havah ❌ Coming soon
+  - Solana ✅
+  - Injective ✅
 
+### Cross-chain bridging (Bridge) [📖](./docs/BRIDGE.md)
+  - EVM (Arbitrum, Avalanche, Base, BSC, Optimism, Polygon, Sonic, HyperEVM, Lightlink) ✅
+  - Sui ✅
+  - Stellar ✅
+  - ICON ✅
+  - Solana ✅
+  - Injective ✅
 
-## Installation
+### Migration [📖](./docs/MIGRATION.md)
+ - Legacy bnUSD <> New bnUSD:
+ - ICX <> SODA
+ - BALN <> SODA
+
+ ### Staking SODA [📖](./docs/STAKING.md)
+  - EVM (Arbitrum, Avalanche, Base, BSC, Optimism, Polygon, Sonic, HyperEVM❌, Lightlink) ✅
+  - Sui ✅
+  - Stellar ✅
+  - ICON ✅
+  - Solana ✅
+  - Injective ✅
 
+## Installation
+ 
 ```bash
 # Using npm
 npm install @sodax/sdk
@@ -62,8 +80,8 @@ How to setup local development
 ## Intent Solver Endpoints
 
 Current Intent Solver API endpoints:
-- **Production (mainnet)**: "TODO"
-- **Staging** (mainnet): "https://staging-new-world.iconblockchain.xyz"
+- **Production (mainnet)**: "https://sodax-solver-staging.iconblockchain.xyz"
+- **Staging** (mainnet): "https://sodax-solver-staging.iconblockchain.xyz"
 
 **Note** Staging endpoint contains features to be potentially released and is subject to frequent change!
 
@@ -77,19 +95,31 @@ Current Relayer API endpoints:
 
 ## Usage
 
-The Sodax SDK is initialized by creating a new `Sodax` instance with your desired configuration. The SDK supports both Solver (for intent-based swaps) and Money Market (for cross-chain lending and borrowing) services.
+The Sodax SDK is initialized by creating a new `Sodax` instance with your desired configuration. The SDK supports both Swaps (for intent-based solver swaps) and Money Market (for cross-chain lending and borrowing) services.
 
-Both Solver and Money Market configuration and optional. You can always choose to use just a specific feature.
+Both Swaps (Solver) and Money Market configuration and optional. You can always choose to use just a specific feature.
 
 ### Basic Configuration
 
 ```typescript
+import { Sodax } from '@sodax/sdk';
+
 // Initialize Sodax using default Sonic mainnet configurations (no fees)
 const sodax = new Sodax();
 
-// Use default config but put fee on solver (intent swaps)
-const sodaxWithSolverFees = new Sodax({
-  solver: { partnerFee: partnerFeePercentage },
+// If you want dynamic (backend API based - contains latest tokens) configuration,
+// make sure to initialize the instance before usage!
+// By default, configuration from the specific SDK version you are using is used
+await sodax.initialize();
+
+// Use default config but put fee on swaps (solver intent swaps)
+const partnerFeePercentage = {
+  address: '0x0000000000000000000000000000000000000000', // address to receive fee
+  percentage: 100, // 100 = 1%, 10000 = 100%
+};
+
+const sodaxWithSwapFees = new Sodax({
+  swap: { partnerFee: partnerFeePercentage },
 });
 
 // Use default config with fee on money market (borrows)
@@ -97,137 +127,185 @@ const sodaxWithMoneyMarketFees = new Sodax({
   moneyMarket: { partnerFee: partnerFeePercentage },
 });
 
-// or use default config with fees on both solver and money market
+// Or use default config with fees on both swaps and money market
 const sodaxWithFees = new Sodax({
-  solver: { partnerFee: partnerFeePercentage },
+  swap: { partnerFee: partnerFeePercentage },
   moneyMarket: { partnerFee: partnerFeePercentage },
 });
 ```
 
 ### Custom Configuration
 
-Sodax SDK can be customized for partner fee, solver or money market configuration.
+Sodax SDK can be customized for partner fee, swaps or money market configuration.
 
 ```typescript
 import {
   Sodax,
   PartnerFee,
   SolverConfigParams,
+  MoneyMarketConfigParams,
+  EvmHubProviderConfig,
   getSolverConfig,
   getMoneyMarketConfig,
+  getHubChainConfig,
+  SONIC_MAINNET_CHAIN_ID,
 } from '@sodax/sdk';
 
 // Partner fee can be defined as a percentage or a definite token amount.
 // Fee is optional, you can leave it empty/undefined.
 const partnerFeePercentage = {
-  address: '0x0000000000000000000000000000000000000000', // address to receive fee too
+  address: '0x0000000000000000000000000000000000000000', // address to receive fee
   percentage: 100, // 100 = 1%, 10000 = 100%
 } satisfies PartnerFee;
 
 const partnerFeeAmount = {
-  address: '0x0000000000000000000000000000000000000000', // address to receive fee too
+  address: '0x0000000000000000000000000000000000000000', // address to receive fee
   amount: 1000n, // definite amount denominated in token decimal precision
 } satisfies PartnerFee;
 
 // Solver config is optional and is required only if you want to use intent based swaps.
 // You can either use custom solver config or the default one (based on hub chain id - defaults to Sonic chain as hub)
 
-// example of custom solver config
+// Example of custom solver config
 const customSolverConfig = {
   intentsContract: '0x6382D6ccD780758C5e8A6123c33ee8F4472F96ef',
-  solverApiEndpoint: 'https://staging-new-world.iconblockchain.xyz',
+  solverApiEndpoint: 'https://sodax-solver-staging.iconblockchain.xyz',
   partnerFee: partnerFeePercentage, // or partnerFeeAmount
 } satisfies SolverConfigParams;
 
-// pre-defined default solver config per hub chain id (Sonic hub is the default)
+// Pre-defined default solver config per hub chain id (Sonic hub is the default)
 const solverConfig: SolverConfigParams = getSolverConfig(SONIC_MAINNET_CHAIN_ID);
 
-  // example of custom money market config
+// Example of custom money market config
 const customMoneyMarketConfig = {
   lendingPool: '0x553434896D39F867761859D0FE7189d2Af70514E',
   uiPoolDataProvider: '0xC04d746C38f1E51C8b3A3E2730250bbAC2F271bf',
   poolAddressesProvider: '0x036aDe0aBAA4c82445Cb7597f2d6d6130C118c7b',
   bnUSD: '0x94dC79ce9C515ba4AE4D195da8E6AB86c69BFc38',
   bnUSDVault: '0xE801CA34E19aBCbFeA12025378D19c4FBE250131',
-} satisfies MoneyMarketConfig;
+} satisfies MoneyMarketConfigParams;
 
-// pre-defined default money market config per hub chain id (Sonic hub is the default)
+// Pre-defined default money market config per hub chain id (Sonic hub is the default)
 const moneyMarketConfig = getMoneyMarketConfig(SONIC_MAINNET_CHAIN_ID);
 
-// example of custom hub config
+// Example of custom hub config
 const hubConfig = {
   hubRpcUrl: 'https://rpc.soniclabs.com',
   chainConfig: getHubChainConfig(SONIC_MAINNET_CHAIN_ID),
 } satisfies EvmHubProviderConfig;
 
-
 // Initialize Sodax using custom/default configurations
 const sodax = new Sodax({
-  solver: solverConfig,
+  swap: solverConfig,
   moneyMarket: moneyMarketConfig,
   hubProviderConfig: hubConfig,
 });
+
+// Initialize with dynamic configuration (recommended for latest tokens/chains)
+await sodax.initialize();
 ```
 
 ### Using SDK Config and Constants
 
-SDK includes predefined configurations of supported chains, tokens and other relevant information for the client to consume.
+SDK includes predefined configurations of supported chains, tokens and other relevant information for the client to consume. All configurations are accessible through the `config` property of the Sodax instance (`sodax.config`), or through service-specific properties for convenience.
 
-**NOTE** you should generally only use `spokeChains` configuration to retrieve all supported chains and then invoke per spoke chain based configurations. If you are using hub configurations you should know what you are doing.
+**NOTE**: You should generally only use spoke chains configuration to retrieve all supported chains and then invoke per spoke chain based configurations. If you are using hub configurations you should know what you are doing.
 
-Please refer to [SDK constants.ts](https://github.com/icon-project/sodax-frontend/blob/main/packages/sdk/src/constants.ts) for more.
+**IMPORTANT**: If you want dynamic (backend API based - contains latest tokens) configuration, make sure to initialize the instance before usage:
+```typescript
+await sodax.initialize();
+```
+By default, configuration from the specific SDK version you are using is used.
+
+#### General Configuration (sodax.config)
 
 ```typescript
-import {
-  getHubChainConfig,
-  supportedHubAssets,
-  supportedHubChains,
-  supportedSpokeChains,
-  spokeChainConfig,
-  getSupportedSolverTokens,
-  moneyMarketReserveAssets,
-} from "@sodax/sdk";
+import { Sodax, type SpokeChainId, type HubChainId } from "@sodax/sdk";
+
+const sodax = new Sodax();
+await sodax.initialize(); // Initialize for dynamic config (optional but recommended)
+
+// All supported hub chains (Sonic mainnet and testnet)
+const hubChains: HubChainId[] = sodax.config.getSupportedHubChains();
+
+// All supported spoke chains
+const spokeChains: SpokeChainId[] = sodax.config.getSupportedSpokeChains();
+
+// Get all chains configuration
+const chains = sodax.config.getChains();
+
+// Get hub assets configuration
+const hubAssets = sodax.config.getHubAssets();
 
-const hubChainConfig = getHubChainConfig(SONIC_MAINNET_CHAIN_ID);
+// Get hub vaults configuration
+const hubVaults = sodax.config.getHubVaults();
 
-// all supported hub chains (Sonic mainnet and testnet)
-export const hubChains: HubChainId[] = supportedHubChains;
+// Get money market reserve assets
+const moneyMarketReserves = sodax.config.getMoneyMarketReserveAssets();
 
-// all supported spoke chains
-export const spokeChains: SpokeChainId[] = supportedSpokeChains;
+// Check if a token is valid for a given chain
+const isValid = sodax.config.isValidOriginalAssetAddress(chainId, tokenAddress);
 
-// all hub assets (original asset addresses mapped to "Abstracted evm addresses")
-export const hubAssets: Set<Address> = supportedHubAssets;
+// Get hub asset info for a given chain and original asset
+const hubAssetInfo = sodax.config.getHubAssetInfo(chainId, tokenAddress);
+```
+
+#### Swap Configuration (sodax.swap)
 
-// all money market reserve addresses on hub chain (sonic)
-export const moneyMarketReserves = moneyMarketReserveAssets;
+```typescript
+import { Sodax, type SpokeChainId, type Token } from "@sodax/sdk";
 
-// record mapping spoke chain Id to spoke chain configs
-export spokeChainConfigRecord : Record<SpokeChainId, SpokeChainConfig> = spokeChainConfig;
+const sodax = new Sodax();
+await sodax.initialize(); // Initialize for dynamic config (optional but recommended)
 
-// using spoke chain id to retrieve supported tokens for solver (intent swaps)
-const supportedSolverTokens: readonly Token[] = getSupportedSolverTokens(spokeChainId);
+// Get supported swap tokens for a specific chain
+const supportedSwapTokens: readonly Token[] = sodax.swap.getSupportedSwapTokensByChainId(chainId);
 
-// using spoke chain id to retrieve supported tokens address (on spoke chain = original address) for money market
-const supportedMoneyMarketTokens: readonly Token[] = getSupportedMoneyMarketTokens(spokeChainId)
+// Get all supported swap tokens per chain
+const allSwapTokens: Record<SpokeChainId, readonly Token[]> = sodax.swap.getSupportedSwapTokens();
 
-// checkout constants.ts for all configs available
+// Alternative: Access through config service
+const swapTokensFromConfig: readonly Token[] = sodax.config.getSupportedSwapTokensByChainId(chainId);
+const allSwapTokensFromConfig = sodax.config.getSupportedSwapTokens();
 ```
 
+#### Money Market Configuration (sodax.moneyMarket)
+
+```typescript
+import { Sodax, type SpokeChainId, type Token, type Address } from "@sodax/sdk";
+
+const sodax = new Sodax();
+await sodax.initialize(); // Initialize for dynamic config (optional but recommended)
+
+// Get supported money market tokens for a specific chain
+const supportedMoneyMarketTokens: readonly Token[] = sodax.moneyMarket.getSupportedTokensByChainId(chainId);
+
+// Get all supported money market tokens
+const allMoneyMarketTokens = sodax.moneyMarket.getSupportedTokens();
+
+// Get supported money market reserves
+const reserves: readonly Address[] = sodax.moneyMarket.getSupportedReserves();
+
+// Alternative: Access through config service
+const moneyMarketTokensFromConfig: readonly Token[] = sodax.config.getSupportedMoneyMarketTokensByChainId(chainId);
+const allMoneyMarketTokensFromConfig = sodax.config.getSupportedMoneyMarketTokens();
+```
+
+Please refer to [SDK constants.ts](https://github.com/icon-project/sodax-frontend/blob/main/packages/sdk/src/constants.ts) for additional static constants and configurations.
+
 ### Wallet Providers
 
 Sodax SDK does not force the usage of a specific wallet or library, but requires client to provide implementation of `IWalletProvider` interfaces (e.g. for EVM chains `IEvmWalletProvider` has to be implemented).
 
-As part of Sodax suite, xWagmi SDK is also going to be provided as one example wallet provider implementation. You are free to choose between using our xWagmi SDK or implementing your own wallet connectivity for each chain.
+As part of Sodax suite, Wallet SDK is also going to be provided as one example wallet provider implementation. You are free to choose between using our Wallet SDK or implementing your own wallet connectivity for each chain.
 
 - Supported Wallet Provider Interface (`IWalletProvider`)
   - `IEvmWalletProvider`: EVM (Arbitrum, Avalanche, Base, BSC, Optimism, Polygon) ✅
   - `ISuiWalletProvider`: Sui ✅
   - `IIconWalletProvider`: ICON ✅
   - `IStellarWalletProvider`: Stellar ✅
-  - Solana ❌ Coming soon
-  - Injective ❌ Coming soon
-  - Havah ❌ Coming soon
+  - `ISolanaWalletProvider`: Solana ✅
+  - `IInjectiveWalletProvider`: Injective ✅
 
 ### Initialising Spoke Provider
 
@@ -242,20 +320,102 @@ EVM Provider example:
 ```typescript
 import { EvmProvider, EvmHubProvider, EvmSpokeProvider, AVALANCHE_MAINNET_CHAIN_ID, SONIC_MAINNET_CHAIN_ID } from "@sodax/sdk"
 
-const evmWalletProvider: IEvmWalletProvider = // injected by xWagmi SDK or your own implementation
+const evmWalletProvider: IEvmWalletProvider = // injected by Wallet SDK or your own implementation
 
 // spoke provider represents connection to a specific chain, should be instantiated for each supported chain when user connects wallet
 const bscSpokeProvider: EvmSpokeProvider = new EvmSpokeProvider(
   evmWalletProvider, // user connected wallet
-  spokeChainConfig[BSC_MAINNET_CHAIN_ID] as EvmSpokeChainConfig, // connected chain config
+  spokeChainConfig[BSC_MAINNET_CHAIN_ID], // connected chain config
 );
 ```
 
+### Estimate Gas for Raw Transactions
+
+The `estimateGas` function allows you to estimate the gas cost for raw transactions before executing them. This is particularly useful for all Sodax operations (swaps, money market operations, approvals) to provide users with accurate gas estimates.
+
+The function is available on all service classes:
+- `SwapService.estimateGas()` - for solver/intent operations (reachable through `sodax.swap`)
+- `MoneyMarketService.estimateGas()` - for money market operations (reachable through `sodax.moneyMarket`)
+- `SpokeService.estimateGas()` - for general spoke chain operations
+
+```typescript
+import { 
+  SwapService, 
+  MoneyMarketService, 
+  SpokeService,
+  MoneyMarketSupplyParams 
+} from "@sodax/sdk";
+
+// Example: Estimate gas for a solver swap transaction
+const createIntentResult = await sodax.swap.createIntent(
+  createIntentParams,
+  bscSpokeProvider,
+  partnerFeeAmount,
+  true, // true = get raw transaction
+);
+
+if (createIntentResult.ok) {
+  const [rawTx, intent] = createIntentResult.value;
+  
+  // Estimate gas for the raw transaction
+  const gasEstimate = await SwapService.estimateGas(rawTx, bscSpokeProvider);
+  
+  if (gasEstimate.ok) {
+    console.log('Estimated gas for swap:', gasEstimate.value);
+  } else {
+    console.error('Failed to estimate gas for swap:', gasEstimate.error);
+  }
+}
+
+// Example: Estimate gas for a money market supply transaction
+const supplyResult = await sodax.moneyMarket.createSupplyIntent(
+  supplyParams,
+  bscSpokeProvider,
+  true, // true = get raw transaction
+);
+
+if (supplyResult.ok) {
+  const rawTx = supplyResult.value;
+  
+  // Estimate gas for the raw transaction
+  const gasEstimate = await MoneyMarketService.estimateGas(rawTx, bscSpokeProvider);
+  
+  if (gasEstimate.ok) {
+    console.log('Estimated gas for supply:', gasEstimate.value);
+  } else {
+    console.error('Failed to estimate gas for supply:', gasEstimate.error);
+  }
+}
+
+// Example: Estimate gas for an approval transaction
+const approveResult = await sodax.swap.approve(
+  tokenAddress,
+  amount,
+  bscSpokeProvider,
+  true // true = get raw transaction
+);
+
+if (approveResult.ok) {
+  const rawTx = approveResult.value;
+  
+  // Estimate gas for the approval transaction
+  const gasEstimate = await SpokeService.estimateGas(rawTx, bscSpokeProvider);
+  
+  if (gasEstimate.ok) {
+    console.log('Estimated gas for approval:', gasEstimate.value);
+  } else {
+    console.error('Failed to estimate gas for approval:', gasEstimate.error);
+  }
+}
+```
+
 ### Accessing Sodax Features
 
 Sodax feature set currently contain:
-- Solver: used for intent based swaps. Please find documentation for Solver part of the SDK in [SOLVER.md](./docs/SOLVER.md)
-- Money Market: used for lending and borowing. Please find documentation for Solver part of the SDK in [MONEY_MARKET.md](./docs/MONEY_MARKET.md)
+- Swap (Solver): used for intent based swaps. Please find documentation for Swaps part of the SDK in [SWAPS.md](./docs/SWAPS.md)
+- Money Market: used for lending and borowing. Please find documentation for Money Market part of the SDK in [MONEY_MARKET.md](./docs/MONEY_MARKET.md)
+- Bridge: provides functionality to bridge tokens between different blockchain chains [BRIDGE.md](./docs/BRIDGE.md)
+- Staking: provides functionality to stake SODA tokens from different blockchain chains [STAKING.md](./docs/STAKING.md)
 
 ## Intent Relay API