11 KiB
Arc + Circle — Next-Phase Roadmap
Deepening Arc + Circle usage beyond the foundation already shipped. This is the agreed plan of record; phases are implemented one by one in the order below.
Already shipped (the foundation — do NOT re-do)
@settlekit/arc— chain config (real Arc testnet5042002addresses for USDC/EURC/USYC, CCTP, Gateway, FxEscrow, Permit2, Multicall3), multi-asset on-chain transfer verification, USDC-denominated fee estimation. Live-verified againstrpc.testnet.arc.network. API:/v1/arc/{info,fee-estimate,verify}.@settlekit/cctp— CCTP V2:depositForBurn+depositForBurnWithHook(hookData plumbed), Iris attestation polling,receiveMessage/mint, domain map,FINALITY_THRESHOLD_STANDARD(1000)/FAST(500). API:/v1/cctp/{burn-tx,attestation,mint-tx}.@settlekit/gateway— Unified Balance: deposit, EIP-712 burn intents, transfer attestation, gateway-mint, on-chain balance reads. API:/v1/gateway/*.@settlekit/circle-wallets+@settlekit/treasury— dev-controlled W3S wallets + treasury policy engine. Real payout execution (POST /v1/payouts/:id/execute)providerRefpersistence +POST /:id/reconcile+ workerpayout-reconcilejob.
@settlekit/paymaster— Circle Paymaster (pay gas in USDC) + Gas Station policies. API:/v1/paymaster/*,/v1/gas-station/policies.@settlekit/stablefx— Circle Mint (mint/redeem) + pure FX quote math. API:/v1/fx/{quote,swap-request},/v1/mint,/v1/mint/redeem.
Every Circle/Arc leg is cred-gated: a real client when creds are present, else
null / in-memory double. New work MUST preserve this pass-through.
Blocked / spike-only (do NOT build on guesses)
- FxEscrow on-chain ABI — RESOLVED (was "unpublished"). The contract is
verified on-chain on Arc testnet (proxy
0x8676…, impl0x721e…F658, "FxEscrow"); its ABI is captured in@settlekit/onchainfx-escrow-abi.ts(read from the Arc Blockscout explorer). The EIP-712 witness types were read live from the contract's*_WITNESS_TYPE()getters —Consideration(bytes32 quoteId,address base,address quote,uint256 baseAmount, uint256 quoteAmount,uint256 maturity),TakerDetails,MakerDetails, funded via canonical Permit2. Exposed atGET /v1/fx/onchain/info. The off-chain RFQ HTTP schema is ALSO RESOLVED — sourced from Circle's published OpenAPI spec (developers.circle.com/openapi/stablefx.yaml).stablefx/rfq.tsnow matches the real endpoints (/quotes,/trades,/signatures,/signatures/presign/{id}) + shapes: the quote returns the EIP-712typedData(PermitWitnessTransferFrom) the taker signs, then the signed Permit2 message + signature are submitted at trade creation. - USYC on Arc — architectural finding (not a doc gap): the Arc USYC token is a
YieldCoinSatellite(cross-chain representation, proxy verified). The mint/redeem Teller is NOT co-located on Arc — subscription/redemption happens on the home chain; on Arc the satellite token accrues value by price. So "USYC yield via an on-Arc Teller" is not available by design; treasury would hold the satellite token. - Arc mainnet addresses — unpublished. Stay testnet-scoped; no mainnet cutover.
- CCTP V2 hook target contract —
hookDatais plumbed but there is no on-Arc hook handler in the repo. Atomic "credit checkout on mint" needs a deployed handler whose interface comes from CCTP V2 hook docs. Spike first.
Phases (implementation order)
Phase 1 — Compliance Engine: Transaction Screening (HIGHEST LEVERAGE)
Screen every payout destination + pay-in sender against Circle Transaction
Screening (sanctions/risk) before funds move. Block/hold on DENIED/high-risk.
- Extends:
packages/compliance(17-line stub today),apps/api/src/payouts/executor.ts,apps/api/src/routes/payments.ts,config/integrations.ts,config/env.ts. - Steps: (1) spike Circle Transaction Screening API; (2) screening client with an
injected-transport seam (mirror
circle-wallets/src/http.ts), map verdict →ComplianceDecision(allow|review|block); (3) gate payoutexecute()— block → typedcompliance_blocked+ held state; (4) gate pay-in confirm on the sender; (5) cred-gate inintegrations.ts. - Fail-safe: unconfigured = pass-through (logged); payout direction blocks on uncertainty.
- Risk: H. Entirely cred-gated.
Phase 2 — Circle Push Webhooks: real-time settlement + screening alerts
Inbound Circle webhook receiver; settle payouts in real time; ingest screening alerts. Poll job becomes a slower safety-net fallback.
- Extends:
apps/api(newPOST /v1/webhooks/circle),packages/webhooks(add inbound verification — outbound-only today),payout-reconcile-job.ts. - Steps: (1) spike Circle webhook signature scheme (ECDSA + Circle public key —
distinct from SettleKit's outbound HMAC); (2) inbound verifier
(
packages/webhooks/src/inbound.ts); (3) verified, idempotent route advancing payouts viamarkPaid/markFailed, routing screening alerts to the Phase 1 decision store; (4) demote poll job to fallback. - Risk: H (signature verification is security-critical).
Phase 3 — CCTP V2 Hooks + Fast Transfer (CHEAP / LIVE-NOW quick win)
- Steps (cheap, live-now): (1) add
hookDatatoburnSchemainapps/api/src/routes/cctp.tsand thread intobuildBurnTx; (2) add afastoption mapping toFINALITY_THRESHOLD_FAST+ surface themaxFeetradeoff. - Step (expensive, blocked): (3) on-Arc hook handler contract (deploy via
create2Factory) for atomic credit-on-mint — spike the CCTP V2 hook interface first. - Risk: L for steps 1–2.
Phase 4 — Wire services/arc-indexer for direct on-chain payments
Merchants accept USDC by sharing an Arc address; the indexer auto-confirms.
- Protocol fix (blocker): indexer POSTs
/v1/payments/{txHash}/confirm(txHash as id), but the real route needs an internal payment id tied to a checkout session. - Steps: (1) new
POST /v1/payments/observethat creates+confirms a payment from an observed Transfer, resolving merchant/session by watched address, re-verifying on-chain viaarcVerifier(never trust the indexer), running Phase 1 sender screening; (2) pointservices/arc-indexer/src/settlekit.rsat it; (3) wire indexer to Arc testnet. - Risk: H.
Phase 5 — StableFX RFQ (expensive, partially blocked)
Replace the modeled FxSwapRequest with the real RFQ flow for USDC↔EURC.
- Spike Circle RFQ API (schemas, signing domain, Permit2 witness) first. Keep
computeFxQuotefor previews; add an RFQ client; wire Permit2 funding (address in config). Implement last. - Risk: H.
Phase 6 — Spikes (researched; findings below)
- User-controlled wallets — DONE. Fully documented W3S API; shipped
createUserWalletsClientin@settlekit/circle-wallets(create user / mint user token / PIN+wallet/transfer challenges that the client SDK completes / list wallets, all viaX-User-Token) + cred-gated/v1/user-wallets/*. 6 tests. - CCTP V2 hook handler — BUILT.
contracts/src/SettleKitCctpHook.solimplements the publishedIMessageHandlerV2; decodeshookData = abi.encode(merchant, orderId)and forwards the freshly-minted USDC to the merchant atomically. Compiled (solc 0.8.30) + 4 Foundry tests. Remaining: deploy to Arc testnet (faucet-funded key). - On-chain Arc escrow — BUILT.
contracts/src/SettleKitEscrow.sol— trustless USDC escrow (fund/release/refund/dispute + arbiter), the on-chain counterpart to the off-chain escrow product. Compiled + 9 Foundry tests. Remaining: deploy to Arc. - USYC yield — mechanism known, contract details pending. USYC is a permissioned ERC-20 (Hashnote SDYF, Circle-owned) minted/redeemed against USDC via a Teller contract (T+0). Remaining: the exact Teller address + ABI on Arc (verify at developers.circle.com/tokenized/usyc) before encoding deposit/redeem.
- StableFX — FULLY RESOLVED. On-chain: FxEscrow ABI + EIP-712 witness types from
the verified contract (
@settlekit/onchain;/v1/fx/onchain/info). Off-chain: the RFQ HTTP schema from Circle's OpenAPI spec (stablefx.yaml) —stablefx/rfq.tsrewritten to match (/quotes→typedData,/trades,/signatures, presign). No remaining guesses. - Permit2 / Multicall3 — fold Permit2 into Phase 5 funding; Multicall3 deferred.
Cross-cutting rules
- Fail-safe gating — never silently block legit settlement or silently allow a sanctioned one; log loudly, choose the safe default per flow.
- Inbound ≠ outbound webhooks — the Circle inbound verifier is a separate scheme
from SettleKit's outbound HMAC (see the
webhook-signingmemory note). - Don't trust the indexer —
observere-verifies on-chain.
On-chain integration (contracts → product)
The Solidity contracts are now usable end-to-end from the API (signer-agnostic):
@settlekit/onchain— ABIs + tx-builders for escrow (createAndFund/release/refund/dispute) + ERC-20 approve. 4 tests.- CCTP hook payload —
encodeSettleKitHookData({merchant, orderId})in@settlekit/cctp;/v1/cctp/burn-txaccepts{hook:{merchant,orderId}}→depositForBurnWithHooktargetingSettleKitCctpHook. 4 tests. /v1/onchain-escrow/*— returns unsigned{to,data,value}for the escrow lifecycle (fund returns the USDC approve + createAndFund). Live-verified.contracts/script/Deploy.s.sol— deploys both contracts (Arc testnet address defaults); dry-run simulates cleanly. Broadcast needs a faucet-funded key.
Status
- Phase 1 — Compliance screening (payout-destination screening shipped; pay-in
sender screening pending the Arc verifier surfacing
from) - Phase 2 — Circle push webhooks (inbound ECDSA verifier + public-key resolver +
POST /v1/circle/webhookssettling payouts in real time; poll job = fallback) - Phase 3 — CCTP hooks + fast transfer (steps 1–2:
hookData+fastexposed on/v1/cctp/burn-tx, live-verified; step 3 on-Arc hook handler = spike, deferred) - Phase 4 — arc-indexer direct payments (
POST /v1/payments/observere-verifies on-chain + screens sender + records confirmed direct payment, idempotent; indexer rewired to it withORGANIZATION_ID. Spoof-rejection live-verified.) - Phase 5 — StableFX RFQ (real orchestration client quote→trade→funding→status +
cred-gated
/v1/fx/rfq/*; exact endpoint schemas + EIP-712 taker-intent/Permit2 signing structure flagged as needing confirmation vs Circle's api-reference — the api-reference pages are not publicly accessible, so wire-details are MODELED from the technical guide. Taker signs with their own wallet; no signing helper shipped until the EIP-712 schema is published.) - [~] Phase 6 — user-controlled wallets DONE; CCTP hook handler + on-chain escrow
contracts BUILT + tested (
contracts/, 13 Foundry tests) — pending Arc deploy; USYC mechanism researched (need Teller ABI); StableFX exact schemas + FxEscrow ABI remain genuinely unpublished