Skip to content

Latest commit

 

History

History
147 lines (121 loc) · 8.62 KB

DEVIATIONS.md

File metadata and controls

147 lines (121 loc) · 8.62 KB

Deviations, unknowns and cuts

Read this before demoing or submitting. Every item is either an unverified assumption, something deliberately not built, or something cut because checking it first showed it already existed elsewhere.

1. Nothing in this repo has been compiled or run yet

The machine that wrote it has no node, npm, forge or gh. So:

  • forge build / forge test — not run. The Solidity is written against 0.8.24 and reviewed by eye; expect small compile fixes (most likely candidates: the forge-std import path, an unused-variable warning, or the payable-address handling around Arc's native USDC).
  • npx tsx demo/policy-checks.ts — not run. This is the highest-value thing to execute first: 17 assertions on the decision logic with no network, no wallet and no money.
  • npx tsx demo/offline.ts — not run.
  • The dashboard — not loaded in a browser. It pulls ethers v6 UMD from jsDelivr; if that path is wrong, install ethers locally, the app only uses BrowserProvider and Contract.

First five commands for whoever finishes this: npm install && forge install foundry-rs/forge-std && forge build && forge test -vv && npx tsx demo/policy-checks.ts

2. Contract addresses — deliberately blank, do not guess

What Status
Arc native USDC ERC-20 interface 0x3600000000000000000000000000000000000000 — from Arc docs
Aave V4 vault on Arc Not deployed (as of 2026-09-26). Circle Earn lists Morpho only.
Morpho · Keyrock Prime USDC 0x5befab92a5a3d60f578cb51eeb4e4fd50a1e3123 — asset() == USDC, active, deep liquidity
Morpho · Bitwise RWA USDC 0x7610094b846657dcf166d59e42973db52c7015f9 — asset() == USDC, high APY, thin exit
EURC, USYC, USYC Teller, Entitlements, CCTP, Gateway documented in Arc's contract-addresses page; not used by v0.1

Also check maxWithdraw is not permanently zero. During the Arc testnet rehearsal (2026-09-26) Circle Earn's "EarnKit USDC Vault" accepted a deposit and reported share balance correctly, but maxWithdraw(holder) and maxRedeem were 0 — no async requestWithdraw either. A vault can pass asset() == USDC and still be a one-way door. Call maxWithdraw for a holder that already has shares (or maxDeposit for a fresh one) before binding.

A plausible-looking address on a three-week-old chain is more often a clone than a deployment. Verify on explorer.arc.io, then confirm by calling asset() on the vault and checking it returns the USDC interface — YieldFloat._setVault() enforces the same check on-chain, so a wrong address reverts at configuration instead of quietly stranding funds.

3. Arc's native USDC and smart-contract signatures — now answered

Resolved from Circle's docs (2026-09-26), no extra test required for the current design. Gateway Nanopayments and x402 batch settlement require EOA signatures and do not support ERC-1271. Facilitator Service documents that buyers can pay "from a standard wallet address or a deployed smart contract account," but the safest and already-shipped shape is the one in this repo:

the float lives in the owner's EOA, and only the reserve lives in the contract.

That is compatible with both facilitators. Moving the float into a policy-controlled agent wallet would need the Facilitator Service path plus a confirmed ERC-1271 acceptance on Arc's native USDC — a follow-up, not a blocker.

4. Facilitator API shapes — sourced from Circle's OpenAPI

src/agent/seller.ts now follows Gateway Nanopayments:

  • 402 header PAYMENT-REQUIRED = base64 { x402Version, resource, accepts: [PaymentRequirements] }
  • settle = POST {facilitator}/v1/x402/settle with { paymentPayload, paymentRequirements }
  • response = { success, errorReason?, payer?, transaction, network }
  • testnet facilitator https://gateway-api-testnet.circle.com, mainnet https://gateway-api.circle.com

Source: Settle an x402 payment OpenAPI and What is x402?. Facilitator Service (on-chain settle per payment) is a second option; see https://developers.circle.com/facilitator-service. Re-check before a mainnet demo if Circle versions the route.

5. Numbers that are estimates, presented as such

Constant Value Basis
Arc transaction cost ~0.0015 USDC live reports of 0.0010–0.0015 for ordinary Arc transfers; re-measure after deploy
Morpho · Keyrock Prime APY ~27 bps live Circle Earn discovery 2026-09-26; re-check before demo
Morpho · Bitwise RWA APY ~503 bps live Circle Earn discovery 2026-09-26; thin exit liquidity
GAS_RESERVE 0.05 USDC a rounding-error cushion so the manager can always pay for gas
targetFloat / minSweep defaults $20 / $5 arbitrary but overridable; see recommendFloat() for the principled version

These drive whether the product is worth using, so they are computed in src/lib/policy.js rather than hardcoded in a condition. If the measured Arc gas figure differs, shouldSweep()'s verdict changes — that is intended.

6. Things deliberately NOT built

  • Unwind inside the settlement transaction. Impossible with a hosted facilitator: the settlement is one fixed transferWithAuthorization and there is no slot to insert a redeem. The honest alternative is self-hosted settlement, which hands us address-screening and payment-state duties we do not want for a prototype. Kept as a documented "mode B", not implemented.
  • Paying in the yield-bearing token (no unwind at all — the elegant version). Blocked on the same unknown: Circle's facilitator is USDC-only, and arbitrary ERC-20 pulls need Permit2 on a facilitator that supports it on Arc. Unverified, so it stays in the roadmap rather than the code.
  • USYC (Circle's tokenised money-market fund) as the reserve. Native on Arc and redeemable to USDC at NAV — genuinely the most Arc-flavoured option — but it is a permissioned security: allowlist-gated (there is an Entitlements contract), Reg S, non-US, $100k institutional minimums. Wrong instrument for a product a random user can configure. Optional demo flourish on testnet only, after requesting allowlisting via a Circle support ticket (24–48h). Not built.
  • x401 / agent-identity gating. Cut. The seller does not need the payer verified: the authorisation is already signature-authenticated, Arc's finality is deterministic so there is no chargeback, and abuse is priced by the fee. Identity is the payer's problem, solved by spend limits — not the receiver's.
  • Message-hash-in-nonce notarisation ("H"). Cut after checking the x402 extensions index: signed offers and receipts for auditing and dispute resolution already exist as a standard extension, along with Bazaar discovery and AP2's A2A payment extension. makeNonce() still supports it, off by default and documented as off-protocol.
  • Any redistribution or resale of third-party market data. The demo endpoint is offline and deterministic on purpose.

7. Known rough edges in v0.1

  • ensureFloat() is onlyOwner, so the signer is the operator. Fine for a single-user prototype; a real deployment would want a separate, policy-limited agent role.
  • A single durable approve(..., type(uint256).max) to the vault. Convenient, and the standard ERC-4626 pattern, but it means an engine switch should clear it — setVault() requires an unwound position, which limits the blast radius, though it does not revoke the old allowance. Add a revoke on switch if this ever holds real user funds.
  • readEvents() queries the last 8000 blocks; on a very fresh chain that may be the whole history, and some RPCs cap the range. Wrapped in try/catch — the dashboard works without it.
  • The contract never holds a positive USDC balance by design (funds are either in the owner's wallet or in the vault), except GAS_RESERVE. rescueToken() covers accidental ERC-20 arrivals; native USDC cannot be pulled out with transfer because on Arc it is the gas asset.
  • No slippage or MEV protections: irrelevant on Arc's ordered, sub-second, no-front-running model, and stated here so nobody adds them as theatre.

8. Not legal, regulatory or tax advice

Reserve yield is a third-party lending position. Anything that let customers spend yield-bearing dollars at par would raise securities and money-transmission questions far above this prototype's pay grade. The framing here is deliberate: we are a depositor into existing markets, not an issuer, and we are not paying holders yield on a payment stablecoin.