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:
 
@@ -143,14 +143,14 @@ 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 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 **out-of-band** (e.g. over an authenticated HTTP API).
 The bytes never appear on the XRPL ledger.
 
-### 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)):
 
@@ -164,28 +164,28 @@ function executeDirectMintingWithData(
 - `_payment` is the FDC proof of the XRPL `Payment`.
 - `_data` is the ABI-encoded `PackedUserOperation` that was delivered out-of-band.
 - `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 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:
   [
@@ -31,7 +31,7 @@ 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,9 +27,9 @@ 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 Table
 
 | Dimension                          | Custom Instruction (`0xFE`)                                                                   | Raw Custom Instruction (`0xFF`)                                                           |
 | ---------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
@@ -64,7 +64,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:
 

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

@@ -31,16 +31,16 @@ Use the raw flow when you do not want to operate or coordinate with an executor
 
 This guide hits that cap head-on: it executes the same three example calls as the [Custom Instruction TypeScript guide](/smart-accounts/guides/typescript-viem/custom-instruction-ts), but the XRPL memo field is capped at `1024` bytes, and the three calls together exceed that budget when ABI-encoded.
 The script therefore splits the work into two user operations sent in sequence, paying the FAssets minting fee and executor fee on each XRPL payment.
-The same cap is also why some calls - those whose calldata alone overruns the memo budget - cannot be expressed in the 0xFF flow without deploying a shim contract on Flare to compress them.
+The same cap is also why some calls - those whose calldata alone overruns the memo budget - cannot be expressed in the `0xFF` flow without deploying a shim contract on Flare to compress them.
 
 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 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
+## Splitting the Call Array Across Two Payments
 
-XRPL caps the memo at roughly `1024` bytes.
+XRPL caps the memo at `1024` bytes.
 The `pinNotice` call carries a string argument that, together with the other two calls, exceeds that limit, so the script splits the work into two user operations:
 
 ```typescript
@@ -81,7 +81,7 @@ const pinNoticeCalls: Call[] = [
 The `Call` struct fields are the same as for the [custom instruction](/smart-accounts/guides/typescript-viem/custom-instruction-ts#building-the-call-array).
 The split is the entire reason this guide exists: in the [custom instruction flow](/smart-accounts/guides/typescript-viem/custom-instruction-ts) the same three calls fit in a single 42-byte memo, regardless of batch size.
 
-## Encoding the user operation
+## Encoding the User Operation
 
 The XRPL memo carries a 10-byte header followed by an ABI-encoded [`PackedUserOperation`](https://eips.ethereum.org/EIPS/eip-4337#useroperation):
 
@@ -142,9 +142,9 @@ export function encodeExecuteUserOpMemo({
 
 Unlike the custom instruction, which carries only `keccak256(userOp)` in the memo, this header is followed by the full ABI-encoded `PackedUserOperation` - hence the memo cap problem above.
 
-## Sending the user operation
+## Sending the User Operation
 
-The XRPL `Payment` is sent to the FAssets **direct minting payment address** read from the `AssetManagerFXRP` contract - not to an operator wallet.
+The XRPL `Payment` is sent to the FAssets [direct minting payment address](/fassets/reference/IAssetManager#directmintingpaymentaddress) read from the `AssetManagerFXRP` contract - not to an operator wallet.
 The encoded user operation is attached as a memo, with the `0x` prefix removed.
 
 :::warning No destination tags
@@ -196,7 +196,7 @@ export async function sendMemoFieldInstruction({
 There is no `(data, totalCallValue)` to hand off to an executor here: the entire user operation already lives in the memo, so the only handoff is the XRPL payment itself.
 The `xrplClient` and `xrplWallet` are the `Client` and `Wallet` classes from the `xrpl` library, initialized from the `.env` file.
 
-## Waiting for execution
+## Waiting for Execution
 
 Because the raw flow has no executor receipt to parse, the script watches for the `UserOperationExecuted` event with Viem's [`watchContractEvent`](https://viem.sh/docs/contract/watchContractEvent#watchcontractevent), filtering on the personal account and the nonce we submitted:
 
@@ -241,7 +241,7 @@ The bridging is handled by the [Flare Data Connector](/fdc/overview), which caps
 If any inner call reverts, the whole user operation reverts with [`CallFailed`](/smart-accounts/reference/IPersonalAccount#callfailed) and the nonce does not increment.
 The FXRP transfer, however, is performed before the memo is decoded, so the mint succeeds even when the user operation reverts - see [`DirectMintingExecuted`](/smart-accounts/reference/IMasterAccountController#directmintingexecuted).
 
-## Full script
+## Full Script
 
 The repository with the example is available on [GitHub](https://github.com/flare-foundation/flare-viem-starter).
 Helper functions live in the `src/utils` directory.
@@ -250,7 +250,7 @@ Helper functions live in the `src/utils` directory.
   {RawCustomInstructionsScript}
 </CodeBlock>
 
-## Expected output
+## Expected Output
 
 ```bash
 Personal account address: 0xFd2f0eb6b9fA4FE5bb1F7B26fEE3c647ed103d9F