demo-95: reference-aware pay (payIn*WithReference), real permit allowlist (HP-5), 0.6.0 — supersedes #47

[marceloceccon]

demo-95 (Oct-7 demo) — W1 reference-aware pay + W2 green build. Supersedes #47 (its toolchain commit is carried verbatim as 58c1815). Part of the PR set on feat/demo-95-sdk-reference-sub-2026-09-29. Do not merge without Marcelo's go. Nothing published — note that merging to develop lets CI publish its usual 0.6.0-dev.<run> to GitHub Packages (HP-3).

Why

The browser could only send plain payInNative / payInToken, so every SDK payment was detected and settled by the gateway but attributed to no payment request: no status progression, no paymentRequestId / metadata on the webhook, nobody to credit. MerchantPayIn V3.2.3 (merged) has payIn*WithReference; this makes the SDK use it — by default.

What changes (commits)

Commit	Change
58c1815	#47 unchanged: ESLint 9 pin, Tailwind v4 PostCSS plugin, esbuild — lint/build restored.
75f915b	HP-5. KNOWN_PERMIT_TOKENS: the placeholder digest → the real digests for USDC Ethereum, DAI Ethereum, USDC Base, each re-derived from the chain (scripts/verify-permit-domains.mjs: name()/version() read, DOMAIN_SEPARATOR() rebuilt and matched — executed 2026-09-30; docs/PERMIT_ALLOWLIST.md). The four failing signPermit tests now target the allow-listed USDC domain and reach the guard each is named after; the unknown-domain refusal has its own test (wallet never asked). ADR-0004 not weakened, no fake domain. ⚠️ DAI's on-chain PERMIT_TYPEHASH is Permit(holder,spender,nonce,expiry,allowed) — not EIP-2612 (executed). Allow-listing it alone would make permit:'auto' sign a payload DAI cannot redeem and call a selector it lacks, breaking DAI payments that fall back to approve() today. So the digest is in (owner decision) and detectPermitSupport treats any token whose PERMIT_TYPEHASH isn't EIP-2612's as unsupported → approve(). Tokens without that view (OpenZeppelin) are unaffected.
ef56df7	W1. ABI + selectors (0x817da306, 0xa7d020be, pinned against the compiled V3.2.3 artifact); pure buildPayInCall; executePayIn{Native,Token}WithReference; resolveAttribution — the one policy every surface applies before the wallet is touched: attributed is the default and refuses without a valid non-zero bytes32 (MissingPaymentReferenceError); plain payIn* only on mode: 'unattributed'. usePayment().startPayment(…, { paymentReference }); Web3SettleConfig.createPayment(ctx) lets the modal get the reference from the merchant backend at Pay time (exact chain/token/amount + the userId the modal used to drop); headless start(amount, { paymentReference }) → runner; <web3settle-pay-button payment-reference>. Breaking: createTopUpSession / getSessionStatus (+ CreateSessionResponse(Schema), SESSION_POLL_INTERVAL_MS, MAX_POLL_ATTEMPTS) removed — they called /api/storefronts/{id}/sessions, which no gateway serves (404), and payment creation needs the API key, which must stay server-side.
66707f1	README leads with the real create → reference → payIn*WithReference → status → v1 webhook flow; peer table fixed to package.json; known limitation stated; CHANGELOG 0.6.0; version 0.6.0 (chain cut + removed API + new ABI are breaking on 0.x; one line to revert to 0.5.1 if you prefer — HP-3).

API shape chosen (work pack "prefer startPayment({ paymentReference }) OR createAndPay"): startPayment({ paymentReference }) + the modal's createPayment callback. One knob, mode: 'attributed' | 'unattributed' (default attributed) — requireReference: true is exactly the default; a second boolean for the same invariant was not added (R7). No createAndPay, no invented sessions route.

Acceptance — evidence tags

• SDK attributes a pay-in via WithReference — executed end to end: the demo's browser click path pays through usePayment, and the E2E decodes the mined calldata as payInNativeWithReference(reference) (merchant-integration-demo e2e/sdk-bound-checkout.spec.ts, 19/19 on a wiped stack, three runs).
• unit tests: WithReference selector/encoding, refusal without a reference before any wallet call (React hook, headless runner, WC) — executed.
• fix: post-chain-cut remediation (CI / integrity) #47 superseded, build green — executed locally from clean trees: typecheck pass · lint 0 errors (the 10 pre-existing set-state-in-effect warnings) · vitest 199 passed, 0 failed (was 165 / 4 failing) · build pass. The demo Docker image ran this SDK's npm ci && npm run build successfully (executed).
• TRON (./tron) pay-ins are not reference-aware yet (root humanpending.md HP-25).
• Known limitation: WEB3SETTLE_PAYMENT_CONFIG_PUBKEY_PRIMARY is still all-zero, so Web3SettleTopUpModal / Web3SettlePayButton / the headless controller cannot load a real gateway's signed config (HP-24 — needs the real key). The demo therefore uses usePayment with its own chain config.

Commits authored as Marcelo Ceccon <marcelo@ceccon.org> (git identity set per repo in this devcontainer, from the repos' history) by the demo-95 agent run.

Root PR (runbook DEMO_OCT7.md, humanpending, SoftwareGaps): web3settle/web3settle-monorepo#7