docs: add Arc Transaction Memo integration example with Multi-Agent O…

[consumeobeydie]

Summary

This PR adds an example showing how to integrate Arc's newly announced Transaction Memos feature (June 18, 2026) with an existing contract, without modifying it.

What's included

• Predeployed Memo contract address and function signature
• Step-by-step calldata construction example
• Common pitfalls discovered during integration (empty revert data, inner call requirements, bytes32 formatting)
• Live verified transaction on Arc Testnet

Live Verification

Tested against the MultiAgentOrchestrator contract from arc-multi-agent:

• Memo contract: 0x5294E9927c3306DcBaDb03fe70b92e01cCede505
• Target: 0xe81f5BA4181eA29061C3C229c8D6EB4cFE56639C
• Tx: https://testnet.arcscan.app/tx/0x7532ce470169e2db2be43e5f9c43dd523d21e9071c04268ff5941f8ca839ef7b
• Status: Success, confirmed in 0.58 seconds

Note on signature derivation

Since the official ABI wasn't published in docs.arc.io at the time of writing, the function signature was reverse-engineered by inspecting the Memo contract bytecode dispatcher and decoding a real on-chain transaction's calldata.

Related PRs

This is the 9th example added to this series:
1-8. Foundry, X402, ERC-8004, ERC-8183, Unified Flow, Dashboard, MCP Server, Multi-Agent
9. Transaction Memo integration (this PR)

[osr21]

Great work documenting this — we've been integrating the Memo precompile into Arc Swap (a token swap + gasless payment DApp on Arc Testnet) and have some findings that might be useful.

The function name is memo, not callWithMemo

The selector 0xc3b2c4f8 you correctly decoded from on-chain calldata corresponds to:

memo(address target, bytes data, bytes32 memoId, bytes memoData)

Not callWithMemo(address,bytes,bytes32,string) — that signature produces selector 0x688231a5. Since function names aren't stored in bytecode, the reverse-engineering step gets the selector right but the name is a guess. We discovered the actual name from a working integration where we pass the ABI explicitly to viem and have confirmed live transactions.

The 4th parameter is also bytes not string (same ABI encoding, but matters for the selector).

There's also a simpler single-argument overload

memo(bytes data)   →   selector 0x58ea363f

This one attaches metadata to the current transaction without routing an inner call — useful for fire-and-forget labeling where you don't need atomicity with another call.

Two integration patterns we've confirmed live

Pattern 1 — atomic inner call (payment route): wraps an ERC20 transfer so the payment and its metadata land in one atomic on-chain event.

// viem — calls memo(address,bytes,bytes32,bytes)
const transferCalldata = encodeFunctionData({
  abi: ERC20_ABI,
  functionName: "transfer",
  args: [recipient, amountOut],
});

const memoId = `0x${(BigInt(Date.now()) * 0x100000000n + BigInt(randPart))
  .toString(16).padStart(64, "0")}` as `0x${string}`;

await walletClient.writeContract({
  address: "0x5294E9927c3306DcBaDb03fe70b92e01cCede505",
  abi: [{ name: "memo", type: "function", stateMutability: "nonpayable",
    inputs: [
      { name: "target",   type: "address" },
      { name: "data",     type: "bytes"   },
      { name: "memoId",   type: "bytes32" },
      { name: "memoData", type: "bytes"   },
    ], outputs: [] }],
  functionName: "memo",
  args: [tokenAddress, transferCalldata, memoId, toHex(Buffer.from(memoText, "utf8"))],
  gas: 200_000n,  // eth_estimateGas is broken on Arc Testnet — always pass explicit gas
});

Pattern 2 — fire-and-forget label (swap route): non-atomic, appended after a swap is already settled.

// calls memo(bytes) — attaches a label to this tx, no inner call
await walletClient.writeContract({
  address: "0x5294E9927c3306DcBaDb03fe70b92e01cCede505",
  abi: [{ name: "memo", type: "function", stateMutability: "nonpayable",
    inputs: [{ name: "data", type: "bytes" }], outputs: [] }],
  functionName: "memo",
  args: [toHex(Buffer.from("Arc Swap: USDC → EURC | 10 in → 8.72 out", "utf8"))],
  gas: 100_000n,
});

One critical Arc Testnet gotcha worth adding

eth_estimateGas is broken on Arc Testnet — it returns incorrect values or fails entirely. Every writeContract call to the Memo contract (or any contract) needs an explicit gas: override or it will revert silently. We've found 200_000n works reliably for the atomic inner-call pattern and 100_000n for the simple label pattern.

Hope this helps — happy to share any live tx hashes for verification if useful.

[osr21]

Alternative pattern: embed memo in the contract rather than using the Memo precompile

Great PR — having callWithMemo documented is really useful. Wanted to add a complementary approach we validated while building Arc Stablecoin DApp that covers a case the precompile pattern does not:

---

Why a third pattern is needed

We originally tried the self-call memo approach — encode a UTF-8 string as calldata and send from the user address to itself. This fails on Arc at the consensus level with:

External transactions to internal accounts cannot include data

This is a different error from the gas-estimation bug in issue #189 — the transaction is rejected at block inclusion, not during estimation, so passing an explicit gas: field does not help. The Memo precompile is the correct fix when you do not own the target contract. But if you do own the contract, there is a simpler path.

---

Pattern 3 — memo as a contract function parameter

Add string calldata memo to the function signature and emit it in an event. The memo lands in the transaction log in the same confirmation — no extra tx, no precompile call, no gas-estimation workaround needed:

// BatchTransfer.sol — deployed on Arc Testnet
// 0x76d5dd51ad28D607cD8804dc5230cAE93403eD3d (source-verified)

event BatchExecuted(
    address indexed sender,
    address indexed token,
    uint256 totalAmount,
    uint256 count,
    string  memo           // stored in the event log, decoded by name on ArcScan
);

function batchTransfer(
    address          token,
    address[] calldata recipients,
    uint256[] calldata amounts,
    string    calldata memo   // caller passes the memo string directly
) external {
    // ... ERC-20 transfer loop ...
    emit BatchExecuted(msg.sender, token, total, recipients.length, memo);
}

Frontend call (viem):

await walletClient.writeContract({
  address: "0x76d5dd51ad28D607cD8804dc5230cAE93403eD3d",
  abi: BATCH_TRANSFER_ABI,
  functionName: "batchTransfer",
  args: [tokenAddr, recipients, amounts, "Invoice MR"],
  gas: 80_000n + BigInt(recipients.length) * 60_000n,
});

Because the contract is source-verified on ArcScan, the memo field is decoded by name in the Logs tab on every transaction — no extra tooling or indexer needed.

Live example — memo "Invoice MR" visible in the BatchExecuted event log:
https://testnet.arcscan.app/tx/0xacc2bc5a96ecac286549132303e664f3ade81969c26e788c814798f20f13b429?tab=logs

---

Decision guide for builders

Scenario	Recommended approach
Target contract you do not own	Memo precompile (0x5294...) — Pattern 1 or 2 from this PR, with explicit gas:
Target contract you own	Add string memo param to the function — Pattern 3 above
Self-call memo (from == to + data)	Not supported on Arc — use one of the above instead

---

The self-call restriction is filed separately as a standalone issue for documentation purposes. Happy to provide a full working example for Pattern 3 if it would be a useful addition to this PR.