@atumlabs/payment-gateway-client 3.0.1 → 4.0.0

package/dist/{sender-auth-verify-C-Q-zvAO.d.ts → sender-auth-verify-CEf7FN6s.d.ts}

@@ -87,6 +87,13 @@ type PaymentRequest = {
      * point no new quotes are accepted. The gateway injects no default and validates the value
      * is in the future. The originator must supply it, and a request that omits it or supplies
      * a past value is rejected with 400.
+     *
+     * Keep this window short. A settler holds its quoted price for a limited period of its
+     * own choosing, and the gateway selects only once the window has closed, so a deadline
+     * set beyond that hold leaves no quote still awardable and the request is declined with
+     * QUOTE_WINDOW_TOO_LONG. That hold is set by each settler and is not part of this
+     * contract, so treat 60 seconds as a practical upper bound and prefer a shorter window
+     * where your integration allows.
      */
     quote_deadline: string;
     /**
@@ -96,6 +103,14 @@ type PaymentRequest = {
      * supplies a past value is rejected with 400.
      */
     fulfillment_deadline: string;
+    /**
+     * Who performs each leg of the payment. Omitted on the wire means settler for every leg. The split object keeps deposit, reserve, and fulfill as separate keys.
+     */
+    executor?: 'settler' | 'originator' | {
+        deposit: 'settler' | 'originator';
+        reserve: 'settler' | 'originator';
+        fulfill: 'settler' | 'originator';
+    };
     /**
      * Policy requirements for settler authentication. Keys are policy names, values indicate if the policy is required.
      */
@@ -110,10 +125,11 @@ type PaymentRequest = {
      */
     quote_selector?: string;
     /**
-     * Third-party service that will independently verify your payment was delivered.
-     * Leave empty to use the default verifier.
+     * The verification service that confirms the payment was delivered before the escrow
+     * releases the source funds, and the account it signs with. Required on every chain:
+     * the gateway's `/v1/defaults` response supplies it for each chain.
      */
-    fulfillment_verifier?: {
+    fulfillment_verifier: {
         /**
          * The wallet address or public key of the verification service
          */
@@ -126,9 +142,9 @@ type PaymentRequest = {
         endpoint: string;
     };
     /**
-     * Escrow contract address, used to protect source funds until proof of fulfillment has been verified. Leave empty to use the default.
+     * Escrow contract on the source chain that holds the source funds until proof of fulfillment has been verified. Required on every chain. Take the value for the source chain from the payment gateway's GET /v1/defaults (`escrow_contract`).
      */
-    escrow_contract_address?: string;
+    escrow_contract_address: string;
     /**
      * Fulfillment Proxy contract address, used to emit proof of fulfillment on the destination chain. Leave empty to use the default.
      */
@@ -147,6 +163,47 @@ type PaymentRequest = {
         blacklist?: Array<(string)>;
     };
 };
+type deposit = 'settler' | 'originator';
+type reserve = 'settler' | 'originator';
+type fulfill = 'settler' | 'originator';
+/**
+ * Authorization for an originator to fulfill a payment request. The settler produces this declaration after authorizeFulfillment when the payment request's fulfill executor is "originator". A settler fulfill does not produce it.
+ *
+ * Canonical JSON Schema: schemas/declarations/FulfillmentAuthorization/v1/schema.json
+ * Published at https://schemas.atum.xyz/declarations/FulfillmentAuthorization/v1
+ */
+type FulfillmentAuthorization = {
+    /**
+     * Semver-shaped declaration version (MAJOR.MINOR). The major component is locked to this schema's parent directory (v1 → major must be 1).
+     */
+    version: string;
+    /**
+     * Authorization scheme.
+     */
+    scheme: 'EIP-3009';
+    /**
+     * Signed authorization. For scheme EIP-3009, message_prehash is the EIP-712 TransferWithAuthorization typed data as a JSON string ({domain, types, primaryType, message}, with uint256 values as decimal strings), message is its EIP-712 digest, signature is the settler's 65-byte signature over that digest, and payload is absent. message.validBefore is the payment request's fulfillment_deadline in whole unix seconds, and message.nonce is the fulfillment quote hash.
+     */
+    authorization: SignedMessage;
+    /**
+     * Raw JSON of the fulfillment quote (schemas/declarations/FulfillmentQuote/v1/schema.json), including proof metadata so its canonical quote hash can be computed.
+     */
+    fulfillment_quote_json: string;
+    /**
+     * Pointer to the on-chain evidence of the fulfillment authorization.
+     */
+    evidence: {
+        /**
+         * Chain transaction identifier. EVM transactions are 0x-prefixed hex, Tron transactions are hex without that prefix, and Solana transactions are base58.
+         */
+        transaction_id: string;
+        log_index: number;
+    };
+};
+/**
+ * Authorization scheme.
+ */
+type scheme = 'EIP-3009';
 /**
  * Confirmation details after a payment has been successfully delivered.
  * Contains proof of delivery and transaction details for both source and destination chains.
@@ -168,7 +225,7 @@ type FulfillmentConfirmation = {
     /**
      * Timestamp when the fulfillment was completed
      */
-    fulfillment_timestamp: string;
+    fulfillment_timestamp?: string;
     /**
      * The blockchain where funds were locked in escrow, using CAIP-2 format.
      * CAIP-2 is a standard way to identify blockchains: {namespace}:{reference}
@@ -194,11 +251,11 @@ type FulfillmentConfirmation = {
     /**
      * Transaction hash of the escrow reservation on the source chain
      */
-    source_tx_hash?: string;
+    source_tx_hash: string;
     /**
      * Transaction hash of the fulfillment on the destination chain
      */
-    destination_tx_hash?: string;
+    destination_tx_hash: string;
     /**
      * Block number where the source transaction was confirmed
      */
@@ -264,14 +321,12 @@ type SenderAuthMessageScheme = 'EVM_PERMIT2' | 'EVM_PERMIT2_ESCROW' | 'SOLANA' |
  */
 type SignedMessage = {
     /**
-     * The data that was signed. Format depends on the blockchain:
-     * - EVM: Hex-encoded message hash (with 0x prefix)
-     * - Solana: Hex-encoded message hash (with 0x prefix)
-     * - Tron: Hex-encoded message hash (possibly without 0x prefix)
+     * The data that was signed, hex-encoded with a 0x prefix on every supported chain. For the deposit (signed_messages[0]) it is the 32-byte hash of message_prehash.
      */
     message: string;
     /**
-     * Optional: If 'message' contains a hash, this field contains the original data before it was hashed. Useful for verification and debugging.
+     * The original data that `message` is the hash of. Required on every entry of a payment
+     * request's `sender_auth.signed_messages`: the gateway reads the signed terms from it.
      */
     message_prehash?: string;
     /**
@@ -363,9 +418,20 @@ type VerifiableCredential = {
  * - `completed`: delivered, with the required confirmations behind it.
  * - `failed`: did not complete. Any funds held in escrow are returned, and `error`
  * describes what went wrong.
+ * - `refunding`: the settler will not deliver this payment and your funds are being
+ * returned from escrow. NOT FINAL: it becomes `refund_available` or `refunded`, and it
+ * can still become `completed` or `failed`.
+ * - `refund_available`: the settler did not deliver and the refund is authorized for you
+ * to submit. GET /v1/payments/{paymentId}/status returns `refund_signature`, which you
+ * submit to the source escrow to return your funds. The other responses report this
+ * status without the signature. NOT FINAL: the funds are still in escrow, so it becomes
+ * `refunded` once the refund lands, or `completed` if the settler delivers late and is
+ * paid first. Do not pay again while it is `refund_available`.
+ * - `refunded`: your funds were returned from the source escrow. `transactions.refund` is
+ * the refund transaction, when it is known.
  *
- * `completed` and `failed` are final and will not change afterwards. `pending` and
- * `finalizing` will.
+ * `completed`, `failed` and `refunded` are final and will not change afterwards.
+ * `pending`, `finalizing`, `refunding` and `refund_available` will.
  *
  * **Do not treat `finalizing` as delivered.** It says the payment has been made on
  * chain but is not yet irreversible, much as a card authorization is not yet a
@@ -379,7 +445,7 @@ type VerifiableCredential = {
  * the recipient yet.
  *
  */
-type PaymentStatus = 'pending' | 'finalizing' | 'completed' | 'failed';
+type PaymentStatus = 'pending' | 'finalizing' | 'completed' | 'failed' | 'refunding' | 'refund_available' | 'refunded';
 /**
  * One on-chain transaction belonging to a payment: which chain, which transaction, and
  * which block it landed in.
@@ -413,9 +479,10 @@ type PaymentTransaction = {
  * The transactions a payment has produced, one entry per stage, added as each becomes
  * known. A stage absent here has produced no transaction yet.
  *
- * These are the two movements that decide whether your payment happened: your funds
- * being committed, and your recipient being paid. Present on every outcome, so a
- * payment that did not complete can still be traced on chain.
+ * These are the movements that decide whether your payment happened: your funds being
+ * committed, your recipient being paid, and your funds being returned when the payment
+ * is refunded. Present on every outcome, so a payment that did not complete can still be
+ * traced on chain.
  * `fulfillment_confirmation` is not a substitute: it is written only once a payment
  * completes, and describes the finished delivery rather than progress towards it.
  *
@@ -432,6 +499,39 @@ type PaymentTransactions = {
      * Paying your recipient on the destination chain.
      */
     fulfillment?: PaymentTransaction;
+    /**
+     * Returning your funds from the escrow on the source chain. Can be absent on a
+     * `refunded` payment when the refund transaction is not known.
+     *
+     */
+    refund?: PaymentTransaction;
+};
+/**
+ * The refund authorization for a `refund_available` payment, as the verifier signed it.
+ * Submit it to the source chain's escrow `refund` to return your funds yourself.
+ *
+ * Anyone holding it can submit the refund, but the escrow only ever pays the depositor. If
+ * the settler delivers late and is paid first, the refund no longer goes through.
+ * On Solana the submitter also receives the rent of the deposit account the refund closes.
+ *
+ */
+type RefundSignature = {
+    /**
+     * The verifier's signature over `message_hash`. Hex with the `0x` prefix on EVM and
+     * Tron chains, hex without it on Solana.
+     *
+     */
+    signature: string;
+    /**
+     * The signed digest, hex without the `0x` prefix.
+     */
+    message_hash: string;
+    /**
+     * The signed message as JSON. On EVM and Tron chains it carries the RefundWitness the
+     * escrow's `refund` takes.
+     *
+     */
+    message_prehash: string;
 };
 /**
  * Response from submitting a payment request. If settlement completes inside the
@@ -522,7 +622,63 @@ type PaymentResponse = {
         [key: string]: unknown;
     };
     fulfillment_confirmation?: FulfillmentConfirmation;
+    /**
+     * The settler-signed FulfillmentAuthorization for this payment, returned verbatim as an
+     * opaque signed document (structurally the canonical FulfillmentAuthorization/v1 declaration at
+     * https://schemas.atum.xyz/declarations/FulfillmentAuthorization/v1; see also
+     * `#/components/schemas/FulfillmentAuthorization`). The inner declaration requires
+     * `version`, `scheme`, `authorization` (the signed EIP-3009 transfer, in `authorization.message_prehash`), `fulfillment_quote_json`,
+     * and `evidence` (the on-chain authorizeFulfillment transaction). On the wire the settler
+     * typically wraps that declaration in JSON-LD with `@context`, `type`, and `proof` — those
+     * envelope fields ride alongside the declaration and MUST be preserved byte-for-byte.
+     *
+     * Present when the settler authorized an originator fulfill. Mutually exclusive with
+     * `fulfillment_confirmation` until the originator fulfills: when this field is populated,
+     * `fulfillment_confirmation` is absent.
+     *
+     * The service returns these bytes verbatim and does not re-serialize through a typed
+     * representation (which would normalize timestamps and reorder JSON-LD envelope fields).
+     *
+     */
+    fulfillment_authorization?: {
+        [key: string]: unknown;
+    };
     error?: PaymentFailure;
+    /**
+     * Why the settler did not deliver, as it reported when it gave up. Present only when
+     * `status` is `refunding`, `refund_available` or `refunded`, and absent when the refund
+     * started without a reason from the settler. `status` decides what to do next: its
+     * `retry_classification` and `request_id_reusable` describe the settler's error, not
+     * this payment, and never mean paying again while it is `refunding` or `refund_available`.
+     *
+     */
+    refund_reason?: PaymentFailure;
+    /**
+     * How many settler agents this payment's auction was broadcast to. Accompanies
+     * `decline_summary` and is present under the same condition. Same meaning and same
+     * absence rule as on GET /v1/payments/{paymentId}/status: absent means unknown, never
+     * zero.
+     *
+     */
+    requested_count?: number;
+    /**
+     * Why the payment drew few or no quotes, carried on the submission response so that a
+     * `failed` payment explains itself here rather than requiring a follow-up read. A
+     * payment that ran out its quote deadline reports `NO_QUOTES_RECEIVED` on `error`;
+     * this is what the settlers actually said.
+     *
+     * Present when `status` is `failed`, alongside `error`. A submission rejected before
+     * its auction opened is answered as an error response rather than this type and carries
+     * no breakdown, and GET /v1/payments/{paymentId}/status reports the breakdown in every
+     * state.
+     *
+     * Same counting rules as GET /v1/payments/{paymentId}/status: every declining agent is
+     * counted exactly once under its most recent reason, empty means no agent declined,
+     * absent means the breakdown could not be read. The free-form decline detail is never
+     * relayed.
+     *
+     */
+    decline_summary?: Array<DeclineSummaryEntry>;
 };
 type GetPaymentStatusResponse = {
     /**
@@ -569,7 +725,41 @@ type GetPaymentStatusResponse = {
         [key: string]: unknown;
     };
     fulfillment_confirmation?: FulfillmentConfirmation;
+    /**
+     * The settler-signed FulfillmentAuthorization for this payment, returned verbatim as an
+     * opaque signed document (structurally the canonical FulfillmentAuthorization/v1 declaration at
+     * https://schemas.atum.xyz/declarations/FulfillmentAuthorization/v1; see also
+     * `#/components/schemas/FulfillmentAuthorization`). The inner declaration requires
+     * `version`, `scheme`, `authorization` (the signed EIP-3009 transfer, in `authorization.message_prehash`), `fulfillment_quote_json`,
+     * and `evidence` (the on-chain authorizeFulfillment transaction). On the wire the settler
+     * typically wraps that declaration in JSON-LD with `@context`, `type`, and `proof` — those
+     * envelope fields ride alongside the declaration and MUST be preserved byte-for-byte.
+     *
+     * Present when the settler authorized an originator fulfill. Mutually exclusive with
+     * `fulfillment_confirmation` until the originator fulfills: when this field is populated,
+     * `fulfillment_confirmation` is absent.
+     *
+     * The service returns these bytes verbatim and does not re-serialize through a typed
+     * representation (which would normalize timestamps and reorder JSON-LD envelope fields).
+     *
+     */
+    fulfillment_authorization?: {
+        [key: string]: unknown;
+    };
     error?: PaymentFailure;
+    /**
+     * Why the settler did not deliver, as it reported when it gave up. Present only when
+     * `status` is `refunding`, `refund_available` or `refunded`, and absent when the refund
+     * started without a reason from the settler. `status` decides what to do next: its
+     * `retry_classification` and `request_id_reusable` describe the settler's error, not
+     * this payment, and never mean paying again while it is `refunding` or `refund_available`.
+     *
+     */
+    refund_reason?: PaymentFailure;
+    /**
+     * Present only when `status` is `refund_available`.
+     */
+    refund_signature?: RefundSignature;
     /**
      * How many settler agents this payment's auction was broadcast to. Absent means
      * unknown, never zero.
@@ -591,7 +781,8 @@ type GetPaymentStatusResponse = {
     decline_summary?: Array<DeclineSummaryEntry>;
 };
 /**
- * Why a payment failed. Present only when `status` is `failed`, and identical
+ * Why a payment failed, or why its settler gave up. As `error` it is present only when
+ * `status` is `failed`, as `refund_reason` only on the refund statuses, and it is identical
  * however you ask about the payment.
  *
  * `code` is the stable, machine-readable identity of the failure — branch on it
@@ -628,6 +819,10 @@ type PaymentFailure = {
      * Re-sending the same `request_id` is an idempotent replay and always safe. This value is about submitting a new one, which starts a new payment. See https://docs.atum.xyz/errors for the value set.
      */
     retry_classification?: string;
+    /**
+     * Whether the caller may re-send the `request_id` this payment was created under. On this shape it is almost always false, because a payment exists by definition, but it is carried rather than assumed so a caller reads the same field here as on a synchronous error. Absent means undetermined, which a caller should read as false.
+     */
+    request_id_reusable?: boolean;
     blockchain_context?: PaymentBlockchainContext;
 };
 /**
@@ -781,6 +976,15 @@ type PaymentTimelineResponse = {
     total_duration_ms?: number;
     summary?: PaymentSummary;
     error?: PaymentFailure;
+    /**
+     * Why the settler did not deliver, as it reported when it gave up. Present only when
+     * `status` is `refunding`, `refund_available` or `refunded`, and absent when the refund
+     * started without a reason from the settler. `status` decides what to do next: its
+     * `retry_classification` and `request_id_reusable` describe the settler's error, not
+     * this payment, and never mean paying again while it is `refunding` or `refund_available`.
+     *
+     */
+    refund_reason?: PaymentFailure;
     steps: Array<TimelineStep>;
 };
 /**
@@ -897,6 +1101,10 @@ type ErrorResponse = {
      * Re-sending the same `request_id` is an idempotent replay and always safe. This value is about submitting a new one, which starts a new operation. See https://docs.atum.xyz/errors for the value set.
      */
     retry_classification?: string;
+    /**
+     * Whether the caller may re-send this same request_id. True means no payment was created for it, so the id is still free. False means a payment exists for it, so the id is spent and re-sending only replays this outcome. Absent means undetermined, which a caller should read as false. Separate from retry_classification, which answers what the caller must change rather than whether the id survived.
+     */
+    request_id_reusable?: boolean;
 };
 /**
  * Request body for opening a quote-request batch. Structurally the existing PaymentRequest
@@ -940,6 +1148,13 @@ type CreateQuoteRequest = {
      * value is carried through verbatim to the award call. It must be supplied and must be in
      * the future. Must be strictly earlier than fulfillment_deadline.
      *
+     * Keep this window short. A settler holds its quoted price for a limited period of its
+     * own choosing, and the gateway selects only once the window has closed, so a deadline
+     * set beyond that hold leaves no quote still awardable and the request is declined with
+     * QUOTE_WINDOW_TOO_LONG. That hold is set by each settler and is not part of this
+     * contract, so treat 60 seconds as a practical upper bound and prefer a shorter window
+     * where your integration allows.
+     *
      */
     quote_deadline: string;
     /**
@@ -964,9 +1179,12 @@ type CreateQuoteRequest = {
      */
     quote_selector?: string;
     /**
-     * Optional third-party service that independently verifies delivery. Leave empty for the default verifier.
+     * The verification service that confirms the payment was delivered before the escrow
+     * releases the source funds, and the account it signs with. Required on every chain:
+     * the gateway's `/v1/defaults` response supplies it for each chain.
+     *
      */
-    fulfillment_verifier?: {
+    fulfillment_verifier: {
         /**
          * The wallet address or public key of the verification service
          */
@@ -980,9 +1198,12 @@ type CreateQuoteRequest = {
         endpoint: string;
     };
     /**
-     * Optional escrow contract address. Leave empty to use the default.
+     * Escrow contract on the source chain that holds the source funds until proof of
+     * fulfillment has been verified. Required on every chain: the gateway's `/v1/defaults`
+     * response supplies it for each chain (`escrow_contract`).
+     *
      */
-    escrow_contract_address?: string;
+    escrow_contract_address: string;
     /**
      * Optional fulfillment-proxy contract address on the destination chain. Leave empty to use the default.
      */
@@ -1451,6 +1672,27 @@ type AwardResponse = {
      */
     status: 'awarding' | 'completed' | 'failed' | 'cancelled';
     fulfillment_confirmation?: FulfillmentConfirmation;
+    /**
+     * The settler-signed FulfillmentAuthorization for this payment, returned verbatim as an
+     * opaque signed document (structurally the canonical FulfillmentAuthorization/v1 declaration at
+     * https://schemas.atum.xyz/declarations/FulfillmentAuthorization/v1; see also
+     * `#/components/schemas/FulfillmentAuthorization`). The inner declaration requires
+     * `version`, `scheme`, `authorization` (the signed EIP-3009 transfer, in `authorization.message_prehash`), `fulfillment_quote_json`,
+     * and `evidence` (the on-chain authorizeFulfillment transaction). On the wire the settler
+     * typically wraps that declaration in JSON-LD with `@context`, `type`, and `proof` — those
+     * envelope fields ride alongside the declaration and MUST be preserved byte-for-byte.
+     *
+     * Present when the settler authorized an originator fulfill within the sync wait.
+     * Mutually exclusive with `fulfillment_confirmation` until the originator fulfills: when
+     * this field is populated, `fulfillment_confirmation` is absent.
+     *
+     * The service returns these bytes verbatim and does not re-serialize through a typed
+     * representation (which would normalize timestamps and reorder JSON-LD envelope fields).
+     *
+     */
+    fulfillment_authorization?: {
+        [key: string]: unknown;
+    };
 };
 /**
  * Payment lifecycle status on the award response:
@@ -1519,10 +1761,6 @@ type ChainDefaults = {
      * The Permit2 this chain's escrow verifies against, sent only when it is not the canonical deployment. When absent, use the canonical Permit2 address for the chain. EVM and Tron only.
      */
     permit2_contract?: string;
-    /**
-     * Which deposit witness this chain's escrow expects. `4` and above select the four-member witness, `3` the two-member one; absent means four. EVM and Tron only - on Solana this is carried by `svm_signature_domain_version`.
-     */
-    deposit_witness_version?: number;
     /**
      * Tokens this chain's escrow accepts for deposit. Absent when the gateway has no listing for the chain, which does not mean no token is accepted.
      */
@@ -1542,9 +1780,13 @@ type ChainDefaults = {
      */
     svm_signature_cluster_id?: string;
     /**
-     * Solana only. Version of the escrow's signing domain. Absent for EVM and Tron.
+     * Solana only. The escrow's signature domain version, which the deposit hash commits to. Absent for EVM and Tron.
      */
     svm_signature_domain_version?: number;
+    /**
+     * The depositRequestHash version to sign for a deposit from this chain: 1 is keccak256 of the request_id, 2 is the hash of the payment terms, computed over the request body exactly as it is then posted. Absent means 1. A deposit signed with version 1 is still accepted while the gateway publishes 2. The gateway publishes 2 for a chain only once every reader of the deposit there reads version 2, veri-fill's release check included, so this is the network-wide signal a client signs by and a merchant lists 2 in an x402 or MPP challenge by.
+     */
+    deposit_request_hash_version?: number;
 };
 /**
  * Either one chain's defaults or every chain keyed by CAIP-2 chain id, depending on whether `chain_id` was supplied. A top-level `chain_id` identifies the first.
@@ -1949,18 +2191,39 @@ interface ParsedPermit {
     spender?: string;
     /** Solana only (the signed depositor). */
     depositor?: string;
-    /**
-     * The escrow commitments as actually signed. EVM only today: Tron signs the frozen
-     * two-member witness and the Solana prehash has no destination member, so both leave these
-     * undefined. Undefined means "this scheme does not carry the commitment", NOT "the commitment
-     * was absent" — on EVM an absent one is rejected as a malformed prehash and never gets here.
-     */
+    /** The escrow commitments as signed: the payee and the hash of the request id. */
     destination?: string;
     depositRequestHash?: string;
 }
-/** One verified `signed_messages[]` entry: the signed terms plus the parsed permit. */
+/** How the destination commitment check ended. Only `verified` admits a payment. */
+type CommitmentOutcome = 'verified' | 'scheme_mismatch' | 'commitment_absent' | 'prehash_mismatch' | 'signer_mismatch' | 'destination_mismatch' | 'request_hash_mismatch' | 'request_malformed' | 'verifier_misconfigured' | 'quote_request_mismatch';
+/** The destination commitment check's result: the outcome and both copies of the payee. */
+interface CommitmentResult {
+    outcome: CommitmentOutcome;
+    detail: string;
+    namespace: string;
+    scheme: string;
+    signedDestination: string;
+    expectedDestination: string;
+    signedDepositRequestHash: string;
+    expectedDepositRequestHash: string;
+    /** The request's depositRequestHash v2, when the check was given one (opted in, and the strict reader admitted the request). */
+    expectedDepositRequestHashV2?: string;
+    /** Why the strict reader refused the request, with `depositRequestHashV2Mode: 'audit'`. */
+    strictDetail?: string;
+    /** The depositRequestHash version the deposit matched, once opted in with `depositRequestHashV2Mode`. */
+    depositRequestHashVersion?: 'v1' | 'v2';
+}
+/** The Solana escrow signature domain, from your chain configuration. */
+interface SolanaDomain {
+    escrowProgramId: string;
+    clusterId: string;
+    domainVersion: number;
+}
+/** One verified `signed_messages[]` entry: the signed terms, the parsed permit and the commitment. */
 interface VerifiedSenderAuth extends AuthTerms {
     permit: ParsedPermit;
+    commitment: CommitmentResult;
 }
 /** What {@link verifyPaymentRequest} returns. */
 interface VerifyResult {
@@ -1968,13 +2231,19 @@ interface VerifyResult {
     results: VerifiedSenderAuth[];
     /** The `source.account` every signature was verified to recover to. */
     recoveredAccount: string;
+    /**
+     * The commitment check's result, once {@link verifyPaymentRequestJSON} is opted in with
+     * `depositRequestHashV2Mode`: the depositRequestHash version the deposit matched and, in audit mode,
+     * `strictDetail`. Absent otherwise.
+     */
+    commitment?: CommitmentResult;
 }
 /**
  * Expectations for {@link verifyPaymentRequest}.
  *
- * The first three are what turn this into a check against YOUR terms. Omit them and the token,
+ * Pass the first three to check the signatures against your own terms. When omitted, the token,
  * network and amount are taken from the request itself, which proves only that the signatures
- * are self-consistent with fields the request's author controls.
+ * are consistent with fields the request's author controls.
  */
 interface VerifyPaymentRequestExpectations {
     /** Authoritative source-asset address (bare token, no CAIP prefix). */
@@ -1987,9 +2256,6 @@ interface VerifyPaymentRequestExpectations {
     escrowContract?: string;
     reserver?: string;
     releaser?: string;
-    /** Opt-in commitment checks. Compose `destination` from the REQUEST's destination. */
-    destination?: string;
-    requestId?: string;
     /** Solana: additionally required by the deposit-hash domain, independent of role binding. */
     svmSignatureClusterId?: string;
     svmSignatureDomainVersion?: number;
@@ -1997,17 +2263,54 @@ interface VerifyPaymentRequestExpectations {
     permit2Contract?: string;
     /** Freshness reference, Unix seconds. Defaults to now. */
     nowSec?: number;
+    /**
+     * How {@link verifyPaymentRequestJSON} reads depositRequestHash v2. Absent, only v1 is accepted, as
+     * before v2. `audit` also accepts v2 and reports a request the strict reader refuses; `enforce`
+     * also accepts v2 and refuses such a request. {@link verifyPaymentRequest} accepts only v1 and
+     * refuses it as `verifier_misconfigured`.
+     */
+    depositRequestHashV2Mode?: 'audit' | 'enforce';
 }
 /**
  * Recovers every `sender_auth.signed_messages[]` entry and binds the signed terms to
  * `expected`, returning the parsed permits and the account they all recover to.
  *
- * Strict by design: every entry must be a bindable permit, and a malformed one throws rather
- * than being skipped. A caller with deliberately mixed messages — an EVM setup approval
- * alongside the permit, say — must compose the per-entry adapter calls itself.
+ * Every deposit must commit to the request's own `destination` and `request_id`, so a request
+ * whose payee or request id was changed after signing is refused.
  *
- * This is the sender_auth layer only. Request-shape and per-consumer policy are the caller's.
+ * Every entry must be a bindable permit; a malformed entry throws. A caller with mixed messages
+ * (for example an EVM setup approval alongside the permit) composes the per-entry adapter calls
+ * itself. Request-shape and policy checks remain the caller's.
+ *
+ * @throws If any entry fails to recover, bind, or match `expected`.
+ * @deprecated A parsed request keeps one value for a member name that appears twice, so this
+ * checks a copy of the request rather than the text received, and it accepts only
+ * depositRequestHash v1. Use {@link verifyPaymentRequestJSON} with the request as received.
  */
 declare function verifyPaymentRequest(request: PaymentRequest, expected?: VerifyPaymentRequestExpectations): VerifyResult;
+/**
+ * Recovers every `sender_auth.signed_messages[]` entry of the request as received and binds the
+ * signed terms to `expected`, returning the parsed permits and the account they all recover to. It
+ * refuses a repeated member name, including names that differ only in letter case, where it reads,
+ * and every deposit must commit to the request's own `destination` and request: depositRequestHash
+ * v1 by default, v1 or v2 with `expected.depositRequestHashV2Mode`, which also returns the commitment
+ * check's result as `commitment`.
+ *
+ * @throws If the JSON is ambiguous or does not decode, or if any entry fails to recover, bind, or
+ * match `expected`; {@link commitmentResultOf} returns the outcome.
+ */
+declare function verifyPaymentRequestJSON(request: string | Uint8Array, expected?: VerifyPaymentRequestExpectations): VerifyResult;
+/**
+ * The payee check alone, over the request's JSON: the deposit must commit to the request's own
+ * `destination` and `request_id`. It does not recover the signer, so it also serves a
+ * contract-account payer (ERC-1271, such as a Safe), whose signature Permit2 checks on chain.
+ * `solana` is required for a Solana source. `options.depositRequestHashV2Mode` also accepts a deposit
+ * that commits depositRequestHash v2, as it does for {@link verifyPaymentRequestJSON}.
+ *
+ * @throws If the check refuses; {@link commitmentResultOf} returns the outcome.
+ */
+declare function verifyRequestCommitment(request: string | Uint8Array, solana?: SolanaDomain, options?: Pick<VerifyPaymentRequestExpectations, 'depositRequestHashV2Mode'>): CommitmentResult;
+/** The commitment result a verification error carries, if any; log its outcome and detail. */
+declare function commitmentResultOf(error: unknown): CommitmentResult | undefined;
 
-export { type $OpenApiTs as $, type AuthTerms as A, type AwardedPayment as B, type CreateQuoteRequestData as C, type AwardedQuote as D, type ErrorResponse as E, type BidAward as F, type GetDefaultsData as G, type HealthCheckResponse as H, type ChainDefaultsByChain as I, type ChainDefaults as J, type DataIntegrityProof as K, type DeclineReason as L, type DeclineSummaryEntry as M, type FulfillmentConfirmation as N, type GetDefaultsResult as O, type PaymentRequest as P, type GetPaymentStatusResponse as Q, type ResolvePaymentData as R, type SubmitPaymentData as S, type OwnedAsset as T, type PaymentBlockchainContext as U, type VerifiedSenderAuth as V, type PaymentFailure as W, type PaymentResponse as X, type PaymentStatus as Y, type PaymentSummary as Z, type PaymentTimelineResponse as _, type ParsedPermit as a, type PaymentTransaction as a0, type PaymentTransactions as a1, type PreparePaymentRequest as a2, type PreparePaymentResponse as a3, type Quote as a4, type QuoteRequestAccepted as a5, type QuoteRequestResponse as a6, type QuoteRequestStatusResponse as a7, type ResolvePaymentResponse as a8, type SenderAuth as a9, type SenderAuthMessageScheme as aa, type TimelineStep as ab, type VerifiableCredential as ac, type VerifiableCredentialAuth as ad, type domain as ae, type error_code as af, type status as ag, type status2 as ah, type status3 as ai, type status4 as aj, type status5 as ak, type status6 as al, type status7 as am, type VerifyPaymentRequestExpectations as b, type VerifyResult as c, type AuthorizePaymentData as d, type AuthorizePaymentResponse as e, type GetDefaultsResponse as f, type SubmitPaymentResponse as g, type GetPaymentStatusData as h, type GetPaymentStatusResponse2 as i, type ResolvePaymentResponse2 as j, type GetPaymentTimelineData as k, type GetPaymentTimelineResponse as l, type PreparePaymentData as m, type PreparePaymentResponse2 as n, type CreateQuoteRequestResponse as o, type GetQuoteRequestStatusData as p, type GetQuoteRequestStatusResponse as q, type AwardQuoteData as r, type AwardQuoteResponse as s, type SignedMessage as t, type CreateQuoteRequest as u, verifyPaymentRequest as v, type AuthorizationResult as w, type AwardAccepted as x, type AwardRequest as y, type AwardResponse as z };
+export { type $OpenApiTs as $, type AuthTerms as A, type SignedMessage as B, type CommitmentOutcome as C, type CreateQuoteRequest as D, type ErrorResponse as E, type AuthorizationResult as F, type GetDefaultsData as G, type HealthCheckResponse as H, type AwardAccepted as I, type AwardRequest as J, type AwardResponse as K, type AwardedPayment as L, type AwardedQuote as M, type BidAward as N, type ChainDefaultsByChain as O, type PaymentRequest as P, type ChainDefaults as Q, type ResolvePaymentData as R, type SolanaDomain as S, type DataIntegrityProof as T, type DeclineReason as U, type VerifiedSenderAuth as V, type DeclineSummaryEntry as W, type FulfillmentAuthorization as X, type FulfillmentConfirmation as Y, type GetDefaultsResult as Z, type GetPaymentStatusResponse as _, type CommitmentResult as a, type OwnedAsset as a0, type PaymentBlockchainContext as a1, type PaymentFailure as a2, type PaymentResponse as a3, type PaymentStatus as a4, type PaymentSummary as a5, type PaymentTimelineResponse as a6, type PaymentTransaction as a7, type PaymentTransactions as a8, type PreparePaymentRequest as a9, type PreparePaymentResponse as aa, type Quote as ab, type QuoteRequestAccepted as ac, type QuoteRequestResponse as ad, type QuoteRequestStatusResponse as ae, type RefundSignature as af, type ResolvePaymentResponse as ag, type SenderAuth as ah, type SenderAuthMessageScheme as ai, type TimelineStep as aj, type VerifiableCredential as ak, type VerifiableCredentialAuth as al, type deposit as am, type domain as an, type error_code as ao, type fulfill as ap, type reserve as aq, type scheme as ar, type status as as, type status2 as at, type status3 as au, type status4 as av, type status5 as aw, type status6 as ax, type status7 as ay, type ParsedPermit as b, type VerifyPaymentRequestExpectations as c, type VerifyResult as d, commitmentResultOf as e, verifyPaymentRequestJSON as f, verifyRequestCommitment as g, type AuthorizePaymentData as h, type AuthorizePaymentResponse as i, type GetDefaultsResponse as j, type SubmitPaymentData as k, type SubmitPaymentResponse as l, type GetPaymentStatusData as m, type GetPaymentStatusResponse2 as n, type ResolvePaymentResponse2 as o, type GetPaymentTimelineData as p, type GetPaymentTimelineResponse as q, type PreparePaymentData as r, type PreparePaymentResponse2 as s, type CreateQuoteRequestData as t, type CreateQuoteRequestResponse as u, verifyPaymentRequest as v, type GetQuoteRequestStatusData as w, type GetQuoteRequestStatusResponse as x, type AwardQuoteData as y, type AwardQuoteResponse as z };

package/dist/signing.d.ts

@@ -1,5 +1,5 @@
-import { P as PaymentRequest } from './sender-auth-verify-C-Q-zvAO.js';
-export { A as AuthTerms, a as ParsedPermit, V as VerifiedSenderAuth, b as VerifyPaymentRequestExpectations, c as VerifyResult, v as verifyPaymentRequest } from './sender-auth-verify-C-Q-zvAO.js';
+import { P as PaymentRequest } from './sender-auth-verify-CEf7FN6s.js';
+export { A as AuthTerms, C as CommitmentOutcome, a as CommitmentResult, b as ParsedPermit, S as SolanaDomain, V as VerifiedSenderAuth, c as VerifyPaymentRequestExpectations, d as VerifyResult, e as commitmentResultOf, v as verifyPaymentRequest, f as verifyPaymentRequestJSON, g as verifyRequestCommitment } from './sender-auth-verify-CEf7FN6s.js';
 
 /** Options for {@link signDeclaration}. */
 interface SignDeclarationOptions {