feat: canonical Casper settlement v3 production RC

[coinsecuritiescompany]

Scope

Supersedes chain-local agent-registration settlement with a value-only canonical settlement contract for the global Agent Passport architecture.

Economics

• route 1 = AIFP-1: gross-inclusive 99% merchant / 1% AiFinPay treasury / 0% creator
• route 2 = AIFP-2/x402: 100% merchant/provider / 0% AiFinPay / 0% creator
• no fee-on-top path
• AIFP-1 rejects amounts whose 1% leg rounds to zero

Identity boundary

The contract no longer treats from_agent/to_agent strings as financial identity. Payer authorization is the Casper caller; global @username/AIFP-ID resolution stays in AIFP-3 with signed wallet bindings.

Safety

• new install, starts paused
• installer becomes admin; explicit treasury account-hash
• admin pause/treasury/admin rotation
• 20-minute max expiry window
• request-id replay rejection before transfers
• atomic native CSPR merchant + treasury settlement
• stored receipt/event includes gross and split

Asset scope

Casper defaults to native CSPR only. No USDC/USD₮ contract is claimed without issuer-confirmed canonical asset support.

Release gate

Source-level RC only. Requires CI green, independent review, new deploy, named-key/config readback, exact artifact evidence, paid AIFP-1/AIFP-2 E2E and replay/expiry negative tests before unpause.

Built from the security-hardening work in PR #11; that PR should not be treated as the final canonical economic model.

[enot3615]

Independent pre-deploy verification flag. The v3 contract verifies clean (value-only atomic transfer-before-receipt, 99/1/0 + 100/0/0, replay/expiry/pause). But the JS tooling still targets the LEGACY v1 entrypoint. The handoff says "wallet builder uses exact StoredContractByHash::pay", yet no builder calls pay — every payment path builds pay_agent with v1 args (from_agent/to_agent/amount), which v3 does not expose:

• demo/demo-mainnet.js (~L83) — the "LIVE MAINNET agent settlement" script → pay_agent
• demo/demo.js (~L120) → pay_agent

→ A settlement against v3 via this tooling would fail (or hit the quarantined v1). Fix the JS builders/demo to call the v3 pay entrypoint with v3 args before any Casper E2E.

[enot3615]

Ready-to-apply spec for the testnet builder (follow-up to my legacy-entrypoint flag — I read the v3 pay signature in src/main.rs, so here is the exact change).

v3 entrypoint is pay with args: route:u8, merchant:String, gross_amount:U512, request_id:String, valid_until_ms:u64. There is no agent registry in v3 — drop register_agent entirely and settle straight to the merchant account-hash.

In demo/demo-mainnet.js (and the testnet demo), replace the two register_agent calls + the pay_agent call with a single pay:

// no register_agent — v3 has no agent registry
const validUntilMs = blockTimeMs + 10 * 60 * 1000;        // ≤ 20 min ahead, else PaymentExpired
h = await submit(callContract(kp, 'pay', RuntimeArgs.fromMap({
  route:          CLValueBuilder.u8(1),                    // 1 = AIFP-1 (99/1/0); 2 = AIFP-2 (100/0/0)
  merchant:       CLValueBuilder.string(providerHash),     // 'account-hash-…' of the payee
  gross_amount:   CLValueBuilder.u512(AMOUNT),             // payer total in motes; fee is deducted FROM gross
  request_id:     CLValueBuilder.string(REQ),
  valid_until_ms: CLValueBuilder.u64(validUntilMs),
})));

Three semantic gotchas the demo's assertion must track (else it fails a correct contract):

1. Gross-inclusive. For route=1 the provider receives gross − 1% (99%), not the full AMOUNT. The "provider balance increases by the exact settlement amount" check has to expect the 99% leg (and treasury +1%); for route=2 it's the full 100%.
2. valid_until_ms is mandatory and capped ~20 min ahead — pull block time, don't hard-code a far-future constant.
3. No from_agent/to_agent. The payer is the deploy signer; the payee is the merchant account-hash string.

Happy to open this as a PR against your RC branch if you'd rather I land it — just say the word; leaving it as a spec so I don't step on the testnet-builder work you're doing.