fix(docs): apply suggested changes

Co-authored-by: Kristaps Grinbergs <fassko@gmail.com>

Author: nikerzetic-aflabs

docs/smart-accounts/1-overview.mdx

@@ -174,13 +174,13 @@ 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`.
-The facet 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`).
+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`).
 
 ## Actions on Flare
 
 The XRPL user's smart account performs the actions in the instructions.
 This can be any of the instructions listed above, reserving collateral for minting FXRP, transferring FXRP to another address, redeeming FXRP, depositing it into a vault ...
-Furthermore, custom instructions can be executed - arbitrary function calls on Flare, encoded as an EIP-4337 `PackedUserOperation` and replayed on-chain by the personal account.
+Furthermore, custom instructions can be executed - arbitrary function calls on Flare, encoded as an [EIP-4337](https://eips.ethereum.org/EIPS/eip-4337) `PackedUserOperation` and replayed on-chain by the personal account.
 The user operation can be committed to as a 32-byte hash with the bytes delivered to Flare by an off-chain executor (opcode `0xFE`, see the [Custom Instruction guide](/smart-accounts/custom-instruction)), or carried in the XRPL memo in full (opcode `0xFF`, see the [Raw Custom Instruction guide](/smart-accounts/raw-custom-instruction)).
 Authorization comes from the XRPL `Payment` signature itself; the on-chain check only validates the `sender` and `nonce` fields of the `PackedUserOperation`.
 The [Custom Instruction Comparison](/smart-accounts/custom-instruction-comparison) covers when to pick each.

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

@@ -33,17 +33,17 @@ XRPL transactions targeting smart accounts must not use a destination tag.
 A destination tag forces [FAssets direct minting](/fassets/direct-minting) to credit the tag-holder, which would let an unrelated party front-run the user operation.
 :::
 
-## User operation payload
+## User Operation Payload
 
-A custom instruction has two layers: the outer EIP-4337 [`PackedUserOperation`](https://eips.ethereum.org/EIPS/eip-4337#useroperation) that the XRPL memo commits to, and the inner [`executeUserOp(Call[])`](/smart-accounts/reference/IPersonalAccount#executeuserop) that the personal account runs once the controller dispatches it.
+A custom instruction has two layers: the outer [EIP-4337](https://eips.ethereum.org/EIPS/eip-4337) [`PackedUserOperation`](https://eips.ethereum.org/EIPS/eip-4337#useroperation) that the XRPL memo commits to, and the inner [`executeUserOp(Call[])`](/smart-accounts/reference/IPersonalAccount#executeuserop) that the personal account runs once the controller dispatches it.
 
 Only three fields from the [`PackedUserOperation`](https://eips.ethereum.org/EIPS/eip-4337#useroperation) struct are required for Flare Smart Accounts:
 
 - `sender` **must** equal the address of the personal account derived from the XRPL sender.
   Use [`getPersonalAccount`](/smart-accounts/reference/IMasterAccountController#getpersonalaccount) to look it up - the address is deterministic, so you can fetch it before the account is even deployed.
 - `nonce` **must** equal the personal account's current nonce returned by [`getNonce`](/smart-accounts/reference/IMasterAccountController#getnonce).
   The nonce auto-increments on every successful execution to prevent replay.
-- `callData` is the calldata that the controller invokes on the personal account.
+- `callData` is the data that the controller invokes on the personal account.
   In practice, this is `abi.encodeCall(IPersonalAccount.executeUserOp, (calls))` - anything else either reverts or is rejected by the personal account's `onlyController` modifier.
 
 The remaining fields are not validated on-chain and can be left empty.
@@ -98,7 +98,7 @@ const callData = encodeFunctionData({
 
 The encoded `callData` becomes the `callData` field of the `PackedUserOperation` that the XRPL memo commits to.
 
-## Memo layout
+## Memo Layout
 
 The custom instruction memo is a constant 42 bytes:
 
@@ -115,9 +115,9 @@ This is the main practical advantage over the [Raw Custom Instruction](/smart-ac
 The off-chain delivery also makes the call payload **private on XRPL**.
 Only the 32-byte commitment is published; the inner `target`, `value`, and `data` of each call only become visible when the executor submits the user operation to Flare.
 
-## Three-step protocol
+## Three-step Protocol
 
-The 0xFE flow runs three steps that map onto two independent actors in production.
+The `0xFE` flow runs three steps that map onto two independent actors.
 A demo script can run all three from the same process, but the on-chain checks are designed around the two-actor split.
 The executor bridges the XRPL payment to Flare with a proof from the [Flare Data Connector (FDC)](/fdc/overview), the same attestation system used by the proof-based flow:
 
@@ -133,7 +133,7 @@ sequenceDiagram
     User->>User: 1. encode UserOp
     User->>User: compute keccak256(userOp)
     User->>XRPL: 2. Payment to direct-minting<br/>address with 42-byte memo<br/>[0xFE][walletId][fee][hash]
-    Note over Executor: receives userOp bytes<br/>out-of-band
+    Note over Executor: receives userOp bytes<br/>off-chain
 
     Executor->>Executor: 3. fetch FDC XRPPayment proof
     Executor->>AM: 4. executeDirectMintingWithData(proof, data)<br/>{value: sum(call.value)}
@@ -143,16 +143,15 @@ sequenceDiagram
     MasterAccountController-->>User: UserOperationExecuted event
 ```
 
-### Step 1: user side
+### Step 1: User Side
 
 The user constructs the `PackedUserOperation` as described in [User operation payload](#user-operation-payload), computes `keccak256` over the ABI encoding, and packs the 42-byte memo from [Memo layout](#memo-layout).
 
-The user sends an XRPL `Payment` to the FAssets direct-minting address with this memo, and delivers the full `PackedUserOperation` bytes to the executor **out-of-band** (e.g. over an authenticated HTTP API).
-The bytes never appear on the XRPL ledger.
+The user sends an XRPL `Payment` to the FAssets [direct minting address](/fassets/reference/IAssetManager#directmintingpaymentaddress) with this memo, and delivers the full `PackedUserOperation` bytes to the executor **off-chain** (e.g. over an authenticated HTTP API).
 
-### Step 2: executor side
+### Step 2: Executor Side
 
-The executor takes the XRPL transaction hash, requests an [`IXRPPayment` attestation](/fdc/attestation-types/payment) from the [Flare Data Connector](/fdc/overview), and calls `executeDirectMintingWithData` on `AssetManagerFXRP` (see the [FAssets direct minting page](/fassets/direct-minting)):
+The executor takes the XRPL transaction hash, requests an [`XRPPayment` attestation](/fdc/attestation-types/xrp-payment) from the [Flare Data Connector](/fdc/overview), and calls `executeDirectMintingWithData` on `AssetManagerFXRP` (see the [FAssets direct minting page](/fassets/direct-minting)):
 
 ```solidity
 function executeDirectMintingWithData(
@@ -162,30 +161,30 @@ function executeDirectMintingWithData(
 ```
 
 - `_payment` is the FDC proof of the XRPL `Payment`.
-- `_data` is the ABI-encoded `PackedUserOperation` that was delivered out-of-band.
+- `_data` is the ABI-encoded `PackedUserOperation` that was delivered off-chain.
 - `msg.value` **must equal the sum of `call.value` across the user operation**.
-  `AssetManagerFXRP` forwards this value into `MasterAccountController.handleMintedFAssets`, which forwards it again into the personal account's `executeUserOp` so the inner calls can attach native value.
+  The `AssetManagerFXRP` forwards this value to the `MasterAccountController` function `handleMintedFAssets`, which forwards it to the personal account's `executeUserOp` function so that the inner calls can attach the native value.
 
 The `executeDirectMintingWithData` function is **only valid for smart-account targets** - calling it for a non-smart-account direct mint reverts.
 
-### Step 3: confirmation
+### Step 3: Confirmation
 
 The `MasterAccountController` verifies on-chain that `keccak256(_data) == userOpHash` from the memo.
 If it matches, it decodes `_data` as a `PackedUserOperation`, validates `sender` and `nonce`, executes `executeUserOp` on the personal account, and emits [`UserOperationExecuted`](/smart-accounts/reference/IMasterAccountController#useroperationexecuted) - **all inside the executor's transaction**.
 This is the key difference from the proof-based dispatch: there is no separate cross-chain wait, because the executor's call already executed the user operation by the time it returns.
 
-## Hash mismatch
+## Hash Mismatch
 
 If the bytes the executor submits do not hash to the commitment in the memo, `handleMintedFAssets` reverts with `CustomInstructionHashMismatch(expected, actual)`.
-The FAsset transfer is performed before the memo is decoded, however, so even on a mismatch the FXRP credited by direct minting remains in the personal account, and the user can recover by issuing a fresh user operation (see [Failure Handling](#failure-handling)).
+The FAsset transfer is performed before the memo is decoded, however, so even on a mismatch the FXRP credited by direct minting remains in the personal account, and the user can recover by issuing a new user operation (see [Failure Handling](#failure-handling)).
 
-## Call value accounting
+## Call Value Accounting
 
 Whatever native value the executor attaches to `executeDirectMintingWithData` is forwarded all the way to `executeUserOp` (`AssetManagerFXRP -> MasterAccountController.handleMintedFAssets -> PersonalAccount.executeUserOp`).
-The executor must therefore compute the total native value to attach as the sum of `call.value` across the user operation it received out-of-band.
+The executor must therefore compute the total native value to attach as the sum of `call.value` across the user operation it received off-chain.
 The user-side helper in the [TypeScript guide](/smart-accounts/guides/typescript-viem/custom-instruction-ts) returns this value alongside the XRPL transaction hash, so the executor does not have to recompute it from scratch.
 
-## Replay protection
+## Replay Protection
 
 Two replay-protection layers gate every custom instruction:
 

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

@@ -3,7 +3,7 @@ sidebar_position: 1
 slug: raw-custom-instruction
 title: Raw Custom Instruction
 authors: [nikerzetic]
-description: Performing custom function calls in the Flare Smart Accounts by carrying the full PackedUserOperation in the XRPL memo (0xFF).
+description: Performing custom function calls in the Flare Smart Accounts by carrying the full PackedUserOperation in the XRPL memo.
 tags: [intermediate, ethereum, flare-smart-accounts]
 keywords:
   [
@@ -24,14 +24,14 @@ Reach for the raw variant when you do not want to operate or coordinate with an
 The [comparison guide](/smart-accounts/custom-instruction-comparison) breaks down when each is appropriate.
 
 This page covers only what differs from the [Custom Instruction](/smart-accounts/custom-instruction).
-For the [`PackedUserOperation` construction](/smart-accounts/custom-instruction#user-operation-payload) (`sender`, `nonce`, `callData`), the [`Call` struct](/smart-accounts/custom-instruction#executeuserop-and-the-call-struct), and how to [build `callData` in TypeScript](/smart-accounts/custom-instruction#building-calldata-in-typescript), refer to the Custom Instruction page.
+For the [`PackedUserOperation` construction](/smart-accounts/custom-instruction#user-operation-payload) (`sender`, `nonce`, `callData`), the [`Call` struct](/smart-accounts/custom-instruction#executeuserop-and-the-call-struct), and how to [build `callData` in TypeScript](/smart-accounts/custom-instruction#building-calldata-in-typescript), refer to the [Custom Instruction page](/smart-accounts/custom-instruction).
 
 :::warning No destination tags
 XRPL transactions targeting smart accounts must not use a destination tag.
 A destination tag forces [FAssets direct minting](/fassets/direct-minting) to credit the tag-holder, which would let an unrelated party front-run the user operation.
 :::
 
-## Memo layout
+## Memo Layout
 
 The XRPL memo carries a 10-byte instruction header followed by the ABI-encoded `PackedUserOperation`:
 
@@ -45,12 +45,12 @@ The XRPL memo carries a 10-byte instruction header followed by the ABI-encoded `
 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.
 
-## Dispatch flow
+## Dispatch Flow
 
 A single XRPL payment drives the whole flow: the FAssets `AssetManager` mints FXRP into the smart account, calls `MasterAccountController.handleMintedFAssets`, and the controller decodes the `PackedUserOperation` directly from the memo bytes (no `_data` parameter, no hash check) before dispatching `executeUserOp` on the personal account.
 There is no executor split: any indexer that observes the XRPL payment can submit the FDC proof through `executeDirectMinting(proof)`, and the `MasterAccountController` validates the same `sender`, `nonce`, and `callData` fields as for the [custom instruction](/smart-accounts/custom-instruction#user-operation-payload).
 
-## Replay protection
+## Replay Protection
 
 Each personal account maintains a monotonically increasing nonce, accessible via [`getNonce`](/smart-accounts/reference/IMasterAccountController#getnonce).
 A successful `executeUserOp` increments the nonce and emits [`UserOperationExecuted`](/smart-accounts/reference/IMasterAccountController#useroperationexecuted), so the same `PackedUserOperation` cannot be re-executed.
@@ -68,7 +68,7 @@ The whole pipeline is atomic with respect to the user operation:
 Because the FXRP transfer is performed before the memo is decoded, **the mint succeeds even if the user operation reverts** - see [`DirectMintingExecuted`](/smart-accounts/reference/IMasterAccountController#directmintingexecuted).
 The freshly minted FXRP remains in the personal account, and the user can either re-submit a fixed user operation or transfer the FXRP to another address via standard [FAssets instructions](/smart-accounts/fasset-instructions).
 
-## Next steps
+## Next Steps
 
 - Walk through a Viem implementation in the [Raw Custom Instruction TypeScript guide](/smart-accounts/guides/typescript-viem/raw-custom-instruction-ts).
 - Read the [Custom Instruction](/smart-accounts/custom-instruction) for the recommended hash-commitment variant.

docs/smart-accounts/5-custom-instruction-comparison.mdx

@@ -16,7 +16,7 @@ keywords:
   ]
 ---
 
-Flare Smart Accounts expose two custom instruction memo opcodes that ultimately execute the same `PackedUserOperation` against a personal account:
+Flare Smart Accounts expose two custom instruction memo opcodes that ultimately execute the same `PackedUserOperation` in the personal account scope:
 
 - [**Custom Instruction**](/smart-accounts/custom-instruction) - opcode `0xFE`.
   The XRPL memo carries only `keccak256(userOp)` in fixed 42 bytes; an off-chain executor delivers the ABI-encoded custom instruction (`userOp`) via `executeDirectMintingWithData`.
@@ -27,11 +27,11 @@ Both flows are validated on-chain against the same `(sender, nonce)` rules and e
 The difference is purely in how the user-operation bytes travel to Flare, and which actor performs which step.
 
 The hash-based flow was added because the XRPL `Payment` memo is capped at `1024` bytes - small enough that non-trivial user operations either had to be split across multiple XRPL payments (each paying its own minting and executor fees) or routed through purpose-built shim contracts on Flare that compressed the call into something memo-sized.
-The 0xFE memo is a constant 42 bytes regardless of the user operation size, which removes the need for both workarounds.
+The `0xFE` memo is a constant 42 bytes regardless of the user's operation size, removing the need for both workarounds.
 
-## Side-by-side
+## Comparison
 
-| Dimension                          | Custom Instruction (`0xFE`)                                                                   | Raw Custom Instruction (`0xFF`)                                                           |
+| Dimension                          | [Custom Instruction](/smart-accounts/custom-instruction) (`0xFE`)                             | [Raw Custom Instruction](/smart-accounts/raw-custom-instruction) (`0xFF`)                 |
 | ---------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
 | XRPL memo payload                  | 10-byte header + `keccak256(userOp)` (fixed 42 bytes)                                         | 10-byte header + `abi.encode(PackedUserOperation)`                                        |
 | XRPL memo size                     | Constant 42 bytes regardless of batch size                                                    | Grows linearly with batch and argument sizes; capped at ~1024 bytes                       |
@@ -44,8 +44,6 @@ The 0xFE memo is a constant 42 bytes regardless of the user operation size, whic
 | Replay protection                  | Same as raw - plus the on-chain hash check pins `_data` to the memo's commitment              | Personal account nonce + `usedTransactionIds`                                             |
 | Failure modes specific to the flow | `CustomInstructionHashMismatch` if `keccak256(_data)` differs from the commitment             | None beyond shared ones                                                                   |
 
-## When to use which
-
 **Use the custom instruction (`0xFE`) when**
 
 - The user operation's ABI encoding exceeds the XRPL memo cap (long `bytes` arguments, large call batches, or deeply nested structs).
@@ -64,7 +62,7 @@ The 0xFE memo is a constant 42 bytes regardless of the user operation size, whic
 In short, the custom instruction trades a small amount of off-chain coordination (and one extra on-chain proof-binding check) for a fixed memo size and private payloads.
 The raw custom instruction trades memo bandwidth for end-to-end simplicity.
 
-## What stays the same
+## Similarities
 
 The two flows share more than they differ: