Skip to content

docs: add alternative nanopayment architecture reference (vault + batched voucher settlement) - #25

Open
osr21 wants to merge 1 commit into
circlefin:masterfrom
osr21:docs/alt-architecture-vault-batched-settlement
Open

docs: add alternative nanopayment architecture reference (vault + batched voucher settlement)#25
osr21 wants to merge 1 commit into
circlefin:masterfrom
osr21:docs/alt-architecture-vault-batched-settlement

Conversation

@osr21

@osr21 osr21 commented Jul 4, 2026

Copy link
Copy Markdown

Summary

Adds docs/ALTERNATIVE_ARCHITECTURES.md, a short reference comparing this
repo's Gateway x402 batching model to an alternative vault + EIP-712 session
voucher + keeper-batched-settlement design (NanopayVault, from
osr21/arc-stablecoin-dapp),
built while integrating agent-to-agent nanopayments on Arc.

Why

Both approaches solve the same "avoid gas-per-micropayment" problem but make
different tradeoffs (managed facilitator vs. self-hosted keeper batching,
per-request settlement vs. per-session voucher + off-chain metering). This is
purely additive documentation — no changes to any existing code path — meant
as a reference point for anyone comparing designs for agent-to-agent
micropayments on Arc, not a suggestion to change this repo's approach.

@osr21

osr21 commented Jul 21, 2026

Copy link
Copy Markdown
Author

Great reference — we've extended the same project with a third architecture variant since this PR was opened.

NanopayP2P (NanopayP2P.sol, deployed on Arc Testnet at 0x65a2FD4E63767Cee00d2Aa08cba2feBFb1a21a9f) removes the operator/keeper role entirely — the seller claims directly, no relay key anywhere in the system.

arc-nanopayments (this repo) NanopayVault (from this PR) NanopayP2P (new)
Token custody Gateway facilitator On-chain vault contract On-chain channel contract
Buyer authorizes x402 PaymentRequirements per request EIP-712 SessionVoucher (zero gas) EIP-712 PaymentVoucher (zero gas)
Settlement trigger Per-request (facilitator) Keeper batch (settleBatch()) Seller calls claim() directly
Trusted operator / relay key Circle Gateway ✅ required ❌ none
Server private key ✅ seller wallet ✅ operator relay key ❌ none
Withdrawal attack surface ✅ (see issue #29) ✅ (operator key exposure) ❌ eliminated
Cumulative payment ceiling Per-request Per-session maxBudget Per-channel deposit

The elimination of the server key is what resolves the attack in issue #29 — there's no private key on the server and no withdrawal endpoint to hit. Worth noting as a fourth row in ALTERNATIVE_ARCHITECTURES.md if you extend that doc, since it represents a different point on the trust/UX tradeoff spectrum.

Source: osr21/arc-stablecoin-dappcontracts/src/NanopayP2P.sol and artifacts/arc-dapp/src/pages/nanopay.tsx.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant