feature/docs: gasless cross-asset transfer on Arc Testnet — EIP-2612 permit + sequential relayer txs + Multicall3From msg.sender trap

[osr21]

Summary

While building gasless cross-asset payments on Arc Testnet (Arc Swap), we discovered a critical pitfall with Multicall3From that will affect anyone trying to do batched ERC-20 transferFrom from a relayer wallet.

---

The Multicall3From msg.sender Trap

Multicall3From address: 0x522fAf9A91c41c443c66765030741e4AaCe147D0

The initial design batched three calls — permit(), transferFrom(), and transfer() — into a single Multicall3From call. Every payment reverted.

Root cause:

Inside a Multicall3From subcall, msg.sender is the Multicall3From contract address, not the original caller (EOA or relayer wallet).

ERC-20's transferFrom checks:

require(allowance[owner][msg.sender] >= amount);

The EIP-2612 permit had set allowance[owner][relayerWallet] = amount.
Inside the Multicall3From subcall, msg.sender = 0x522fAf9A91c41c443c66765030741e4AaCe147D0.
So the check reads allowance[owner][Multicall3From] = 0 → revert.

This is not Arc-specific — it's correct EVM behaviour (CALL sets msg.sender to the caller), but it's easy to miss when Multicall3From is described as letting you "call as" a specific address.

Fix: submit three sequential direct transactions from the relayer wallet. Each presents msg.sender = relayerWallet and the permit allowance matches.

---

Working Gasless Cross-Asset Transfer Pattern

The full pattern for a relayer-pays-gas, user-signs-only cross-asset payment on Arc Testnet:

Step 1 — Frontend: collect permit signature (zero gas for user)

// Read current nonce
const nonce = await publicClient.readContract({
  address: USDC_ADDRESS,
  abi: erc20PermitAbi,
  functionName: "nonces",
  args: [userAddress],
});

const deadline = BigInt(Math.floor(Date.now() / 1000) + 3600);

// EIP-2612 typed data — Arc Testnet domain
const signature = await walletClient.signTypedData({
  domain: {
    name: "USDC",          // must match token's EIP-712 name
    version: "2",          // "2" for both USDC and EURC on Arc Testnet
    chainId: 5042002n,
    verifyingContract: USDC_ADDRESS,
  },
  types: {
    Permit: [
      { name: "owner",    type: "address" },
      { name: "spender",  type: "address" },
      { name: "value",    type: "uint256" },
      { name: "nonce",    type: "uint256" },
      { name: "deadline", type: "uint256" },
    ],
  },
  primaryType: "Permit",
  message: { owner: userAddress, spender: RELAY_WALLET, value: amountIn, nonce, deadline },
});

// Send { deadline, v, r, s } to backend — user is done

Step 2 — Backend: three sequential direct transactions (relayer pays all gas)

// Always pass explicit gas — eth_estimateGas is unreliable on Arc Testnet
const GAS = {
  permit:       100_000n,
  transferFrom: 100_000n,
  transfer:     100_000n,
  memo:         100_000n,
};

// 1. Permit — sets allowance[user][relayerWallet] = amountIn
const permitHash = await walletClient.writeContract({
  address: tokenIn.address,
  abi: erc20PermitAbi,
  functionName: "permit",
  args: [userAddress, RELAY_WALLET, amountIn, deadline, v, r, s],
  gas: GAS.permit,
});
const permitReceipt = await publicClient.waitForTransactionReceipt({ hash: permitHash });
if (permitReceipt.status === "reverted") throw new Error("permit reverted");
// ↑ Arc Testnet receipts do NOT auto-throw on revert — always check status manually

// 2. TransferFrom — pulls tokenIn from user to relayer
const tfHash = await walletClient.writeContract({
  address: tokenIn.address,
  abi: erc20Abi,
  functionName: "transferFrom",
  args: [userAddress, RELAY_WALLET, amountIn],
  gas: GAS.transferFrom,
});
const tfReceipt = await publicClient.waitForTransactionReceipt({ hash: tfHash });
if (tfReceipt.status === "reverted") throw new Error("transferFrom reverted");

// 3. Transfer — sends tokenOut from relayer to recipient
const amountOut = computeAmountOut(amountIn, tokenIn, tokenOut); // apply rate + fee
const transferHash = await walletClient.writeContract({
  address: tokenOut.address,
  abi: erc20Abi,
  functionName: "transfer",
  args: [recipientAddress, amountOut],
  gas: GAS.transfer,
});
const transferReceipt = await publicClient.waitForTransactionReceipt({ hash: transferHash });

// Refund if outbound fails after inbound succeeded
if (transferReceipt.status === "reverted") {
  await walletClient.writeContract({
    address: tokenIn.address,
    abi: erc20Abi,
    functionName: "transfer",
    args: [userAddress, amountIn],
    gas: GAS.transfer,
  });
  throw new Error("outbound transfer reverted — user refunded");
}

// 4. Optional: on-chain memo via Arc v0.7.2 Memo precompile (fire-and-forget)
// Precompile address: 0x5294E9927c3306DcBaDb03fe70b92e01cCede505
// Activated on Arc Testnet 2026-06-18
if (memo) {
  walletClient.writeContract({
    address: "0x5294E9927c3306DcBaDb03fe70b92e01cCede505",
    abi: [{ name: "memo", type: "function", inputs: [{ name: "data", type: "bytes" }], outputs: [] }],
    functionName: "memo",
    args: [toHex(Buffer.from(memo, "utf8"))],
    gas: GAS.memo,
  }).catch(err => logger.error({ err }, "memo precompile failed (non-fatal)"));
}

---

Rate Calculation (Circle Kit swap unusable — see #88)

Circle Kit's estimateSwap() returns incorrect rates on Arc Testnet (~17 EURC/USDC vs ~0.91 real rate) and swap() fails with ONCHAIN_SIMULATION_FAILED in both directions. We use real market rates instead:

Pair	API	Cache
USD/EUR	Frankfurter	5 min
BTC/USD	CoinGecko	5 min

const effectiveAmountIn = amountIn * (1 - FEE_RATE); // 0.3% platform fee
const amountOut = effectiveAmountIn * marketRate;

---

Arc Testnet EVM Quirks (Summary)

Quirk	Workaround
eth_estimateGas unreliable	Always pass explicit gas values on all writeContract calls
Receipts don't auto-throw on revert	Always check receipt.status === "reverted" manually
Multicall3From subcalls use contract msg.sender	Use sequential direct transactions from relayer wallet instead
UniswapV2Factory.createPair() needs ~5M gas	Pass gas: 5_000_000n explicitly; standard 500k will revert

---

Reference Implementation

Full working implementation: osr21/arc-swap

• Backend route: artifacts/api-server/src/routes/pay.ts
• Frontend hook: artifacts/arc-swap/src/hooks/use-kit-pay.ts
• Architecture doc: docs/send-architecture.md

Happy to answer questions.

[osr21]

Correction: Memo contract ABI is wrong in the example above

After reading the official Transaction memos docs, the memo(bytes) signature shown in the code sample above is incorrect. The actual ABI is:

function memo(
    address target,
    bytes calldata data,
    bytes32 memoId,
    bytes calldata memoData
) external;

The Memo contract is a wrapper — it forwards data to target via the CallFrom precompile (preserving msg.sender), and emits BeforeMemo / Memo events around the inner call. It is not a standalone "emit bytes" call.

Calling it with a single bytes argument matches the selector (by coincidence, memo(bytes) = 0x58ea363f is a valid 4-byte prefix) but passes garbage to the ABI decoder → empty revert every time.

Corrected viem usage

import { encodeFunctionData, toHex } from "viem";

const MEMO_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: [],
  },
] as const;

// Encode the inner call (e.g. USDC transfer)
const transferCalldata = encodeFunctionData({
  abi: erc20Abi,
  functionName: "transfer",
  args: [recipientAddress, amountOut],
});

// Unique bytes32 memoId — use a timestamp, UUID truncated, or application-defined key
const memoId = `0x${BigInt(Date.now()).toString(16).padStart(64, "0")}` as `0x${string}`;

// Wrap the transfer in Memo.memo() — atomic: if transfer reverts, whole tx reverts
const txHash = await walletClient.writeContract({
  address: "0x5294E9927c3306DcBaDb03fe70b92e01cCede505",
  abi: MEMO_ABI,
  functionName: "memo",
  args: [
    USDC_ADDRESS,                                   // target contract
    transferCalldata,                               // calldata to forward
    memoId,                                         // bytes32 identifier
    toHex(Buffer.from("your memo text", "utf8")),   // memoData bytes
  ],
  gas: 200_000n,  // higher than a plain transfer — wraps an inner call
});

Key constraints from the docs

• Must be called directly from an EOA — intermediary contracts with a different msg.sender revert (sender spoofing not allowed)
• If the inner call (child) reverts, the outer Memo tx reverts too — the memo index rolls back
• Do not use STATICCALL or DELEGATECALL into Memo
• The CallFrom precompile must not be called directly from an EOA — only through Memo or Multicall3From

What the emitted events look like

After a successful call, ArcScan / your indexer will see:

1. BeforeMemo(memoIndex) — emitted before the inner call
2. The inner contract's own events (e.g. USDC Transfer)
3. Memo(sender, target, callDataHash, memoId, memo, memoIndex) — emitted after

Query by indexed memoId or sender to reconcile payments against memo records.

Sorry for the incorrect snippet — updated the reference implementation in osr21/arc-swap (artifacts/api-server/src/routes/pay.ts) to use the correct ABI.

[osr21]

Confirmed working implementation in Arc Swap

We built exactly this pattern in Arc Swap — a Uniswap V2 DEX on Arc Testnet — and can confirm all the findings here.

Sequential 3-tx relayer pattern ✅

The Multicall3From msg.sender trap caught us too. After switching to three sequential direct transactions from the relayer wallet, all backend swaps work reliably.

A few additional Arc Testnet quirks we hit in the same execution flow:

• Receipt status must be checked manually after every tx — Arc Testnet receipts do NOT auto-throw on revert. A reverted transferFrom returns a normal receipt with status: "reverted"; if you don't check it, the backend will proceed to send output tokens to the user even though the inbound pull never settled (free money bug).
• Always pass explicit gas — eth_estimateGas is unreliable on Arc Testnet and often under-estimates, causing silent reverts. We use 100_000n for every ERC-20 call.
• Automatic refund on outbound failure — if transfer() (step 3) reverts after transferFrom() (step 2) succeeded, you must refund the user's tokenIn. We track pullHash separately so we can always refund even if the kit swap path consumed the tokens.

Memo precompile (v0.7.2)

We just wired the memo precompile (0x5294E9927c3306DcBaDb03fe70b92e01cCede505) into Arc Swap's backend. After every real swap completes, we fire-and-forget a memo tx with the swap label:

const MEMO_PRECOMPILE = "0x5294E9927c3306DcBaDb03fe70b92e01cCede505" as `0x${string}`;

const memoText = `Arc Swap: ${tokenIn} → ${tokenOut} | ${amountIn} in → ${amountOut} out`;
walletClient.writeContract({
  address: MEMO_PRECOMPILE,
  abi: [{ name: "memo", type: "function", stateMutability: "nonpayable",
          inputs: [{ name: "data", type: "bytes" }], outputs: [] }],
  functionName: "memo",
  args: [toHex(Buffer.from(memoText, "utf8"))],
  account: backendAccount,
  gas: 100_000n,
}).catch(err => logger.error({ err }, "memo precompile failed (non-fatal)"));

Rate calculation (Circle Kit unusable)

As noted in #88, kit.swap() throws ONCHAIN_SIMULATION_FAILED on Arc Testnet and kit.estimateSwap() returns incorrect rates. We removed App Kit from the estimate path entirely and now use:

1. On-chain getReserves() from the Uniswap V2 pool (constant-product math) when pool rate is within 5% of real forex
2. Frankfurter for USD/EUR, CoinGecko for BTC/USD as fallback

This gives rates that match what the router will actually execute.

[osr21]

Update: Circle App Kit swap confirmed working on Arc Testnet (intermittently)

Following up on the rate calculation note in the original issue — we have a confirmed successful kit.swap() execution:

Tx: 0x237678e4...b65a15 — 1.99 USDC → 2.333 EURC, confirmed in 0.54 seconds

Circle App Kit routes USDC/EURC through LiFi Diamond → Curve StableSwap (not Uniswap V2), using WUSDC as an intermediate token between two separate Curve pools. This is a completely different liquidity source from any deployed Uniswap V2 pool.

ONCHAIN_SIMULATION_FAILED appears to be a liquidity depth signal from the Curve pools, not a permanent Arc Testnet incompatibility. The recommended pattern is try-with-fallback rather than skipping App Kit entirely:

1. Try kit.swap() → succeeds when Curve pool liquidity is sufficient
2. Fall back to Uniswap V2 router or peer-to-peer at real forex rate → always works

This means the gasless cross-asset pattern in this issue can potentially use App Kit as the primary executor on Arc Testnet, not just as a fallback.