WDK Core Documentation Refactor

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)

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 %}
 
@@ -96,10 +92,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)
@@ -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

sdk/core-module/guides/account-management.md

@@ -0,0 +1,111 @@
+---
+title: Manage Accounts
+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
+
+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 %}
+
+{% 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
+
+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).

sdk/core-module/guides/error-handling.md

@@ -0,0 +1,74 @@
+---
+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
+
+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 %}
+
+{% 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
+
+*   **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).

sdk/core-module/guides/installation.md

@@ -0,0 +1,43 @@
+---
+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
+
+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.

sdk/core-module/guides/instantiation.md

@@ -0,0 +1,73 @@
+---
+title: Instantiate WDK
+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
+
+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 %}
+
+{% 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
+
+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.