@provex/utils 1.9.2 → 1.10.0-rc.20260820232714.83636f8

package/dist/chain.d.ts

@@ -380,6 +380,19 @@ export declare const chainIds: (369 | 8453)[];
  * ```
  */
 export type ChainId = (typeof chainIds)[number];
+/**
+ * Narrow an arbitrary number to a supported chain id.
+ *
+ * Chain ids reach the server as untyped JSON — a request body, a query string,
+ * a `Number(...)` of either. Casting those straight to {@link ChainId} tells
+ * the compiler a lie, and the lookup that follows silently returns nothing for
+ * a chain we never supported. Narrow first so an unsupported chain is a branch
+ * the caller has to handle rather than an undefined it discovers later.
+ *
+ * @param value - Any number, typically parsed from a request
+ * @returns True when the value is one of the supported chain ids
+ */
+export declare const isChainId: (value: number) => value is ChainId;
 /**
  * Human-readable chain names for URL params and display.
  * Maps chain IDs to lowercase slug-style names for URL-safe usage.

package/dist/chain.js

@@ -22,6 +22,19 @@ export const chains = [pulsechain, base];
  * Currently: [369 (Pulsechain), 8453 (Base)]
  */
 export const chainIds = chains.map((chain) => chain.id);
+/**
+ * Narrow an arbitrary number to a supported chain id.
+ *
+ * Chain ids reach the server as untyped JSON — a request body, a query string,
+ * a `Number(...)` of either. Casting those straight to {@link ChainId} tells
+ * the compiler a lie, and the lookup that follows silently returns nothing for
+ * a chain we never supported. Narrow first so an unsupported chain is a branch
+ * the caller has to handle rather than an undefined it discovers later.
+ *
+ * @param value - Any number, typically parsed from a request
+ * @returns True when the value is one of the supported chain ids
+ */
+export const isChainId = (value) => chainIds.includes(value);
 /**
  * Human-readable chain names for URL params and display.
  * Maps chain IDs to lowercase slug-style names for URL-safe usage.

package/dist/contracts.config.test.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Configuration invariants for the contract registry.
+ *
+ * `contracts.test.ts` tests what the accessor functions *do*. This file tests
+ * whether the data they read is *internally consistent* — the class of mistake
+ * that has no wrong-looking code anywhere, only a wrong address or a missing
+ * key, and that surfaces in production as an empty orderbook or a reverted
+ * submission rather than as a thrown error.
+ *
+ * Every test here sweeps the whole registry rather than spot-checking a chain,
+ * so registering a new generation or a new chain is covered the moment it lands
+ * in `contracts` — nobody has to remember to extend a list.
+ *
+ * These invariants are what makes the v4 flip safe: registering
+ * `contracts.v4[chainId]` is supposed to be the *only* step, and each assertion
+ * below is one of the things that silently has to be true for that to hold.
+ */
+export {};

package/dist/contracts.config.test.js

@@ -0,0 +1,220 @@
+/**
+ * @fileoverview Configuration invariants for the contract registry.
+ *
+ * `contracts.test.ts` tests what the accessor functions *do*. This file tests
+ * whether the data they read is *internally consistent* — the class of mistake
+ * that has no wrong-looking code anywhere, only a wrong address or a missing
+ * key, and that surfaces in production as an empty orderbook or a reverted
+ * submission rather than as a thrown error.
+ *
+ * Every test here sweeps the whole registry rather than spot-checking a chain,
+ * so registering a new generation or a new chain is covered the moment it lands
+ * in `contracts` — nobody has to remember to extend a list.
+ *
+ * These invariants are what makes the v4 flip safe: registering
+ * `contracts.v4[chainId]` is supposed to be the *only* step, and each assertion
+ * below is one of the things that silently has to be true for that to hold.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { getAddress, isAddress } from 'viem';
+import { chainIds } from './chain.js';
+import { contracts, versionKeys, getContracts, getLatestContract, getLatestConfiguredVersion, getPaymentAttestationVerifier, getAllEscrowContracts, getEscrowLocation, detectVersionFromEscrow, getConfiguredOrchestratorForEscrow, V3_PULSECHAIN_DEPLOYMENT_REFERENCE, V4_PULSECHAIN_DEPLOYMENT_REFERENCE, reclaimSigners, } from './contracts.js';
+/** Every (version, chain) pair that has a contract set registered. */
+const registeredSets = () => versionKeys.flatMap((version) => chainIds.flatMap((chainId) => {
+    const set = getContracts(version, chainId);
+    return set ? [{ version, chainId, set: set }] : [];
+}));
+/** Flatten a contract set to every address it holds, address-array or scalar. */
+const addressesIn = (set) => Object.entries(set).flatMap(([key, value]) => {
+    if (typeof value === 'string')
+        return [{ key, address: value }];
+    if (Array.isArray(value))
+        return value.map((address) => ({ key, address: String(address) }));
+    return [];
+});
+/** Read an address-array field off a contract set whose exact shape varies by generation. */
+const addressArray = (set, key) => set?.[key] ?? [];
+describe('contract registry configuration', () => {
+    describe('address hygiene', () => {
+        it('stores every address in EIP-55 checksummed form', () => {
+            // The registry runs each literal through viem's `getAddress`, so a
+            // checksum failure here means an address bypassed that call — and a
+            // non-checksummed address breaks the case-sensitive `===` comparisons
+            // that several call sites still do against these constants.
+            for (const { version, chainId, set } of registeredSets()) {
+                for (const { key, address } of addressesIn(set)) {
+                    assert.strictEqual(address, getAddress(address), `${version}[${chainId}].${key} is not checksummed: ${address}`);
+                }
+            }
+        });
+        it('holds only syntactically valid addresses, reference blocks included', () => {
+            // The `*_DEPLOYMENT_REFERENCE` objects are plain string literals — they
+            // never pass through `getAddress`, so nothing but this test would catch a
+            // truncated or mistyped ops address before someone pastes it into a
+            // `cast send`.
+            const referenced = [
+                ...Object.entries(V3_PULSECHAIN_DEPLOYMENT_REFERENCE),
+                ...Object.entries(V4_PULSECHAIN_DEPLOYMENT_REFERENCE),
+                ...Object.entries(reclaimSigners),
+            ];
+            for (const [key, address] of referenced) {
+                assert.ok(isAddress(address, { strict: false }), `${key} is not an address: ${address}`);
+            }
+        });
+    });
+    describe('escrow identity', () => {
+        it('never repeats an escrow address across generations or chains', () => {
+            // `getEscrowLocation` is a single address-keyed map, so a duplicate does
+            // not error — one of the two entries just wins and every deposit in the
+            // other is attributed to the wrong generation or the wrong chain.
+            const seen = new Map();
+            for (const { version, chainId, escrow } of getAllEscrowContracts()) {
+                const key = escrow.toLowerCase();
+                const owner = `${version}[${chainId}]`;
+                const previous = seen.get(key);
+                assert.strictEqual(previous, undefined, `${escrow} is claimed by both ${previous} and ${owner}`);
+                seen.set(key, owner);
+            }
+        });
+        it('resolves every configured escrow back to its own version and chain', () => {
+            for (const location of getAllEscrowContracts()) {
+                assert.deepStrictEqual(getEscrowLocation(location.escrow), location, `${location.escrow} did not round-trip through getEscrowLocation`);
+                assert.strictEqual(detectVersionFromEscrow(location.escrow), location.version);
+            }
+        });
+        it('resolves escrows case-insensitively — indexer rows are lowercased', () => {
+            for (const location of getAllEscrowContracts()) {
+                assert.strictEqual(detectVersionFromEscrow(location.escrow.toLowerCase()), location.version);
+            }
+        });
+    });
+    describe('generation completeness', () => {
+        it('gives every registered v4 chain a full V4Contracts shape', () => {
+            // A v4 set missing `orchestrator` is the dangerous partial: deposit
+            // creation still flips to v4 (that only needs `escrow`), but
+            // `getConfiguredOrchestratorForEscrow` returns null and every intent read
+            // falls back to `escrow.orchestrator()`, which EscrowV2 does not expose.
+            for (const [chainIdStr, set] of Object.entries(contracts.v4)) {
+                const v4 = set;
+                const where = `v4[${chainIdStr}]`;
+                assert.ok(v4.usdc, `${where} has no usdc`);
+                assert.ok(v4.gatingService, `${where} has no gatingService`);
+                assert.ok(v4.escrow?.length, `${where} has no escrow`);
+                assert.ok(v4.unifiedPaymentVerifier?.length, `${where} has no unifiedPaymentVerifier`);
+                assert.ok(v4.orchestrator?.length, `${where} has no orchestrator`);
+                assert.ok(v4.orchestratorRegistry, `${where} has no orchestratorRegistry`);
+            }
+        });
+        it('answers the orchestrator from config for v4 and only for v4', () => {
+            for (const { version, escrow } of getAllEscrowContracts()) {
+                const orchestrator = getConfiguredOrchestratorForEscrow(escrow);
+                if (version === 'v4') {
+                    assert.ok(orchestrator, `v4 escrow ${escrow} has no configured orchestrator`);
+                    continue;
+                }
+                // v2/v3 escrows expose `orchestrator()`; returning an address here
+                // would shadow the on-chain read with a stale constant.
+                assert.strictEqual(orchestrator, null, `${version} escrow ${escrow} should defer to the chain`);
+            }
+        });
+        it('does not reuse a v3 address anywhere in a v4 set', () => {
+            // The copy-paste failure when standing up a new generation. Reusing the
+            // v3 escrow means v4 deposits land in the v3 contract; reusing the v3
+            // verifier means attestations get signed against a retired domain.
+            for (const chainId of chainIds) {
+                const v3 = getContracts('v3', chainId);
+                const v4 = getContracts('v4', chainId);
+                if (!v3 || !v4)
+                    continue;
+                for (const key of ['escrow', 'unifiedPaymentVerifier']) {
+                    const v3Addresses = new Set(addressArray(v3, key).map((a) => a.toLowerCase()));
+                    for (const address of addressArray(v4, key)) {
+                        assert.ok(!v3Addresses.has(address.toLowerCase()), `v4[${chainId}].${key} reuses the v3 address ${address}`);
+                    }
+                }
+            }
+        });
+    });
+    describe('version routing', () => {
+        it('routes each chain to a version that actually has an escrow', () => {
+            for (const chainId of chainIds) {
+                const version = getLatestConfiguredVersion(chainId);
+                assert.ok(getContracts(version, chainId)?.escrow?.length, `getLatestConfiguredVersion(${chainId}) chose ${version}, which has no escrow`);
+            }
+        });
+        it('routes to the newest registered generation, not merely a configured one', () => {
+            // Derives the expectation from the declaration order of `versions`
+            // instead of restating the precedence list. Adding `v5` to `contracts`
+            // but forgetting it in VERSION_PRECEDENCE fails here — the flip would
+            // otherwise stay silently on v4 with no code looking wrong.
+            for (const chainId of chainIds) {
+                const newest = [...versionKeys]
+                    .reverse()
+                    .find((version) => getContracts(version, chainId)?.escrow?.length);
+                assert.strictEqual(getLatestConfiguredVersion(chainId), newest, `chain ${chainId} should route new deposits to ${newest}`);
+            }
+        });
+        it('keeps `versions` and the `contracts` map in step', () => {
+            assert.deepStrictEqual(Object.keys(contracts).sort(), [...versionKeys].sort(), 'a generation exists in one of `contracts` / `versions` but not the other');
+        });
+    });
+    describe('cross-generation coupling', () => {
+        it('names the current verifier for the attestation domain on every chain', () => {
+            // `UnifiedPaymentVerifier` sets `verifyingContract = address(this)`, so
+            // this address is load-bearing for the on-chain signature check.
+            for (const chainId of chainIds) {
+                const verifier = getPaymentAttestationVerifier(chainId);
+                assert.ok(verifier, `chain ${chainId} has no payment attestation verifier`);
+                assert.strictEqual(verifier, getLatestContract(chainId, 'unifiedPaymentVerifier', getLatestConfiguredVersion(chainId)));
+            }
+        });
+        it('never leaves the attestation domain on a superseded verifier', () => {
+            for (const chainId of chainIds) {
+                const current = getPaymentAttestationVerifier(chainId);
+                const latest = getLatestConfiguredVersion(chainId);
+                for (const version of versionKeys) {
+                    if (version === latest || version === 'v2')
+                        continue;
+                    const superseded = getLatestContract(chainId, 'unifiedPaymentVerifier', version);
+                    if (!superseded)
+                        continue;
+                    assert.notStrictEqual(current, superseded, `chain ${chainId} still signs attestations against the ${version} verifier`);
+                }
+            }
+        });
+        it('settles every generation on one chain in the same token', () => {
+            // Volume, reputation tiers, and the taker ladder all sum across
+            // generations in raw base units. If v3 and v4 settled in different
+            // tokens those sums would silently mix currencies and decimals.
+            for (const chainId of chainIds) {
+                const tokens = new Set(versionKeys
+                    .map((version) => getContracts(version, chainId)?.usdc)
+                    .filter((token) => !!token)
+                    .map((token) => token.toLowerCase()));
+                assert.strictEqual(tokens.size, 1, `chain ${chainId} settles generations in ${tokens.size} tokens`);
+            }
+        });
+        it('shares one gating service across orchestrator generations on a chain', () => {
+            // Load-bearing, not cosmetic: several call sites still resolve the
+            // gating service without a version and therefore get the v3 entry
+            // (`getDefaultVersion` returns 'v3') — `AddressesMenu.tsx`, and
+            // `ProveXClient.ts` which pins 'v3' outright. Those are correct only
+            // while every orchestrator generation on a chain names the same signer.
+            // If a future generation ever needs its own, those call sites must be
+            // fixed in the same change that breaks this test.
+            //
+            // v2 is excluded deliberately: Base v2 does name a different signer, but
+            // nothing routes there (`getDefaultVersion` returns 'v3' and v2 is
+            // historical-read-only), so that divergence is inert.
+            for (const chainId of chainIds) {
+                const signers = new Set(versionKeys
+                    .filter((version) => version !== 'v2')
+                    .map((version) => getLatestContract(chainId, 'gatingService', version))
+                    .filter((signer) => !!signer)
+                    .map((signer) => signer.toLowerCase()));
+                assert.strictEqual(signers.size, 1, `chain ${chainId} has ${signers.size} gating services; version-less call sites will pick the wrong one`);
+            }
+        });
+    });
+});

package/dist/contracts.d.ts

@@ -23,7 +23,7 @@
  * @see {@link abis} for contract ABIs
  */
 import { type Hex } from 'viem';
-import type { ChainId } from './chain.js';
+import { type ChainId } from './chain.js';
 /**
  * Contract type definitions for the app.
  */
@@ -85,29 +85,22 @@ export declare const v3BaseContracts: V3Contracts;
  */
 export declare const v4BaseContracts: V4Contracts;
 /**
- * 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 declare const v4PulsechainContracts: V4Contracts;
 /**
  * V3 contracts deployed to Pulsechain (Chain ID 369)
  * Deployed: 2026-01-12
@@ -132,6 +125,22 @@ export declare const V3_PULSECHAIN_DEPLOYMENT_REFERENCE: {
     readonly nullifierRegistry: "0x4AeA2288ec542963256b66D70EfddF4cB8754f82";
     readonly 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 declare const V4_PULSECHAIN_DEPLOYMENT_REFERENCE: {
+    readonly multiAttestationVerifier: "0xd98bdf683a8b218Ea45Cc8A258ef1A662ef8e9ae";
+    readonly addressGroupRegistry: "0x2e6E054eca4EC24149516AC8036Dd30c937237AF";
+    readonly whitelistPreIntentHookV2: "0x4F7f6691f8c362d31d19567133Ce33CC3EEd6d51";
+    readonly protocolViewerV2: "0x02CC2997B73A1d1E1D0151319F25125B11A55565";
+};
 export declare const versions: {
     readonly V2: "v2";
     readonly V3: "v3";
@@ -156,6 +165,7 @@ export declare const contracts: {
     };
     v4: {
         8453: V4Contracts;
+        369: V4Contracts;
     };
 };
 /**
@@ -170,9 +180,9 @@ export declare const getContracts: (version: Version, chainId: ChainId) => V2Con
  *
  * 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
@@ -182,10 +192,9 @@ export declare const getContracts: (version: Version, chainId: ChainId) => V2Con
  * @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 declare const getLatestConfiguredVersion: (chainId: ChainId) => Version;
 /**
@@ -210,6 +219,100 @@ export declare const getLatestConfiguredVersion: (chainId: ChainId) => Version;
  * const v2Escrow = getLatestContract(pulsechain.id, 'escrow', 'v2')
  */
 export declare const getLatestContract: (chainId: ChainId, key: ContractKey, version?: Version) => Hex | null;
+/**
+ * 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 declare const getPaymentAttestationVerifier: (chainId: ChainId) => Hex | null;
+/**
+ * The outcome of checking a client-supplied `verifyingContract`.
+ *
+ * `unconfigured` and `mismatch` are kept apart because they mean different
+ * things operationally: the first is our own misconfiguration (a chain with no
+ * verifier registered), the second is a request asking us to sign for an
+ * address that is not the one this chain settles against.
+ */
+export type VerifyingContractCheck = {
+    ok: true;
+    verifyingContract: Hex;
+} | {
+    ok: false;
+    reason: 'unconfigured';
+    expected: null;
+    received: Hex | undefined;
+} | {
+    ok: false;
+    reason: 'mismatch';
+    expected: Hex;
+    received: Hex | undefined;
+};
+/**
+ * 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 declare const checkPaymentAttestationVerifier: ({ chainId, verifyingContract, }: {
+    chainId: number;
+    verifyingContract: Hex | undefined;
+}) => VerifyingContractCheck;
 /**
  * Represents a unique escrow location identified by version, chain, and address
  */
@@ -234,6 +337,43 @@ export type EscrowLocation = {
  * // ]
  */
 export declare function getAllEscrowContracts(): EscrowLocation[];
+/**
+ * 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 declare function getEscrowLocation(escrow: Hex): EscrowLocation | 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 declare function detectVersionFromEscrow(escrow: Hex): 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 declare function getConfiguredOrchestratorForEscrow(escrow: Hex): Hex | null;
 /**
  * Get all V3 escrow contracts across all chains.
  * Used for cross-chain nullifier checking to prevent double-spending.