Make XGuard one-signature x402: no API key, no prepay, fee only after finality

[moelayyan90]

Product goal

Make the normal x402 seller path as close as possible to “use the service and XGuard takes a small disclosed share” without breaking the buyer-signed x402 exact payment.

Recommended seller flow

1. Open https://xguardgate.com/start.
2. Connect the merchant payTo wallet and sign one short-lived activation message containing the exact XGuard pricing terms.
3. Point the standard x402 HTTPFacilitatorClient at https://xguardgate.com.
4. Keep using ordinary x402. No XGuard account, email, password, API key, subscription, or prepaid balance is required after activation.

The activation signature proves control of payTo and acceptance of the disclosed service terms. It does not authorize a token transfer and does not change the merchant payment recipient.

Pricing in this PR

Default signed terms:

• 0.5% (50 bps) of an independently finalized successful merchant settlement
• maximum XGuard fee: $0.001 per settlement
• verify: $0
• failed settlement: $0
• unresolved ambiguity: no fee earned
• idempotent retry: no additional fee
• default unpaid XGuard service-fee limit: $1.00

The accepted pricing version, bps, cap and postpaid limit are persisted per activated payTo; runtime config does not silently rewrite previously signed merchant terms.

Why XGuard does not silently skim the buyer payment

x402 exact binds the buyer-authorized recipient and amount. Reducing the merchant amount or rewriting payTo would invalidate/alter the signed payment contract. XGuard therefore leaves the buyer payment exactly intact and records a separate postpaid service receivable only after independent finality proves success.

Safety preserved / strengthened

• strict x402 v2 / Base native-USDC / EIP-3009 parsing
• one durable settlement owner under concurrency
• Payment Identifier and authorization replay binding
• no blind second settlement route after outbound submission starts
• independent Base finality before zero-friction revenue recognition
• explicit FINALIZED, PENDING, PROVEN_FAILED, CONFLICT truth states
• activation nonce is hashed, short-lived and single-use
• merchant ownership must be proven before postpaid billing is activated
• activation signature includes exact pricing terms
• rate limiting and concurrency limiting before expensive work
• unique transaction/log identity prevents double-crediting service-fee payments

Accounting changes

Adds migration 0016_zero_friction_postpaid.sql for:

• activated merchant/pricing state
• activation challenges
• finalized XGuard fee events
• postpaid XGuard service-fee credits

Zero-friction fees are calculated from the independently finalized settlement amount and the merchant’s stored signed terms. Failures and ambiguity create no fee hold/refund cycle.

Compatibility

Legacy API-key/prepaid universal-gateway endpoints remain available for existing clients but are no longer the recommended x402 seller path.

Documentation / machine contract

README, Quickstart, Pricing, Billing, API docs, facilitator policy, Distribution, OpenAPI, costs, unit economics and the documentation quality gate are updated so tooling cannot silently regress the primary x402 path back to API-key/prepaid onboarding.

Release requirement

Do not merge unless verify:release, Payment Security, CodeQL and protected-branch checks are green. Apply D1 migrations before/with the mainnet Worker deployment and verify /start, the payment manifest, /supported, /verify, /settle and settlement-truth surfaces after deployment.

[moelayyan90]

Product-direction update: keep this PR as draft. The canonical XGuard model is now rail-embedded infrastructure, not merchant activation. Merchant signatures/accounts/API keys/prepay must not be required when a facilitator/payment rail embeds XGuard. Preserve this branch for reusable post-finality accounting and compatibility work, but do not merge it as the primary product path. The replacement architecture is tracked in draft PR #277.