Skip to content

WDK Core Documentation Refactor

Created by: ihsraham

This PR refactors the monolithic sdk/core-module/usage.md into 8 granular "How-to" guides.

This refactor was validated using a "User Zero" approach: verification was performed by explicitly following the newly created guides step-by-step from a fresh state to ensure accuracy and reproducibility. During this process, several critical gaps and inaccuracies were identified and resolved.

Resolved Issues

1. Replaced Unavailable TON Bridge

  • Issue: @tetherto/wdk-protocol-bridge-usdt0-ton is not available on NPM.
  • Resolution: Removed TON bridge references and replaced them with the working @tetherto/wdk-protocol-bridge-usdt0-evm package in protocol-integration.md.

2. Corrected Failover Middleware

  • Issue: References to @tetherto/wdk-wrapper-failover-cascade were incorrect (404).
  • Resolution: Updated documentation to use @tetherto/wdk-provider-failover with the correct createFallbackWallet wrapper pattern (moved out of registerMiddleware).

Corrections & Value Additions

2. Configuration Corrections (TON)

  • Invalid Config Structure: The docs had a flat config (tonApiKey, tonApiEndpoint) but the SDK requires a nested tonClient object.
  • Missing API Key Instructions: Users were blocked without instructions on obtaining keys.
  • Network/Endpoint Mismatch: Users faced "Network not allowed" errors when mixing Testnet keys with Mainnet endpoints.
    • Addition: Added "Note" callouts explicitly listing Mainnet vs. Testnet endpoints for TON and Ethereum.

3. Functional Verification Fixes

  • Installation Instructions: Initial guides missed npm install steps for wallet and protocol packages.
  • Invalid Test Data: The TON recipient address in transactions.md was malformed (checksum error).
    • Correction: Replaced with a valid address (UQCz5ON7jj...).
  • Unusable Transaction Defaults: The Ethereum example sent 1 ETH, far exceeding faucet limits.
    • Correction: Reduced to 0.001 ETH.
  • Chain Mismatch: The Ethereum example used a Mainnet RPC but users typically have Testnet funds.
    • Addition: Added callouts for Sepolia RPCs and Faucet links (Google Cloud, TON Testgiver).

4. Visual & Style Improvements

  • GitBook Hints: GitBook-native hints ({% hint style="info" %}) for consistent rendering.
  • Usage Landing Page: Updated usage.md index to use a Cards Grid Layout, matching the design of other module pages.

File Changes

Verification Report

Guide Status Notes
Installation ✅ Verified Installed @tetherto/wdk successfully.
Instantiation ✅ Verified Instance created and seed generated.
Register Wallets ✅ Verified Fixed: Updated TON configuration structure & added missing API key context.
Manage Accounts ✅ Verified Fixed: Added network/key mismatch (Testnet vs Mainnet) warning.
Send Transactions ✅ Verified Fixed: Updated invalid TON address, added faucet links, fixed Sepolia RPC mismatch.
Integrate Protocols ✅ Verified Velora verified. USDT0 Bridge (TON) removed, replaced with EVM example.
Middleware ✅ Verified Logging verified. Failover updated to correct Wrapper usage (not registerMiddleware).
Error Handling ✅ Verified Confirmed error patterns and dispose() functionality.

Merge request reports