fix(tx-sdk): improve guides

Author: dineshpinto

docs/network/8-flare-tx-sdk.mdx

@@ -9,22 +9,22 @@ import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 import DocCardList from "@theme/DocCardList";
 
-The Flare Transaction SDK ([`@flarenetwork/flare-tx-sdk`](https://www.npmjs.com/package/@flarenetwork/flare-tx-sdk/)) is the official Node.js toolkit for performing common actions on all Flare networks:
+The Flare Transaction SDK ([`@flarenetwork/flare-tx-sdk`](https://www.npmjs.com/package/@flarenetwork/flare-tx-sdk/)) is the official Node.js toolkit for performing common actions on all Flare networks - Flare, Coston2, Songbird, and Coston.
 
 - Claim rewards (FlareDrop, staking, FTSO delegation, rFLR)
 - Delegate to FTSO providers
 - Stake on the P-chain
 - Vote on governance proposals
-- Retrieving account and balance information
-- Transferring native and wrapped coins
+- Retrieve account and balance information
+- Transfer native and wrapped coins
 - Interact with C-Chain contracts
 
-This guide covers installation, core concepts, and a cookbook of practical tasks.
+Explore the following guides to get started:
 
 <DocCardList />
 
-:::tip[Need help?]
+:::tip[Need help or found a bug?]
 
-You can raise an issue on the [flare-foundation/flare-tx-sdk](https://github.com/flare-foundation/flare-tx-sdk) GitHub repository.
+Open an issue on the [flare-foundation/flare-tx-sdk](https://github.com/flare-foundation/flare-tx-sdk) GitHub repository.
 
 :::

docs/network/flare-tx-sdk/1-getting-started.mdx

@@ -25,7 +25,7 @@ This guide walks you through installation, core concepts, and a quick start exam
 
 Before you start, ensure you have the following:
 
-- [Node.js](https://nodejs.org/en/download) v18 or later
+- [Node.js](https://nodejs.org/en/download) v18+ (LTS recommended) and a package manager (npm, yarn, or pnpm)
 - A compatible wallet:
   - **EIP-1193 wallets** (e.g. MetaMask, WalletConnect)
   - **Hardware wallets** (Ledger, Trezor).
@@ -54,15 +54,17 @@ Add the SDK to your project:
 
 ## Core concepts
 
-The SDK is built around two key objects:
+The SDK separates network logic from account management.
+This ensures the same wallet can be used across multiple networks without code changes.
 
 - **`Network`**: Represents the blockchain network you want to connect to. Available networks include:
   - `Network.FLARE`
+  - `Network.COSTON2`
   - `Network.SONGBIRD`
   - `Network.COSTON`
-  - `Network.COSTON2`
 
   The `Network` object provides methods to query balances, transfer tokens, claim rewards, and interact with contracts.
+  It uses Flare's [public RPCs](/network/overview#configuration) by default.
 
 - **`Wallet`**: Represents a user account. The SDK does not store private keys. Instead, it defines a `Wallet` interface which can be implemented by:
   - MetaMask and other browser wallets (`EIP1193WalletController`)
@@ -116,30 +118,30 @@ Example output:
 }
 ```
 
-:::note[Units]
+:::info[Units]
 
 The SDK uses nats (smallest unit of FLR, equivalent to wei).
-Use helpers such as `Amount.nats(x)` for FLR and `Amount.wnats(x)` for WFLR.
+Use helpers methods `Amount.nats(x)` for FLR and `Amount.wnats(x)` for WFLR.
 
 :::
 
 ## Wallet controllers
 
-The SDK doesn't store keys. Instead, it adapts external signers into a common [`Wallet`](https://github.com/flare-foundation/flare-tx-sdk/blob/HEAD/src/wallet/index.ts) interface via controllers.
-This guide shows how to connect EIP-1193 wallets (e.g., MetaMask/WalletConnect), Ledger, Trezor, and how to author a custom wallet.
+Wallet controllers adapt third-party wallets into the SDK's [`Wallet`](https://github.com/flare-foundation/flare-tx-sdk/blob/HEAD/src/wallet/index.ts) interface.
+They handle signing and address derivation, while your keys remain securely stored in the original wallet.
 
-A controller is a helper class that wraps a standard wallet library (like EIP-1193 for MetaMask or Zondax for Ledger) and produces SDK-compatible objects.
-The SDK includes controllers for popular wallet standards to make this easy.
+This guide shows how to connect EIP-1193 wallets (e.g., MetaMask/WalletConnect) and hardware wallets (Ledger and Trezor).
 
-:::tip
+### EIP-1193 (MetaMask, WalletConnect)
 
-If none of the Wallet controllers here meet your needs, you can implement a [custom wallet controller](/network/flare-tx-sdk/advanced-usage#custom-wallets).
+Use the [`EIP1193WalletController`](https://github.com/flare-foundation/flare-tx-sdk/blob/HEAD/src/wallet/eip1193/controller.ts) with any browser wallet that exposes an EIP-1193 provider (e.g., `window.ethereum`).
 
-:::
+:::tip[Security]
 
-### EIP-1193 (MetaMask, WalletConnect)
+Your private keys **never** leave your wallet.
+The SDK only communicates with the wallet for signing.
 
-Use the [`EIP1193WalletController`](https://github.com/flare-foundation/flare-tx-sdk/blob/HEAD/src/wallet/eip1193/controller.ts) with any browser wallet that exposes an EIP-1193 provider (e.g., `window.ethereum`).
+:::
 
 ```javascript
 import { Network, EIP1193WalletController } from "@flarenetwork/flare-tx-sdk";
@@ -177,6 +179,13 @@ async function connectEip1193() {
 Use the [`LedgerWalletController`](https://github.com/flare-foundation/flare-tx-sdk/blob/HEAD/src/wallet/ledger/controller.ts).
 It supports either Zondax Flare App ([`@zondax/ledger-flare`](https://www.npmjs.com/package/@zondax/ledger-flare)) or Ledger ETH App ([`@ledgerHQ/hw-app-eth`](https://www.npmjs.com/package/@ledgerhq/hw-app-eth)).
 
+:::tip[Security]
+
+Your private keys **never** leave your Ledger device.
+The SDK only communicates with the device for signing.
+
+:::
+
 1.  **Installation:**
 
      <Tabs groupId="ledger-connector">
@@ -233,7 +242,9 @@ It supports either Zondax Flare App ([`@zondax/ledger-flare`](https://www.npmjs.
     import { Eth } from "@ledgerHQ/hw-app-eth"
 
     async function connectLedgerViaEthApp() {
-        ethApp = Eth(...) // add transport here
+        // add Ledger transports here
+        // see https://developers.ledger.com/docs/device-interaction/integration/how_to/transports
+        const ethApp = Eth(...)
         const controller = new LedgerWalletController(null, ethApp);
 
         const path = "m/44'/60'/0'/0/0";
@@ -255,6 +266,13 @@ It supports either Zondax Flare App ([`@zondax/ledger-flare`](https://www.npmjs.
 
 Use the [`TrezorWalletController`](https://github.com/flare-foundation/flare-tx-sdk/blob/HEAD/src/wallet/trezor/controller.ts) with [Trezor Connect](https://connect.trezor.io/9/readme/connect/).
 
+:::tip[Security]
+
+Your private keys **never** leave your Trezor device.
+The SDK only communicates with the device for signing.
+
+:::
+
 1. **Installation:**
 
    ```bash
@@ -268,7 +286,9 @@ Use the [`TrezorWalletController`](https://github.com/flare-foundation/flare-tx-
    import { TrezorWalletController } from "@flarenetwork/flare-tx-sdk";
 
    async function connectTrezor() {
-       TrezorConnect.init(...) // add manifest here
+       // add Trezor manifest
+       // see https://connect.trezor.io/9/methods/other/init/
+       TrezorConnect.init(...)
        const controller = new TrezorWalletController(TrezorConnect);
 
        const path = "m/44'/60'/0'/0/0";
@@ -282,7 +302,14 @@ Use the [`TrezorWalletController`](https://github.com/flare-foundation/flare-tx-
    }
    ```
 
+:::info[Advanced]
+
+If none of the Wallet controllers listed here meet your needs, you can implement a [custom wallet controller](/network/flare-tx-sdk/advanced-usage#custom-wallets).
+
+:::
+
 ## Next steps
 
 - Explore the [Cookbook](/network/flare-tx-sdk/cookbook) for task-oriented guides (balances, transfers, rewards, staking).
 - Check the [Advanced Features](/network/flare-tx-sdk/advanced-usage) for transaction callbacks and custom wallets.
+- Read the SDK source code on [GitHub](https://github.com/flare-foundation/flare-tx-sdk).

docs/network/flare-tx-sdk/2-cookbook.mdx

@@ -16,9 +16,9 @@ keywords:
 tags: [intermediate, javascript]
 ---
 
-The Cookbook contains ready-to-use code snippets for common operations with the Flare Transaction SDK.
+This Cookbook contains ready-to-use code snippets for common operations with the Flare Transaction SDK.
 
-## Get account balances
+## Retrieve account balances
 
 The Flare network uses two chains:
 
@@ -55,6 +55,7 @@ Use `Amount.nats()` or `Amount.wnats()` helpers to convert human-readable values
 ## Wrap and transfer
 
 Transfer native FLR and its wrapped form (WFLR) on the C-Chain.
+Wrapping is required for governance and FTSO delegation, since only WFLR can be delegated.
 
 - **FLR** (native token) lives on both chains.
 - **WFLR** (wrapped FLR) exists only on the C-Chain for use in smart contracts and delegation.
@@ -83,7 +84,7 @@ await network.unwrapToNative(wallet, Amount.wnats(1));
 
 :::
 
-## Rewards
+## Claim rewards
 
 Flare supports multiple reward sources: FlareDrops, staking rewards, rNat (e.g. rFLR), and FTSO rewards.
 
@@ -123,8 +124,13 @@ Optional parameters are the same as [FlareDrops](#flaredrops).
 
 rNat tokens (rFLR on Flare) represent vested rewards.
 They are backed by WFLR in a dedicated rNat account.
+The flow of rFLR:
 
-#### List and claim rewards
+```plaintext
+rFLR (reward token) → backed by WFLR → claimable → withdraw → optional penalty if locked.
+```
+
+#### List and claim
 
 ```javascript
 // Get a list of all rNat projects
@@ -143,7 +149,7 @@ Claim rewards for one or more projects:
 await network.claimRNatReward(wallet, [projectId1, projectId2]);
 ```
 
-Claimed rewards are deposited as wrapped coins to the rNat account linked to the wallet's C-chain address.
+Claimed rewards are deposited as wrapped coins to the rNat account linked to the wallet's C-Chain address.
 
 #### Manage balances
 
@@ -174,7 +180,7 @@ The returned [`RNatAccountBalance`](https://github.com/flare-foundation/flare-tx
 You can also withdraw all funds (locked + unlocked):
 
 ```javascript
-await network.withdrawAllFromRNatAccount(wallet, wrap);
+await network.withdrawAllFromRNatAccount(wallet, /* wrap: boolean */ true);
 ```
 
 Withdrawing locked balance incurs a **penalty**, so the withdrawn amount will be reduced.
@@ -220,13 +226,14 @@ if (ftsoRewardAmount > 0) {
 
 Optional parameters:
 
-- `rewardOwner` (address) - C-chain address of the reward owner
-- `recipient` (address) - C-chain address of where the reward should be transferred
+- `rewardOwner` (address) - C-Chain address of the reward owner
+- `recipient` (address) - C-Chain address of where the reward should be transferred
 - `wrap` (bool) - transfer reward as native (default) or wrapped.
 
 #### Claim with proofs
 
 If a reward isn't initialized, you must provide a Merkle proof available in the [flare-foundation/fsp-rewards](https://github.com/flare-foundation/fsp-rewards/) repository.
+As an example for reward epoch 320, see the proofs in [`reward-distribution-data.json`](https://github.com/flare-foundation/fsp-rewards/blob/main/flare/320/reward-distribution-data.json).
 
 ```javascript
 await network.claimFtsoReward(wallet, rewardOwner, recipient, wrap, proofs);
@@ -304,10 +311,10 @@ The SDK automates these steps.
 
    ```javascript
    // Transfer 100 FLR from C-Chain to P-Chain
-   await network.transferToP(wallet, Amount.nats(100););
+   await network.transferToP(wallet, Amount.nats(100));
    ```
 
-2. **Delegate on P-chain:** Once funds are on the P-Chain, you can delegate them.
+2. **Delegate on P-Chain:** Once funds are on the P-Chain, you can delegate them.
 
    ```javascript
    const amountToDelegate = Amount.nats(50);
@@ -331,7 +338,7 @@ The SDK automates these steps.
    await network.transferToC(wallet);
    ```
 
-## Voting on governance proposals
+## Vote on governance proposals
 
 Governance proposals allow community members to vote on protocol decisions using their voting power (based on WFLR balance and staking).
 
@@ -364,19 +371,10 @@ A proposal can be voted on only when its `state` is ACTIVE.
 // Check if a voter has already voted:
 await network.hasCastVoteForFoundationProposal(cAddress, proposalId);
 
-// Cast FOR vote
-await network.castVoteForFoundationProposal(
-  wallet,
-  proposalId,
-  FoundationProposalSupport.FOR,
-);
+const support = FoundationProposalSupport.FOR; // or FoundationProposalSupport.AGAINST
 
-// Cast AGAINST vote
-await network.castVoteForFoundationProposal(
-  wallet,
-  proposalId,
-  FoundationProposalSupport.AGAINST,
-);
+// Cast vote
+await network.castVoteForFoundationProposal(wallet, proposalId, support);
 ```
 
 ### Delegate votes
@@ -395,7 +393,7 @@ let delegate = await network.getCurrentGovernanceVoteDelegate(cAddress);
 
 ```javascript
 // Delegate all vote power to another address:
-await network.delegateGovernanceVotePower(wallet, delegate);
+await network.delegateGovernanceVotePower(wallet, delegateAddress);
 
 // Remove delegation:
 await network.undelegateGovernanceVotePower(wallet);
@@ -416,10 +414,11 @@ const delegate = await network.getVoteDelegateForFoundationProposal(
 );
 ```
 
-Queries may **fail** for older proposals, since historical governance vote data is periodically removed from C-chain storage.
+Queries may **fail** for older proposals, since historical governance vote data is periodically removed from C-Chain storage.
 
 :::
 
 ## Next steps
 
 - Check the [Advanced Features](/network/flare-tx-sdk/advanced-usage) for transaction callbacks and custom wallets.
+- Read the SDK source code on [GitHub](https://github.com/flare-foundation/flare-tx-sdk).