@absol-labs/agent 0.11.0 → 0.12.0-rc.2

package/dist/x402-opener/scheme.js

@@ -0,0 +1,1035 @@
+import { streamEscrowV2Abi, x402UpfrontStreamOpenerAbi, x402UpfrontStreamOpenerFactoryAbi, } from "@absol-labs/shared";
+import { deepEqual } from "@x402/core/utils";
+import { isEIP3009Payload, toFacilitatorEvmSigner, } from "@x402/evm";
+import { ExactEvmScheme } from "@x402/evm/exact/facilitator";
+import { BaseError, ContractFunctionRevertedError, decodeEventLog, getAddress, isAddress, isErc6492Signature, isHex, } from "viem";
+import { x402StreamOpenerAbi, x402StreamOpenerFactoryAbi } from "./abi.js";
+import { RelayerQueue } from "./relayer-queue.js";
+import { chainIdFromNetwork, assertValidUpfrontTerms, maxEarnable, OPENER_EXTRA_KEY, OPENER_SCHEME, OPENER_TERMS_VERSION, parseUintString, termsFromExtra, termsTuple, upfrontRefundable, upfrontTermsTuple, } from "./terms.js";
+/**
+ * `MetrikOpenerExactScheme` — an x402 v2 `exact` facilitator scheme that
+ * settles every payment INTO a `StreamEscrowV2` stream through the ownerless
+ * `X402StreamOpenerFactory` (metrik-agent#116, metrik-contracts#48).
+ *
+ * ## What it composes, and what it refuses
+ *
+ * Standard `exact` checks (EIP-712 signature, recipient == `payTo`, value ==
+ * amount, validity window, asset is a contract, balance / nonce simulation of
+ * the transfer) are delegated to the official `@x402/evm` `ExactEvmScheme`
+ * verifier, never reimplemented. On top of it, every payment must satisfy:
+ *
+ * - `assetTransferMethod` is EIP-3009. Permit2 and every other method are
+ *   refused: the opener only ever pulls an EIP-3009 authorization.
+ * - The signature is NOT ERC-6492-wrapped. A counterfactual smart wallet would
+ *   need a factory deploy the opener cannot perform; refused with a reason.
+ * - `asset` is on the allowlist AND is the factory's own settlement token.
+ * - `payTo == factory.predict(terms)`, recomputed on-chain from the configured
+ *   factory for the terms in `extra.metrikStreamOpener` — never compared by
+ *   code or codehash (a byte-identical clone outside the factory proves
+ *   nothing). The factory named in `extra` must be the configured one.
+ * - `(operator, serviceRef)` resolve to exactly ONE operator-signed listing via
+ *   the existing discovery signature verification; the rate is inside the
+ *   listing's signed commercial bounds when it declares them.
+ * - `0 < amount <= ratePerSecond * maxDuration`.
+ * - `factory.deployAndSettle` simulates cleanly from the relayer.
+ *
+ * Any doubt — an RPC error, an unreachable registry, a malformed field — is an
+ * invalid verdict. Nothing here ever fails open.
+ *
+ * ## Settlement
+ *
+ * `settle` re-runs the full verification, then calls `deployAndSettle` from the
+ * relayer, waits for the receipt, and returns success ONLY when the mined
+ * receipt carries both the opener's `StreamOpenedFor` and the escrow's
+ * `StreamOpened` for exactly this payer, nonce, amount and terms. The stock
+ * `ExactEvmScheme.settle` is never called: it would transfer the USDC straight
+ * to `payTo`, and USDC that reaches an opener any other way than
+ * `settleAndOpen` is unrecoverable. The signer handed to the stock scheme
+ * cannot broadcast at all, so that path is closed structurally too.
+ *
+ * ## At most one success per authorization
+ *
+ * An EIP-3009 authorization (chain + asset + payer + nonce) receives AT MOST
+ * ONE successful `SettleResponse` from this instance, ever. A settle of an
+ * authorization that is in flight, or already settled, returns `success:
+ * false` with `duplicate_settlement` (carrying the tx hash when there is one),
+ * and `verify` refuses it the same way — so one payment can never buy two
+ * served responses. After a `settlement_pending` (receipt wait timed out) the
+ * next settle of the SAME payload reconciles against the broadcast tx and may
+ * receive the one success, if none was delivered before. The ledger is
+ * in-memory and per instance: a multi-instance deployment needs a shared store
+ * and does not have one today.
+ *
+ * Relayer submissions (simulate + write) are serialized so concurrent payers
+ * never race for the relayer's account nonce.
+ *
+ * ## The upfront ("minimum charge") opener kind
+ *
+ * With `upfrontFactoryAddress` set, a quote may also name the
+ * `X402UpfrontStreamOpenerFactory` (metrik-contracts#54). Its 6-field terms
+ * add `price` and a non-refundable `upfrontAmount`; the kind is decided by
+ * WHICH configured factory the quote names, never by the wire fields. Verify
+ * additionally requires the factory's own `validateTerms` rules,
+ * `price - upfrontAmount <= rate * maxDuration`, `amount == price` and
+ * `payTo == upfrontFactory.predict(terms)`, and simulates the 6-tuple
+ * `deployAndSettle`. Settle succeeds only on a receipt that shows exactly the
+ * signed split (see {@link MetrikOpenerExactScheme.upfrontSettlement}); an
+ * upfront-only payment (`upfrontAmount == price`) opens no stream and is
+ * reported with `streamId: null`.
+ */
+/** Reasons this scheme adds to the stock `exact` ones. All fail closed. */
+export const OpenerInvalidReason = {
+    unsupportedScheme: "metrik_opener_unsupported_scheme",
+    unsupportedNetwork: "metrik_opener_unsupported_network",
+    unsupportedVersion: "metrik_opener_unsupported_x402_version",
+    acceptedMismatch: "metrik_opener_accepted_requirements_mismatch",
+    unsupportedAssetTransferMethod: "metrik_opener_asset_transfer_method_not_eip3009",
+    erc6492Unsupported: "metrik_opener_erc6492_signature_unsupported",
+    missingSignature: "metrik_opener_missing_signature",
+    assetNotAllowed: "metrik_opener_asset_not_allowed",
+    invalidTerms: "metrik_opener_invalid_terms",
+    factoryMismatch: "metrik_opener_factory_mismatch",
+    payToMismatch: "metrik_opener_pay_to_not_predicted_opener",
+    invalidAmount: "metrik_opener_invalid_amount",
+    amountExceedsTerms: "metrik_opener_amount_exceeds_rate_times_duration",
+    listingUnavailable: "metrik_opener_listing_registry_unavailable",
+    listingNotFound: "metrik_opener_listing_not_found",
+    listingAmbiguous: "metrik_opener_listing_ambiguous",
+    listingRateOutOfBounds: "metrik_opener_listing_rate_out_of_bounds",
+    simulationFailed: "metrik_opener_settle_simulation_failed",
+    verifyError: "metrik_opener_verify_error",
+    transactionReverted: "metrik_opener_transaction_reverted",
+    streamEventMismatch: "metrik_opener_stream_event_mismatch",
+    settlementPending: "settlement_pending",
+    settleError: "metrik_opener_settle_error",
+    amountBelowMinimum: "metrik_opener_amount_below_minimum",
+    /**
+     * This authorization is already being settled, or already settled, by this
+     * facilitator instance. May carry the settlement transaction hash. Never a
+     * second success (see "At most one success" on the class).
+     */
+    duplicateSettlement: "duplicate_settlement",
+    settlementCapacity: "metrik_opener_settlement_capacity_exhausted",
+};
+/** Default facilitator minimum payment: 10000 base units = 0.01 USDC. */
+export const DEFAULT_OPENER_MIN_AMOUNT = 10000n;
+/** Hard cap on remembered authorizations; beyond it new settles fail closed. */
+const MAX_LEDGER_ENTRIES = 100_000;
+/** Grace after an authorization's `validBefore` before its ledger entry is dropped. */
+const LEDGER_GRACE_SECONDS = 600n;
+export class MetrikOpenerExactScheme {
+    config;
+    scheme = OPENER_SCHEME;
+    caipFamily = "eip155:*";
+    stock;
+    chainId;
+    allowlist;
+    receiptTimeoutMs;
+    minAmount;
+    now;
+    ledger = new Map();
+    /** Serializes relayer submissions (simulate + write) so nonces never collide. */
+    relayerQueue;
+    binding;
+    constructor(config) {
+        this.config = config;
+        this.chainId = chainIdFromNetwork(config.network);
+        if (!isAddress(config.factoryAddress)) {
+            throw new Error("factoryAddress must be an EVM address");
+        }
+        if (!isAddress(config.escrowAddress)) {
+            throw new Error("escrowAddress must be an EVM address");
+        }
+        if (config.upfrontFactoryAddress !== undefined &&
+            (!isAddress(config.upfrontFactoryAddress) ||
+                getAddress(config.upfrontFactoryAddress) ===
+                    getAddress(config.factoryAddress))) {
+            throw new Error("upfrontFactoryAddress must be an EVM address other than factoryAddress");
+        }
+        if (config.upfrontImplementation !== undefined &&
+            !isAddress(config.upfrontImplementation)) {
+            throw new Error("upfrontImplementation must be an EVM address");
+        }
+        if (config.assetAllowlist.length === 0) {
+            throw new Error("assetAllowlist must not be empty");
+        }
+        for (const asset of config.assetAllowlist) {
+            if (!isAddress(asset)) {
+                throw new Error(`assetAllowlist entry is not an address: ${asset}`);
+            }
+        }
+        this.allowlist = new Set(config.assetAllowlist.map((asset) => asset.toLowerCase()));
+        this.receiptTimeoutMs = config.receiptTimeoutMs ?? 60_000;
+        if (!Number.isInteger(this.receiptTimeoutMs) ||
+            this.receiptTimeoutMs <= 0) {
+            throw new Error("receiptTimeoutMs must be a positive integer");
+        }
+        this.minAmount = config.minAmount ?? DEFAULT_OPENER_MIN_AMOUNT;
+        if (this.minAmount <= 0n) {
+            throw new Error("minAmount must be > 0");
+        }
+        this.now = config.now ?? (() => Math.floor(Date.now() / 1000));
+        this.relayerQueue = config.relayerQueue ?? new RelayerQueue();
+        // The stock verifier gets a READ-ONLY signer. Its settle path would send the
+        // USDC straight to payTo; making writes impossible closes that path even if
+        // a future refactor called it by mistake.
+        const publicClient = config.publicClient;
+        const refuseWrite = async () => {
+            throw new Error("MetrikOpenerExactScheme: the stock exact scheme may not broadcast; opener payments settle only via deployAndSettle");
+        };
+        this.stock = new ExactEvmScheme(toFacilitatorEvmSigner({
+            address: config.walletClient.account.address,
+            readContract: (args) => publicClient.readContract(args),
+            verifyTypedData: (args) => publicClient.verifyTypedData(args),
+            getCode: (args) => publicClient.getCode(args),
+            waitForTransactionReceipt: refuseWrite,
+            writeContract: refuseWrite,
+            sendTransaction: refuseWrite,
+        }), 
+        // ERC-6492 factory deployment disabled: 6492 signatures are refused
+        // before the stock verifier is ever reached.
+        { eip6492AllowedFactories: [] });
+    }
+    /**
+     * Proves the on-chain wiring before the facilitator serves anything: the RPC
+     * is on the configured chain, the factory has code, points at the configured
+     * escrow, and its token is allowlisted. Throws otherwise (the service refuses
+     * to start).
+     */
+    async init() {
+        const { publicClient, factoryAddress, escrowAddress } = this.config;
+        const rpcChainId = await publicClient.getChainId();
+        if (rpcChainId !== this.chainId) {
+            throw new Error(`RPC chain id ${rpcChainId} does not match network ${this.config.network}`);
+        }
+        const code = await publicClient.getCode({ address: factoryAddress });
+        if (code === undefined || code === "0x") {
+            throw new Error(`no contract at factory address ${factoryAddress}`);
+        }
+        const [factoryEscrow, factoryUsdc] = await Promise.all([
+            publicClient.readContract({
+                address: factoryAddress,
+                abi: x402StreamOpenerFactoryAbi,
+                functionName: "escrow",
+            }),
+            publicClient.readContract({
+                address: factoryAddress,
+                abi: x402StreamOpenerFactoryAbi,
+                functionName: "usdc",
+            }),
+        ]);
+        if (getAddress(factoryEscrow) !== getAddress(escrowAddress)) {
+            throw new Error(`factory escrow ${factoryEscrow} is not the configured escrow ${escrowAddress}`);
+        }
+        if (!this.allowlist.has(factoryUsdc.toLowerCase())) {
+            throw new Error(`factory settlement token ${factoryUsdc} is not on the asset allowlist`);
+        }
+        let upfront;
+        if (this.config.upfrontFactoryAddress !== undefined) {
+            const upfrontFactory = getAddress(this.config.upfrontFactoryAddress);
+            const upfrontCode = await publicClient.getCode({
+                address: upfrontFactory,
+            });
+            if (upfrontCode === undefined || upfrontCode === "0x") {
+                throw new Error(`no contract at upfront factory address ${upfrontFactory}`);
+            }
+            const [upEscrow, upUsdc, upImplementation] = await Promise.all([
+                publicClient.readContract({
+                    address: upfrontFactory,
+                    abi: x402UpfrontStreamOpenerFactoryAbi,
+                    functionName: "escrow",
+                }),
+                publicClient.readContract({
+                    address: upfrontFactory,
+                    abi: x402UpfrontStreamOpenerFactoryAbi,
+                    functionName: "usdc",
+                }),
+                publicClient.readContract({
+                    address: upfrontFactory,
+                    abi: x402UpfrontStreamOpenerFactoryAbi,
+                    functionName: "implementation",
+                }),
+            ]);
+            if (getAddress(upEscrow) !== getAddress(escrowAddress)) {
+                throw new Error(`upfront factory escrow ${upEscrow} is not the configured escrow ${escrowAddress}`);
+            }
+            if (getAddress(upUsdc) !== getAddress(factoryUsdc)) {
+                throw new Error(`upfront factory token ${upUsdc} is not the stream factory's ${factoryUsdc}`);
+            }
+            if (this.config.upfrontImplementation !== undefined &&
+                getAddress(upImplementation) !==
+                    getAddress(this.config.upfrontImplementation)) {
+                throw new Error(`upfront factory implementation ${upImplementation} is not the expected ${this.config.upfrontImplementation}`);
+            }
+            upfront = {
+                factory: upfrontFactory,
+                implementation: getAddress(upImplementation),
+            };
+        }
+        this.binding = {
+            chainId: this.chainId,
+            factory: getAddress(factoryAddress),
+            escrow: getAddress(factoryEscrow),
+            usdc: getAddress(factoryUsdc),
+            relayer: this.config.walletClient.account.address,
+            ...(upfront === undefined ? {} : { upfront }),
+        };
+        return this.binding;
+    }
+    /** `/supported` extra: the marker a resource server checks before quoting an opener. */
+    getExtra(_network) {
+        const binding = this.binding;
+        if (binding === undefined) {
+            return undefined;
+        }
+        const marker = {
+            settlement: "x402-stream-opener",
+            factory: binding.factory,
+            escrow: binding.escrow,
+            usdc: binding.usdc,
+            chainId: binding.chainId,
+            minAmount: this.minAmount.toString(),
+            receiptTimeoutSeconds: Math.ceil(this.receiptTimeoutMs / 1000),
+            ...(this.config.advertiseRefundRelay === true
+                ? { refundRelay: true }
+                : {}),
+            ...(binding.upfront === undefined
+                ? {}
+                : {
+                    upfrontOpener: {
+                        factory: binding.upfront.factory,
+                        implementation: binding.upfront.implementation,
+                        escrow: binding.escrow,
+                        termsVersion: OPENER_TERMS_VERSION.upfront,
+                    },
+                }),
+        };
+        return { [OPENER_EXTRA_KEY]: marker };
+    }
+    getSigners(_network) {
+        return [this.config.walletClient.account.address];
+    }
+    async verify(payload, requirements, context) {
+        try {
+            const key = this.ledgerKey(payload);
+            const entry = key === undefined ? undefined : this.ledger.get(key);
+            if (entry !== undefined) {
+                if (entry.state === "pending" &&
+                    deepEqual(entry.payload, payload) &&
+                    deepEqual(entry.requirements, requirements)) {
+                    // Submitted earlier, receipt not yet seen: the authorization may
+                    // already be used on-chain, so the on-chain checks would refuse it.
+                    // The retry is valid only so that settle can reconcile THIS tx.
+                    return { isValid: true, payer: entry.auth.authorization.from };
+                }
+                return invalid(OpenerInvalidReason.duplicateSettlement, "this authorization is already being settled or was settled", payerOf(payload));
+            }
+            const checked = await this.check(payload, requirements, context);
+            if (!checked.ok) {
+                return checked.response;
+            }
+            return { isValid: true, payer: checked.auth.authorization.from };
+        }
+        catch (error) {
+            return invalid(OpenerInvalidReason.verifyError, describe(error), payerOf(payload));
+        }
+    }
+    async settle(payload, requirements, context) {
+        const network = requirements.network;
+        const payer = payerOf(payload);
+        const key = this.ledgerKey(payload);
+        if (key === undefined) {
+            // Not a parseable EIP-3009 authorization: the full check refuses it.
+            const checked = await this.check(payload, requirements, context).catch((error) => ({
+                ok: false,
+                response: invalid(OpenerInvalidReason.verifyError, describe(error), payer),
+            }));
+            return checked.ok
+                ? failure(OpenerInvalidReason.verifyError, network, payer, "unparseable authorization")
+                : refusal(checked.response, network, payer);
+        }
+        // ── At most one success per authorization ─────────────────────────────
+        // Everything from here to the ledger write is synchronous, so two
+        // concurrent settles of the same authorization can never both claim it.
+        this.pruneLedger();
+        const existing = this.ledger.get(key);
+        if (existing !== undefined) {
+            if (existing.state === "pending" &&
+                deepEqual(existing.payload, payload) &&
+                deepEqual(existing.requirements, requirements)) {
+                this.ledger.set(key, {
+                    state: "in-flight",
+                    validBefore: existing.validBefore,
+                    hash: existing.hash,
+                });
+                return this.finish(key, payload, requirements, existing.validBefore, await this.awaitSettlement(existing.hash, existing.auth, existing.plan, existing.opener, network), existing);
+            }
+            return failure(OpenerInvalidReason.duplicateSettlement, network, payer, "this authorization is already being settled or was settled", existing.hash ?? "");
+        }
+        if (this.ledger.size >= MAX_LEDGER_ENTRIES) {
+            return failure(OpenerInvalidReason.settlementCapacity, network, payer, undefined);
+        }
+        const validBefore = BigInt(eip3009(payload).authorization.validBefore);
+        const entry = { state: "in-flight", validBefore };
+        this.ledger.set(key, entry);
+        try {
+            const checked = await this.check(payload, requirements, context);
+            if (!checked.ok) {
+                this.ledger.delete(key);
+                return refusal(checked.response, network, payer);
+            }
+            const { auth, plan, opener } = checked;
+            let hash;
+            try {
+                hash = await this.submitSerialized(auth, plan);
+            }
+            catch (error) {
+                this.ledger.delete(key);
+                return failure(OpenerInvalidReason.simulationFailed, network, auth.authorization.from, revertReason(error));
+            }
+            entry.hash = hash;
+            return this.finish(key, payload, requirements, validBefore, await this.awaitSettlement(hash, auth, plan, opener, network), { auth, plan, opener });
+        }
+        catch (error) {
+            // Unknown state after a possible broadcast: keep the authorization
+            // blocked (never a second success), but only if something was sent.
+            if (entry.hash === undefined) {
+                this.ledger.delete(key);
+            }
+            else {
+                this.ledger.set(key, { state: "final", validBefore, hash: entry.hash });
+            }
+            return failure(OpenerInvalidReason.settleError, network, payer, describe(error), entry.hash ?? "");
+        }
+    }
+    /** Records the outcome of one settle attempt in the ledger and returns it. */
+    finish(key, payload, requirements, validBefore, result, context) {
+        if (result.success) {
+            // THE one success for this authorization. Nothing succeeds again.
+            this.ledger.set(key, {
+                state: "final",
+                validBefore,
+                hash: result.transaction,
+            });
+            return result;
+        }
+        if (result.errorReason === OpenerInvalidReason.settlementPending) {
+            this.ledger.set(key, {
+                state: "pending",
+                validBefore,
+                hash: result.transaction,
+                payload,
+                requirements,
+                auth: context.auth,
+                plan: context.plan,
+                opener: context.opener,
+            });
+            return result;
+        }
+        if (result.errorReason === OpenerInvalidReason.transactionReverted) {
+            // A reverted deployAndSettle consumed nothing (the whole call reverts),
+            // so the authorization may be settled again.
+            this.ledger.delete(key);
+            return result;
+        }
+        // Mined but not the expected stream, or anything else terminal: block.
+        this.ledger.set(key, {
+            state: "final",
+            validBefore,
+            hash: result.transaction || "",
+        });
+        return result;
+    }
+    /**
+     * Simulate + broadcast `deployAndSettle`, one at a time. Concurrent
+     * submissions from one relayer would otherwise race for the same account
+     * nonce and all but one would fail after the upstream already did the work.
+     */
+    submitSerialized(auth, plan) {
+        const run = async () => {
+            const { request } = await this.simulateDeployAndSettle(auth, plan);
+            return this.config.walletClient.writeContract({
+                ...request,
+                chain: this.config.walletClient.chain ?? null,
+            });
+        };
+        return this.relayerQueue.run(run);
+    }
+    /** chain + asset + payer + authorization nonce, or undefined if unparseable. */
+    ledgerKey(payload) {
+        const auth = eip3009(payload);
+        const asset = payload.accepted?.asset;
+        if (auth === undefined || typeof asset !== "string")
+            return undefined;
+        return [
+            this.chainId,
+            asset.toLowerCase(),
+            auth.authorization.from.toLowerCase(),
+            auth.authorization.nonce.toLowerCase(),
+        ].join(":");
+    }
+    /**
+     * Drops entries whose authorization can no longer be settled by anyone
+     * (past `validBefore` plus a grace). Never drops an in-flight entry.
+     */
+    pruneLedger() {
+        const now = BigInt(this.now());
+        for (const [key, entry] of this.ledger) {
+            if (entry.state !== "in-flight" &&
+                entry.validBefore + LEDGER_GRACE_SECONDS < now) {
+                this.ledger.delete(key);
+            }
+        }
+    }
+    /**
+     * `eth_call` (simulate) `deployAndSettle` on the factory of the plan's kind:
+     * the 4-tuple stream factory, or the 6-tuple upfront factory.
+     */
+    async simulateDeployAndSettle(auth, plan) {
+        const { publicClient, walletClient } = this.config;
+        if (plan.kind === "upfront") {
+            const factory = this.binding?.upfront?.factory;
+            if (factory === undefined) {
+                throw new Error("the upfront opener factory is not configured");
+            }
+            return await publicClient.simulateContract({
+                account: walletClient.account,
+                address: factory,
+                abi: x402UpfrontStreamOpenerFactoryAbi,
+                functionName: "deployAndSettle",
+                args: [upfrontTermsTuple(plan.terms), authorizationTuple(auth)],
+            });
+        }
+        return await publicClient.simulateContract({
+            account: walletClient.account,
+            address: this.config.factoryAddress,
+            abi: x402StreamOpenerFactoryAbi,
+            functionName: "deployAndSettle",
+            args: [termsTuple(plan.terms), authorizationTuple(auth)],
+        });
+    }
+    async awaitSettlement(hash, auth, plan, opener, network) {
+        const payer = getAddress(auth.authorization.from);
+        let receipt;
+        try {
+            receipt = await this.config.publicClient.waitForTransactionReceipt({
+                hash,
+                timeout: this.receiptTimeoutMs,
+            });
+        }
+        catch (error) {
+            // Broadcast but unconfirmed: keep the pending entry so a retry
+            // reconciles against this hash. Never success without a receipt.
+            return failure(OpenerInvalidReason.settlementPending, network, payer, describe(error), hash);
+        }
+        if (receipt.status !== "success") {
+            return failure(OpenerInvalidReason.transactionReverted, network, payer, "deployAndSettle reverted on-chain", hash);
+        }
+        if (plan.kind === "upfront") {
+            return this.upfrontSettlement(receipt.logs, hash, auth, plan.terms, opener, network);
+        }
+        const terms = plan.terms;
+        const opened = findStreamOpened(receipt.logs, opener, getAddress(this.config.escrowAddress), auth, terms, BigInt(auth.authorization.value));
+        if (opened === undefined) {
+            return failure(OpenerInvalidReason.streamEventMismatch, network, payer, "the mined receipt does not show the expected stream", hash);
+        }
+        return {
+            success: true,
+            transaction: hash,
+            network,
+            payer,
+            amount: auth.authorization.value,
+            extra: {
+                [OPENER_EXTRA_KEY]: {
+                    streamId: opened.streamId,
+                    opener,
+                    escrow: getAddress(this.config.escrowAddress),
+                    deposit: auth.authorization.value,
+                    ratePerSecond: terms.ratePerSecond.toString(),
+                    // A JSON NUMBER: the SDK buyer (payWithX402) validates it as one.
+                    expiresAt: Number(opened.expiresAt),
+                },
+            },
+        };
+    }
+    /**
+     * The success response of a mined UPFRONT settlement, or a mismatch failure.
+     * The receipt must show exactly what the signed terms imply:
+     *
+     * - `upfrontAmount > 0`: the opener's `UpfrontCharged` for this payer, nonce
+     *   and operator, for exactly `upfrontAmount`, naming the stream it opened
+     *   (or `bytes32(0)` when none was);
+     * - `price > upfrontAmount`: the escrow's `StreamOpened` (buyer = opener) and
+     *   the opener's `StreamOpenedFor` with `deposit = price - upfrontAmount`;
+     * - `upfrontAmount == price` (upfront-only): NO stream at all. Success, with
+     *   `streamId: null`: nothing was escrowed and there is nothing to refund.
+     *
+     * The reported `upfrontAmount` / `upfrontFee` are read from `UpfrontCharged`.
+     */
+    /** @internal */
+    upfrontSettlement(logs, hash, auth, terms, opener, network) {
+        const payer = getAddress(auth.authorization.from);
+        const escrow = getAddress(this.config.escrowAddress);
+        const refundable = upfrontRefundable(terms);
+        const mismatch = (why) => failure(OpenerInvalidReason.streamEventMismatch, network, payer, `the mined receipt does not show the expected upfront settlement: ${why}`, hash);
+        const charged = findUpfrontCharged(logs, opener, auth, terms);
+        if (terms.upfrontAmount > 0n && charged === undefined) {
+            return mismatch(`no UpfrontCharged for ${terms.upfrontAmount}`);
+        }
+        if (terms.upfrontAmount === 0n && charged !== undefined) {
+            return mismatch("an UpfrontCharged for terms without an upfront part");
+        }
+        let streamId = null;
+        let expiresAt = null;
+        if (refundable > 0n) {
+            const opened = findStreamOpened(logs, opener, escrow, auth, terms, refundable);
+            if (opened === undefined) {
+                return mismatch(`no stream with deposit ${refundable}`);
+            }
+            if (charged !== undefined &&
+                charged.streamId.toLowerCase() !== opened.streamId.toLowerCase()) {
+                return mismatch("UpfrontCharged names another stream");
+            }
+            streamId = opened.streamId;
+            expiresAt = opened.expiresAt;
+        }
+        else {
+            // Upfront-only: the opener must have opened nothing.
+            if (charged === undefined || !/^0x0{64}$/i.test(charged.streamId)) {
+                return mismatch("an upfront-only payment must report streamId 0");
+            }
+            if (findStreamOpened(logs, opener, escrow, auth, terms, undefined) !==
+                undefined) {
+                return mismatch("an upfront-only payment opened a stream");
+            }
+        }
+        return {
+            success: true,
+            transaction: hash,
+            network,
+            payer,
+            amount: auth.authorization.value,
+            extra: {
+                [OPENER_EXTRA_KEY]: {
+                    // `null` (not bytes32(0)) for an upfront-only payment: no stream.
+                    streamId,
+                    opener,
+                    escrow,
+                    // The refundable, metered part — the most any refund can return.
+                    deposit: refundable.toString(),
+                    ratePerSecond: terms.ratePerSecond.toString(),
+                    ...(expiresAt === null ? {} : { expiresAt: Number(expiresAt) }),
+                    upfrontAmount: (charged?.amount ?? 0n).toString(),
+                    upfrontFee: (charged?.fee ?? 0n).toString(),
+                },
+            },
+        };
+    }
+    /** Every Metrik check plus the stock verifier. Cheapest, most local first. */
+    async check(payload, requirements, context) {
+        const payer = payerOf(payload);
+        const refuse = (reason, message) => ({ ok: false, response: invalid(reason, message, payer) });
+        if (payload.x402Version !== 2) {
+            return refuse(OpenerInvalidReason.unsupportedVersion);
+        }
+        if (requirements.scheme !== OPENER_SCHEME) {
+            return refuse(OpenerInvalidReason.unsupportedScheme);
+        }
+        if (requirements.network !== this.config.network ||
+            payload.accepted?.network !== this.config.network) {
+            return refuse(OpenerInvalidReason.unsupportedNetwork);
+        }
+        // The payer signed against `accepted`; settle exactly that, nothing else.
+        if (!deepEqual(payload.accepted, requirements)) {
+            return refuse(OpenerInvalidReason.acceptedMismatch);
+        }
+        const method = requirements.extra?.assetTransferMethod;
+        if (method !== undefined && method !== "eip3009") {
+            return refuse(OpenerInvalidReason.unsupportedAssetTransferMethod);
+        }
+        const auth = eip3009(payload);
+        if (auth === undefined) {
+            return refuse(OpenerInvalidReason.unsupportedAssetTransferMethod);
+        }
+        if (auth.signature === undefined || !isHex(auth.signature)) {
+            return refuse(OpenerInvalidReason.missingSignature);
+        }
+        if (isErc6492Signature(auth.signature)) {
+            return refuse(OpenerInvalidReason.erc6492Unsupported, "ERC-6492 (counterfactual smart wallet) signatures cannot be settled through the stream opener; deploy the wallet first");
+        }
+        const binding = this.binding;
+        if (binding === undefined) {
+            return refuse(OpenerInvalidReason.verifyError, "facilitator not initialized");
+        }
+        if (!isAddress(requirements.asset) ||
+            !this.allowlist.has(requirements.asset.toLowerCase()) ||
+            getAddress(requirements.asset) !== binding.usdc) {
+            return refuse(OpenerInvalidReason.assetNotAllowed);
+        }
+        let parsed;
+        try {
+            parsed = termsFromExtra(requirements.extra);
+        }
+        catch (error) {
+            return refuse(OpenerInvalidReason.invalidTerms, describe(error));
+        }
+        const { terms, factory } = parsed;
+        // Only a factory this facilitator is bound to (and proved in init) is
+        // ever settled; its kind decides the terms shape — never the wire fields.
+        let kind;
+        if (factory === binding.factory) {
+            kind = "stream";
+        }
+        else if (binding.upfront !== undefined &&
+            factory === binding.upfront.factory) {
+            kind = "upfront";
+        }
+        else {
+            return refuse(OpenerInvalidReason.factoryMismatch);
+        }
+        if (parsed.termsVersion !== undefined &&
+            parsed.termsVersion !== OPENER_TERMS_VERSION[kind]) {
+            return refuse(OpenerInvalidReason.invalidTerms, `termsVersion ${parsed.termsVersion} does not match the ${kind} opener factory (${OPENER_TERMS_VERSION[kind]})`);
+        }
+        let plan;
+        if (kind === "upfront") {
+            if (parsed.upfront === undefined) {
+                return refuse(OpenerInvalidReason.invalidTerms, "the upfront opener factory needs price and upfrontAmount in the terms");
+            }
+            const upfrontTerms = { ...terms, ...parsed.upfront };
+            try {
+                assertValidUpfrontTerms(upfrontTerms);
+            }
+            catch (error) {
+                return refuse(OpenerInvalidReason.invalidTerms, describe(error));
+            }
+            plan = { kind, terms: upfrontTerms };
+        }
+        else {
+            if (parsed.upfront !== undefined) {
+                return refuse(OpenerInvalidReason.invalidTerms, "price/upfrontAmount are not terms of the stream opener factory (its payTo does not commit to them)");
+            }
+            plan = { kind, terms };
+        }
+        let amount;
+        try {
+            amount = parseUintString(requirements.amount, "amount");
+        }
+        catch (error) {
+            return refuse(OpenerInvalidReason.invalidAmount, describe(error));
+        }
+        if (amount <= 0n) {
+            return refuse(OpenerInvalidReason.invalidAmount, "amount must be > 0");
+        }
+        if (amount < this.minAmount) {
+            return refuse(OpenerInvalidReason.amountBelowMinimum, `amount ${amount} is below this facilitator's minimum ${this.minAmount}`);
+        }
+        if (plan.kind === "upfront") {
+            // The opener accepts exactly its price; anything else reverts on-chain.
+            if (amount !== plan.terms.price) {
+                return refuse(OpenerInvalidReason.invalidAmount, `amount ${amount} is not the upfront opener's fixed price ${plan.terms.price}`);
+            }
+        }
+        else if (amount > maxEarnable(terms)) {
+            return refuse(OpenerInvalidReason.amountExceedsTerms);
+        }
+        let predicted;
+        try {
+            predicted =
+                plan.kind === "upfront"
+                    ? await this.config.publicClient.readContract({
+                        address: binding.upfront?.factory,
+                        abi: x402UpfrontStreamOpenerFactoryAbi,
+                        functionName: "predict",
+                        args: [upfrontTermsTuple(plan.terms)],
+                    })
+                    : await this.config.publicClient.readContract({
+                        address: binding.factory,
+                        abi: x402StreamOpenerFactoryAbi,
+                        functionName: "predict",
+                        args: [termsTuple(terms)],
+                    });
+        }
+        catch (error) {
+            // predict reverts InvalidTerms for terms no transaction can deploy.
+            if (revertReason(error) === "InvalidTerms") {
+                return refuse(OpenerInvalidReason.invalidTerms, "InvalidTerms");
+            }
+            throw error;
+        }
+        if (!isAddress(requirements.payTo) ||
+            getAddress(requirements.payTo) !== getAddress(predicted)) {
+            return refuse(OpenerInvalidReason.payToMismatch);
+        }
+        const listing = await this.config.listingResolver.resolve(terms);
+        if (!listing.ok) {
+            const reason = {
+                "listing-registry-unavailable": OpenerInvalidReason.listingUnavailable,
+                "listing-not-found": OpenerInvalidReason.listingNotFound,
+                "listing-ambiguous": OpenerInvalidReason.listingAmbiguous,
+                "listing-rate-out-of-bounds": OpenerInvalidReason.listingRateOutOfBounds,
+            }[listing.reason];
+            return refuse(reason, listing.message);
+        }
+        // Standard exact checks: signature, to == payTo, value == amount, window,
+        // asset contract, and a simulation of the EIP-3009 transfer itself.
+        const stock = await this.stock.verify(payload, requirements, context);
+        if (!stock.isValid) {
+            return { ok: false, response: stock };
+        }
+        const signed = auth;
+        try {
+            await this.simulateDeployAndSettle(signed, plan);
+        }
+        catch (error) {
+            return refuse(OpenerInvalidReason.simulationFailed, revertReason(error));
+        }
+        return { ok: true, auth: signed, plan, opener: getAddress(predicted) };
+    }
+}
+function authorizationTuple(auth) {
+    return {
+        from: getAddress(auth.authorization.from),
+        value: BigInt(auth.authorization.value),
+        validAfter: BigInt(auth.authorization.validAfter),
+        validBefore: BigInt(auth.authorization.validBefore),
+        nonce: auth.authorization.nonce,
+        signature: auth.signature,
+    };
+}
+/**
+ * Finds the pair of events a genuine opener settlement emits in ONE receipt:
+ * the escrow's `StreamOpened` with `buyer == opener` and exactly these terms,
+ * and the opener's `StreamOpenedFor` binding that stream to this payer, nonce
+ * and amount.
+ */
+function findStreamOpened(logs, opener, escrow, auth, terms, 
+/** Expected stream deposit; `undefined` matches ANY deposit (an absence check). */
+deposit) {
+    const payer = getAddress(auth.authorization.from);
+    const escrowStreams = new Map();
+    for (const log of logs) {
+        if (getAddress(log.address) !== escrow)
+            continue;
+        try {
+            const decoded = decodeEventLog({
+                abi: streamEscrowV2Abi,
+                data: log.data,
+                topics: log.topics,
+            });
+            if (decoded.eventName !== "StreamOpened")
+                continue;
+            const args = decoded.args;
+            if (getAddress(args.buyer) === opener &&
+                getAddress(args.operator) === getAddress(terms.operator) &&
+                args.serviceRef.toLowerCase() === terms.serviceRef.toLowerCase() &&
+                (deposit === undefined || args.deposit === deposit) &&
+                args.ratePerSecond === terms.ratePerSecond) {
+                escrowStreams.set(args.streamId.toLowerCase(), BigInt(args.expiresAt));
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    for (const log of logs) {
+        if (getAddress(log.address) !== opener)
+            continue;
+        try {
+            const decoded = decodeEventLog({
+                abi: x402StreamOpenerAbi,
+                data: log.data,
+                topics: log.topics,
+            });
+            if (decoded.eventName !== "StreamOpenedFor")
+                continue;
+            const args = decoded.args;
+            const expiresAt = escrowStreams.get(args.streamId.toLowerCase());
+            if (expiresAt !== undefined &&
+                getAddress(args.payer) === payer &&
+                args.authorizationNonce.toLowerCase() ===
+                    auth.authorization.nonce.toLowerCase() &&
+                (deposit === undefined || args.deposit === deposit)) {
+                return { streamId: args.streamId, expiresAt };
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
+/**
+ * The opener's `UpfrontCharged` for this payer, authorization nonce and
+ * operator, for exactly the terms' `upfrontAmount` (its `fee` is the protocol
+ * fee taken out of it). `undefined` when the receipt carries none.
+ */
+function findUpfrontCharged(logs, opener, auth, terms) {
+    const payer = getAddress(auth.authorization.from);
+    for (const log of logs) {
+        if (getAddress(log.address) !== opener)
+            continue;
+        try {
+            const decoded = decodeEventLog({
+                abi: x402UpfrontStreamOpenerAbi,
+                data: log.data,
+                topics: log.topics,
+            });
+            if (decoded.eventName !== "UpfrontCharged")
+                continue;
+            const args = decoded.args;
+            if (getAddress(args.payer) === payer &&
+                args.authorizationNonce.toLowerCase() ===
+                    auth.authorization.nonce.toLowerCase() &&
+                getAddress(args.operator) === getAddress(terms.operator) &&
+                args.amount === terms.upfrontAmount &&
+                args.fee <= args.amount) {
+                return { streamId: args.streamId, amount: args.amount, fee: args.fee };
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
+/**
+ * Reads an opener facilitator marker out of a `/supported` kind's `extra`, or
+ * `undefined` when the facilitator does not advertise opener settlement.
+ */
+export function readOpenerFacilitatorMarker(extra) {
+    const raw = extra?.[OPENER_EXTRA_KEY];
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const marker = raw;
+    if (marker.settlement !== "x402-stream-opener" ||
+        typeof marker.factory !== "string" ||
+        !isAddress(marker.factory) ||
+        typeof marker.escrow !== "string" ||
+        !isAddress(marker.escrow) ||
+        typeof marker.usdc !== "string" ||
+        !isAddress(marker.usdc) ||
+        typeof marker.chainId !== "number" ||
+        typeof marker.minAmount !== "string" ||
+        !/^[1-9]\d*$/.test(marker.minAmount) ||
+        typeof marker.receiptTimeoutSeconds !== "number" ||
+        !Number.isInteger(marker.receiptTimeoutSeconds) ||
+        marker.receiptTimeoutSeconds <= 0) {
+        return undefined;
+    }
+    return {
+        settlement: "x402-stream-opener",
+        factory: getAddress(marker.factory),
+        escrow: getAddress(marker.escrow),
+        usdc: getAddress(marker.usdc),
+        chainId: marker.chainId,
+        minAmount: marker.minAmount,
+        receiptTimeoutSeconds: marker.receiptTimeoutSeconds,
+        ...(marker.refundRelay === true ? { refundRelay: true } : {}),
+        ...(readUpfrontMarker(marker.upfrontOpener) ?? {}),
+    };
+}
+/** The optional `upfrontOpener` entry of a marker; a malformed one is ignored (absent). */
+function readUpfrontMarker(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const entry = raw;
+    if (typeof entry.factory !== "string" ||
+        !isAddress(entry.factory) ||
+        typeof entry.implementation !== "string" ||
+        !isAddress(entry.implementation) ||
+        typeof entry.escrow !== "string" ||
+        !isAddress(entry.escrow) ||
+        entry.termsVersion !== OPENER_TERMS_VERSION.upfront) {
+        return undefined;
+    }
+    return {
+        upfrontOpener: {
+            factory: getAddress(entry.factory),
+            implementation: getAddress(entry.implementation),
+            escrow: getAddress(entry.escrow),
+            termsVersion: OPENER_TERMS_VERSION.upfront,
+        },
+    };
+}
+function eip3009(payload) {
+    const inner = payload.payload;
+    if (typeof inner !== "object" || inner === null)
+        return undefined;
+    const candidate = inner;
+    if (!isEIP3009Payload(candidate))
+        return undefined;
+    const authorization = candidate.authorization;
+    if (typeof authorization !== "object" ||
+        authorization === null ||
+        typeof authorization.from !== "string" ||
+        !isAddress(authorization.from) ||
+        typeof authorization.to !== "string" ||
+        typeof authorization.value !== "string" ||
+        typeof authorization.validAfter !== "string" ||
+        typeof authorization.validBefore !== "string" ||
+        typeof authorization.nonce !== "string" ||
+        !isHex(authorization.nonce) ||
+        authorization.nonce.length !== 66) {
+        return undefined;
+    }
+    try {
+        parseUintString(authorization.value, "authorization.value");
+        parseUintString(authorization.validAfter, "authorization.validAfter");
+        parseUintString(authorization.validBefore, "authorization.validBefore");
+    }
+    catch {
+        return undefined;
+    }
+    return candidate;
+}
+function payerOf(payload) {
+    const from = payload.payload?.authorization?.from;
+    return typeof from === "string" && isAddress(from)
+        ? getAddress(from)
+        : undefined;
+}
+function invalid(reason, message, payer) {
+    return {
+        isValid: false,
+        invalidReason: reason,
+        ...(message === undefined ? {} : { invalidMessage: message }),
+        ...(payer === undefined ? {} : { payer }),
+    };
+}
+function failure(reason, network, payer, message, transaction = "") {
+    return {
+        success: false,
+        errorReason: reason,
+        ...(message === undefined ? {} : { errorMessage: message }),
+        transaction,
+        network,
+        ...(payer === undefined ? {} : { payer }),
+    };
+}
+function refusal(response, network, payer) {
+    return {
+        success: false,
+        errorReason: response.invalidReason ?? OpenerInvalidReason.verifyError,
+        ...(response.invalidMessage === undefined
+            ? {}
+            : { errorMessage: response.invalidMessage }),
+        transaction: "",
+        network,
+        ...(payer === undefined ? {} : { payer }),
+    };
+}
+function revertReason(error) {
+    if (error instanceof BaseError) {
+        const reverted = error.walk((cause) => cause instanceof ContractFunctionRevertedError);
+        if (reverted instanceof ContractFunctionRevertedError) {
+            return (reverted.data?.errorName ?? reverted.reason ?? reverted.shortMessage);
+        }
+        return error.shortMessage;
+    }
+    return describe(error);
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=scheme.js.map