fix(docs): apply additional suggested changes

Author: nikerzetic-aflabs

docs/smart-accounts/1-overview.mdx

@@ -52,8 +52,8 @@ Flare Smart Accounts support two complementary flows for turning an XRPL `Paymen
 ### Direct-minting (memo) flow
 
 1. The XRPL user sends a `Payment` to an FAssets agent's XRPL address that mints FXRP directly to the smart account, with the [memo field](/smart-accounts/custom-instruction-comparison) carrying the instruction.
-2. The FAssets `AssetManager` mints FXRP to the `MasterAccountController` and calls back into [`handleMintedFAssets`](/smart-accounts/reference/IMasterAccountController#handlemintedfassets) on `MemoInstructionsFacet`.
-3. The facet routes the FAssets to the user's `PersonalAccount`, optionally pays an executor fee, and dispatches any memo instruction (`0xFF` execute UserOp, `0xE0` ignore memo, `0xE1` set nonce, `0xE2` replace fee, `0xD0`/`0xD1` set/remove executor).
+2. The FAssets `AssetManager` mints FXRP to the `MasterAccountController` and calls back into [`handleMintedFAssets`](/smart-accounts/reference/IMasterAccountController#handlemintedfassets).
+3. The `MasterAccountController` routes the FAssets to the user's `PersonalAccount`, optionally pays an executor fee, and dispatches any [memo instruction](#memo-opcodes-direct-minting-flow).
 
 ```mermaid
 graph TB
@@ -106,7 +106,7 @@ The first nibble is the instruction type.
 This is either `FXRP`, `Firelight`, or `Upshift` (with corresponding type IDS `0`, `1`, and `2`).
 The second nibble is the instruction command; the available commands are different for each instruction type.
 
-For the direct-minting flow, the memo carries a different layout - see the [Custom Instruction guide](/smart-accounts/custom-instruction) for the 0xFE variant, the [Raw Custom Instruction guide](/smart-accounts/raw-custom-instruction) for the `PackedUserOperation` format, or the [comparison](/smart-accounts/custom-instruction-comparison) of `0xFE`/`0xFF` and the executor-management codes `0xE0`/`0xE1`/`0xE2`/`0xD0`/`0xD1`.
+For the direct-minting flow, the memo carries a different layout; the first byte selects one of the [memo opcodes](#memo-opcodes-direct-minting-flow) listed below.
 
 <details>
   <summary>Table of instruction IDs and corresponding actions.</summary>
@@ -151,12 +151,28 @@ Instructions for interacting with an Upshift-type vault.
 
 </details>
 
+### Memo opcodes (direct-minting flow)
+
+The XRPL memo for the direct-minting flow selects one of the following opcodes in its first byte:
+
+| Memo opcode | Action                 | Description                                                                                                                                       |
+| ----------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `0xFE`      | Custom Instruction     | Carry `keccak256(PackedUserOperation)` in the memo; the bytes are delivered off-chain by an executor. See [Custom Instruction](/smart-accounts/custom-instruction). |
+| `0xFF`      | Raw Custom Instruction | Carry the full ABI-encoded `PackedUserOperation` inline in the memo. See [Raw Custom Instruction](/smart-accounts/raw-custom-instruction).        |
+| `0xE0`      | Skip memo              | Mark a target XRPL transaction's memo to be skipped on its next direct mint.                                                                      |
+| `0xE1`      | Fast-forward nonce     | Advance the personal account's memo-instruction nonce.                                                                                            |
+| `0xE2`      | Replace executor fee   | Set a replacement executor fee for a stuck XRPL transaction.                                                                                      |
+| `0xD0`      | Pin executor           | Pin a specific executor address to the personal account.                                                                                          |
+| `0xD1`      | Unpin executor         | Unpin the executor from the personal account.                                                                                                     |
+
+The [Custom Instruction Comparison](/smart-accounts/custom-instruction-comparison) covers when to choose `0xFE` over `0xFF`.
+
 ## Dispatch on Flare
 
 ### Proof-based flow
 
 The operator monitors incoming transactions to the specified XRPL address.
-Upon receiving a payment, it requests a [`Payment` attestation](/fdc/attestation-types/payment) from the FDC and submits the proof together with the user's XRPL address to the appropriate facet on the `MasterAccountController`:
+Upon receiving a payment, it requests a [`Payment` attestation](/fdc/attestation-types/payment) from the FDC and submits the proof together with the user's XRPL address to the appropriate function on the `MasterAccountController`:
 
 - [`reserveCollateral`](/smart-accounts/reference/IMasterAccountController#reservecollateral) — for command `00` of any instruction type.
   Takes the payment reference and XRPL transaction ID (no FDC proof needed at this stage, the user has only committed to mint).
@@ -173,8 +189,8 @@ The contract then resolves the XRPL user's `PersonalAccount` from the address ma
 
 ### Direct-minting flow
 
-When the user mints FXRP directly to their smart account via [FAssets direct minting](/fassets/direct-minting), the FAssets `AssetManager` calls back into [`handleMintedFAssets`](/smart-accounts/reference/IMasterAccountController#handlemintedfassets) on `MemoInstructionsFacet`.
-It enforces that the caller is the `AssetManager`, resolves (or deploys) the user's `PersonalAccount`, pays an executor fee out of the minted FAssets, forwards the remainder to the personal account, and dispatches any memo instruction (`0xFF`, `0xFE`, `0xE0`, `0xE1`, `0xE2`, `0xD0`, `0xD1`).
+When the user mints FXRP directly to their smart account via [FAssets direct minting](/fassets/direct-minting), the FAssets `AssetManager` calls back into [`handleMintedFAssets`](/smart-accounts/reference/IMasterAccountController#handlemintedfassets) on the `MasterAccountController`.
+It enforces that the caller is the `AssetManager`, resolves (or deploys) the user's `PersonalAccount`, pays an executor fee out of the minted FAssets, forwards the remainder to the personal account, and dispatches any [memo instruction](#memo-opcodes-direct-minting-flow).
 
 ## Actions on Flare
 

docs/smart-accounts/3-custom-instruction.mdx

@@ -3,7 +3,7 @@ sidebar_position: 1
 slug: custom-instruction
 title: Custom Instruction
 authors: [nikerzetic]
-description: Performing custom function calls in the Flare Smart Accounts by committing to a PackedUserOperation hash on XRPL and delivering the bytes via an executor (0xFE).
+description: Performing custom function calls in Flare Smart Accounts via XRPL payments with an off-chain executor.
 tags: [intermediate, ethereum, flare-smart-accounts]
 keywords:
   [

docs/smart-accounts/4-raw-custom-instruction.mdx

@@ -40,7 +40,7 @@ The XRPL memo carries a 10-byte instruction header followed by the ABI-encoded `
 | `0`   | `instructionId`  | `0xFF` - raw custom instruction                                        |
 | `1`   | `walletId`       | One-byte wallet identifier assigned by Flare; `0` if not registered    |
 | `2-9` | `executorFeeUBA` | Executor fee in the FAsset's smallest unit, big-endian `uint64`        |
-| `10+` | `userOpData`     | `abi.encode(PackedUserOperation)` - the call payload the facet decodes |
+| `10+` | `userOpData`     | `abi.encode(PackedUserOperation)` - the call payload the controller decodes |
 
 The total memo length is `10 + len(abi.encode(userOp))` bytes.
 The XRPL caps each memo at `1024` bytes, so large or repetitive call batches must be split across multiple XRPL payments - each of which pays its own FAssets minting fee and executor fee - and a single call whose ABI-encoded calldata alone exceeds the budget cannot be expressed at all without deploying a shim contract on Flare to compress it.

docs/smart-accounts/guides/typescript-viem/02-custom-instruction.mdx

@@ -3,7 +3,7 @@ sidebar_position: 2
 slug: custom-instruction-ts
 title: Custom Instruction
 authors: [nikerzetic]
-description: Sending only keccak256(userOp) on XRPL and delivering the PackedUserOperation bytes via an executor (0xFE flow).
+description: Sending custom smart account instructions via XRPL using Viem and an off-chain executor.
 tags: [quickstart, ethereum, flare-smart-accounts]
 keywords:
   [
@@ -20,13 +20,16 @@ unlisted: false
 import CodeBlock from "@theme/CodeBlock";
 import CustomInstructionsScript from "!!raw-loader!/examples/developer-hub-javascript/smart-accounts/custom-instructions.ts";
 
-The [Custom Instruction overview](/smart-accounts/custom-instruction) introduces the 0xFE memo opcode, which keeps the XRPL memo at a fixed 42 bytes by carrying only `keccak256(PackedUserOperation)` and delivers the user operation bytes to Flare through an off-chain executor.
+The [Custom Instruction overview](/smart-accounts/custom-instruction) introduces the `0xFE` memo opcode, which keeps the XRPL memo at a fixed 42 bytes by carrying only `keccak256(PackedUserOperation)` and delivers the user operation bytes to Flare through an off-chain executor.
 This guide walks through a TypeScript script that drives all three steps of the protocol with Viem and the [Flare Data Connector (FDC)](/fdc/overview).
 
 A prerequisite for the user operation to be executed is that the personal account holds enough native tokens to cover the call values.
 The script forwards a total of `2` C2FLR (Coston2 Flare native tokens), so fund the personal account from the [Flare faucet](https://faucet.flare.network/coston2) before running it.
 The [State Lookup guide](/smart-accounts/guides/typescript-viem/state-lookup-ts#personal-account-of-an-xrpl-address) shows how to derive the personal account address.
 
+The XRPL wallet that signs the `Payment` also needs enough XRP to cover the payment amount (net mint plus fees, computed below).
+Before sending, the script reads the wallet's XRP balance with the `getXrpBalance` helper and aborts if it is below the required amount.
+
 The full code is available on [GitHub](https://github.com/flare-foundation/flare-viem-starter/blob/main/src/custom-instructions.ts).
 
 ## Contracts
@@ -288,6 +291,52 @@ export async function computeDirectMintingPaymentAmountXrp({
 
 The script also mints `10` FXRP as a side effect of the same payment, so the payment amount includes the net mint amount on top of the fees.
 
+## Checking the XRPL Wallet Balance
+
+The signer of the XRPL `Payment` must hold at least `paymentAmountXrp` XRP, otherwise the payment will fail when submitted to the network.
+The `getXrpBalance` helper issues an [`account_info`](https://xrpl.org/account_info.html) request against the validated ledger and returns the wallet's balance in XRP.
+It reuses the caller's `Client` when one is passed in, and otherwise opens and closes its own connection:
+
+```typescript
+export async function getXrpBalance(
+  xrplAddress: string,
+  client?: Client,
+): Promise<number> {
+  const ownsClient = client === undefined;
+  const xrplClient = client ?? new Client(process.env.XRPL_TESTNET_RPC_URL!);
+  if (!xrplClient.isConnected()) {
+    await xrplClient.connect();
+  }
+  try {
+    const response = await xrplClient.request({
+      command: "account_info",
+      account: xrplAddress,
+      ledger_index: "validated",
+    });
+    return Number(dropsToXrp(response.result.account_data.Balance));
+  } finally {
+    if (ownsClient) {
+      await xrplClient.disconnect();
+    }
+  }
+}
+```
+
+The `main` function calls it right after computing `paymentAmountXrp` and aborts before touching XRPL if the wallet is short.
+Failing fast here avoids a half-committed flow where the XRPL submission errors out after the user has already paid gas on Flare for unrelated reads:
+
+```typescript
+const xrpBalance = await getXrpBalance(xrplWallet.address, xrplClient);
+if (xrpBalance < paymentAmountXrp) {
+  throw new Error(
+    `Insufficient XRP balance on ${xrplWallet.address}: have ${xrpBalance} XRP, need ${paymentAmountXrp} XRP`,
+  );
+}
+```
+
+This check covers only the payment amount; the XRPL network also requires the account to keep its base reserve, which is not subtracted here.
+If the wallet's spendable balance is close to the reserve, the payment can still fail with `tecUNFUNDED_PAYMENT` even though this check passes.
+
 ## Step 1: Send the hash memo on XRPL
 
 The user-side helper function computes the memo, sends the XRPL `Payment` to the FAssets direct-minting address, and returns everything the executor needs to drive Step 2:
@@ -503,6 +552,8 @@ Personal account address: 0xFd2f0eb6b9fA4FE5bb1F7B26fEE3c647ed103d9F
 
 Payment amount (XRP, net mint + fees): 10.2
 
+XRPL wallet XRP balance: 1000
+
 [hash-instruction-batch] calls: [
   {
     target: '0xEE6D54382aA623f4D16e856193f5f8384E487002',

docs/smart-accounts/guides/typescript-viem/03-raw-custom-instruction.mdx

@@ -38,6 +38,19 @@ The same cap is also why some calls - those whose calldata alone overruns the me
 A prerequisite for the user operation to be executed is that the personal account holds enough native tokens to cover the call values.
 The script calls forward a total of `2` C2FLR (Coston2 Flare native tokens), so fund the personal account from the [Flare faucet](https://faucet.flare.network/coston2) before running it.
 
+The XRPL wallet must also cover the **sum** of both payments, `paymentAmountXrp + memoOnlyAmountXrp`, since the raw flow splits the batch into two XRPL `Payment` transactions.
+The script reads the wallet's balance with the shared [`getXrpBalance`](/smart-accounts/guides/typescript-viem/custom-instruction-ts#checking-the-xrpl-wallet-balance) helper and aborts before sending either payment if the wallet is short, so neither half of the batch is submitted on partial funding:
+
+```typescript
+const totalRequiredXrp = paymentAmountXrp + memoOnlyAmountXrp;
+const xrpBalance = await getXrpBalance(xrplWallet.address, xrplClient);
+if (xrpBalance < totalRequiredXrp) {
+  throw new Error(
+    `Insufficient XRP balance on ${xrplWallet.address}: have ${xrpBalance} XRP, need ${totalRequiredXrp} XRP (both payments)`,
+  );
+}
+```
+
 The full code is available on [GitHub](https://github.com/flare-foundation/flare-viem-starter/blob/main/src/custom-instructions-raw.ts).
 
 ## Splitting the Call Array Across Two Payments
@@ -261,6 +274,8 @@ Payment amount (XRP, net mint + fees): 10.0011
 
 Memo-only amount (XRP, fees only): 0.0011
 
+XRPL wallet XRP balance: 1000
+
 [checkpoint-and-deposit] calls: [
   {
     target: '0xEE6D54382aA623f4D16e856193f5f8384E487002',

examples/developer-hub-javascript/smart-accounts/custom-instructions-raw.ts

@@ -9,6 +9,7 @@ import {
   type Call,
 } from "./utils/smart-accounts";
 import { computeDirectMintingPaymentAmountXrp } from "./utils/fassets";
+import { getXrpBalance } from "./utils/xrpl";
 
 // NOTE:(Nik) For this example to work, you first need to faucet C2FLR to your personal account address.
 async function main() {
@@ -73,6 +74,15 @@ async function main() {
   console.log("Payment amount (XRP, net mint + fees):", paymentAmountXrp, "\n");
   console.log("Memo-only amount (XRP, fees only):", memoOnlyAmountXrp, "\n");
 
+  const totalRequiredXrp = paymentAmountXrp + memoOnlyAmountXrp;
+  const xrpBalance = await getXrpBalance(xrplWallet.address, xrplClient);
+  console.log("XRPL wallet XRP balance:", xrpBalance, "\n");
+  if (xrpBalance < totalRequiredXrp) {
+    throw new Error(
+      `Insufficient XRP balance on ${xrplWallet.address}: have ${xrpBalance} XRP, need ${totalRequiredXrp} XRP (both payments)`,
+    );
+  }
+
   await sendMemoFieldInstruction({
     label: "checkpoint-and-deposit",
     calls: checkpointAndDepositCalls,

examples/developer-hub-javascript/smart-accounts/custom-instructions.ts

@@ -11,6 +11,7 @@ import {
   type Call,
 } from "./utils/smart-accounts";
 import { computeDirectMintingPaymentAmountXrp } from "./utils/fassets";
+import { getXrpBalance } from "./utils/xrpl";
 
 // NOTE:(Nik) For this example to work, you first need to faucet C2FLR to your personal account address.
 //
@@ -80,6 +81,14 @@ async function main() {
   console.log("Personal account address:", personalAccount, "\n");
   console.log("Payment amount (XRP, net mint + fees):", paymentAmountXrp, "\n");
 
+  const xrpBalance = await getXrpBalance(xrplWallet.address, xrplClient);
+  console.log("XRPL wallet XRP balance:", xrpBalance, "\n");
+  if (xrpBalance < paymentAmountXrp) {
+    throw new Error(
+      `Insufficient XRP balance on ${xrplWallet.address}: have ${xrpBalance} XRP, need ${paymentAmountXrp} XRP`,
+    );
+  }
+
   // --- 1. USER SIDE -------------------------------------------------------
   // Send the XRPL Payment carrying the 32-byte UserOp hash in the memo. The
   // full PackedUserOperation bytes (returned as `data`) never go onto XRPL.