@provex/utils 1.9.2 → 1.10.0-rc.20260912192040.fdbb8fc

package/dist/contracts.js

@@ -24,6 +24,7 @@
  */
 import { getAddress } from 'viem';
 import { base, pulsechain } from 'viem/chains';
+import { isChainId } from './chain.js';
 export const reclaimSigners = {
     peerWitnessSigner: '0x0636c417755E3ae25C6c166D181c0607F4C572A3',
     reclaimWitnessSigner: '0x244897572368eadf65bfbc5aec98d8e5443a9072',
@@ -97,29 +98,29 @@ export const v4BaseContracts = {
     orchestratorRegistry: getAddress('0xBe9fED15ED7A4B915C03EFcEcb9662739C3382A9'),
 };
 /**
- * V4 contracts on PulseChain (Chain ID 369) — NOT YET DEPLOYED.
- *
- * EscrowV2 + OrchestratorV2 are not live on PulseChain yet (the deploy reverts
- * at the EscrowV2 step). When the deploy lands — whether on mainnet or on a
- * local Anvil fork of PulseChain (chain id stays 369 on a fork) — fill the six
- * values below from `zkp2p-contracts/deployments/pulsechain/{EscrowV2,
- * OrchestratorV2,UnifiedPaymentVerifierV2,OrchestratorRegistry}.json` and
- * register it in the `contracts.v4` map. `getLatestConfiguredVersion(369)` then
- * routes new PulseChain deposits to v4 automatically.
- *
- * Leaving it unregistered (rather than filled with placeholder addresses) keeps
- * `getContracts('v4', 369)` returning `undefined`, so no path can accidentally
- * write to a non-existent contract before the real addresses exist.
- *
- * export const v4PulsechainContracts = {
- *   usdc:                   getAddress('0x15D38573d2feeb82e7ad5187aB8c1D52810B1f07'), // same PLSD/USDC as v3
- *   gatingService:          getAddress('0x…'),
- *   escrow:                 [getAddress('0x…')], // EscrowV2
- *   unifiedPaymentVerifier: [getAddress('0x…')], // UnifiedPaymentVerifierV2
- *   orchestrator:           [getAddress('0x…')], // OrchestratorV2
- *   orchestratorRegistry:   getAddress('0x…'),
- * } as V4Contracts
+ * V4 contracts on PulseChain (Chain ID 369) — LIVE as of 2026-07-24.
+ *
+ * EscrowV2 + OrchestratorV2 landed on PulseChain mainnet at blocks
+ * 27112395–27112403 (deployer 0x948eB6D3A08BEb29Dc1D08d09753862573A94122).
+ * Bytecode verified on chain 369. Addresses taken from
+ * `zkp2p-contracts/deployments/pulsechain/{EscrowV2,OrchestratorV2,
+ * OrchestratorRegistry,UnifiedPaymentVerifierV2}.json`.
+ *
+ * Registered in the `contracts.v4` map below, so `getLatestConfiguredVersion(369)`
+ * now routes new PulseChain deposits to v4. This must ship alongside the indexer
+ * wiring in `packages/indexer/ponder.config.ts` (PulseChain v4 streams +
+ * `startBlocks.pulsechain.v4Escrow` = 27112398): deploy the indexer first so a
+ * fresh reindex covers the EscrowV2 events before the UI starts writing v4
+ * deposits it would otherwise fail to read.
  */
+export const v4PulsechainContracts = {
+    usdc: getAddress('0x15D38573d2feeb82e7ad5187aB8c1D52810B1f07'), // same PLSD/USDC as v3
+    gatingService: getAddress('0x4Bd6364FCC4D8A537aBfee33B16E959794fDf9Cf'), // same off-chain signer as v3
+    escrow: [getAddress('0xD48184389e7FE8EFb4f16AE62d8eFad9145099e3')], // EscrowV2
+    unifiedPaymentVerifier: [getAddress('0x8966f5428CD8893722BF5EbF74D44BE93F600796')], // UnifiedPaymentVerifierV2
+    orchestrator: [getAddress('0xc5CcE8D7AAcFDa82111bC8896Eb0F8f49888d171')], // OrchestratorV2
+    orchestratorRegistry: getAddress('0x18c0CE7814895327518ae625F7c72cA1315dAb89'),
+};
 /**
  * V3 contracts deployed to Pulsechain (Chain ID 369)
  * Deployed: 2026-01-12
@@ -149,10 +150,36 @@ export const V3_PULSECHAIN_DEPLOYMENT_REFERENCE = {
     nullifierRegistry: '0x4AeA2288ec542963256b66D70EfddF4cB8754f82',
     simpleAttestationVerifier: '0x49DAd1f29a3FE2E4D90a59e6687d9f7A2836B4a8',
 };
+/**
+ * V4 (EscrowV2 / OrchestratorV2) Pulsechain ancillary contracts - FOR REFERENCE ONLY
+ *
+ * Deployed on chain 369 on 2026-07-24 but NOT read by any runtime code path today
+ * (unlike V3_PULSECHAIN_DEPLOYMENT_REFERENCE, whose entries the escrow exposes
+ * dynamically). Recorded purely as an ops reference — a documented home for the
+ * addresses you need when making owner calls or wiring a future feature. Do NOT
+ * import these into runtime paths; if one ever gets called, add a typed entry to
+ * the version contract sets above instead.
+ */
+export const V4_PULSECHAIN_DEPLOYMENT_REFERENCE = {
+    // N-of-M witness attestation verifier (EnumerableSet witnesses + configurable
+    // threshold; defaults to 1 = "any witness"). Swap target for the multi-
+    // attestation cutover via UnifiedPaymentVerifier.setAttestationVerifier();
+    // drop-in replacement for the single-witness simpleAttestationVerifier.
+    multiAttestationVerifier: '0xd98bdf683a8b218Ea45Cc8A258ef1A662ef8e9ae',
+    // Whitelist-groups system — only live on PulseChain (Base has neither yet).
+    // WhitelistPreIntentHookV2 admits a taker who is directly whitelisted OR a
+    // member of any attached AddressGroupRegistry group; supersedes the V1 hook.
+    addressGroupRegistry: '0x2e6E054eca4EC24149516AC8036Dd30c937237AF',
+    whitelistPreIntentHookV2: '0x4F7f6691f8c362d31d19567133Ce33CC3EEd6d51',
+    // Read-only v4 aggregator: every external fn is `view`, holds no state, and
+    // takes the escrow/orchestrator as call params (so it works against any v4
+    // deployment). Pairs with the V3 protocolViewer above.
+    protocolViewerV2: '0x02CC2997B73A1d1E1D0151319F25125B11A55565',
+};
 export const versions = {
     V2: 'v2', // Deprecated: Historical data only
     V3: 'v3', // Active: Primary version for Base buy/sell UI
-    V4: 'v4', // OrchestratorV2 + EscrowV2 (Base live; PulseChain pending)
+    V4: 'v4', // OrchestratorV2 + EscrowV2 (live on Base and PulseChain)
 };
 export const versionKeys = Object.values(versions);
 /**
@@ -173,9 +200,11 @@ export const contracts = {
         [pulsechain.id]: v3PulsechainContracts,
     },
     v4: {
-        // OrchestratorV2 + EscrowV2. Base only until a PulseChain v4 deploy exists;
-        // getContracts('v4', 369) returns undefined until then.
+        // OrchestratorV2 + EscrowV2. Live on both Base and PulseChain (369 deploy
+        // landed 2026-07-24). getLatestConfiguredVersion routes new deposits on both
+        // chains to v4.
         [base.id]: v4BaseContracts,
+        [pulsechain.id]: v4PulsechainContracts,
     },
 };
 /**
@@ -216,9 +245,9 @@ const VERSION_PRECEDENCE = ['v4', 'v3', 'v2'];
  *
  * This is the routing decision for **new deposits**: a chain automatically
  * moves to v4 the moment its v4 contracts are registered in
- * `contracts.v4[chainId]` — no code change, no flag flip. Base returns `'v4'`
- * today (EscrowV2/OrchestratorV2 are live); PulseChain returns `'v3'` until a
- * v4 deploy lands there, then flips to `'v4'` on its own.
+ * `contracts.v4[chainId]` — no code change, no flag flip. Both Base and
+ * PulseChain return `'v4'` today (EscrowV2/OrchestratorV2 are live on both; the
+ * PulseChain deploy landed 2026-07-24).
  *
  * Distinct from {@link getLatestContract}'s `getDefaultVersion` fallback, which
  * stays on v3 for read paths that aggregate across generations. Only deposit
@@ -228,10 +257,9 @@ const VERSION_PRECEDENCE = ['v4', 'v3', 'v2'];
  * @returns The newest version with a configured escrow, or `'v3'` as a safe fallback
  *
  * @example
- * // Base has v4 contracts registered → new deposits go to v4
+ * // Both chains have v4 contracts registered → new deposits go to v4
  * getLatestConfiguredVersion(base.id) // 'v4'
- * // PulseChain has no v4 contracts yet → new deposits stay on v3
- * getLatestConfiguredVersion(pulsechain.id) // 'v3'
+ * getLatestConfiguredVersion(pulsechain.id) // 'v4'
  */
 export const getLatestConfiguredVersion = (chainId) => {
     for (const version of VERSION_PRECEDENCE) {
@@ -274,6 +302,83 @@ export const getLatestContract = (chainId, key, version) => {
         return null;
     return Array.isArray(target) ? target.at(-1) : target;
 };
+/**
+ * The UnifiedPaymentVerifier whose address belongs in the EIP-712 domain of a
+ * payment attestation on this chain.
+ *
+ * **Why this is not keyed on the deposit's generation.** A v3 deposit and a v4
+ * deposit do not get different verifiers. Both escrow generations point at the
+ * *same* `PaymentVerifierRegistry`, and the registry resolves a payment method
+ * to a verifier — so the verifier follows the registry's current mapping, never
+ * the escrow the deposit happens to live in. Verified on chain 369 on
+ * 2026-07-24: `escrow.paymentVerifierRegistry()` returns
+ * `0x6a4fF1950Be05995dEe75920cf27CD8FEbB6597A` for both the v3 escrow
+ * (`0x0B42…f11a`) and the v4 escrow (`0xD481…99e3`), and `getVerifier(...)` on
+ * that registry returns the v4 UnifiedPaymentVerifierV2
+ * (`0x8966f5428CD8893722BF5EbF74D44BE93F600796`) for **all 15** registered
+ * payment methods — including every method a v3 deposit uses.
+ *
+ * **Why it matters.** `UnifiedPaymentVerifier` builds its domain separator with
+ * `verifyingContract = address(this)`, so an attestation signed against the
+ * wrong verifier address produces a digest the on-chain check rejects. Pinning
+ * this to `'v3'` (as every call site used to) hands the signer the retired
+ * `0x0e73181a…` and every submission fails signature verification.
+ *
+ * Tracking the latest configured version keeps this correct through the next
+ * verifier generation too, for the same reason
+ * {@link getLatestConfiguredVersion} keeps deposit routing correct: registering
+ * the new addresses is the only step.
+ *
+ * @param chainId - The chain the intent lives on (use `deposit.chainId`).
+ * @returns The verifier address, or null when the chain has none configured.
+ *
+ * @example
+ * ```ts
+ * const verifyingContract = getPaymentAttestationVerifier(deposit.chainId)
+ * // chain 369 → 0x8966f5428CD8893722BF5EbF74D44BE93F600796
+ * ```
+ */
+export const getPaymentAttestationVerifier = (chainId) => getLatestContract(chainId, 'unifiedPaymentVerifier', getLatestConfiguredVersion(chainId));
+/**
+ * Check a client-supplied `verifyingContract` against the verifier this chain
+ * actually settles against, and refuse anything else.
+ *
+ * **Why a server-side check exists at all.** The attestation signers take
+ * `verifyingContract` from the request body and sign the EIP-712 digest built
+ * around it. Whatever address the caller names is what our key attests to. A
+ * stale browser bundle still holding the retired v3 verifier therefore gets a
+ * perfectly valid signature over the wrong domain — and the buyer discovers it
+ * only when `fulfillIntent` reverts on signature verification, *after* the
+ * fiat has left their bank. Nobody can refund that from our side.
+ *
+ * Fail closed: signing is the irreversible step, so an unrecognised chain or an
+ * unparseable address is a refusal, never a pass-through.
+ *
+ * Comparison is case-insensitive because the address arrives as JSON from a
+ * browser and may be checksummed, lowercased, or neither.
+ *
+ * @param chainId - The chain the attestation will settle on
+ * @param verifyingContract - The address the caller asked us to sign for
+ * @returns The configured address on success, or the reason for refusing
+ *
+ * @example
+ * ```ts
+ * const check = checkPaymentAttestationVerifier({ chainId, verifyingContract })
+ * if (!check.ok) {
+ *   res.status(400).json({ error: 'VERIFYING_CONTRACT_REJECTED', reason: check.reason })
+ *   return
+ * }
+ * ```
+ */
+export const checkPaymentAttestationVerifier = ({ chainId, verifyingContract, }) => {
+    const expected = isChainId(chainId) ? getPaymentAttestationVerifier(chainId) : null;
+    if (!expected)
+        return { ok: false, reason: 'unconfigured', expected: null, received: verifyingContract };
+    if (!verifyingContract || verifyingContract.toLowerCase() !== expected.toLowerCase()) {
+        return { ok: false, reason: 'mismatch', expected, received: verifyingContract };
+    }
+    return { ok: true, verifyingContract: expected };
+};
 /**
  * Get all escrow contracts across all versions and chains.
  * Returns a flat list of all escrow locations for querying deposits.
@@ -308,6 +413,58 @@ export function getAllEscrowContracts() {
     }
     return escrows;
 }
+/** Lazily-built escrow address (lowercased) → location index. */
+let escrowLocationIndex = null;
+/**
+ * Locate a known escrow by address: which generation and which chain it is.
+ *
+ * The address is the only thing a deposit row reliably carries, so this is how
+ * a call site with a `deposit` in hand answers "is this v3 or v4?" without a
+ * network read.
+ *
+ * @param escrow - The escrow contract address (case-insensitive).
+ * @returns Its location, or null when the address is not a configured escrow.
+ */
+export function getEscrowLocation(escrow) {
+    if (!escrowLocationIndex) {
+        escrowLocationIndex = new Map(getAllEscrowContracts().map((location) => [location.escrow.toLowerCase(), location]));
+    }
+    return escrowLocationIndex.get(escrow.toLowerCase()) ?? null;
+}
+/**
+ * The protocol generation an escrow address belongs to.
+ *
+ * @param escrow - The escrow contract address (case-insensitive).
+ * @returns The version, or null when the address is not a configured escrow.
+ *
+ * @example
+ * detectVersionFromEscrow('0xD48184389e7FE8EFb4f16AE62d8eFad9145099e3') // 'v4'
+ */
+export function detectVersionFromEscrow(escrow) {
+    return getEscrowLocation(escrow)?.version ?? null;
+}
+/**
+ * The Orchestrator that governs intents for a given escrow.
+ *
+ * **Only v4 can be answered from configuration, and only v4 has to be.** A v2
+ * or v3 escrow exposes `orchestrator()` and callers read it from the chain.
+ * EscrowV2 (v4) does not: it authorizes through an `OrchestratorRegistry` and
+ * has no `orchestrator()` function at all, so that call reverts. The v4
+ * orchestrator address is therefore held explicitly in the v4 contract sets and
+ * returned from here.
+ *
+ * @param escrow - The escrow contract address (case-insensitive).
+ * @returns The orchestrator address for a v4 escrow; null for any other
+ *   generation (the caller should read `orchestrator()` on-chain instead) and
+ *   for unknown addresses.
+ */
+export function getConfiguredOrchestratorForEscrow(escrow) {
+    const location = getEscrowLocation(escrow);
+    if (!location || location.version !== 'v4')
+        return null;
+    const v4ForChain = contracts.v4[location.chainId];
+    return v4ForChain?.orchestrator?.at(-1) ?? null;
+}
 /**
  * Get all V3 escrow contracts across all chains.
  * Used for cross-chain nullifier checking to prevent double-spending.

package/dist/contracts.test.js

@@ -1,7 +1,7 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import { base, pulsechain } from 'viem/chains';
-import { getContracts, getLatestContract, getLatestConfiguredVersion, getAllEscrowContracts, getAllV3EscrowContracts, shortenEscrowAddress, getEscrowVersion, isV3Escrow, supportsOrchestrator, supportsOrchestratorEscrow, v2BaseContracts, v3BaseContracts, v4BaseContracts, v2PulsechainContracts, v3PulsechainContracts, V3_PULSECHAIN_DEPLOYMENT_REFERENCE, contracts, } from './contracts.js';
+import { getContracts, getLatestContract, getLatestConfiguredVersion, getPaymentAttestationVerifier, checkPaymentAttestationVerifier, detectVersionFromEscrow, getConfiguredOrchestratorForEscrow, getAllEscrowContracts, getAllV3EscrowContracts, shortenEscrowAddress, getEscrowVersion, isV3Escrow, supportsOrchestrator, supportsOrchestratorEscrow, v2BaseContracts, v3BaseContracts, v4BaseContracts, v2PulsechainContracts, v3PulsechainContracts, v4PulsechainContracts, V3_PULSECHAIN_DEPLOYMENT_REFERENCE, contracts, } from './contracts.js';
 describe('contracts', () => {
     describe('getDefaultVersion', () => {
         it('returns v3 for Base', async () => {
@@ -24,12 +24,14 @@ describe('contracts', () => {
         it('routes Base to v4 because EscrowV2/OrchestratorV2 are registered', () => {
             assert.strictEqual(getLatestConfiguredVersion(base.id), 'v4');
         });
-        it('keeps PulseChain on v3 until its v4 contracts are registered', () => {
-            // No contracts.v4[369] entry exists yet (the PulseChain v4 deploy hasn't
-            // landed). Routing to v4 here would point new deposits at a missing
-            // escrow — so it must stay v3 until the entry is filled in.
-            assert.strictEqual(getContracts('v4', pulsechain.id), undefined);
-            assert.strictEqual(getLatestConfiguredVersion(pulsechain.id), 'v3');
+        it('routes PulseChain to v4 now that its EscrowV2 is registered', () => {
+            // The PulseChain v4 deploy landed 2026-07-24 and its addresses went into
+            // contracts.v4[369], which is the entire flip: registering the escrow is
+            // what moves new deposits onto it. Every read path keyed on the
+            // generation has to follow — see `buyEligibleDepositVersionsCondition`
+            // and `getPaymentAttestationVerifier`.
+            assert.ok(getContracts('v4', pulsechain.id)?.escrow?.length);
+            assert.strictEqual(getLatestConfiguredVersion(pulsechain.id), 'v4');
         });
         it('resolves to a version that has an escrow, with nothing newer configured', () => {
             // The invariant that makes the auto-flip safe: the resolved version is
@@ -336,4 +338,129 @@ describe('contracts', () => {
             assert.strictEqual(supportsOrchestratorEscrow('0x0000000000000000000000000000000000000000', base.id), false);
         });
     });
+    describe('getPaymentAttestationVerifier', () => {
+        // The EIP-712 domain of a payment attestation carries the verifier's own
+        // address (`verifyingContract = address(this)` in UnifiedPaymentVerifier),
+        // so signing against the wrong one yields a digest the on-chain check
+        // rejects and every submission fails.
+        it('follows the latest configured generation, not a pinned v3', () => {
+            // Both escrow generations share one PaymentVerifierRegistry, and that
+            // registry resolves every payment method to the newest verifier — so the
+            // answer tracks the newest configured version rather than the deposit's
+            // own escrow. Verified on chain 369 on 2026-07-24: all 15 registered
+            // methods, v3 deposits included, resolve to the v4 verifier.
+            for (const chainId of [base.id, pulsechain.id]) {
+                assert.strictEqual(getPaymentAttestationVerifier(chainId), getLatestContract(chainId, 'unifiedPaymentVerifier', getLatestConfiguredVersion(chainId)));
+            }
+        });
+        it('does not return the retired v3 verifier on PulseChain', () => {
+            assert.notStrictEqual(getPaymentAttestationVerifier(pulsechain.id), v3PulsechainContracts.unifiedPaymentVerifier.at(-1));
+            assert.strictEqual(getPaymentAttestationVerifier(pulsechain.id), v4PulsechainContracts.unifiedPaymentVerifier.at(-1));
+        });
+    });
+    describe('detectVersionFromEscrow', () => {
+        it('names the generation an escrow address belongs to', () => {
+            assert.strictEqual(detectVersionFromEscrow(v2BaseContracts.escrow[0]), 'v2');
+            assert.strictEqual(detectVersionFromEscrow(v3PulsechainContracts.escrow[0]), 'v3');
+            assert.strictEqual(detectVersionFromEscrow(v4PulsechainContracts.escrow[0]), 'v4');
+        });
+        it('is case-insensitive — indexer rows store lowercased addresses', () => {
+            assert.strictEqual(detectVersionFromEscrow(v4PulsechainContracts.escrow[0].toLowerCase()), 'v4');
+        });
+        it('returns null for an address that is not a configured escrow', () => {
+            assert.strictEqual(detectVersionFromEscrow('0x0000000000000000000000000000000000000000'), null);
+        });
+    });
+    describe('getConfiguredOrchestratorForEscrow', () => {
+        it('answers for v4, whose escrow has no orchestrator() to read', () => {
+            // EscrowV2 authorizes through an OrchestratorRegistry and exposes no
+            // `orchestrator()`, so that call reverts and the address has to come
+            // from configuration. Without this, every dependent step (fulfill,
+            // payee details, fee display) waits on an address that never arrives.
+            assert.strictEqual(getConfiguredOrchestratorForEscrow(v4PulsechainContracts.escrow[0]), v4PulsechainContracts.orchestrator.at(-1));
+        });
+        it('returns null for v2/v3, which expose orchestrator() and are read on-chain', () => {
+            assert.strictEqual(getConfiguredOrchestratorForEscrow(v3PulsechainContracts.escrow[0]), null);
+            assert.strictEqual(getConfiguredOrchestratorForEscrow(v2BaseContracts.escrow[0]), null);
+        });
+        it('returns null for an unknown escrow address', () => {
+            assert.strictEqual(getConfiguredOrchestratorForEscrow('0x0000000000000000000000000000000000000000'), null);
+        });
+    });
+    describe('checkPaymentAttestationVerifier', () => {
+        // These are not "does the comparison work" tests. The signer takes
+        // `verifyingContract` from the request body and signs the EIP-712 digest
+        // built around it, so whatever passes this check is what our key attests
+        // to. A pass that should have been a refusal produces a valid signature
+        // over the wrong domain, and the buyer learns about it when
+        // `fulfillIntent` reverts AFTER their fiat has already left their bank.
+        // Every assertion below is about that one failure.
+        it('accepts the verifier the chain actually settles against', () => {
+            const expected = getPaymentAttestationVerifier(pulsechain.id);
+            const result = checkPaymentAttestationVerifier({
+                chainId: pulsechain.id,
+                verifyingContract: expected,
+            });
+            assert.strictEqual(result.ok, true);
+            assert.strictEqual(result.ok && result.verifyingContract, expected);
+        });
+        it('accepts regardless of address casing', () => {
+            // The address arrives as JSON from a browser and may be checksummed,
+            // lowercased, or neither. Rejecting on casing alone would break every
+            // honest client.
+            const expected = getPaymentAttestationVerifier(pulsechain.id);
+            assert.strictEqual(checkPaymentAttestationVerifier({
+                chainId: pulsechain.id,
+                verifyingContract: expected.toLowerCase(),
+            }).ok, true);
+            assert.strictEqual(checkPaymentAttestationVerifier({
+                chainId: pulsechain.id,
+                verifyingContract: expected.toUpperCase().replace('0X', '0x'),
+            }).ok, true);
+        });
+        it('refuses the retired verifier a stale bundle would ask for', () => {
+            // The concrete regression: a browser still running the pre-v4 bundle
+            // names the v3 UnifiedPaymentVerifier. It is a real, once-correct
+            // address — nothing about it looks malformed.
+            const retired = getLatestContract(pulsechain.id, 'unifiedPaymentVerifier', 'v3');
+            const current = getPaymentAttestationVerifier(pulsechain.id);
+            assert.notStrictEqual(retired, current, 'fixture is meaningless if these match');
+            const result = checkPaymentAttestationVerifier({
+                chainId: pulsechain.id,
+                verifyingContract: retired,
+            });
+            assert.strictEqual(result.ok, false);
+            assert.strictEqual(!result.ok && result.reason, 'mismatch');
+            assert.strictEqual(!result.ok && result.expected, current);
+        });
+        it('refuses an arbitrary address', () => {
+            const result = checkPaymentAttestationVerifier({
+                chainId: pulsechain.id,
+                verifyingContract: '0x000000000000000000000000000000000000dEaD',
+            });
+            assert.strictEqual(result.ok, false);
+            assert.strictEqual(!result.ok && result.reason, 'mismatch');
+        });
+        it('refuses a missing verifyingContract rather than defaulting to the configured one', () => {
+            // Fail closed. Silently substituting the configured address would sign
+            // for a caller who never named a domain at all.
+            const result = checkPaymentAttestationVerifier({
+                chainId: pulsechain.id,
+                verifyingContract: undefined,
+            });
+            assert.strictEqual(result.ok, false);
+            assert.strictEqual(!result.ok && result.reason, 'mismatch');
+        });
+        it('refuses an unsupported chain instead of trusting the caller', () => {
+            // chainId reaches the handler as untyped JSON. An unknown chain has no
+            // verifier to compare against, so there is nothing to validate — the
+            // only safe answer is no.
+            const result = checkPaymentAttestationVerifier({
+                chainId: 1,
+                verifyingContract: getPaymentAttestationVerifier(pulsechain.id),
+            });
+            assert.strictEqual(result.ok, false);
+            assert.strictEqual(!result.ok && result.reason, 'unconfigured');
+        });
+    });
 });

package/dist/deposit.d.ts

@@ -68,3 +68,53 @@ export type EscrowVersion = (typeof escrowVersions)[keyof typeof escrowVersions]
  * Array of escrow version values for use with onchainEnum in ponder.schema.ts.
  */
 export declare const ESCROW_VERSIONS: readonly EscrowVersion[];
+/**
+ * The escrow generations that make up the protocol as it runs today.
+ *
+ * Public surfaces — the activity chart, the deposits table, the analytics
+ * dashboard — deliberately exclude v2 on PulseChain: those deposits predate the
+ * v3 launch entirely and are abandoned, so counting them makes today's numbers
+ * unreadable. That exclusion used to be written as `version === 'v3'` at each
+ * call site, which quietly became "everything except the current generation"
+ * the day v4 went live and flat-lined every one of those surfaces.
+ *
+ * Name the set once so shipping a generation is one edit here, not a hunt for
+ * every hard-coded `'v3'`.
+ */
+export declare const CURRENT_ESCROW_VERSIONS: readonly ["v3", "v4"];
+/**
+ * A currency entry as the escrow's `createDeposit` / `addPaymentMethods` /
+ * `addCurrencies` calls expect it, before generation-specific fields.
+ */
+export type EscrowCurrency = {
+    code: `0x${string}`;
+    minConversionRate: bigint;
+};
+/**
+ * v4's currency struct carries an `oracleRateConfig`; a zeroed config means
+ * "no oracle — settle at the fixed `minConversionRate`", which reproduces v3
+ * behaviour exactly. Deposits that do not price off an oracle use this.
+ */
+export declare const EMPTY_ORACLE_RATE_CONFIG: {
+    readonly adapter: `0x${string}`;
+    readonly adapterConfig: `0x${string}`;
+    readonly spreadBps: 0;
+    readonly maxStaleness: 0;
+};
+/**
+ * Shape currency entries for a given escrow generation.
+ *
+ * Three escrow writes changed their currency tuple in v4 — `createDeposit`,
+ * `addPaymentMethods` and `addCurrencies` all gained the oracle rate config,
+ * which changes their selector. Sending v3-shaped currencies to EscrowV2
+ * produces a call it cannot decode; sending v4-shaped currencies to a v3
+ * escrow does the same. Route every currency list through here so the two
+ * stay paired with the interface the caller selected.
+ *
+ * @param currencies - The currency entries to shape
+ * @param version - The escrow generation being written to
+ * @returns The entries, with the zeroed oracle config attached for v4
+ */
+export declare const toEscrowCurrencies: <T extends EscrowCurrency>(currencies: readonly T[], version: EscrowVersion) => readonly (T | (T & {
+    oracleRateConfig: typeof EMPTY_ORACLE_RATE_CONFIG;
+}))[];

package/dist/deposit.js

@@ -51,3 +51,48 @@ export const escrowVersions = {
  * Array of escrow version values for use with onchainEnum in ponder.schema.ts.
  */
 export const ESCROW_VERSIONS = Object.values(escrowVersions);
+/**
+ * The escrow generations that make up the protocol as it runs today.
+ *
+ * Public surfaces — the activity chart, the deposits table, the analytics
+ * dashboard — deliberately exclude v2 on PulseChain: those deposits predate the
+ * v3 launch entirely and are abandoned, so counting them makes today's numbers
+ * unreadable. That exclusion used to be written as `version === 'v3'` at each
+ * call site, which quietly became "everything except the current generation"
+ * the day v4 went live and flat-lined every one of those surfaces.
+ *
+ * Name the set once so shipping a generation is one edit here, not a hunt for
+ * every hard-coded `'v3'`.
+ */
+export const CURRENT_ESCROW_VERSIONS = [
+    escrowVersions.V3,
+    escrowVersions.V4,
+];
+/**
+ * v4's currency struct carries an `oracleRateConfig`; a zeroed config means
+ * "no oracle — settle at the fixed `minConversionRate`", which reproduces v3
+ * behaviour exactly. Deposits that do not price off an oracle use this.
+ */
+export const EMPTY_ORACLE_RATE_CONFIG = {
+    adapter: '0x0000000000000000000000000000000000000000',
+    adapterConfig: '0x',
+    spreadBps: 0,
+    maxStaleness: 0,
+};
+/**
+ * Shape currency entries for a given escrow generation.
+ *
+ * Three escrow writes changed their currency tuple in v4 — `createDeposit`,
+ * `addPaymentMethods` and `addCurrencies` all gained the oracle rate config,
+ * which changes their selector. Sending v3-shaped currencies to EscrowV2
+ * produces a call it cannot decode; sending v4-shaped currencies to a v3
+ * escrow does the same. Route every currency list through here so the two
+ * stay paired with the interface the caller selected.
+ *
+ * @param currencies - The currency entries to shape
+ * @param version - The escrow generation being written to
+ * @returns The entries, with the zeroed oracle config attached for v4
+ */
+export const toEscrowCurrencies = (currencies, version) => version === 'v4'
+    ? currencies.map((currency) => ({ ...currency, oracleRateConfig: EMPTY_ORACLE_RATE_CONFIG }))
+    : currencies;

package/dist/events.d.ts

@@ -23,7 +23,7 @@
  * 3. Deposit close events (withdrawal, close)
  * 4. Protocol configuration events (dust, fees, registries)
  */
-export declare const eventOrder: readonly ["deposit_received", "deposit_payment_method_added", "deposit_payment_method_active_updated", "deposit_currency_added", "deposit_delegate_set", "deposit_delegate_removed", "deposit_conversion_rate_updated", "deposit_accepting_intents_updated", "deposit_intent_amount_range_updated", "deposit_funds_added", "intent_signaled", "funds_locked", "payment_verified", "funds_unlocked_and_transferred", "intent_fulfilled", "intent_pruned", "funds_unlocked", "intent_expiry_extended", "funds_removed", "deposit_withdrawn", "deposit_closed", "dust_collected", "dust_recipient_updated", "dust_threshold_updated", "deposit_retain_on_empty_updated", "payment_method_currency_added", "payment_method_currency_removed", "payment_method_added", "payment_method_removed", "allow_multiple_intents_updated", "escrow_registry_updated", "post_intent_hook_registry_updated", "protocol_fee_recipient_updated", "protocol_fee_updated", "relayer_registry_updated", "unpaused", "paused", "intent_expiration_period_updated", "max_intents_per_deposit_updated", "min_deposit_amount_set", "orchestrator_updated", "ownership_transferred", "payment_verifier_registry_updated", "provider_hash_added", "provider_hash_removed"];
+export declare const eventOrder: readonly ["deposit_received", "deposit_payment_method_added", "deposit_payment_method_active_updated", "deposit_currency_added", "deposit_delegate_set", "deposit_delegate_removed", "deposit_rate_manager_set", "deposit_rate_manager_cleared", "deposit_pre_intent_hook_set", "deposit_whitelist_hook_set", "deposit_conversion_rate_updated", "deposit_oracle_rate_config_set", "deposit_oracle_rate_config_removed", "deposit_accepting_intents_updated", "deposit_intent_amount_range_updated", "deposit_funds_added", "intent_signaled", "funds_locked", "payment_verified", "funds_unlocked_and_transferred", "intent_fulfilled", "intent_pruned", "funds_unlocked", "intent_expiry_extended", "intent_manager_fee_snapshotted", "intent_referral_fee_distributed", "funds_removed", "deposit_withdrawn", "deposit_closed", "dust_collected", "dust_recipient_updated", "dust_threshold_updated", "deposit_retain_on_empty_updated", "payment_method_currency_added", "payment_method_currency_removed", "payment_method_added", "payment_method_removed", "allow_multiple_intents_updated", "escrow_registry_updated", "orchestrator_registry_updated", "partial_manual_release_delay_updated", "post_intent_hook_registry_updated", "protocol_fee_recipient_updated", "protocol_fee_updated", "relayer_registry_updated", "unpaused", "paused", "intent_expiration_period_updated", "max_intents_per_deposit_updated", "min_deposit_amount_set", "orchestrator_updated", "ownership_transferred", "payment_verifier_registry_updated", "provider_hash_added", "provider_hash_removed"];
 /**
  * Union type of all valid event type names.
  * Use this when filtering or handling specific event types.
@@ -38,4 +38,4 @@ export type EventType = (typeof eventOrder)[number];
  * const id = eventOrderId.get('intent_signaled') // 9
  * ```
  */
-export declare const eventOrderId: Map<"paused" | "deposit_received" | "deposit_payment_method_added" | "deposit_payment_method_active_updated" | "deposit_currency_added" | "deposit_delegate_set" | "deposit_delegate_removed" | "deposit_conversion_rate_updated" | "deposit_accepting_intents_updated" | "deposit_intent_amount_range_updated" | "deposit_funds_added" | "intent_signaled" | "funds_locked" | "payment_verified" | "funds_unlocked_and_transferred" | "intent_fulfilled" | "intent_pruned" | "funds_unlocked" | "intent_expiry_extended" | "funds_removed" | "deposit_withdrawn" | "deposit_closed" | "dust_collected" | "dust_recipient_updated" | "dust_threshold_updated" | "deposit_retain_on_empty_updated" | "payment_method_currency_added" | "payment_method_currency_removed" | "payment_method_added" | "payment_method_removed" | "allow_multiple_intents_updated" | "escrow_registry_updated" | "post_intent_hook_registry_updated" | "protocol_fee_recipient_updated" | "protocol_fee_updated" | "relayer_registry_updated" | "unpaused" | "intent_expiration_period_updated" | "max_intents_per_deposit_updated" | "min_deposit_amount_set" | "orchestrator_updated" | "ownership_transferred" | "payment_verifier_registry_updated" | "provider_hash_added" | "provider_hash_removed", number>;
+export declare const eventOrderId: Map<"paused" | "deposit_received" | "deposit_payment_method_added" | "deposit_payment_method_active_updated" | "deposit_currency_added" | "deposit_delegate_set" | "deposit_delegate_removed" | "deposit_rate_manager_set" | "deposit_rate_manager_cleared" | "deposit_pre_intent_hook_set" | "deposit_whitelist_hook_set" | "deposit_conversion_rate_updated" | "deposit_oracle_rate_config_set" | "deposit_oracle_rate_config_removed" | "deposit_accepting_intents_updated" | "deposit_intent_amount_range_updated" | "deposit_funds_added" | "intent_signaled" | "funds_locked" | "payment_verified" | "funds_unlocked_and_transferred" | "intent_fulfilled" | "intent_pruned" | "funds_unlocked" | "intent_expiry_extended" | "intent_manager_fee_snapshotted" | "intent_referral_fee_distributed" | "funds_removed" | "deposit_withdrawn" | "deposit_closed" | "dust_collected" | "dust_recipient_updated" | "dust_threshold_updated" | "deposit_retain_on_empty_updated" | "payment_method_currency_added" | "payment_method_currency_removed" | "payment_method_added" | "payment_method_removed" | "allow_multiple_intents_updated" | "escrow_registry_updated" | "orchestrator_registry_updated" | "partial_manual_release_delay_updated" | "post_intent_hook_registry_updated" | "protocol_fee_recipient_updated" | "protocol_fee_updated" | "relayer_registry_updated" | "unpaused" | "intent_expiration_period_updated" | "max_intents_per_deposit_updated" | "min_deposit_amount_set" | "orchestrator_updated" | "ownership_transferred" | "payment_verifier_registry_updated" | "provider_hash_added" | "provider_hash_removed", number>;

package/dist/events.js

@@ -31,8 +31,23 @@ export const eventOrder = [
     'deposit_currency_added',
     'deposit_delegate_set',
     'deposit_delegate_removed',
+    // v4: rate-management authority, delegated separately from the deposit
+    // delegate. Grouped with the delegate events because it is the same kind of
+    // fact — who, other than the owner, may act on this deposit.
+    'deposit_rate_manager_set',
+    'deposit_rate_manager_cleared',
+    // v4: per-deposit hooks held on the orchestrator. A whitelist hook makes a
+    // deposit reservable only by addresses it approves, so a reader that ignores
+    // this offers the deposit to buyers whose `signalIntent` will revert.
+    'deposit_pre_intent_hook_set',
+    'deposit_whitelist_hook_set',
     // configuration events (these happen before funds_added in deposit creation)
     'deposit_conversion_rate_updated',
+    // v4: an oracle config makes `deposit_conversion_rate_updated` a FLOOR rather
+    // than the settlement rate, so it belongs immediately beside it in a
+    // deposit's history — reading one without the other misstates the price.
+    'deposit_oracle_rate_config_set',
+    'deposit_oracle_rate_config_removed',
     'deposit_accepting_intents_updated',
     'deposit_intent_amount_range_updated',
     // funds added comes after configuration so it appears first in UI (newest-first)
@@ -46,6 +61,9 @@ export const eventOrder = [
     'intent_pruned',
     'funds_unlocked',
     'intent_expiry_extended',
+    // v4: fee accounting recorded against a settled intent.
+    'intent_manager_fee_snapshotted',
+    'intent_referral_fee_distributed',
     // deposit close events
     'funds_removed', // synthetic UI event for partial withdrawal (remaining > 0)
     'deposit_withdrawn', // full withdrawal that closes the deposit (remaining = 0)
@@ -63,6 +81,8 @@ export const eventOrder = [
     'payment_method_removed',
     'allow_multiple_intents_updated',
     'escrow_registry_updated',
+    'orchestrator_registry_updated',
+    'partial_manual_release_delay_updated',
     'post_intent_hook_registry_updated',
     'protocol_fee_recipient_updated',
     'protocol_fee_updated',

package/dist/payment.currency.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Tests for currency-aware payment-provider selection.
+ *
+ * These exist because the Buy page auto-picked a payment method without ever
+ * consulting the buyer's currency. The volume leaders on every chain are
+ * United States dollar rails (Venmo, Zelle, Cash App), so a buyer who chose
+ * pounds or euros was seeded onto a rail that structurally cannot serve them
+ * and shown an empty order book. Each test below names the behaviour that
+ * failure would break, not just the value it returns.
+ */
+export {};