YNU-864: Address quickstart review comments

- Align Node TypeScript config with the runnable lifecycle example.
- Remove internal checklist terminology and internal stress endpoint defaults from PR1 docs.
- Make app-session nonce and version snippets copy-paste safe.
- Clarify home-channel vs app-session deposit amounts and the Node local-account transaction shim.
- Tighten key-term definitions and footer metadata from review feedback.

Author: ihsraham

docs/nitrolite/build/getting-started/key-terms.mdx

@@ -10,7 +10,7 @@ keywords: [terminology, glossary, concepts, state channels, mental models]
 Nitrolite uses one shared vocabulary across the SDK, protocol docs, and on-chain contracts. Learn these terms first and the rest of the docs become much easier to scan.
 
 :::info Canonical source
-The protocol source of truth is [Protocol Terminology](../../protocol/terminology). PR7 will add a dedicated Learn glossary; until then, use this page as the builder-facing quick reference.
+The protocol source of truth is [Protocol Terminology](../../protocol/terminology). Use this page as the builder-facing quick reference for the SDK docs.
 :::
 
 ## Core mental model
@@ -22,15 +22,16 @@ Nitrolite lets a user and Nitronode exchange signed channel states off-chain, th
 | Term | What it means | Builder cue |
 |------|---------------|-------------|
 | **Channel** | A state container shared by a user and Nitronode for one unified asset. | The thing your deposits, transfers, withdrawals, and checkpoints update. |
-| **Home Channel** | The default user-Nitronode channel whose home ledger is enforced on its home chain. | Most apps start here. `deposit()`, `transfer()`, and `checkpoint()` act on the home channel for an asset. |
+| **Home Channel** (for a specific Asset) | The default user-Nitronode channel whose home ledger for the Asset is enforced on its home chain. | Most apps start here. `deposit()`, `transfer()`, and `checkpoint()` act on the home channel for an asset. |
 | **Escrow Channel** | A temporary cross-chain channel derived from a home channel for escrow operations. | You meet this when funds move between chains. |
 | **Channel State** | The current agreed channel configuration: ledgers, version, and transition data. | SDK state operations return a state before you decide whether to checkpoint it. |
 | **Channel Definition** | The immutable channel parameters: user, node, asset, nonce, challenge duration, and signature validators. | Fixed at channel creation. Do not model it as app-level mutable config. |
 | **Ledger** | A record of asset allocations and net flows for a specific blockchain inside a channel state. | Ledger math must balance exactly. |
 | **Home Ledger** | The ledger tied to the chain where the current channel state is enforced. | This is the authoritative ledger for checkpoint and challenge flows. |
 | **Non-Home Ledger** | A secondary ledger for a blockchain other than the home chain. | Used by escrow and migration flows, not as a synonym for home channel. |
-| **Vault** | Nitronode's per-chain pool of available funds used to cover required locking during transitions. | Cross-chain availability depends on node liquidity in the right vault. |
+| **(Node) Vault** | Nitronode's per-chain pool of available funds used to cover required locking during transitions. | Cross-chain availability depends on node liquidity in the right vault. |
 | **Asset** | A logical value unit, such as USDC, with a symbol and decimal precision independent of any one chain. | The SDK takes asset symbols like `'usdc'`, not token addresses, for high-level channel operations. |
+| **Token** | The per-blockchain contract representation of an Asset. | Nitronode asset config maps an asset symbol to the token address used on each supported chain. |
 | **Decimal** | An exact decimal amount represented with `decimal.js`. | Use `new Decimal(5)`, not JavaScript floating-point numbers, for SDK amounts. |
 | **App Session** | An application extension that commits channel funds into a multi-party off-chain session. | Games, matching, escrow, and other multi-party flows live here. |
 | **Quorum** | The minimum weighted approval needed for an app session state update. | If weights are `[40, 40, 50]` and quorum is `80`, two participants may be enough. |
@@ -39,7 +40,7 @@ Nitrolite lets a user and Nitronode exchange signed channel states off-chain, th
 | **Checkpoint** | The operation of submitting a signed state to the blockchain layer for enforcement. | `client.checkpoint('usdc')` settles the latest agreed state for that asset. |
 | **Nitronode** | The v1 off-chain coordinator that serves RPC, co-signs valid states, tracks channels, and coordinates app sessions. | This is the node your SDK client connects to over WebSocket. |
 | **ChannelHub** | The v1 on-chain entrypoint for channel create, deposit, withdraw, checkpoint, challenge, and close operations. | The SDK hides most contract calls, but this is the contract enforcing the state. |
-| **Migration** | A transition that moves the channel's home-chain relationship as part of cross-chain operation. | Treat it as protocol state movement, not a package upgrade. |
+| **Migration** | A transition that moves the home-chain channel of a specific Asset to another blockchain. | Treat it as protocol state enforcement configuration, not a package upgrade. |
 | **Transition** | A typed operation explaining why the channel state changed. | Every state advancement carries one transition type. |
 
 ## Channel lifecycle statuses

docs/nitrolite/build/getting-started/prerequisites.mdx

@@ -89,8 +89,8 @@ Create `tsconfig.json`:
 {
   "compilerOptions": {
     "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
     "strict": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
@@ -101,6 +101,8 @@ Create `tsconfig.json`:
 }
 ```
 
+This config matches the checked-in Node.js lifecycle example. If your app is built by Vite, webpack, or another bundler, `moduleResolution: "bundler"` can be valid there, but do not use it for a plain `tsc` + `node dist/...` script.
+
 Update `package.json`:
 
 ```json
@@ -121,14 +123,14 @@ Create `.env` for sensitive values:
 # .env - never commit this file
 USER_PRIVATE_KEY=0x...
 APP_PRIVATE_KEY=0x...
-NITRONODE_WS_URL=wss://nitronode-stress.yellow.org/v1/ws
+NITRONODE_WS_URL=<sandbox-url-coming-soon>
 RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
 CHAIN_ID=11155111
 ASSET=yellow
 ```
 
 :::info Test endpoint
-`NITRONODE_WS_URL` should point at a v1 Nitronode endpoint for the environment you are testing against. The quickstart lifecycle example uses the current public stress endpoint and Sepolia test assets.
+`NITRONODE_WS_URL` should point at a v1 Nitronode endpoint for the environment you are testing against. Use the current sandbox or test endpoint provided for your environment until the public sandbox URL is pinned.
 :::
 
 Add local files to `.gitignore`:
@@ -165,7 +167,7 @@ node dist/scripts/create-wallet.js
 
 ### Get Test Tokens
 
-<!-- coming soon: faucet endpoint pending; OQ-6
+<!-- coming soon: faucet endpoint pending
 
 ```bash
 curl -XPOST https://clearnet-sandbox.yellow.com/faucet/requestTokens \

docs/nitrolite/build/getting-started/quickstart.mdx

@@ -39,7 +39,7 @@ Edit `.env`:
 ```bash title=".env"
 USER_PRIVATE_KEY=0x...
 APP_PRIVATE_KEY=0x...
-NITRONODE_WS_URL=wss://nitronode-stress.yellow.org/v1/ws
+NITRONODE_WS_URL=<sandbox-url-coming-soon>
 RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
 CHAIN_ID=11155111
 ASSET=yellow
@@ -50,6 +50,8 @@ OPERATE_AMOUNT=0.001
 WITHDRAW_AMOUNT=0.002
 ```
 
+`CHANNEL_DEPOSIT_AMOUNT` is the amount available in the user's home channel. `APP_DEPOSIT_AMOUNT` is the smaller amount committed from that home-channel balance into the app session.
+
 Use a dedicated test wallet. Do not reuse a wallet that holds mainnet funds.
 
 ## Step 2: Connect clients
@@ -70,6 +72,8 @@ const user = await Client.create(
 
 `createSigners()` derives both signer types the SDK needs: off-chain state signing and on-chain transaction signing.
 
+The checked-in Node.js script also applies `enableNodeLocalAccountTransactions()` after client creation. Public RPC transports need the local account preserved on `writeContract()` calls, otherwise `approveToken()` and `checkpoint()` can fail with viem account errors. Browser wallet apps do not need this shim.
+
 ## Step 3: Prepare the home channel
 
 The script loads Nitronode config, checks the configured asset, sets the asset home blockchain, and prepares the user home channel.
@@ -100,7 +104,7 @@ const definition: AppDefinitionV1 = {
     { walletAddress: appAddress, signatureWeight: 1 },
   ],
   quorum: 2,
-  nonce: BigInt(Date.now()) * 1_000_000n,
+  nonce: BigInt(Date.now()) * 1_000_000n + BigInt(Math.floor(Math.random() * 1_000_000)),
 };
 
 const payload = packCreateAppSessionRequestV1(definition, sessionData);
@@ -115,18 +119,25 @@ const created = await client.createAppSession(definition, sessionData, [userSig,
 The user commits part of the home-channel balance into the app session with a deposit intent:
 
 ```typescript
+const { sessions } = await client.getAppSessions({ appSessionId: created.appSessionId });
+const session = sessions[0];
+
 const update: AppStateUpdateV1 = {
   appSessionId: created.appSessionId,
   intent: AppStateUpdateIntent.Deposit,
-  version: 2n,
+  version: session.version + 1n,
   allocations: [
     { participant: userAddress, asset, amount: appDepositAmount },
     { participant: appAddress, asset, amount: new Decimal(0) },
   ],
   sessionData: JSON.stringify({ intent: 'user_deposit' }),
 };
 
-await client.submitAppSessionDeposit(update, [userSig, appSig], asset, appDepositAmount);
+const updatePayload = packAppStateUpdateV1(update);
+const updateUserSig = await userSessionSigner.signMessage(updatePayload);
+const updateAppSig = await appSessionSigner.signMessage(updatePayload);
+
+await client.submitAppSessionDeposit(update, [updateUserSig, updateAppSig], asset, appDepositAmount);
 ```
 
 ## Step 6: Operate, withdraw, and close

examples/nitrolite-v1-lifecycle/.env.example

@@ -3,12 +3,14 @@ USER_PRIVATE_KEY=0x...
 APP_PRIVATE_KEY=0x...
 
 # Native v1 Nitronode and matching chain RPC.
-NITRONODE_WS_URL=wss://nitronode-stress.yellow.org/v1/ws
+NITRONODE_WS_URL=<sandbox-url-coming-soon>
 RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
 CHAIN_ID=11155111
 ASSET=yellow
 
-# Keep these tiny for docs verification. Adjust for the faucet asset and chain.
+# Keep these tiny for docs verification. CHANNEL_DEPOSIT_AMOUNT funds the
+# user's home channel; APP_DEPOSIT_AMOUNT is committed from that balance into
+# the app session. Adjust both for the faucet asset and chain.
 CHANNEL_DEPOSIT_AMOUNT=0.01
 APP_DEPOSIT_AMOUNT=0.005
 OPERATE_AMOUNT=0.001

examples/nitrolite-v1-lifecycle/README.md

@@ -22,4 +22,8 @@ npm run lifecycle
 
 Use disposable test wallets only. The app signer can be an unfunded test wallet; the user wallet needs Sepolia gas and the selected test asset.
 
+Set `NITRONODE_WS_URL` to the current v1 sandbox or test endpoint provided for your environment before running `npm run lifecycle`.
+
+The script calls `enableNodeLocalAccountTransactions()` after creating each SDK client. This keeps viem's local account attached to `writeContract()` requests in Node.js so `approveToken()` and `checkpoint()` can send transactions through public RPC endpoints. Browser wallet apps do not need this shim.
+
 Set `CLOSE_HOME_CHANNEL=true` only when you intentionally want to close the example home channel after the app-session lifecycle.

i18n/en/docusaurus-theme-classic/footer.json

@@ -21,7 +21,7 @@
   },
   "link.item.label.Build": {
     "message": "Build",
-    "description": "The label of footer link with label=Build linking to /docs/build/quick-start"
+    "description": "The label of footer link with label=Build linking to /nitrolite/build/getting-started/quickstart"
   },
   "link.item.label.Guides": {
     "message": "Guides",