You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/smart-accounts/5-custom-instruction-comparison.mdx
+8-4Lines changed: 8 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,8 +18,10 @@ keywords:
18
18
19
19
Flare Smart Accounts expose two custom instruction memo opcodes that ultimately execute the same `PackedUserOperation` against a personal account:
20
20
21
-
-[**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`.
22
-
-[**Raw Custom Instruction**](/smart-accounts/raw-custom-instruction) - opcode `0xFF`. The XRPL memo contains the ABI-encoded `PackedUserOperation` in full.
The XRPL memo carries only `keccak256(userOp)` in fixed 42 bytes; an off-chain executor delivers the ABI-encoded custom instruction (`userOp`) via `executeDirectMintingWithData`.
The XRPL memo contains the ABI-encoded `PackedUserOperation` in full.
23
25
24
26
Both flows are validated on-chain against the same `(sender, nonce)` rules and emit the same [`UserOperationExecuted`](/smart-accounts/reference/IMasterAccountController#useroperationexecuted) event.
25
27
The difference is purely in how the user-operation bytes travel to Flare, and which actor performs which step.
@@ -46,7 +48,8 @@ The 0xFE memo is a constant 42 bytes regardless of the user operation size, whic
46
48
47
49
**Use the custom instruction (`0xFE`) when**
48
50
49
-
- The user operation's ABI encoding exceeds the XRPL memo cap (long `bytes` arguments, large call batches, or deeply nested structs). Without it, you would either split the logical user operation into multiple XRPL payments (paying minting and executor fees on each) or deploy a Flare-side shim contract to compress the call - the custom instruction eliminates both.
51
+
- The user operation's ABI encoding exceeds the XRPL memo cap (long `bytes` arguments, large call batches, or deeply nested structs).
52
+
Without it, you would either split the logical user operation into multiple XRPL payments (paying minting and executor fees on each) or deploy a Flare-side shim contract to compress the call - the custom instruction eliminates both.
50
53
- You want the call payload to remain off the public XRPL ledger.
51
54
- You already operate an executor that observes XRPL payments and submits Flare transactions - the custom instruction lets that executor batch deliveries or rate-limit submissions without splitting user operations into multiple XRPL payments.
52
55
- You need fee predictability: the XRPL memo is always 42 bytes, so the XRPL fee is constant regardless of how complex the user operation is.
@@ -81,7 +84,8 @@ The example helpers in [`flare-viem-starter`](https://github.com/flare-foundatio
81
84
82
85
A practical decision rule when integrating:
83
86
84
-
1. Default to the custom instruction (`0xFE`). It fits every call batch and keeps the call payload off the public XRPL ledger.
87
+
1. Default to the custom instruction (`0xFE`).
88
+
It fits every call batch and keeps the call payload off the public XRPL ledger.
85
89
2. Reach for the raw custom instruction (`0xFF`) only when you do not want to operate or coordinate with an executor service, and you can guarantee `abi.encode(userOp)` stays well under ~900 bytes (leaving room for the 10-byte header and XRPL framing).
Copy file name to clipboardExpand all lines: docs/smart-accounts/guides/typescript-viem/02-custom-instruction.mdx
+11-5Lines changed: 11 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -148,9 +148,12 @@ The on-chain checks (XRPL signature, `proofOwner` binding, `keccak256(data)` com
148
148
149
149
Each entry in the user operation is a [`Call`](/smart-accounts/reference/IPersonalAccount#call) struct with three fields:
150
150
151
-
-`target` - the address of the Flare contract to invoke. The personal account dispatches the call with itself as `msg.sender`, so this is the contract that ultimately runs the call.
152
-
-`value` - the amount of the native token (FLR on mainnet, C2FLR on Coston2) in wei to attach to the call. The sum of `value` across all calls is what the executor must attach as `msg.value` on `executeDirectMintingWithData` in Step 2; that value flows `AssetManagerFXRP -> MasterAccountController -> PersonalAccount.executeUserOp` and is split back across the inner calls.
153
-
-`data` - the ABI-encoded calldata (4-byte function selector followed by ABI-encoded arguments) the personal account passes to `target`. Use Viem's [`encodeFunctionData`](https://viem.sh/docs/contract/encodeFunctionData) to build it from the contract ABI, function name, and arguments.
151
+
-`target` - the address of the Flare contract to invoke.
152
+
The personal account dispatches the call with itself as `msg.sender`, so this is the contract that ultimately runs the call.
153
+
-`value` - the amount of the native token (FLR on mainnet, C2FLR on Coston2) in wei to attach to the call.
154
+
The sum of `value` across all calls is what the executor must attach as `msg.value` on `executeDirectMintingWithData` in Step 2; that value flows `AssetManagerFXRP -> MasterAccountController -> PersonalAccount.executeUserOp` and is split back across the inner calls.
155
+
-`data` - the ABI-encoded calldata (4-byte function selector followed by ABI-encoded arguments) the personal account passes to `target`.
156
+
Use Viem's [`encodeFunctionData`](https://viem.sh/docs/contract/encodeFunctionData) to build it from the contract ABI, function name, and arguments.
154
157
155
158
```typescript
156
159
exporttypeCall= {
@@ -411,8 +414,11 @@ export async function executeDirectMintingWithData({
411
414
412
415
Two details are critical here:
413
416
414
-
-**`proofOwner`**: the FDC `XRPPayment` request binds the proof to the externally owned account that will eventually submit it. `AssetManagerFXRP` enforces this through `TransactionAttestation.verifyProofOwnership`. Pass the executor's address so the proof can only be used by that executor.
415
-
-**`value`**: `msg.value` on `executeDirectMintingWithData` is forwarded `AssetManager -> MasterAccountController.handleMintedFAssets -> PersonalAccount.executeUserOp`. It must therefore equal the sum of `call.value` across the user operation - exactly the `totalCallValue` returned by Step 1.
417
+
-**`proofOwner`**: the FDC `XRPPayment` request binds the proof to the externally owned account that will eventually submit it.
418
+
`AssetManagerFXRP` enforces this through `TransactionAttestation.verifyProofOwnership`.
419
+
Pass the executor's address so the proof can only be used by that executor.
420
+
-**`value`**: `msg.value` on `executeDirectMintingWithData` is forwarded `AssetManager -> MasterAccountController.handleMintedFAssets -> PersonalAccount.executeUserOp`.
421
+
It must therefore equal the sum of `call.value` across the user operation - exactly the `totalCallValue` returned by Step 1.
Copy file name to clipboardExpand all lines: docs/smart-accounts/reference/IMasterAccountController.mdx
+2-1Lines changed: 2 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -273,7 +273,8 @@ Parameters:
273
273
-`_underlyingTimestamp`: The XRPL transaction timestamp.
274
274
-`_memoData`: The raw XRPL memo bytes carrying the [memo instruction](/smart-accounts/custom-instruction-comparison).
275
275
-`_executor`: The executor address; must equal the personal account's pinned executor when one is set.
276
-
-`_data`: Extra data not contained in the XRPL memo. For the `0xFE` custom instruction this is the ABI-encoded `PackedUserOperation`; for all other instruction IDs it is ignored.
276
+
-`_data`: Extra data not contained in the XRPL memo.
277
+
For the `0xFE` custom instruction this is the ABI-encoded `PackedUserOperation`; for all other instruction IDs it is ignored.
277
278
278
279
The `AssetManager` is the only address allowed to call this function — any other caller reverts with [`OnlyAssetManager`](#onlyassetmanager).
0 commit comments