WDK Core Documentation Refactor

[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.
  • Correction: Updated guides/wallet-registration.md and configuration.md to use the correct structure:

    tonClient: { secretKey: '...', url: '...' }

• Missing API Key Instructions: Users were blocked without instructions on obtaining keys.
  • Addition: Added links to TON Center (https://t.me/toncenter) and their docs (https://docs.ton.org/...) in guides/wallet-registration.md.
• 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.
  • Correction: Added explicit installation sections to wallet-registration.md and protocol-integration.md.
• 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

• Refactor: sdk/core-module/usage.md -> Splitted into sdk/core-module/guides/*.md
• Update: sdk/core-module/configuration.md (Fixed TON config)
• Update: sdk/core-module/guides/protocol-integration.md (Removed TON bridge, replaced with EVM bridge)
• Update: sdk/core-module/guides/middleware.md (Updated Failover section to use createFallbackWallet wrapper pattern)

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.

[lucas-tortora]

Beautiful PR :) Just a few comments regarding style and structure.

[lucas-tortora]

Beautiful PR :) Just a few comments regarding style and structure.

[jonathunne]

Thanks @ihsraham !