From 0fd5ab245e7d5cbf8894c8d2f482a80ddb2656ca Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Sat, 17 Jan 2026 12:51:42 +0530 Subject: [PATCH 01/27] docs: start refactoring core module usage - added installation guide --- sdk/core-module/guides/installation.md | 29 ++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 sdk/core-module/guides/installation.md diff --git a/sdk/core-module/guides/installation.md b/sdk/core-module/guides/installation.md new file mode 100644 index 0000000..cf6d5d8 --- /dev/null +++ b/sdk/core-module/guides/installation.md @@ -0,0 +1,29 @@ +--- +title: Install WDK Core +description: Learn how to install and set up the WDK Core module. +--- + +# Install WDK Core + +This guide shows you how to install the `@tetherto/wdk` package, which serves as the main entry point for the Wallet Development Kit (WDK). + +## Prerequisites + +Before you begin, ensure you have the following installed: + +* **Node.js**: version 18 or higher. +* **npm**: usually comes with Node.js. + +## Installation + +To install the WDK Core package, run the following command in your terminal: + +```bash +npm install @tetherto/wdk +``` + +This package allows you to manage different blockchain wallets and protocols through a single interface. + +## Next steps + +Now that you have installed the core package, you can [instantiate the WDK](./instantiation.md) to start creating wallets. From 994287c34f176a8aa9287af493048c1d2353d179 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Sat, 17 Jan 2026 12:52:38 +0530 Subject: [PATCH 02/27] docs: Add WDK Core instantiation guide --- sdk/core-module/guides/instantiation.md | 58 +++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 sdk/core-module/guides/instantiation.md diff --git a/sdk/core-module/guides/instantiation.md b/sdk/core-module/guides/instantiation.md new file mode 100644 index 0000000..b7352c7 --- /dev/null +++ b/sdk/core-module/guides/instantiation.md @@ -0,0 +1,58 @@ +--- +title: Instantiate WDK +description: Learn how to import and initialize the WDK Core module. +--- + +# Instantiate WDK + +This guide explains how to import the WDK Core module and create a new instance to start managing your wallets. + +## Import the module + +First, import the `WDK` class from the package you installed: + +{% code title="Import WDK Core"lineNumbers="true" %} +```typescript +import WDK from '@tetherto/wdk' +``` +{% endcode %} + +## Create an Instance + +To use the SDK, you must create an instance of the `WDK` class. This instance acts as the central manager for all your wallets and protocols. + +You can initialize `WDK` in two ways: with a new seed phrase or an existing one. + +### Option 1: Generate a new wallet + +If you are creating a fresh wallet for a user, use the static `getRandomSeedPhrase()` method to generate a secure mnemonic. + +{% code title="Create new WDK Instance" lineNumbers="true" %} +```typescript +// 1. Generate a secure random seed phrase +const seedPhrase = WDK.getRandomSeedPhrase() + +// 2. Initialize the WDK instance with the new seed +const wdk = new WDK(seedPhrase) +``` +{% endcode %} + +> [!IMPORTANT] +> **Secure the Seed Phrase:** You must securely store this seed phrase immediately. If it is lost, the user will permanently lose access to their funds. + +### Option 2: Restore an existing wallet + +If a user already has a seed phrase (e.g., from a previous session or another wallet), you can pass it directly to the constructor. + +{% code title="Restore WDK Instance" lineNumbers="true" %} +```typescript +// Replace this string with the user's actual seed phrase +const existingSeed = 'witch collapse practice feed shame open despair creek road again ice ...' + +const wdk = new WDK(existingSeed) +``` +{% endcode %} + +## Next steps + +With your WDK instance ready, you can now [register wallet modules](./wallet-registration.md) to interact with specific blockchains like Ethereum, TON, or Bitcoin. From eaa310821f406b0fed9a89bc6227f44986da62be Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Sat, 17 Jan 2026 16:49:55 +0530 Subject: [PATCH 03/27] docs: add core module wallet registration guide --- sdk/core-module/guides/wallet-registration.md | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 sdk/core-module/guides/wallet-registration.md diff --git a/sdk/core-module/guides/wallet-registration.md b/sdk/core-module/guides/wallet-registration.md new file mode 100644 index 0000000..9d59a43 --- /dev/null +++ b/sdk/core-module/guides/wallet-registration.md @@ -0,0 +1,78 @@ +--- +title: Register Wallets +description: Learn how to register wallet modules for different blockchains. +--- + +# Register Wallets + +This guide explains how to register wallet modules with your WDK instance. The WDK Core module itself doesn't contain blockchain-specific logic; instead, you register separate modules for each chain you want to support (e.g., Ethereum, TON, Bitcoin). + +## How it works + +The WDK uses a builder pattern, allowing you to chain `.registerWallet()` calls. Each call connects a blockchain-specific manager to your central WDK instance. + +### Parameters + +The `registerWallet` method requires three arguments: + +1. **Symbol**: A unique string identifier for the chain (e.g., `'ethereum'`, `'ton'`). You will use this ID later to retrieve accounts. +2. **Manager Class**: The wallet manager class imported from the specific module (e.g., `WalletManagerEvm`). +3. **Configuration**: An object containing the chain-specific settings (e.g., RPC providers, API keys). + +## Installation + +Install the wallet managers for the blockchains you want to support: + +```bash +npm install @tetherto/wdk-wallet-evm @tetherto/wdk-wallet-ton @tetherto/wdk-wallet-btc +``` + +## Example: Registering Multiple Wallets + +First, import the necessary wallet manager packages: + +{% code title="Import Modules" lineNumbers="true" %} +```typescript +import WalletManagerEvm from '@tetherto/wdk-wallet-evm' +import WalletManagerTon from '@tetherto/wdk-wallet-ton' +import WalletManagerBtc from '@tetherto/wdk-wallet-btc' +``` +{% endcode %} + +Then, instantiate WDK and chain the registration calls: + +{% code title="Register Wallets" lineNumbers="true" %} +```typescript +const wdk = new WDK(seedPhrase) + // 1. Register Ethereum + .registerWallet('ethereum', WalletManagerEvm, { + provider: 'https://eth.drpc.org' + }) + // 2. Register TON + .registerWallet('ton', WalletManagerTon, { + // Get your API key: https://docs.ton.org/ecosystem/api/toncenter/get-api-key + tonClient: { + secretKey: 'YOUR_TON_API_KEY', + url: 'https://toncenter.com/api/v2/jsonRPC' + } + }) + // 3. Register Bitcoin + .registerWallet('bitcoin', WalletManagerBtc, { + provider: 'https://blockstream.info/api' + }) +``` +{% endcode %} + +> [!NOTE] +> **Ethereum Networks:** Choose the RPC endpoint that matches your environment (Mainnet or Testnet). +> * **Mainnet:** `https://eth.drpc.org` +> * **Sepolia (Testnet):** `https://sepolia.drpc.org` + +> [!NOTE] +> **TON Networks:** The endpoint (`url`) you use must match your API key environment. +> * **Mainnet:** `https://toncenter.com/api/v2/jsonRPC` +> * **Testnet:** `https://testnet.toncenter.com/api/v2/jsonRPC` + +## Next steps + +Once your wallets are registered, you can [manage accounts and specific addresses](./account-management.md). From 8dcf6737aa91dc9184e1b6f8d6fb0f8f42a7f202 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Sat, 17 Jan 2026 16:50:05 +0530 Subject: [PATCH 04/27] docs: add core module account management guide --- sdk/core-module/guides/account-management.md | 88 ++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 sdk/core-module/guides/account-management.md diff --git a/sdk/core-module/guides/account-management.md b/sdk/core-module/guides/account-management.md new file mode 100644 index 0000000..8029f0c --- /dev/null +++ b/sdk/core-module/guides/account-management.md @@ -0,0 +1,88 @@ +--- +title: Manage Accounts +description: Learn how to retrieve accounts, view addresses, and check balances. +--- + +# Manage Accounts + +This guide explains how to access accounts from your registered wallets. An "Account" object in WDK is your interface for inspecting balances and sending transactions on a specific blockchain. + +## Retrieve Accounts + +You can retrieve an account using a simple index or a custom derivation path. + +### By Index (Recommended) + +The simplest way to get an account is by its index (starting at `0`). This uses the default derivation path for the specified blockchain. + +{% code title="Get Account by Index" lineNumbers="true" %} +```typescript +// Get the first account (index 0) for Ethereum and TON +const ethAccount = await wdk.getAccount('ethereum', 0) +const tonAccount = await wdk.getAccount('ton', 0) +``` +{% endcode %} + +### By Derivation Path (Advanced) + +If you need a specific hierarchy, you can request an account by its unique derivation path. + +{% code title="Get Account by Path" lineNumbers="true" %} +```typescript +// Custom path for Ethereum +const customEthAccount = await wdk.getAccountByPath('ethereum', "0'/0/1") +``` +{% endcode %} + +> [!NOTE] +> The WDK instance caches accounts. calling `getAccount` twice for the same index returns the same object instance. + +## View Addresses + +Once you have an account object, you can retrieve its public blockchain address. + +{% code title="Get Addresses" lineNumbers="true" %} +```typescript +const ethAddress = await ethAccount.getAddress() +console.log('Ethereum address:', ethAddress) +``` +{% endcode %} + +## Check Balances + +You can check the native token balance of any account (e.g., ETH on Ethereum, TON on TON). + +{% code title="Get Balance" lineNumbers="true" %} +```typescript +try { + const balance = await ethAccount.getBalance() + console.log('Balance:', balance) +} catch (error) { + console.error('Failed to fetch balance:', error) +} +``` +{% endcode %} + +### Multi-Chain Balance Check + +Because WDK offers a unified interface, you can easily iterate through multiple chains to fetch balances. + +{% code title="Check All Balances" lineNumbers="true" %} +```typescript +const chains = ['ethereum', 'ton', 'bitcoin'] + +for (const chain of chains) { + try { + const account = await wdk.getAccount(chain, 0) + const balance = await account.getBalance() + console.log(`${chain} balance:`, balance) + } catch (error) { + console.log(`${chain}: Wallet not registered or unavailable`) + } +} +``` +{% endcode %} + +## Next steps + +Now that you can access your accounts, learn how to [send transactions](./transactions.md). From b30ab97565575745011fa57cf84a3e1101480990 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Sat, 17 Jan 2026 16:50:12 +0530 Subject: [PATCH 05/27] docs: add core module transactions guide --- sdk/core-module/guides/transactions.md | 86 ++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 sdk/core-module/guides/transactions.md diff --git a/sdk/core-module/guides/transactions.md b/sdk/core-module/guides/transactions.md new file mode 100644 index 0000000..a5fe40c --- /dev/null +++ b/sdk/core-module/guides/transactions.md @@ -0,0 +1,86 @@ +--- +title: Send Transactions +description: Learn how to send native tokens on different blockchains. +--- + +# Send Transactions + +This guide explains how to send native tokens (like ETH, TON, or BTC) from your wallet to another address. + +## Sending Native Tokens + +The `sendTransaction` method allows you to transfer value. It accepts a unified configuration object, though specific parameters (like `value` formatting) may vary slightly depending on the chain's requirements. + +### Ethereum Example + +On EVM chains, values are typically expressed in Wei (1 ETH = 10^18 Wei). + +{% code title="Send ETH" lineNumbers="true" %} +```typescript +const ethAccount = await wdk.getAccount('ethereum', 0) + +const result = await ethAccount.sendTransaction({ + to: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F', + value: 1000000000000000n // 0.001 ETH (in Wei) +}) + +console.log('Transaction sent! Hash:', result.hash) +``` +{% endcode %} + +### TON Example + +On TON, values are expressed in Nanotons (1 TON = 10^9 Nanotons). + +{% code title="Send TON" lineNumbers="true" %} +```typescript +// Send TON transaction +const tonAccount = await wdk.getAccount('ton', 0) +const tonResult = await tonAccount.sendTransaction({ + to: 'UQCz5ON7jjK32HnqPushubsHxgsXgeSZDZPvh8P__oqol90r', + value: 1000000000n // 1 TON +}) +console.log('TON transaction:', tonResult.hash) +``` +{% endcode %} + +> [!NOTE] +> **Get Testnet Funds:** To test these transactions without spending real money, verify you are on a testnet and use a faucet: +> * **Ethereum (Sepolia):** [Google Cloud Faucet](https://cloud.google.com/application/web3/faucet/ethereum/sepolia) +> * **TON Testnet:** [Testgiver Bot](https://t.me/testgiver_ton_bot) + +> [!IMPORTANT] +> **BigInt Usage:** Always use `BigInt` (the `n` suffix) for monetary values to avoid precision loss with large numbers. + +## Handling Responses + +The `sendTransaction` method returns a transaction result object. The most important field is typically `hash`, which represents the transaction ID on the blockchain. You can use this hash to track the status of your payment on a block explorer. + +## Multi-Chain Transactions + +You can orchestrate payments across different chains in a single function by acting on multiple account objects sequentially. + +{% code title="Multi-Chain Payment" lineNumbers="true" %} +```typescript +async function sendCrossChainPayments(wdk) { + const ethAccount = await wdk.getAccount('ethereum', 0) + const tonAccount = await wdk.getAccount('ton', 0) + + // 1. Send ETH + await ethAccount.sendTransaction({ + to: '0x...', + value: 1000000000000000000n + }) + + // 2. Send TON + await tonAccount.sendTransaction({ + to: 'EQ...', + value: 1000000000n + }) +} +``` +{% endcode %} + +## Next steps + +For more complex interactions like swapping tokens or bridging assets, learn how to [integrate protocols](./protocol-integration.md). From 67fa9c07eb9c0ddad21b3ebed5790773aeec26c2 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Sat, 17 Jan 2026 16:50:18 +0530 Subject: [PATCH 06/27] docs: add core module protocol integration guide --- .../guides/protocol-integration.md | 113 ++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 sdk/core-module/guides/protocol-integration.md diff --git a/sdk/core-module/guides/protocol-integration.md b/sdk/core-module/guides/protocol-integration.md new file mode 100644 index 0000000..2070d62 --- /dev/null +++ b/sdk/core-module/guides/protocol-integration.md @@ -0,0 +1,113 @@ +--- +title: Integrate Protocols +description: Learn how to register and use protocols for Swapping, Bridging, and Lending. +--- + +# Integrate Protocols + +The WDK Core module supports registering external protocols. This allows you to extend the basic wallet functionality with advanced features like token swapping, cross-chain bridging, and lending, all through a unified interface. + +## Register Protocols + +You can register protocols in two ways: globally (for all new accounts) or locally (for a specific existing account). + +### Global Registration (Recommended) + +Global registration ensures that every account you retrieve already has the protocol ready to use. This is done by chaining `.registerProtocol()` on the WDK instance. + +**1. Install Protocol Modules** + +> [!WARNING] +> **TODO:** The `@tetherto/wdk-protocol-bridge-usdt0-ton` package is currently unavailable in the registry. This section is pending confirmation from the development team. + +```bash +npm install @tetherto/wdk-protocol-swap-velora-evm +# npm install @tetherto/wdk-protocol-bridge-usdt0-ton (Pending release) +``` + +**2. Register in Code** + +{% code title="Global Registration" lineNumbers="true" %} +```typescript +import veloraProtocolEvm from '@tetherto/wdk-protocol-swap-velora-evm' +// import Usdt0ProtocolTon from '@tetherto/wdk-protocol-bridge-usdt0-ton' // TODO: Package unavailable + +// Register protocols for specific chains +const wdk = new WDK(seedPhrase) + .registerWallet('ethereum', WalletManagerEvm, ethConfig) + .registerWallet('ton', WalletManagerTon, tonConfig) + + // Register Velora Swap for Ethereum + .registerProtocol('ethereum', 'velora', veloraProtocolEvm, { + apiKey: 'YOUR_API_KEY' + }) + + /* TODO: Pending package release + // Register USDT0 Bridge for TON + .registerProtocol('ton', 'usdt0', Usdt0ProtocolTon, { + tonApiKey: 'YOUR_API_KEY' + }) + */ +``` +{% endcode %} + +### Account-Level Registration + +If you only need a protocol for a single session, you can register it directly on an account object. + +{% code title="Account Registration" lineNumbers="true" %} +```typescript +const account = await wdk.getAccount('ethereum', 0) + +// Register only for this account instance +account.registerProtocol('velora', veloraProtocolEvm, config) +``` +{% endcode %} + +## Use Protocols + +Once registered, you can access the protocol instance using the specific getter methods: `getSwapProtocol`, `getBridgeProtocol`, or `getLendingProtocol`. + +### Swapping Tokens + +Use `getSwapProtocol` to access registered swap services. + +{% code title="Swap Tokens" lineNumbers="true" %} +```typescript +const ethAccount = await wdk.getAccount('ethereum', 0) +const velora = ethAccount.getSwapProtocol('velora') + +const result = await velora.swap({ + tokenIn: '0x...', // Address of token to sell + tokenOut: '0x...', // Address of token to buy + tokenInAmount: 1000000n // Amount to swap +}) +``` +{% endcode %} + +### Bridging Assets + +Use `getBridgeProtocol` to access cross-chain bridges. + +{% code title="Bridge Assets" lineNumbers="true" %} +```typescript +/* TODO: Pending package release +const tonAccount = await wdk.getAccount('ton', 0) +const usdt0 = tonAccount.getBridgeProtocol('usdt0') + +const result = await usdt0.bridge({ + targetChain: 'ethereum', + recipient: '0x...', // Ethereum address + token: 'TON_TOKEN_ADDRESS', + amount: 1000000n +}) +*/ +``` +{% endcode %} + +> [!NOTE] +> **Protocol Availability:** If you try to access a protocol that hasn't been registered (e.g., `getSwapProtocol('uniswap')`), the SDK will throw an error. always ensure registration matches the ID you request. + +## Next steps + +Learn how to [configure middleware](./middleware.md) to add logging or failover protection to your wallet interactions. From 16e1aa2179da411ad737bcbe8470390df60541b7 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Sat, 17 Jan 2026 16:50:21 +0530 Subject: [PATCH 07/27] docs: add core module middleware guide --- sdk/core-module/guides/middleware.md | 63 ++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 sdk/core-module/guides/middleware.md diff --git a/sdk/core-module/guides/middleware.md b/sdk/core-module/guides/middleware.md new file mode 100644 index 0000000..925dee0 --- /dev/null +++ b/sdk/core-module/guides/middleware.md @@ -0,0 +1,63 @@ +--- +title: Configure Middleware +description: Learn how to intercept and enhance wallet operations with middleware. +--- + +# Configure Middleware + +Middleware allows you to intercept wallet operations. You can use this to add logging, implement retry logic, or handle failovers for RPC providers. + +## Register Middleware + +Reference a specific chain when registering middleware. The middleware function runs every time an account is instantiated or an operation is performed, depending on the implementation. + +### Example: Logging + +This simple middleware logs a message whenever a new account is accessed. + +{% code title="Logging Middleware" lineNumbers="true" %} +```typescript +wdk.registerMiddleware('ethereum', async (account) => { + const address = await account.getAddress() + console.log('Accessed Ethereum account:', address) + + // You can also attach custom properties or wrap methods here +}) +``` +{% endcode %} + +## Failover Protection + +> [!WARNING] +> **TODO:** The `@tetherto/wdk-wrapper-failover-cascade` package is currently unavailable in the registry. The section below is pending confirmation from the development team. + +*(This feature is currently pending package release)* + + + +## Next steps + +Learn about [error handling and best practices](./error-handling.md) to ensure your application is robust and secure. From 7e52e3ee8e25c6d7ee93c6cf4abdeadcfeb197d1 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Sat, 17 Jan 2026 16:50:23 +0530 Subject: [PATCH 08/27] docs: add core module error handling guide --- sdk/core-module/guides/error-handling.md | 59 ++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 sdk/core-module/guides/error-handling.md diff --git a/sdk/core-module/guides/error-handling.md b/sdk/core-module/guides/error-handling.md new file mode 100644 index 0000000..e7352b6 --- /dev/null +++ b/sdk/core-module/guides/error-handling.md @@ -0,0 +1,59 @@ +--- +title: Error Handling & Best Practices +description: Learn how to handle common errors and manage clean-up. +--- + +# Error Handling & Best Practices + +This guide covers recommended patterns for error handling and security when using the WDK. + +## Handling Common Errors + +When interacting with multiple chains and protocols, various runtime issues may occur. + +### Missing Registration + +The most common error is attempting to access a wallet or protocol that hasn't been registered. + +{% code title="Check Registration Pattern" lineNumbers="true" %} +```typescript +try { + // This will throw if 'tron' was never registered via .registerWallet() + const tronAccount = await wdk.getAccount('tron', 0) +} catch (error) { + console.error('Tron wallet not available:', error.message) +} +``` +{% endcode %} + +Always use `try/catch` blocks when initializing sessions or accessing dynamic features. + +## Memory Management + +For security, you should clear sensitive data from memory when a session is complete. The WDK provided a `.dispose()` method for this purpose. + +### Disposing the Instance + +Calling `dispose()` clears the seed phrase and private keys derived in memory. + +{% code title="Dispose WDK" lineNumbers="true" %} +```typescript +function endSession(wdk) { + // 1. Clean up sensitive data + wdk.dispose() + + // 2. Modify app state to reflect logged-out status + // ... + + console.log('Session ended, wallet data cleared.') +} +``` +{% endcode %} + +> [!WARNING] +> **After Disposal:** Once disposed, any attempt to use the `wdk` instance or its derived accounts will result in an error. You must inspect a new instance to resume operations. + +## Security Best Practices + +* **Environment Variables:** Never hardcode API keys or seed phrases in your source code. Use environment variables (e.g., `process.env.TON_API_KEY`). +* **Secure Storage:** If persisting a session, never store the raw seed phrase in local storage. Use secure operating system storage (like Keychain on macOS or Keystore on Android). From a108eca2b66612a24676f86429c80f0777a2ba8b Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Sat, 17 Jan 2026 16:50:25 +0530 Subject: [PATCH 09/27] docs: refactor core module usage page to index --- sdk/core-module/usage.md | 504 +-------------------------------------- 1 file changed, 12 insertions(+), 492 deletions(-) diff --git a/sdk/core-module/usage.md b/sdk/core-module/usage.md index 3ec3395..224eba1 100644 --- a/sdk/core-module/usage.md +++ b/sdk/core-module/usage.md @@ -1,499 +1,19 @@ --- title: Usage -description: Learn how to use the WDK Core module -icon: book-open -layout: - width: default - title: - visible: true - description: - visible: true - tableOfContents: - visible: true - outline: - visible: true - pagination: - visible: false - metadata: - visible: false +description: Learn how to use the WDK Core module. --- -This package serves as the main entry point and orchestrator for all WDK wallet modules, allowing you to register and manage different blockchain wallets and protocols through a single interface. +# Usage -## Installation +The WDK Core module is the central orchestrator for your wallet interactions. -Install the `@tetherto/wdk-core` package: +Use the guides below to get started: -```bash -npm install @tetherto/wdk -``` - -*** - -## Basic Usage - -### Importing WDK Core - -{% code title="Import WDK Core" lineNumbers="true" %} -```typescript -import WDK from '@tetherto/wdk' -``` -{% endcode %} - - -### Creating a WDK Instance - -{% code title="Create WDK Instance" lineNumbers="true" %} -```typescript -// Generate a random seed phrase -const seedPhrase = WDK.getRandomSeedPhrase() - -// Create WDK instance -const wdk = new WDK(seedPhrase) - -// Or use your own seed phrase -const wdk = new WDK('your existing seed phrase here...') -``` -{% endcode %} - -*** - -## Wallet Registration - -### Registering Wallets - -{% code title="Register Wallets" lineNumbers="true" %} -```typescript -import WalletManagerEvm from '@tetherto/wdk-wallet-evm' -import WalletManagerTon from '@tetherto/wdk-wallet-ton' -import WalletManagerBtc from '@tetherto/wdk-wallet-btc' - -// Register wallets for different blockchains -const wdk = new WDK(seedPhrase) - .registerWallet('ethereum', WalletManagerEvm, { - provider: 'https://eth.drpc.org' - }) - .registerWallet('ton', WalletManagerTon, { - tonApiKey: 'YOUR_TON_API_KEY', - tonApiEndpoint: 'https://tonapi.io' - }) - .registerWallet('bitcoin', WalletManagerBtc, { - provider: 'https://blockstream.info/api' - }) -``` -{% endcode %} - -*** - -## Account Management - -### Getting Accounts - -{% code title="Get Accounts" lineNumbers="true" %} -```typescript -// Get account by blockchain and index -const ethAccount = await wdk.getAccount('ethereum', 0) -const tonAccount = await wdk.getAccount('ton', 0) - -// Get account by derivation path -const customEthAccount = await wdk.getAccountByPath('ethereum', "0'/0/1") -const customTonAccount = await wdk.getAccountByPath('ton', "1'/2/3") - -// Get addresses -const ethAddress = await ethAccount.getAddress() -const tonAddress = await tonAccount.getAddress() -console.log('Ethereum address:', ethAddress) -console.log('TON address:', tonAddress) -``` -{% endcode %} - -### Multi-Chain Account Management - -{% code title="Multi-Chain Account Management" lineNumbers="true" %} -```typescript -// Get accounts for different chains -const accounts = { - ethereum: await wdk.getAccount('ethereum', 0), - arbitrum: await wdk.getAccount('arbitrum', 0), - ton: await wdk.getAccount('ton', 0), - bitcoin: await wdk.getAccount('bitcoin', 0) -} - -// Get all addresses -for (const [chain, account] of Object.entries(accounts)) { - const address = await account.getAddress() - console.log(`${chain} address:`, address) -} -``` -{% endcode %} - -*** - -## Balance Operations - -### Cross-Chain Balance Checking - -{% code title="Cross-Chain Balance Checking" lineNumbers="true" %} -```typescript -async function checkAllBalances(wdk) { - const chains = ['ethereum', 'arbitrum', 'ton', 'bitcoin'] - const balances = {} - - for (const chain of chains) { - try { - const account = await wdk.getAccount(chain, 0) - const balance = await account.getBalance() - balances[chain] = balance - console.log(`${chain} balance:`, balance) - } catch (error) { - console.log(`${chain}: Wallet not registered`) - } - } - - return balances -} - -// Usage -const balances = await checkAllBalances(wdk) -``` -{% endcode %} - -*** - -## Transaction Operations - -### Sending Transactions - -{% code title="Sending Transactions" lineNumbers="true" %} -```typescript -// Send Ethereum transaction -const ethAccount = await wdk.getAccount('ethereum', 0) -const ethResult = await ethAccount.sendTransaction({ - to: '0x...', - value: 1000000000000000000n // 1 ETH -}) -console.log('Ethereum transaction:', ethResult.hash) - -// Send TON transaction -const tonAccount = await wdk.getAccount('ton', 0) -const tonResult = await tonAccount.sendTransaction({ - to: 'EQ...', - value: 1000000000n // 1 TON -}) -console.log('TON transaction:', tonResult.hash) -``` -{% endcode %} - -### Multi-Chain Transaction Function - -{% code title="Multi-Chain Transaction Function" lineNumbers="true" %} -```typescript -async function sendMultiChainTransactions(wdk) { - // Ethereum transaction - const ethAccount = await wdk.getAccount('ethereum', 0) - const ethResult = await ethAccount.sendTransaction({ - to: '0x...', - value: 1000000000000000000n // 1 ETH - }) - console.log('Ethereum transaction:', ethResult.hash) - - // TON transaction - const tonAccount = await wdk.getAccount('ton', 0) - const tonResult = await tonAccount.sendTransaction({ - to: 'EQ...', - value: 1000000000n // 1 TON - }) - console.log('TON transaction:', tonResult.hash) -} -``` -{% endcode %} - -*** - -## Protocol Integration - -### Registering Protocols - -{% code title="Registering Protocols" lineNumbers="true" %} -```typescript -import veloraProtocolEvm from '@tetherto/wdk-protocol-swap-velora-evm' -import Usdt0ProtocolTon from '@tetherto/wdk-protocol-bridge-usdt0-ton' - -// Register protocols globally -const wdk = new WDK(seedPhrase) - .registerWallet('ethereum', WalletManagerEvm, ethereumWalletConfig) - .registerWallet('ton', WalletManagerTon, tonWalletConfig) - .registerProtocol('ethereum', 'velora', veloraProtocolEvm, { - apiKey: 'YOUR_velora_API_KEY' - }) - .registerProtocol('ton', 'usdt0', Usdt0ProtocolTon, { - tonApiKey: 'YOUR_TON_API_KEY' - }) -``` -{% endcode %} - -### Using Protocols - -{% code title="Using Protocols" lineNumbers="true" %} -```typescript -// Get accounts with protocol support -const ethAccount = await wdk.getAccount('ethereum', 0) -const tonAccount = await wdk.getAccount('ton', 0) - -// Use swap protocol -const velora = ethAccount.getSwapProtocol('velora') -const swapResult = await velora.swap({ - tokenIn: '0x...', - tokenOut: '0x...', - tokenInAmount: 1000000n -}) - -// Use bridge protocol -const usdt0 = tonAccount.getBridgeProtocol('usdt0') -const bridgeResult = await usdt0.bridge({ - targetChain: 'ethereum', - recipient: '0x...', - token: 'TON_TOKEN_ADDRESS', - amount: 1000000n -}) -``` -{% endcode %} - -### Multiple Protocol Types - -{% code title="Multiple Protocol Types" lineNumbers="true" %} -```typescript -// Register different protocol types -const account = await wdk.getAccount('ethereum', 0) - -// Swap protocol -account.registerProtocol('velora', veloraProtocolEvm, veloraConfig) -const velora = account.getSwapProtocol('velora') - -// Bridge protocol -account.registerProtocol('usdt0', Usdt0ProtocolEvm, usdt0Config) -const usdt0 = account.getBridgeProtocol('usdt0') - -// Lending protocol -account.registerProtocol('aave', AaveProtocolEvm, aaveConfig) -const aave = account.getLendingProtocol('aave') -``` -{% endcode %} - -*** - -## Middleware - -### Logging Middleware - -{% code title="Logging Middleware" lineNumbers="true" %} -```typescript -// Register logging middleware -wdk.registerMiddleware('ethereum', async (account) => { - const address = await account.getAddress() - console.log('New Ethereum account created:', address) -}) - -wdk.registerMiddleware('ton', async (account) => { - const address = await account.getAddress() - console.log('New TON account created:', address) -}) - -// This will trigger the middleware -const account = await wdk.getAccount('ethereum', 0) -``` -{% endcode %} - -### Failover Middleware - -{% code title="Failover Middleware" lineNumbers="true" %} -```typescript -import { getFailoverCascadeMiddleware } from '@tetherto/wdk-wrapper-failover-cascade' - -// Register failover middleware -wdk.registerMiddleware('ethereum', getFailoverCascadeMiddleware({ - retries: 3, - delay: 1000, - fallbackProviders: [ - 'https://backup-rpc-1.com', - 'https://backup-rpc-2.com' - ] -})) - -// Transactions will automatically retry with fallback providers -const account = await wdk.getAccount('ethereum', 0) -const result = await account.sendTransaction(tx) // Will retry on failure -``` -{% endcode %} - -*** - -## Complete Examples - -### Multi-Chain Wallet Setup - -{% code title="Multi-Chain Wallet Setup" lineNumbers="true" %} -```typescript -import WDK from '@tetherto/wdk' -import WalletManagerEvm from '@tetherto/wdk-wallet-evm' -import WalletManagerTon from '@tetherto/wdk-wallet-ton' -import veloraProtocolEvm from '@tetherto/wdk-protocol-swap-velora-evm' - -async function setupMultiChainWallet() { - // Generate or use existing seed phrase - const seedPhrase = WDK.getRandomSeedPhrase() - - // Initialize WDK Manager - const wdk = new WDK(seedPhrase) - .registerWallet('ethereum', WalletManagerEvm, { - provider: 'https://eth.drpc.org' - }) - .registerWallet('ton', WalletManagerTon, { - tonApiKey: 'YOUR_TON_API_KEY' - }) - .registerProtocol('ethereum', 'velora', veloraProtocolEvm, { - apiKey: 'YOUR_velora_API_KEY' - }) - - // Get accounts - const ethAccount = await wdk.getAccount('ethereum', 0) - const tonAccount = await wdk.getAccount('ton', 0) - - // Get addresses - const ethAddress = await ethAccount.getAddress() - const tonAddress = await tonAccount.getAddress() - - console.log('Ethereum address:', ethAddress) - console.log('TON address:', tonAddress) - - return { wdk, ethAccount, tonAccount } -} -``` -{% endcode %} - -*** - -## Error Handling - -### Handling Common Errors - -{% code title="Handling Common Errors" lineNumbers="true" %} -```typescript -async function handleErrors(wdk) { - try { - // This will throw if no wallet registered for 'tron' - const tronAccount = await wdk.getAccount('tron', 0) - } catch (error) { - console.error('Tron wallet not registered:', error.message) - } - - try { - const ethAccount = await wdk.getAccount('ethereum', 0) - - // This will throw if no swap protocol registered - const uniswap = ethAccount.getSwapProtocol('uniswap') - } catch (error) { - console.error('Uniswap protocol not registered:', error.message) - } -} -``` -{% endcode %} - -### Memory Management - -{% code title="Memory Management" lineNumbers="true" %} -```typescript -async function cleanupExample(wdk) { - // Use the WDK Manager - const ethAccount = await wdk.getAccount('ethereum', 0) - const tonAccount = await wdk.getAccount('ton', 0) - - // Perform operations - const ethAddress = await ethAccount.getAddress() - const tonAddress = await tonAccount.getAddress() - - // Clean up sensitive data - wdk.dispose() - - // After dispose, accounts are no longer usable - // This will throw an error - try { - await ethAccount.getAddress() - } catch (error) { - console.log('Account disposed, cannot access private keys') - } -} -``` -{% endcode %} - -*** - -## Next Steps - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- :code: - - WDK Core Configuration - Get started with WDK's configuration - WDK Core Configuration -
- :code: - - WDK Core API - Get started with WDK's API - WDK Core API -
- :code: - - Wallet Modules - Explore blockchain-specific wallet modules - WDK Wallet Modules -
- :code: - - Bridge Modules - Cross-chain USD₮0 bridges - Bridge Modules -
- -*** - -## Need Help? - -{% include "../../.gitbook/includes/support-cards.md" %} +* **[Installation](./guides/installation.md)**: Add the package to your project. +* **[Instantiation](./guides/instantiation.md)**: Initialize the WDK with a seed phrase. +* **[Register Wallets](./guides/wallet-registration.md)**: Connect specific blockchains (Ethereum, TON, etc.). +* **[Manage Accounts](./guides/account-management.md)**: Retrieve accounts and check balances. +* **[Send Transactions](./guides/transactions.md)**: Transfer native tokens. +* **[Integrate Protocols](./guides/protocol-integration.md)**: Use Swap, Bridge, and Lending protocols. +* **[Configure Middleware](./guides/middleware.md)**: Add logging and failover protection. +* **[Error Handling](./guides/error-handling.md)**: Best practices for security and stability. From b0225fe7b8f8784e522b44791409060934e68e24 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Sat, 17 Jan 2026 16:50:28 +0530 Subject: [PATCH 10/27] docs: update summary navigation for core module --- SUMMARY.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/SUMMARY.md b/SUMMARY.md index 19489db..7977162 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -20,6 +20,14 @@ * [All Modules](sdk/all-modules.md) * [Core Module](sdk/core-module/README.md) * [Usage](sdk/core-module/usage.md) + * [Installation](sdk/core-module/guides/installation.md) + * [Instantiation](sdk/core-module/guides/instantiation.md) + * [Register Wallets](sdk/core-module/guides/wallet-registration.md) + * [Account Management](sdk/core-module/guides/account-management.md) + * [Send Transactions](sdk/core-module/guides/transactions.md) + * [Protocol Integration](sdk/core-module/guides/protocol-integration.md) + * [Middleware](sdk/core-module/guides/middleware.md) + * [Error Handling](sdk/core-module/guides/error-handling.md) * [Configuration](sdk/core-module/configuration.md) * [API Reference](sdk/core-module/api-reference.md) * [Wallet Modules](sdk/wallet-modules/README.md) From 3f106fb8fd59e78234f9be6f3a1934448018f74c Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Sat, 17 Jan 2026 16:50:33 +0530 Subject: [PATCH 11/27] docs: fix ton configuration structure in config reference --- sdk/core-module/configuration.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sdk/core-module/configuration.md b/sdk/core-module/configuration.md index 4044091..3e5cb39 100644 --- a/sdk/core-module/configuration.md +++ b/sdk/core-module/configuration.md @@ -96,10 +96,10 @@ wdk.registerWallet('ethereum', WalletManagerEvm, ethereumWalletConfig) {% code title="TON WDK Wallet Configuration" lineNumbers="true" %} ```javascript const tonWalletConfig = { - tonApiKey: 'YOUR_TON_API_KEY', - tonApiEndpoint: 'https://tonapi.io', - tonCenterApiKey: 'YOUR_TON_CENTER_API_KEY', - tonCenterEndpoint: 'https://toncenter.com' + tonClient: { + secretKey: 'YOUR_TON_API_KEY', + url: 'https://toncenter.com/api/v2/jsonRPC' + } } wdk.registerWallet('ton', WalletManagerTon, tonWalletConfig) From e72c1205d02284c8bee36949c9dad135ba64c65d Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Sat, 17 Jan 2026 21:40:07 +0530 Subject: [PATCH 12/27] docs: standardize frontmatter headers for core module guides --- sdk/core-module/guides/account-management.md | 16 +++++++++++++++- sdk/core-module/guides/error-handling.md | 18 ++++++++++++++++-- sdk/core-module/guides/installation.md | 14 ++++++++++++++ sdk/core-module/guides/instantiation.md | 16 +++++++++++++++- sdk/core-module/guides/middleware.md | 14 ++++++++++++++ sdk/core-module/guides/protocol-integration.md | 16 +++++++++++++++- sdk/core-module/guides/transactions.md | 14 ++++++++++++++ sdk/core-module/guides/wallet-registration.md | 14 ++++++++++++++ sdk/core-module/usage.md | 18 ++++++++++++++++-- 9 files changed, 133 insertions(+), 7 deletions(-) diff --git a/sdk/core-module/guides/account-management.md b/sdk/core-module/guides/account-management.md index 8029f0c..ca036a6 100644 --- a/sdk/core-module/guides/account-management.md +++ b/sdk/core-module/guides/account-management.md @@ -1,6 +1,20 @@ --- title: Manage Accounts -description: Learn how to retrieve accounts, view addresses, and check balances. +description: Learn how to work with accounts and addresses. +layout: + width: default + title: + visible: true + description: + visible: true + tableOfContents: + visible: true + outline: + visible: true + pagination: + visible: false + metadata: + visible: false --- # Manage Accounts diff --git a/sdk/core-module/guides/error-handling.md b/sdk/core-module/guides/error-handling.md index e7352b6..0414562 100644 --- a/sdk/core-module/guides/error-handling.md +++ b/sdk/core-module/guides/error-handling.md @@ -1,6 +1,20 @@ --- -title: Error Handling & Best Practices -description: Learn how to handle common errors and manage clean-up. +title: Error Handling +description: Learn about common errors and best practices. +layout: + width: default + title: + visible: true + description: + visible: true + tableOfContents: + visible: true + outline: + visible: true + pagination: + visible: false + metadata: + visible: false --- # Error Handling & Best Practices diff --git a/sdk/core-module/guides/installation.md b/sdk/core-module/guides/installation.md index cf6d5d8..fce6fe0 100644 --- a/sdk/core-module/guides/installation.md +++ b/sdk/core-module/guides/installation.md @@ -1,6 +1,20 @@ --- title: Install WDK Core description: Learn how to install and set up the WDK Core module. +layout: + width: default + title: + visible: true + description: + visible: true + tableOfContents: + visible: true + outline: + visible: true + pagination: + visible: false + metadata: + visible: false --- # Install WDK Core diff --git a/sdk/core-module/guides/instantiation.md b/sdk/core-module/guides/instantiation.md index b7352c7..f0b2ecc 100644 --- a/sdk/core-module/guides/instantiation.md +++ b/sdk/core-module/guides/instantiation.md @@ -1,6 +1,20 @@ --- title: Instantiate WDK -description: Learn how to import and initialize the WDK Core module. +description: Learn how to create a new WDK instance. +layout: + width: default + title: + visible: true + description: + visible: true + tableOfContents: + visible: true + outline: + visible: true + pagination: + visible: false + metadata: + visible: false --- # Instantiate WDK diff --git a/sdk/core-module/guides/middleware.md b/sdk/core-module/guides/middleware.md index 925dee0..1e4d757 100644 --- a/sdk/core-module/guides/middleware.md +++ b/sdk/core-module/guides/middleware.md @@ -1,6 +1,20 @@ --- title: Configure Middleware description: Learn how to intercept and enhance wallet operations with middleware. +layout: + width: default + title: + visible: true + description: + visible: true + tableOfContents: + visible: true + outline: + visible: true + pagination: + visible: false + metadata: + visible: false --- # Configure Middleware diff --git a/sdk/core-module/guides/protocol-integration.md b/sdk/core-module/guides/protocol-integration.md index 2070d62..6687b70 100644 --- a/sdk/core-module/guides/protocol-integration.md +++ b/sdk/core-module/guides/protocol-integration.md @@ -1,6 +1,20 @@ --- title: Integrate Protocols -description: Learn how to register and use protocols for Swapping, Bridging, and Lending. +description: Learn how to use Swaps, Bridges, and Lending protocols. +layout: + width: default + title: + visible: true + description: + visible: true + tableOfContents: + visible: true + outline: + visible: true + pagination: + visible: false + metadata: + visible: false --- # Integrate Protocols diff --git a/sdk/core-module/guides/transactions.md b/sdk/core-module/guides/transactions.md index a5fe40c..69fec59 100644 --- a/sdk/core-module/guides/transactions.md +++ b/sdk/core-module/guides/transactions.md @@ -1,6 +1,20 @@ --- title: Send Transactions description: Learn how to send native tokens on different blockchains. +layout: + width: default + title: + visible: true + description: + visible: true + tableOfContents: + visible: true + outline: + visible: true + pagination: + visible: false + metadata: + visible: false --- # Send Transactions diff --git a/sdk/core-module/guides/wallet-registration.md b/sdk/core-module/guides/wallet-registration.md index 9d59a43..ada1d64 100644 --- a/sdk/core-module/guides/wallet-registration.md +++ b/sdk/core-module/guides/wallet-registration.md @@ -1,6 +1,20 @@ --- title: Register Wallets description: Learn how to register wallet modules for different blockchains. +layout: + width: default + title: + visible: true + description: + visible: true + tableOfContents: + visible: true + outline: + visible: true + pagination: + visible: false + metadata: + visible: false --- # Register Wallets diff --git a/sdk/core-module/usage.md b/sdk/core-module/usage.md index 224eba1..31f386a 100644 --- a/sdk/core-module/usage.md +++ b/sdk/core-module/usage.md @@ -1,6 +1,20 @@ --- -title: Usage -description: Learn how to use the WDK Core module. +title: WDK Core Usage +description: Guide to using the WDK Core module. +layout: + width: default + title: + visible: true + description: + visible: true + tableOfContents: + visible: true + outline: + visible: true + pagination: + visible: false + metadata: + visible: false --- # Usage From ce365490dae18bd476cef0f5a038c0a21d046806 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Tue, 20 Jan 2026 08:55:37 +0530 Subject: [PATCH 13/27] docs: finalize middleware failover implementation --- sdk/core-module/configuration.md | 22 ------------- sdk/core-module/guides/middleware.md | 46 ++++++++++++++++------------ 2 files changed, 27 insertions(+), 41 deletions(-) diff --git a/sdk/core-module/configuration.md b/sdk/core-module/configuration.md index 3e5cb39..d142242 100644 --- a/sdk/core-module/configuration.md +++ b/sdk/core-module/configuration.md @@ -58,15 +58,11 @@ const wdk = new WDK(seedPhrase) {% code title="Register WDK Protocol" lineNumbers="true" %} ```javascript import veloraProtocolEvm from '@tetherto/wdk-protocol-swap-velora-evm' -import Usdt0ProtocolTon from '@tetherto/wdk-protocol-bridge-usdt0-ton' const wdk = new WDK(seedPhrase) .registerProtocol('ethereum', 'velora', veloraProtocolEvm, { apiKey: 'YOUR_velora_API_KEY' }) - .registerProtocol('ton', 'usdt0', Usdt0ProtocolTon, { - tonApiKey: 'YOUR_TON_API_KEY' - }) ``` {% endcode %} @@ -125,18 +121,6 @@ wdk.registerProtocol('ethereum', 'velora', veloraProtocolEvm, veloraProtocolConf {% endcode %} -#### Bridge Protocol Configuration - -{% code title="Bridge WDK Protocol Configuration" lineNumbers="true" %} -```javascript -const usdt0ProtocolConfig = { - tonApiKey: 'YOUR_TON_API_KEY', - ethereumRpcUrl: 'https://eth.drpc.org' -} - -wdk.registerProtocol('ton', 'usdt0', Usdt0ProtocolTon, usdt0ProtocolConfig) -``` -{% endcode %} ### Middleware Configuration @@ -150,12 +134,6 @@ wdk.registerMiddleware('ethereum', async (account) => { console.log('New account created:', await account.getAddress()) }) -// Failover cascade middleware -import { getFailoverCascadeMiddleware } from '@tetherto/wdk-wrapper-failover-cascade' - -wdk.registerMiddleware('ethereum', getFailoverCascadeMiddleware(fallbackOptions)) -``` -{% endcode %} ## Environment Variables diff --git a/sdk/core-module/guides/middleware.md b/sdk/core-module/guides/middleware.md index 1e4d757..60bbff4 100644 --- a/sdk/core-module/guides/middleware.md +++ b/sdk/core-module/guides/middleware.md @@ -42,35 +42,43 @@ wdk.registerMiddleware('ethereum', async (account) => { ## Failover Protection -> [!WARNING] -> **TODO:** The `@tetherto/wdk-wrapper-failover-cascade` package is currently unavailable in the registry. The section below is pending confirmation from the development team. -*(This feature is currently pending package release)* +### Using Provider Failover - ## Next steps From 484107c8bc53439db180e725584c443c4cb4d8b8 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Tue, 20 Jan 2026 08:57:01 +0530 Subject: [PATCH 14/27] docs: remove usage of unpublished ton bridge module --- .../guides/protocol-integration.md | 30 ++++++++----------- 1 file changed, 12 insertions(+), 18 deletions(-) diff --git a/sdk/core-module/guides/protocol-integration.md b/sdk/core-module/guides/protocol-integration.md index 6687b70..63731b4 100644 --- a/sdk/core-module/guides/protocol-integration.md +++ b/sdk/core-module/guides/protocol-integration.md @@ -31,12 +31,9 @@ Global registration ensures that every account you retrieve already has the prot **1. Install Protocol Modules** -> [!WARNING] -> **TODO:** The `@tetherto/wdk-protocol-bridge-usdt0-ton` package is currently unavailable in the registry. This section is pending confirmation from the development team. - ```bash npm install @tetherto/wdk-protocol-swap-velora-evm -# npm install @tetherto/wdk-protocol-bridge-usdt0-ton (Pending release) +npm install @tetherto/wdk-protocol-bridge-usdt0-evm ``` **2. Register in Code** @@ -44,24 +41,21 @@ npm install @tetherto/wdk-protocol-swap-velora-evm {% code title="Global Registration" lineNumbers="true" %} ```typescript import veloraProtocolEvm from '@tetherto/wdk-protocol-swap-velora-evm' -// import Usdt0ProtocolTon from '@tetherto/wdk-protocol-bridge-usdt0-ton' // TODO: Package unavailable +import usdt0ProtocolEvm from '@tetherto/wdk-protocol-bridge-usdt0-evm' // Register protocols for specific chains const wdk = new WDK(seedPhrase) .registerWallet('ethereum', WalletManagerEvm, ethConfig) - .registerWallet('ton', WalletManagerTon, tonConfig) // Register Velora Swap for Ethereum .registerProtocol('ethereum', 'velora', veloraProtocolEvm, { apiKey: 'YOUR_API_KEY' }) - /* TODO: Pending package release - // Register USDT0 Bridge for TON - .registerProtocol('ton', 'usdt0', Usdt0ProtocolTon, { - tonApiKey: 'YOUR_API_KEY' + // Register USDT0 Bridge for Ethereum + .registerProtocol('ethereum', 'usdt0', usdt0ProtocolEvm, { + ethereumRpcUrl: 'https://eth.drpc.org' // Configuration depends on the module }) - */ ``` {% endcode %} @@ -105,17 +99,17 @@ Use `getBridgeProtocol` to access cross-chain bridges. {% code title="Bridge Assets" lineNumbers="true" %} ```typescript -/* TODO: Pending package release -const tonAccount = await wdk.getAccount('ton', 0) -const usdt0 = tonAccount.getBridgeProtocol('usdt0') +```typescript +const ethAccount = await wdk.getAccount('ethereum', 0) +const usdt0 = ethAccount.getBridgeProtocol('usdt0') const result = await usdt0.bridge({ - targetChain: 'ethereum', - recipient: '0x...', // Ethereum address - token: 'TON_TOKEN_ADDRESS', + targetChain: 'ton', + recipient: 'UQBla...', // TON address + token: '0x...', // ERC20 Token Address amount: 1000000n }) -*/ +``` ``` {% endcode %} From 766cb1872d0a1671c273d061591958c48bacfd6a Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Tue, 20 Jan 2026 12:24:51 +0530 Subject: [PATCH 15/27] docs: fix gitbook callout syntax and formatting issues --- sdk/core-module/guides/account-management.md | 13 ++++++++++-- sdk/core-module/guides/error-handling.md | 5 +++-- sdk/core-module/guides/instantiation.md | 5 +++-- sdk/core-module/guides/middleware.md | 3 --- .../guides/protocol-integration.md | 7 +++---- sdk/core-module/guides/transactions.md | 16 ++++++++------- sdk/core-module/guides/wallet-registration.md | 20 ++++++++++--------- 7 files changed, 40 insertions(+), 29 deletions(-) diff --git a/sdk/core-module/guides/account-management.md b/sdk/core-module/guides/account-management.md index ca036a6..f84622a 100644 --- a/sdk/core-module/guides/account-management.md +++ b/sdk/core-module/guides/account-management.md @@ -48,8 +48,17 @@ const customEthAccount = await wdk.getAccountByPath('ethereum', "0'/0/1") ``` {% endcode %} -> [!NOTE] -> The WDK instance caches accounts. calling `getAccount` twice for the same index returns the same object instance. +{% hint style="info" %} +The WDK instance caches accounts. calling `getAccount` twice for the same index returns the same object instance. +{% endhint %} + +{% hint style="warning" %} +**Network Mismatch Warning** +Ensure your WDK instance configuration matches your account environment. +* If using **Testnet** keys, ensure you registered the wallet with a **Testnet RPC**. +* If using **Mainnet** keys, ensure you registered the wallet with a **Mainnet RPC**. +Using a Mainnet key on a Testnet RPC (or vice versa) will result in "Network not allowed" or 0 balance errors. +{% endhint %} ## View Addresses diff --git a/sdk/core-module/guides/error-handling.md b/sdk/core-module/guides/error-handling.md index 0414562..4bf589b 100644 --- a/sdk/core-module/guides/error-handling.md +++ b/sdk/core-module/guides/error-handling.md @@ -64,8 +64,9 @@ function endSession(wdk) { ``` {% endcode %} -> [!WARNING] -> **After Disposal:** Once disposed, any attempt to use the `wdk` instance or its derived accounts will result in an error. You must inspect a new instance to resume operations. +{% hint style="warning" %} +**After Disposal:** Once disposed, any attempt to use the `wdk` instance or its derived accounts will result in an error. You must inspect a new instance to resume operations. +{% endhint %} ## Security Best Practices diff --git a/sdk/core-module/guides/instantiation.md b/sdk/core-module/guides/instantiation.md index f0b2ecc..d1d5a14 100644 --- a/sdk/core-module/guides/instantiation.md +++ b/sdk/core-module/guides/instantiation.md @@ -51,8 +51,9 @@ const wdk = new WDK(seedPhrase) ``` {% endcode %} -> [!IMPORTANT] -> **Secure the Seed Phrase:** You must securely store this seed phrase immediately. If it is lost, the user will permanently lose access to their funds. +{% hint style="danger" %} +**Secure the Seed Phrase:** You must securely store this seed phrase immediately. If it is lost, the user will permanently lose access to their funds. +{% endhint %} ### Option 2: Restore an existing wallet diff --git a/sdk/core-module/guides/middleware.md b/sdk/core-module/guides/middleware.md index 60bbff4..3adcff9 100644 --- a/sdk/core-module/guides/middleware.md +++ b/sdk/core-module/guides/middleware.md @@ -74,9 +74,6 @@ const balance = await wallet.getBalance() {% endcode %} This wrapper ensures that if your primary RPC fails, the wallet automatically retries with the fallback providers. -})) -``` -{% endcode %} With this configuration, if `sendTransaction` fails due to a network error, the WDK will automatically retry using the fallback providers without throwing an error to your application. diff --git a/sdk/core-module/guides/protocol-integration.md b/sdk/core-module/guides/protocol-integration.md index 63731b4..a0f390b 100644 --- a/sdk/core-module/guides/protocol-integration.md +++ b/sdk/core-module/guides/protocol-integration.md @@ -99,7 +99,6 @@ Use `getBridgeProtocol` to access cross-chain bridges. {% code title="Bridge Assets" lineNumbers="true" %} ```typescript -```typescript const ethAccount = await wdk.getAccount('ethereum', 0) const usdt0 = ethAccount.getBridgeProtocol('usdt0') @@ -110,11 +109,11 @@ const result = await usdt0.bridge({ amount: 1000000n }) ``` -``` {% endcode %} -> [!NOTE] -> **Protocol Availability:** If you try to access a protocol that hasn't been registered (e.g., `getSwapProtocol('uniswap')`), the SDK will throw an error. always ensure registration matches the ID you request. +{% hint style="info" %} +**Protocol Availability:** If you try to access a protocol that hasn't been registered (e.g., `getSwapProtocol('uniswap')`), the SDK will throw an error. always ensure registration matches the ID you request. +{% endhint %} ## Next steps diff --git a/sdk/core-module/guides/transactions.md b/sdk/core-module/guides/transactions.md index 69fec59..308eedd 100644 --- a/sdk/core-module/guides/transactions.md +++ b/sdk/core-module/guides/transactions.md @@ -58,13 +58,15 @@ console.log('TON transaction:', tonResult.hash) ``` {% endcode %} -> [!NOTE] -> **Get Testnet Funds:** To test these transactions without spending real money, verify you are on a testnet and use a faucet: -> * **Ethereum (Sepolia):** [Google Cloud Faucet](https://cloud.google.com/application/web3/faucet/ethereum/sepolia) -> * **TON Testnet:** [Testgiver Bot](https://t.me/testgiver_ton_bot) - -> [!IMPORTANT] -> **BigInt Usage:** Always use `BigInt` (the `n` suffix) for monetary values to avoid precision loss with large numbers. +{% hint style="info" %} +**Get Testnet Funds:** To test these transactions without spending real money, verify you are on a testnet and use a faucet: +* **Ethereum (Sepolia):** [Google Cloud Faucet](https://cloud.google.com/application/web3/faucet/ethereum/sepolia) +* **TON Testnet:** [Testgiver Bot](https://t.me/testgiver_ton_bot) +{% endhint %} + +{% hint style="warning" %} +**BigInt Usage:** Always use `BigInt` (the `n` suffix) for monetary values to avoid precision loss with large numbers. +{% endhint %} ## Handling Responses diff --git a/sdk/core-module/guides/wallet-registration.md b/sdk/core-module/guides/wallet-registration.md index ada1d64..8c05d2f 100644 --- a/sdk/core-module/guides/wallet-registration.md +++ b/sdk/core-module/guides/wallet-registration.md @@ -77,15 +77,17 @@ const wdk = new WDK(seedPhrase) ``` {% endcode %} -> [!NOTE] -> **Ethereum Networks:** Choose the RPC endpoint that matches your environment (Mainnet or Testnet). -> * **Mainnet:** `https://eth.drpc.org` -> * **Sepolia (Testnet):** `https://sepolia.drpc.org` - -> [!NOTE] -> **TON Networks:** The endpoint (`url`) you use must match your API key environment. -> * **Mainnet:** `https://toncenter.com/api/v2/jsonRPC` -> * **Testnet:** `https://testnet.toncenter.com/api/v2/jsonRPC` +{% hint style="info" %} +**Ethereum Networks:** Choose the RPC endpoint that matches your environment (Mainnet or Testnet). +* **Mainnet:** `https://eth.drpc.org` +* **Sepolia (Testnet):** `https://sepolia.drpc.org` +{% endhint %} + +{% hint style="info" %} +**TON Networks:** The endpoint (`url`) you use must match your API key environment. +* **Mainnet:** `https://toncenter.com/api/v2/jsonRPC` +* **Testnet:** `https://testnet.toncenter.com/api/v2/jsonRPC` +{% endhint %} ## Next steps From f76f5350af332d2307e104816cc29296f31a3015 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Tue, 20 Jan 2026 12:36:12 +0530 Subject: [PATCH 16/27] docs: add missing sidebar icon to core module usage page --- sdk/core-module/usage.md | 1 + 1 file changed, 1 insertion(+) diff --git a/sdk/core-module/usage.md b/sdk/core-module/usage.md index 31f386a..d91a882 100644 --- a/sdk/core-module/usage.md +++ b/sdk/core-module/usage.md @@ -1,6 +1,7 @@ --- title: WDK Core Usage description: Guide to using the WDK Core module. +icon: book-open layout: width: default title: From 9a9e7a47bad8cb4dc2c8e8bc3b17c7521c3c814d Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Tue, 20 Jan 2026 13:09:06 +0530 Subject: [PATCH 17/27] docs: update usage page to use gitbook cards layout --- sdk/core-module/usage.md | 69 ++++++++++++++++++++++++++++++++++------ 1 file changed, 60 insertions(+), 9 deletions(-) diff --git a/sdk/core-module/usage.md b/sdk/core-module/usage.md index d91a882..439adff 100644 --- a/sdk/core-module/usage.md +++ b/sdk/core-module/usage.md @@ -22,13 +22,64 @@ layout: The WDK Core module is the central orchestrator for your wallet interactions. -Use the guides below to get started: -* **[Installation](./guides/installation.md)**: Add the package to your project. -* **[Instantiation](./guides/instantiation.md)**: Initialize the WDK with a seed phrase. -* **[Register Wallets](./guides/wallet-registration.md)**: Connect specific blockchains (Ethereum, TON, etc.). -* **[Manage Accounts](./guides/account-management.md)**: Retrieve accounts and check balances. -* **[Send Transactions](./guides/transactions.md)**: Transfer native tokens. -* **[Integrate Protocols](./guides/protocol-integration.md)**: Use Swap, Bridge, and Lending protocols. -* **[Configure Middleware](./guides/middleware.md)**: Add logging and failover protection. -* **[Error Handling](./guides/error-handling.md)**: Best practices for security and stability. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
:download:InstallationAdd the package to your project.Installation
:code:InstantiationInitialize the WDK with a seed phrase.Instantiation
:wallet:Register WalletsConnect specific blockchains (Ethereum, TON, etc.).Register Wallets
:user:Manage AccountsRetrieve accounts and check balances.Manage Accounts
:exchange-alt:Send TransactionsTransfer native tokens.Send Transactions
:plug:Integrate ProtocolsUse Swap, Bridge, and Lending protocols.Integrate Protocols
:layer-group:Configure MiddlewareAdd logging and failover protection.Configure Middleware
:exclamation-triangle:Error HandlingBest practices for security and stability.Error Handling
From 10e32b09e20f121467ed079ca03757a1656d7a10 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Thu, 22 Jan 2026 11:41:43 +0530 Subject: [PATCH 18/27] docs: refine account management guide with clearer examples and warnings --- sdk/core-module/guides/account-management.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/sdk/core-module/guides/account-management.md b/sdk/core-module/guides/account-management.md index f84622a..b888bcb 100644 --- a/sdk/core-module/guides/account-management.md +++ b/sdk/core-module/guides/account-management.md @@ -49,20 +49,20 @@ const customEthAccount = await wdk.getAccountByPath('ethereum', "0'/0/1") {% endcode %} {% hint style="info" %} -The WDK instance caches accounts. calling `getAccount` twice for the same index returns the same object instance. +The WDK instance caches accounts. If you call `getAccount` twice using the same index, the function will return the same `Account` object instance. {% endhint %} {% hint style="warning" %} **Network Mismatch Warning** Ensure your WDK instance configuration matches your account environment. -* If using **Testnet** keys, ensure you registered the wallet with a **Testnet RPC**. -* If using **Mainnet** keys, ensure you registered the wallet with a **Mainnet RPC**. -Using a Mainnet key on a Testnet RPC (or vice versa) will result in "Network not allowed" or 0 balance errors. +* If using **Testnet** keys, ensure you registered the wallet with a **Testnet RPC** (e.g., `https://sepolia.drpc.org` for ETH, `https://testnet.toncenter.com/api/v2/jsonRPC` for TON). +* If using **Mainnet** keys, ensure you registered the wallet with a **Mainnet RPC** (e.g., `https://eth.drpc.org` for ETH, `https://toncenter.com/api/v2/jsonRPC` for TON). +Using a Mainnet key on a Testnet RPC (or vice versa) will result in "Network not allowed" or zero balance errors. {% endhint %} ## View Addresses -Once you have an account object, you can retrieve its public blockchain address. +Once you have an account object, you can retrieve its public blockchain address using the `getAddress` function. {% code title="Get Addresses" lineNumbers="true" %} ```typescript @@ -73,7 +73,7 @@ console.log('Ethereum address:', ethAddress) ## Check Balances -You can check the native token balance of any account (e.g., ETH on Ethereum, TON on TON). +You can check the native token balance of any account (e.g., ETH on Ethereum, TON on TON) by using the `getBalance()` function. {% code title="Get Balance" lineNumbers="true" %} ```typescript @@ -90,6 +90,12 @@ try { Because WDK offers a unified interface, you can easily iterate through multiple chains to fetch balances. +The following example: +1. Iterates over an array of user defined chains. +2. Retrieves the first account using the respective chain's `getAccount(index)` function. +3. Retrieves the first account's balance using the `getBalance()` function. +4. Logs the balance to the console. + {% code title="Check All Balances" lineNumbers="true" %} ```typescript const chains = ['ethereum', 'ton', 'bitcoin'] From 4ffdf7566fe1f3f971a17c0726bd95dd71f3435b Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Thu, 22 Jan 2026 11:53:25 +0530 Subject: [PATCH 19/27] docs: refine error handling guide with hints and security sections --- sdk/core-module/guides/error-handling.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/sdk/core-module/guides/error-handling.md b/sdk/core-module/guides/error-handling.md index 4bf589b..9c4e2c2 100644 --- a/sdk/core-module/guides/error-handling.md +++ b/sdk/core-module/guides/error-handling.md @@ -40,11 +40,13 @@ try { ``` {% endcode %} +{% hint style="tip" %} Always use `try/catch` blocks when initializing sessions or accessing dynamic features. +{% endhint %} ## Memory Management -For security, you should clear sensitive data from memory when a session is complete. The WDK provided a `.dispose()` method for this purpose. +For security, you should clear sensitive data from memory when a session is complete. The WDK provides a `.dispose()` method for this purpose. ### Disposing the Instance @@ -65,10 +67,15 @@ function endSession(wdk) { {% endcode %} {% hint style="warning" %} -**After Disposal:** Once disposed, any attempt to use the `wdk` instance or its derived accounts will result in an error. You must inspect a new instance to resume operations. +**After Disposal:** Once disposed, any attempt to use the `wdk` instance or its derived accounts will result in an error. You must instantiate a new instance to resume operations. {% endhint %} ## Security Best Practices -* **Environment Variables:** Never hardcode API keys or seed phrases in your source code. Use environment variables (e.g., `process.env.TON_API_KEY`). -* **Secure Storage:** If persisting a session, never store the raw seed phrase in local storage. Use secure operating system storage (like Keychain on macOS or Keystore on Android). +### Environment Variables + +Never hardcode API keys or seed phrases in your source code. Use environment variables (e.g., `process.env.TON_API_KEY`). + +### Secure Storage + +If you persist a session, never store the raw seed phrase in local storage. Use secure operating system storage (like Keychain on macOS or Keystore on Android). From 187721d35caafe420b792b8ad476a529f5b84f00 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Thu, 22 Jan 2026 12:01:37 +0530 Subject: [PATCH 20/27] docs: add resource links to installation guide --- sdk/core-module/guides/installation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sdk/core-module/guides/installation.md b/sdk/core-module/guides/installation.md index fce6fe0..c572bf0 100644 --- a/sdk/core-module/guides/installation.md +++ b/sdk/core-module/guides/installation.md @@ -19,18 +19,18 @@ layout: # Install WDK Core -This guide shows you how to install the `@tetherto/wdk` package, which serves as the main entry point for the Wallet Development Kit (WDK). +This guide shows you how to install the [`@tetherto/wdk`](https://www.npmjs.com/package/@tetherto/wdk) package, which serves as the main entry point for the Wallet Development Kit (WDK). ## Prerequisites Before you begin, ensure you have the following installed: -* **Node.js**: version 18 or higher. -* **npm**: usually comes with Node.js. +* **[Node.js](https://nodejs.org/)**: version 18 or higher. +* **[npm](https://www.npmjs.com/)**: usually comes with Node.js. ## Installation -To install the WDK Core package, run the following command in your terminal: +To install the [`@tetherto/wdk`](https://www.npmjs.com/package/@tetherto/wdk) Core package, run the following command in your terminal: ```bash npm install @tetherto/wdk From 4ee9aa55b70577e587db25adf9ae4dc66f5a1380 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Thu, 22 Jan 2026 12:22:59 +0530 Subject: [PATCH 21/27] docs: refine instantiation guide with internal links, module references, and improved headers --- sdk/core-module/guides/instantiation.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/sdk/core-module/guides/instantiation.md b/sdk/core-module/guides/instantiation.md index d1d5a14..abd1d80 100644 --- a/sdk/core-module/guides/instantiation.md +++ b/sdk/core-module/guides/instantiation.md @@ -23,7 +23,7 @@ This guide explains how to import the WDK Core module and create a new instance ## Import the module -First, import the `WDK` class from the package you installed: +First, import the `WDK` class from the package you installed (see [Installation](./installation.md)): {% code title="Import WDK Core"lineNumbers="true" %} ```typescript @@ -33,11 +33,11 @@ import WDK from '@tetherto/wdk' ## Create an Instance -To use the SDK, you must create an instance of the `WDK` class. This instance acts as the central manager for all your wallets and protocols. +To use WDK, you must create an instance of the `WDK` class. This instance acts as the central manager for all your wallets and protocols. -You can initialize `WDK` in two ways: with a new seed phrase or an existing one. +You can initialize `WDK` in two ways: with a [new seed phrase](#generate-a-new-wallet) or an [existing one](#restore-an-existing-wallet). -### Option 1: Generate a new wallet +### Generate a New Wallet If you are creating a fresh wallet for a user, use the static `getRandomSeedPhrase()` method to generate a secure mnemonic. @@ -55,7 +55,7 @@ const wdk = new WDK(seedPhrase) **Secure the Seed Phrase:** You must securely store this seed phrase immediately. If it is lost, the user will permanently lose access to their funds. {% endhint %} -### Option 2: Restore an existing wallet +### Restore an Existing Wallet If a user already has a seed phrase (e.g., from a previous session or another wallet), you can pass it directly to the constructor. @@ -70,4 +70,4 @@ const wdk = new WDK(existingSeed) ## Next steps -With your WDK instance ready, you can now [register wallet modules](./wallet-registration.md) to interact with specific blockchains like Ethereum, TON, or Bitcoin. +With your WDK instance ready, you can now [register wallet modules](./wallet-registration.md) to interact with specific blockchains like [Ethereum](../../wallet-modules/wallet-evm/README.md), [TON](../../wallet-modules/wallet-ton/README.md), or [Bitcoin](../../wallet-modules/wallet-btc/README.md). From 77ce28078296e1b7075b3e68501bd389e4997cf0 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Thu, 22 Jan 2026 17:07:01 +0530 Subject: [PATCH 22/27] docs: standardize headers and refine middleware guide with resource links --- sdk/core-module/guides/account-management.md | 2 +- sdk/core-module/guides/installation.md | 2 +- sdk/core-module/guides/instantiation.md | 2 +- sdk/core-module/guides/middleware.md | 25 +++++++++++-------- .../guides/protocol-integration.md | 2 +- sdk/core-module/guides/transactions.md | 2 +- sdk/core-module/guides/wallet-registration.md | 2 +- 7 files changed, 20 insertions(+), 17 deletions(-) diff --git a/sdk/core-module/guides/account-management.md b/sdk/core-module/guides/account-management.md index b888bcb..e0fde38 100644 --- a/sdk/core-module/guides/account-management.md +++ b/sdk/core-module/guides/account-management.md @@ -112,6 +112,6 @@ for (const chain of chains) { ``` {% endcode %} -## Next steps +## Next Steps Now that you can access your accounts, learn how to [send transactions](./transactions.md). diff --git a/sdk/core-module/guides/installation.md b/sdk/core-module/guides/installation.md index c572bf0..4d10378 100644 --- a/sdk/core-module/guides/installation.md +++ b/sdk/core-module/guides/installation.md @@ -38,6 +38,6 @@ npm install @tetherto/wdk This package allows you to manage different blockchain wallets and protocols through a single interface. -## Next steps +## Next Steps Now that you have installed the core package, you can [instantiate the WDK](./instantiation.md) to start creating wallets. diff --git a/sdk/core-module/guides/instantiation.md b/sdk/core-module/guides/instantiation.md index abd1d80..51a444c 100644 --- a/sdk/core-module/guides/instantiation.md +++ b/sdk/core-module/guides/instantiation.md @@ -68,6 +68,6 @@ const wdk = new WDK(existingSeed) ``` {% endcode %} -## Next steps +## Next Steps With your WDK instance ready, you can now [register wallet modules](./wallet-registration.md) to interact with specific blockchains like [Ethereum](../../wallet-modules/wallet-evm/README.md), [TON](../../wallet-modules/wallet-ton/README.md), or [Bitcoin](../../wallet-modules/wallet-btc/README.md). diff --git a/sdk/core-module/guides/middleware.md b/sdk/core-module/guides/middleware.md index 3adcff9..07e629e 100644 --- a/sdk/core-module/guides/middleware.md +++ b/sdk/core-module/guides/middleware.md @@ -19,13 +19,13 @@ layout: # Configure Middleware -Middleware allows you to intercept wallet operations. You can use this to add logging, implement retry logic, or handle failovers for RPC providers. +Middleware allows you to intercept wallet operations. You can use this to add [logging](#logging), implement retry logic, or handle [failovers for RPC providers](#failover-protection-with-provider-failover). ## Register Middleware -Reference a specific chain when registering middleware. The middleware function runs every time an account is instantiated or an operation is performed, depending on the implementation. +When registering middleware, you should reference a specific chain. The middleware function runs every time an account is instantiated or an operation is performed, depending on the implementation. -### Example: Logging +### Logging This simple middleware logs a message whenever a new account is accessed. @@ -40,17 +40,24 @@ wdk.registerMiddleware('ethereum', async (account) => { ``` {% endcode %} -## Failover Protection +## Failover Protection with Provider Failover +The [`@tetherto/wdk-provider-failover`](https://www.npmjs.com/package/@tetherto/wdk-provider-failover) package provides a resilient wrapper for wallet instances. Unlike standard middleware, you wrap your wallet class instantiation directly. -### Using Provider Failover +### Install `@tetherto/wdk-provider-failover` -The `@tetherto/wdk-provider-failover` package provides a resilient wrapper for wallet instances. Unlike standard middleware, you wrap your wallet class instantiation directly. +You can install the `@tetherto/wdk-provider-failover` using npm with the following command: ```bash npm install @tetherto/wdk-provider-failover ``` +### Use `createFallbackWallet` + +You can import the `createFallbackWallet` function to ensure that if your primary RPC fails, the wallet automatically retries with the fallback providers. + +With this configuration, if `sendTransaction` fails due to a network error, the WDK will automatically retry using the fallback providers without throwing an error to your application. + {% code title="Failover Wrapper Usage" lineNumbers="true" %} ```typescript import { createFallbackWallet } from '@tetherto/wdk-provider-failover' @@ -73,10 +80,6 @@ const balance = await wallet.getBalance() ``` {% endcode %} -This wrapper ensures that if your primary RPC fails, the wallet automatically retries with the fallback providers. - -With this configuration, if `sendTransaction` fails due to a network error, the WDK will automatically retry using the fallback providers without throwing an error to your application. - -## Next steps +## Next Steps Learn about [error handling and best practices](./error-handling.md) to ensure your application is robust and secure. diff --git a/sdk/core-module/guides/protocol-integration.md b/sdk/core-module/guides/protocol-integration.md index a0f390b..a7200ad 100644 --- a/sdk/core-module/guides/protocol-integration.md +++ b/sdk/core-module/guides/protocol-integration.md @@ -115,6 +115,6 @@ const result = await usdt0.bridge({ **Protocol Availability:** If you try to access a protocol that hasn't been registered (e.g., `getSwapProtocol('uniswap')`), the SDK will throw an error. always ensure registration matches the ID you request. {% endhint %} -## Next steps +## Next Steps Learn how to [configure middleware](./middleware.md) to add logging or failover protection to your wallet interactions. diff --git a/sdk/core-module/guides/transactions.md b/sdk/core-module/guides/transactions.md index 308eedd..2c72623 100644 --- a/sdk/core-module/guides/transactions.md +++ b/sdk/core-module/guides/transactions.md @@ -97,6 +97,6 @@ async function sendCrossChainPayments(wdk) { ``` {% endcode %} -## Next steps +## Next Steps For more complex interactions like swapping tokens or bridging assets, learn how to [integrate protocols](./protocol-integration.md). diff --git a/sdk/core-module/guides/wallet-registration.md b/sdk/core-module/guides/wallet-registration.md index 8c05d2f..c086062 100644 --- a/sdk/core-module/guides/wallet-registration.md +++ b/sdk/core-module/guides/wallet-registration.md @@ -89,6 +89,6 @@ const wdk = new WDK(seedPhrase) * **Testnet:** `https://testnet.toncenter.com/api/v2/jsonRPC` {% endhint %} -## Next steps +## Next Steps Once your wallets are registered, you can [manage accounts and specific addresses](./account-management.md). From 7c74349748029cab02c1dced3f0b221850270f7b Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Thu, 22 Jan 2026 17:21:55 +0530 Subject: [PATCH 23/27] docs: enhance protocol integration guide with header links and package references --- .../guides/protocol-integration.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/sdk/core-module/guides/protocol-integration.md b/sdk/core-module/guides/protocol-integration.md index a7200ad..ca55473 100644 --- a/sdk/core-module/guides/protocol-integration.md +++ b/sdk/core-module/guides/protocol-integration.md @@ -19,24 +19,26 @@ layout: # Integrate Protocols -The WDK Core module supports registering external protocols. This allows you to extend the basic wallet functionality with advanced features like token swapping, cross-chain bridging, and lending, all through a unified interface. +The WDK Core module supports registering external protocols. This allows you to extend the basic wallet functionality with advanced features like [token swapping](#swapping-tokens), [cross-chain bridging](#bridging-assets), and lending, all through a unified interface. ## Register Protocols -You can register protocols in two ways: globally (for all new accounts) or locally (for a specific existing account). +You can register protocols in two ways: [globally](#global-registration-recommended) (for all new accounts) or [locally](#account-level-registration) (for a specific existing account). ### Global Registration (Recommended) -Global registration ensures that every account you retrieve already has the protocol ready to use. This is done by chaining `.registerProtocol()` on the WDK instance. +Global registration ensures that every account you retrieve already has the protocol ready to use. You can do this by chaining a call to `.registerProtocol()` on the WDK instance. -**1. Install Protocol Modules** +### 1. Install Protocol Modules + +Install the [`@tetherto/wdk-protocol-swap-velora-evm`](https://www.npmjs.com/package/@tetherto/wdk-protocol-swap-velora-evm) and [`@tetherto/wdk-protocol-bridge-usdt0-evm`](https://www.npmjs.com/package/@tetherto/wdk-protocol-bridge-usdt0-evm) packages: ```bash npm install @tetherto/wdk-protocol-swap-velora-evm npm install @tetherto/wdk-protocol-bridge-usdt0-evm ``` -**2. Register in Code** +### 2. Register in Code {% code title="Global Registration" lineNumbers="true" %} ```typescript @@ -74,11 +76,11 @@ account.registerProtocol('velora', veloraProtocolEvm, config) ## Use Protocols -Once registered, you can access the protocol instance using the specific getter methods: `getSwapProtocol`, `getBridgeProtocol`, or `getLendingProtocol`. +Once [registered](#register-protocols), you can access the protocol instance using the specific getter methods: `getSwapProtocol`, `getBridgeProtocol`, or `getLendingProtocol`. ### Swapping Tokens -Use `getSwapProtocol` to access registered swap services. +Use `getSwapProtocol` to access registered swap services on any wallet account. {% code title="Swap Tokens" lineNumbers="true" %} ```typescript @@ -95,7 +97,8 @@ const result = await velora.swap({ ### Bridging Assets -Use `getBridgeProtocol` to access cross-chain bridges. +1. Use `getBridgeProtocol` to access cross-chain bridges. +2. Call `bridge` from the bridge protocol to send tokens from one protocol to another. {% code title="Bridge Assets" lineNumbers="true" %} ```typescript From 96eb2157d0bc2e22a67ecbd3c07caa5d1666e58d Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Thu, 22 Jan 2026 17:39:44 +0530 Subject: [PATCH 24/27] docs: optimize installation command in protocol integration guide --- sdk/core-module/guides/protocol-integration.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/sdk/core-module/guides/protocol-integration.md b/sdk/core-module/guides/protocol-integration.md index ca55473..fc4cf47 100644 --- a/sdk/core-module/guides/protocol-integration.md +++ b/sdk/core-module/guides/protocol-integration.md @@ -34,8 +34,7 @@ Global registration ensures that every account you retrieve already has the prot Install the [`@tetherto/wdk-protocol-swap-velora-evm`](https://www.npmjs.com/package/@tetherto/wdk-protocol-swap-velora-evm) and [`@tetherto/wdk-protocol-bridge-usdt0-evm`](https://www.npmjs.com/package/@tetherto/wdk-protocol-bridge-usdt0-evm) packages: ```bash -npm install @tetherto/wdk-protocol-swap-velora-evm -npm install @tetherto/wdk-protocol-bridge-usdt0-evm +npm install @tetherto/wdk-protocol-swap-velora-evm && npm install @tetherto/wdk-protocol-bridge-usdt0-evm ``` ### 2. Register in Code From 021969a0fa1cd31cd16d04d1de1e81e843d65f84 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Thu, 22 Jan 2026 17:43:18 +0530 Subject: [PATCH 25/27] docs: split and explain protocol registration example --- sdk/core-module/guides/protocol-integration.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/sdk/core-module/guides/protocol-integration.md b/sdk/core-module/guides/protocol-integration.md index fc4cf47..65eec6d 100644 --- a/sdk/core-module/guides/protocol-integration.md +++ b/sdk/core-module/guides/protocol-integration.md @@ -39,11 +39,22 @@ npm install @tetherto/wdk-protocol-swap-velora-evm && npm install @tetherto/wdk- ### 2. Register in Code -{% code title="Global Registration" lineNumbers="true" %} + +Now, import the protocol modules and register them with your WDK instance. This makes the protocol methods available to any account derived from that instance. + +First, import the necessary modules: + +{% code title="Import Protocols" lineNumbers="true" %} ```typescript import veloraProtocolEvm from '@tetherto/wdk-protocol-swap-velora-evm' import usdt0ProtocolEvm from '@tetherto/wdk-protocol-bridge-usdt0-evm' +``` +{% endcode %} + +Then, register the protocols for the specific chains they support: +{% code title="Register Protocols" lineNumbers="true" %} +```typescript // Register protocols for specific chains const wdk = new WDK(seedPhrase) .registerWallet('ethereum', WalletManagerEvm, ethConfig) From 02c93909312946127e1eb3920be6eab909c4abbd Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Thu, 22 Jan 2026 18:02:12 +0530 Subject: [PATCH 26/27] docs: restructure transactions guide with better hint placement and tips --- sdk/core-module/guides/transactions.md | 48 ++++++++++++++++++-------- 1 file changed, 34 insertions(+), 14 deletions(-) diff --git a/sdk/core-module/guides/transactions.md b/sdk/core-module/guides/transactions.md index 2c72623..1827f37 100644 --- a/sdk/core-module/guides/transactions.md +++ b/sdk/core-module/guides/transactions.md @@ -19,15 +19,33 @@ layout: # Send Transactions -This guide explains how to send native tokens (like ETH, TON, or BTC) from your wallet to another address. -## Sending Native Tokens +You can send native tokens (like ETH, TON, or BTC) from any of your wallet accounts to another address. -The `sendTransaction` method allows you to transfer value. It accepts a unified configuration object, though specific parameters (like `value` formatting) may vary slightly depending on the chain's requirements. +{% hint style="info" %} +**Get Testnet Funds:** To test these transactions without spending real money, verify you are on a testnet and use a faucet: +* **Ethereum (Sepolia):** [Google Cloud Faucet](https://cloud.google.com/application/web3/faucet/ethereum/sepolia) +* **TON Testnet:** [Testgiver Bot](https://t.me/testgiver_ton_bot) +{% endhint %} + +{% hint style="warning" %} +**BigInt Usage:** Always use `BigInt` (the `n` suffix) for monetary values to avoid precision loss with large numbers. +{% endhint %} + +## Send Native Tokens + +The `sendTransaction` method allows you to transfer value. It accepts a unified configuration object, though specific parameters (like `value` formatting) may vary slightly depending on the blockchain. ### Ethereum Example +{% hint style="tip" %} On EVM chains, values are typically expressed in Wei (1 ETH = 10^18 Wei). +{% endhint %} + +The following example will: + +1. Retrieve the first Ethereum account (see [Manage Accounts](./account-management.md)) +2. Send 0.001 ETH (1000000000000000 wei) to an account using `sendTransaction`. {% code title="Send ETH" lineNumbers="true" %} ```typescript @@ -44,7 +62,14 @@ console.log('Transaction sent! Hash:', result.hash) ### TON Example +{% hint style="tip" %} On TON, values are expressed in Nanotons (1 TON = 10^9 Nanotons). +{% endhint %} + +The following example will: + +1. Retrieve the first TON account +2. Send 1 TON (1000000000 nton) to an account using `sendTransaction`. {% code title="Send TON" lineNumbers="true" %} ```typescript @@ -52,22 +77,12 @@ On TON, values are expressed in Nanotons (1 TON = 10^9 Nanotons). const tonAccount = await wdk.getAccount('ton', 0) const tonResult = await tonAccount.sendTransaction({ to: 'UQCz5ON7jjK32HnqPushubsHxgsXgeSZDZPvh8P__oqol90r', - value: 1000000000n // 1 TON + value: 1000000000n // 1 TON (in nanotons) }) console.log('TON transaction:', tonResult.hash) ``` {% endcode %} -{% hint style="info" %} -**Get Testnet Funds:** To test these transactions without spending real money, verify you are on a testnet and use a faucet: -* **Ethereum (Sepolia):** [Google Cloud Faucet](https://cloud.google.com/application/web3/faucet/ethereum/sepolia) -* **TON Testnet:** [Testgiver Bot](https://t.me/testgiver_ton_bot) -{% endhint %} - -{% hint style="warning" %} -**BigInt Usage:** Always use `BigInt` (the `n` suffix) for monetary values to avoid precision loss with large numbers. -{% endhint %} - ## Handling Responses The `sendTransaction` method returns a transaction result object. The most important field is typically `hash`, which represents the transaction ID on the blockchain. You can use this hash to track the status of your payment on a block explorer. @@ -76,6 +91,11 @@ The `sendTransaction` method returns a transaction result object. The most impor You can orchestrate payments across different chains in a single function by acting on multiple account objects sequentially. +The following example will: +1. Retrieve an ETH and ton account using the `getAccount()` method. +2. Send ETH and `await` the transaction. +3. Send TON and `await` the transaction. + {% code title="Multi-Chain Payment" lineNumbers="true" %} ```typescript async function sendCrossChainPayments(wdk) { From b7a100debeb29b6ce16a33ffc8551f9cca8fd46f Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Thu, 22 Jan 2026 18:17:44 +0530 Subject: [PATCH 27/27] docs: improve wallet registration guide with cross-links --- sdk/core-module/guides/wallet-registration.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/sdk/core-module/guides/wallet-registration.md b/sdk/core-module/guides/wallet-registration.md index c086062..7b1d77f 100644 --- a/sdk/core-module/guides/wallet-registration.md +++ b/sdk/core-module/guides/wallet-registration.md @@ -35,7 +35,7 @@ The `registerWallet` method requires three arguments: ## Installation -Install the wallet managers for the blockchains you want to support: +Install the [wallet managers](../../wallet-modules/README.md) for the blockchains you want to support: ```bash npm install @tetherto/wdk-wallet-evm @tetherto/wdk-wallet-ton @tetherto/wdk-wallet-btc @@ -43,6 +43,8 @@ npm install @tetherto/wdk-wallet-evm @tetherto/wdk-wallet-ton @tetherto/wdk-wall ## Example: Registering Multiple Wallets +### Import the Wallet Manager Packages + First, import the necessary wallet manager packages: {% code title="Import Modules" lineNumbers="true" %} @@ -53,7 +55,9 @@ import WalletManagerBtc from '@tetherto/wdk-wallet-btc' ``` {% endcode %} -Then, instantiate WDK and chain the registration calls: +### Register the Wallets + +Then, [instantiate WDK](./instantiation.md) and chain the registration calls: {% code title="Register Wallets" lineNumbers="true" %} ```typescript