uvd-x402-sdk 2.71.0 → 2.72.0

package/dist/index.d.mts

@@ -842,6 +842,163 @@ interface SignatureParamsInput {
  */
 declare function buildSignatureParams(params: SignatureParamsInput): string;
 
+/**
+ * EIP-7702: make a DELEGATED EOA's EIP-3009 signature settle again.
+ *
+ * **THE PROBLEM.** A gasless-wallet provider's first sponsored operation on a
+ * chain may delegate the user's EOA (EIP-7702) to a smart-account
+ * implementation — Alchemy's `SemiModularAccount7702` (`0x69007702…`) is the one
+ * seen in the wild. From then on the address HAS code, so Circle's USDC (and any
+ * `SignatureChecker` consumer) verifies signatures via **ERC-1271 only**. A raw
+ * ECDSA authorization, however perfect, is rejected: `0x151d90fe`. The account is
+ * not broken and the signature is not wrong — they simply no longer speak the
+ * same dialect.
+ *
+ * Consequence for anything x402: a delegated payer's `transferWithAuthorization`
+ * / `receiveWithAuthorization` becomes **unsettleable on-chain**, so direct x402
+ * payments AND marketplace escrow locks both fail. Measured in production
+ * 2026-07-31: 14 of 14 delegated agents failed their escrow lock; the one
+ * non-delegated agent locked fine. The failure is silent in the worst way — the
+ * sellers looked broken and they were correct.
+ *
+ * **THE FIX** (verified on-chain; the wallet provider needs to change nothing).
+ * That account's `isValidSignature` DOES accept the EOA's own ECDSA — it just
+ * wants it in the account's envelope. Two steps, both provable against the
+ * verified source (`SemiModularAccountBase._exec1271Validation` +
+ * `SparseCalldataSegmentLib`):
+ *
+ * 1. The account does not check `hash` directly; it checks a REPLAY-SAFE hash =
+ *    EIP-712 over the account's OWN domain
+ *    `EIP712Domain(uint256 chainId, address verifyingContract=account)` with
+ *    struct `ReplaySafeHash(bytes32 hash)`. Sign THAT, not the transfer digest.
+ * 2. Wrap the 65-byte signature with the account's fallback-validation locator:
+ *    `0x00 00000000` (validation type 0, entity id 0 = FALLBACK_VALIDATION_ID)
+ *    `FF` (RESERVED_VALIDATION_DATA_INDEX, the final segment) `00`
+ *    (SignatureType.EOA).
+ *
+ * Because step 1 is still an ordinary typed-data signature, a REMOTE signer (a
+ * delegated agentic wallet) can produce it: the private key is never needed
+ * locally.
+ *
+ * **THE WRAP IS DELEGATE-SPECIFIC, NOT "delegated == wrap".** This is the part
+ * that bit us on 2026-08-25, and it is why this module exists in TypeScript at
+ * all: the moment a worker rates an agent through the facilitator's EIP-7702
+ * feedback rail, their EOA becomes delegated to Execution Market's
+ * `FeedbackDelegate` — which validates PLAIN ECDSA
+ * (`ECDSA.recover(hash, sig) == address(this)`). Wrapping that signature makes it
+ * invalid, so *the act of rating would break the rater's next payment*. Same
+ * silent-at-lock-time failure the wrap was built to fix, now caused by
+ * over-applying it.
+ *
+ * **DETECTION IS INJECTABLE, ON PURPOSE.** Knowing whether an address is
+ * delegated needs one `eth_getCode` — a chain read, and this SDK does not own an
+ * RPC policy. So detection is a callable you pass in ({@link DelegationResolver}).
+ * {@link rpcDelegationResolver} ships a default over `fetch`; a caller with its
+ * own endpoints, proxy or rotation passes its own.
+ *
+ * **THE THIRD STATE IS LOAD-BEARING.** A resolver returns `true` / `false` /
+ * **`null` = could not tell**. `null` must never collapse to "not delegated":
+ * that is exactly how the original bug survived eight days — the resolver failed,
+ * returned nothing, and the caller's `if (delegated)` read it as falsy and signed
+ * raw. **An unreadable answer is not a negative answer.**
+ *
+ * Port of `uvd_x402_sdk.erc7702` (Python). Keep the two in step: they are the
+ * same protocol seen from two languages, and a divergence here is a signature
+ * that cannot settle.
+ */
+/** EIP-7702 delegation designator. */
+declare const DELEGATE_PREFIX = "ef0100";
+/**
+ * Delegate targets whose ERC-1271 needs the account-envelope wrap.
+ *
+ * Only a known Alchemy SMA implementation needs it. Every other delegate signs
+ * PLAIN (the standard 1271 "smart-EOA" pattern accepts the EOA's own ECDSA), and
+ * if some exotic future delegate needs a third dialect it fails VISIBLY at lock
+ * time — never silently.
+ *
+ * Notably NOT here: Execution Market's `FeedbackDelegate` (all nine deploys). An
+ * account that has rated through the facilitator's rail is delegated to it and
+ * must sign plain.
+ */
+declare const SMA_WRAP_TARGETS: readonly string[];
+/**
+ * `true` only when this delegate target needs the account-envelope wrap.
+ *
+ * A plain EOA (`target` null/undefined) and any other delegate — FeedbackDelegate,
+ * a standard 1271 smart-EOA — do NOT: they take the ordinary ECDSA signature.
+ */
+declare function needsAccountWrap(target: string | null | undefined): boolean;
+/**
+ * The delegate target this EOA's EIP-7702 code points at, or `null`.
+ *
+ * `null` for a plain EOA, for non-7702 code, and for anything unparseable — the
+ * caller confirms the implementation before applying the wrap.
+ */
+declare function delegateTarget(code: string | null | undefined): string | null;
+/** Wrap a 65-byte ECDSA signature in the account's fallback-EOA envelope. */
+declare function wrapSignature(innerSignature: string): string;
+/**
+ * The typed data whose signature the delegated account accepts.
+ *
+ * The domain is the ACCOUNT's own — `chainId` + `verifyingContract=account`, the
+ * two fields its typehash declares — and the struct is
+ * `ReplaySafeHash(bytes32 hash)` over the inner EIP-3009 digest. Signing THIS,
+ * not the digest, is what validates.
+ */
+declare function replaySafeTypedData(innerDigest: string, chainId: number, account: string): {
+    domain: Record<string, unknown>;
+    types: Record<string, unknown>;
+    message: Record<string, unknown>;
+};
+/**
+ * `(address, network) -> target | true | false | null`.
+ *
+ * Four answers, richer than a boolean on purpose: a resolver MAY return the
+ * delegate **target address** (a string) instead of just `true` — that is what
+ * lets the caller pick the right signing dialect (SMA wrap vs plain). `true` =
+ * delegated, target unknown; `false` = not delegated; `null` = UNKNOWN
+ * (unreadable chain), never "no".
+ */
+type DelegationResolver = (address: string, network: string) => Promise<string | boolean | null> | (string | boolean | null);
+/**
+ * A default resolver over plain JSON-RPC `eth_getCode`, using `fetch`.
+ *
+ * Rotates through `urls` and returns `null` when **every** endpoint failed: an
+ * unreadable chain is not a "not delegated" verdict.
+ *
+ * A caller with its own RPC policy (a signed proxy, paid endpoints, per-chain
+ * routing) should pass its own resolver instead; that is the whole point of the
+ * injection.
+ */
+declare function rpcDelegationResolver(urls: string | string[], timeoutMs?: number): DelegationResolver;
+/** `{ delegated, target }` for one address on one network. */
+interface DelegationVerdict {
+    /** `null` = UNKNOWN. Never treat it as `false`. */
+    delegated: boolean | null;
+    /** The delegate implementation, when the resolver could name it. */
+    target: string | null;
+}
+/**
+ * Resolve one address's delegation on one network.
+ *
+ * - `{delegated: null, target: null}` — unknown (no resolver, or an unreadable
+ *   chain). NEVER "no".
+ * - `{delegated: false, target: null}` — a plain EOA.
+ * - `{delegated: true, target: '0x…'}` — delegated, and we know to WHAT (pick the
+ *   dialect from it).
+ * - `{delegated: true, target: null}` — delegated, target unknown (a legacy
+ *   boolean-only resolver).
+ */
+declare function resolveDelegation(address: string, network: string, resolver?: DelegationResolver): Promise<DelegationVerdict>;
+/**
+ * `true` / `false` / `null` (**unknown**) for one address on one network.
+ *
+ * Without a resolver the answer is `null`, never `false`: "nobody asked" and "the
+ * address is a plain EOA" are different facts and only one of them is safe to
+ * sign on.
+ */
+declare function isDelegated(address: string, network: string, resolver?: DelegationResolver): Promise<boolean | null>;
+
 /**
  * uvd-x402-sdk - Escrow Pre-Auth Builder (sign-on-assignment)
  *
@@ -892,6 +1049,7 @@ declare function buildSignatureParams(params: SignatureParamsInput): string;
  *     (production reference, derived from `uvd_x402_sdk.advanced_escrow`)
  *   - Browser (viem): Execution Market `dashboard/src/services/h2aSigning.ts`
  */
+
 /** AuthCaptureEscrow deposit condition: $100 max per deposit. */
 declare const ESCROW_DEPOSIT_LIMIT_USD = 100;
 /**
@@ -1001,6 +1159,20 @@ interface EscrowPreAuthParams {
      * publishes a different limit.
      */
     depositLimitUsd?: number;
+    /**
+     * How to find out whether `payerWallet` is EIP-7702-delegated, and to what.
+     *
+     * Optional, and its absence is honest rather than convenient: with no resolver
+     * the verdict is UNKNOWN and this function signs the ordinary way, exactly as
+     * it did before. Pass one — {@link rpcDelegationResolver} or your own — as soon
+     * as your payers can be delegated accounts, because a delegated payer signing
+     * the wrong dialect produces an authorization that **cannot settle on-chain**
+     * and only fails at lock time.
+     *
+     * When a resolver IS supplied and it reaches no verdict, this throws instead of
+     * guessing: an unreadable chain is not a "not delegated" answer.
+     */
+    delegationResolver?: DelegationResolver;
 }
 /**
  * Build + sign the escrow lock authorization AT ASSIGNMENT time and return
@@ -1015,4 +1187,4 @@ interface EscrowPreAuthParams {
  */
 declare function buildEscrowPreAuth(wallet: EscrowPreAuthSigner, params: EscrowPreAuthParams): Promise<string>;
 
-export { ANCHOR_MAX_REQUEST_BYTES, type AnchorOptions, type AnchoredEvidence, type BackendOffer, ContentHashMismatch, type CreateSignedFetchConfig, DX402Error, type ERC8128RequestOptions, ESCROW_DEPOSIT_LIMIT_USD, ESCROW_TIER_WINDOWS, EVENT_KINDS, EVIDENCE_HEADER, type EscrowNetworkConfig, type EscrowPaymentInfo, type EscrowPreAuthParams, type EscrowPreAuthSigner, type EscrowTierWindows, type EvidenceMode, EvidenceSkipped, FACILITATOR_ADDRESSES, type FacilitatorAddresses, KEEPALIVE_INTERVAL_MS, OPERATOR_FEE_BPS, type RecipientRole, type SSEFrame, SSEParser, type SignRequestOptions, type SignRequestWithSignerOptions, type SignatureBaseParams, type SignatureHeaders, type SignatureParamsInput, SigningWalletAdapter, type StreamTrafficEventsOptions, type TrafficEvent, type TrafficEventKind, TrafficStreamError, ZERO_ADDRESS, anchorDigest, anchorEvidence, availableBackends, buildEscrowPreAuth, buildSignatureBase, buildSignatureParams, computeEscrowNonce, contentHash, createSignedFetch, dereferencePointer, paymentId as dx402PaymentId, ed25519ToX25519, evidenceFromHeaders, evidenceHeader, fetchNonce, getFacilitatorAddress, isEndToEnd, matchesFilters, parseEvidenceHeader, parseSealed, parseTrafficEvent, payerKeyFromEvmSignature, payerKeyFromSolanaAddress, recoverEvidence, sealEvidence, sealEvidenceTo, sealedRoles, sellerDigestFor, signAnchorEd25519, signAnchorEvm, signRequest, signRequestWithSigner, signRequestWithWallet, streamTrafficEvents, unseal };
+export { ANCHOR_MAX_REQUEST_BYTES, type AnchorOptions, type AnchoredEvidence, type BackendOffer, ContentHashMismatch, type CreateSignedFetchConfig, DELEGATE_PREFIX, DX402Error, type DelegationResolver, type DelegationVerdict, type ERC8128RequestOptions, ESCROW_DEPOSIT_LIMIT_USD, ESCROW_TIER_WINDOWS, EVENT_KINDS, EVIDENCE_HEADER, type EscrowNetworkConfig, type EscrowPaymentInfo, type EscrowPreAuthParams, type EscrowPreAuthSigner, type EscrowTierWindows, type EvidenceMode, EvidenceSkipped, FACILITATOR_ADDRESSES, type FacilitatorAddresses, KEEPALIVE_INTERVAL_MS, OPERATOR_FEE_BPS, type RecipientRole, SMA_WRAP_TARGETS, type SSEFrame, SSEParser, type SignRequestOptions, type SignRequestWithSignerOptions, type SignatureBaseParams, type SignatureHeaders, type SignatureParamsInput, SigningWalletAdapter, type StreamTrafficEventsOptions, type TrafficEvent, type TrafficEventKind, TrafficStreamError, ZERO_ADDRESS, anchorDigest, anchorEvidence, availableBackends, buildEscrowPreAuth, buildSignatureBase, buildSignatureParams, computeEscrowNonce, contentHash, createSignedFetch, delegateTarget, dereferencePointer, paymentId as dx402PaymentId, ed25519ToX25519, evidenceFromHeaders, evidenceHeader, fetchNonce, getFacilitatorAddress, isDelegated, isEndToEnd, matchesFilters, needsAccountWrap, parseEvidenceHeader, parseSealed, parseTrafficEvent, payerKeyFromEvmSignature, payerKeyFromSolanaAddress, recoverEvidence, replaySafeTypedData, resolveDelegation, rpcDelegationResolver, sealEvidence, sealEvidenceTo, sealedRoles, sellerDigestFor, signAnchorEd25519, signAnchorEvm, signRequest, signRequestWithSigner, signRequestWithWallet, streamTrafficEvents, unseal, wrapSignature };

package/dist/index.d.ts

@@ -842,6 +842,163 @@ interface SignatureParamsInput {
  */
 declare function buildSignatureParams(params: SignatureParamsInput): string;
 
+/**
+ * EIP-7702: make a DELEGATED EOA's EIP-3009 signature settle again.
+ *
+ * **THE PROBLEM.** A gasless-wallet provider's first sponsored operation on a
+ * chain may delegate the user's EOA (EIP-7702) to a smart-account
+ * implementation — Alchemy's `SemiModularAccount7702` (`0x69007702…`) is the one
+ * seen in the wild. From then on the address HAS code, so Circle's USDC (and any
+ * `SignatureChecker` consumer) verifies signatures via **ERC-1271 only**. A raw
+ * ECDSA authorization, however perfect, is rejected: `0x151d90fe`. The account is
+ * not broken and the signature is not wrong — they simply no longer speak the
+ * same dialect.
+ *
+ * Consequence for anything x402: a delegated payer's `transferWithAuthorization`
+ * / `receiveWithAuthorization` becomes **unsettleable on-chain**, so direct x402
+ * payments AND marketplace escrow locks both fail. Measured in production
+ * 2026-07-31: 14 of 14 delegated agents failed their escrow lock; the one
+ * non-delegated agent locked fine. The failure is silent in the worst way — the
+ * sellers looked broken and they were correct.
+ *
+ * **THE FIX** (verified on-chain; the wallet provider needs to change nothing).
+ * That account's `isValidSignature` DOES accept the EOA's own ECDSA — it just
+ * wants it in the account's envelope. Two steps, both provable against the
+ * verified source (`SemiModularAccountBase._exec1271Validation` +
+ * `SparseCalldataSegmentLib`):
+ *
+ * 1. The account does not check `hash` directly; it checks a REPLAY-SAFE hash =
+ *    EIP-712 over the account's OWN domain
+ *    `EIP712Domain(uint256 chainId, address verifyingContract=account)` with
+ *    struct `ReplaySafeHash(bytes32 hash)`. Sign THAT, not the transfer digest.
+ * 2. Wrap the 65-byte signature with the account's fallback-validation locator:
+ *    `0x00 00000000` (validation type 0, entity id 0 = FALLBACK_VALIDATION_ID)
+ *    `FF` (RESERVED_VALIDATION_DATA_INDEX, the final segment) `00`
+ *    (SignatureType.EOA).
+ *
+ * Because step 1 is still an ordinary typed-data signature, a REMOTE signer (a
+ * delegated agentic wallet) can produce it: the private key is never needed
+ * locally.
+ *
+ * **THE WRAP IS DELEGATE-SPECIFIC, NOT "delegated == wrap".** This is the part
+ * that bit us on 2026-08-25, and it is why this module exists in TypeScript at
+ * all: the moment a worker rates an agent through the facilitator's EIP-7702
+ * feedback rail, their EOA becomes delegated to Execution Market's
+ * `FeedbackDelegate` — which validates PLAIN ECDSA
+ * (`ECDSA.recover(hash, sig) == address(this)`). Wrapping that signature makes it
+ * invalid, so *the act of rating would break the rater's next payment*. Same
+ * silent-at-lock-time failure the wrap was built to fix, now caused by
+ * over-applying it.
+ *
+ * **DETECTION IS INJECTABLE, ON PURPOSE.** Knowing whether an address is
+ * delegated needs one `eth_getCode` — a chain read, and this SDK does not own an
+ * RPC policy. So detection is a callable you pass in ({@link DelegationResolver}).
+ * {@link rpcDelegationResolver} ships a default over `fetch`; a caller with its
+ * own endpoints, proxy or rotation passes its own.
+ *
+ * **THE THIRD STATE IS LOAD-BEARING.** A resolver returns `true` / `false` /
+ * **`null` = could not tell**. `null` must never collapse to "not delegated":
+ * that is exactly how the original bug survived eight days — the resolver failed,
+ * returned nothing, and the caller's `if (delegated)` read it as falsy and signed
+ * raw. **An unreadable answer is not a negative answer.**
+ *
+ * Port of `uvd_x402_sdk.erc7702` (Python). Keep the two in step: they are the
+ * same protocol seen from two languages, and a divergence here is a signature
+ * that cannot settle.
+ */
+/** EIP-7702 delegation designator. */
+declare const DELEGATE_PREFIX = "ef0100";
+/**
+ * Delegate targets whose ERC-1271 needs the account-envelope wrap.
+ *
+ * Only a known Alchemy SMA implementation needs it. Every other delegate signs
+ * PLAIN (the standard 1271 "smart-EOA" pattern accepts the EOA's own ECDSA), and
+ * if some exotic future delegate needs a third dialect it fails VISIBLY at lock
+ * time — never silently.
+ *
+ * Notably NOT here: Execution Market's `FeedbackDelegate` (all nine deploys). An
+ * account that has rated through the facilitator's rail is delegated to it and
+ * must sign plain.
+ */
+declare const SMA_WRAP_TARGETS: readonly string[];
+/**
+ * `true` only when this delegate target needs the account-envelope wrap.
+ *
+ * A plain EOA (`target` null/undefined) and any other delegate — FeedbackDelegate,
+ * a standard 1271 smart-EOA — do NOT: they take the ordinary ECDSA signature.
+ */
+declare function needsAccountWrap(target: string | null | undefined): boolean;
+/**
+ * The delegate target this EOA's EIP-7702 code points at, or `null`.
+ *
+ * `null` for a plain EOA, for non-7702 code, and for anything unparseable — the
+ * caller confirms the implementation before applying the wrap.
+ */
+declare function delegateTarget(code: string | null | undefined): string | null;
+/** Wrap a 65-byte ECDSA signature in the account's fallback-EOA envelope. */
+declare function wrapSignature(innerSignature: string): string;
+/**
+ * The typed data whose signature the delegated account accepts.
+ *
+ * The domain is the ACCOUNT's own — `chainId` + `verifyingContract=account`, the
+ * two fields its typehash declares — and the struct is
+ * `ReplaySafeHash(bytes32 hash)` over the inner EIP-3009 digest. Signing THIS,
+ * not the digest, is what validates.
+ */
+declare function replaySafeTypedData(innerDigest: string, chainId: number, account: string): {
+    domain: Record<string, unknown>;
+    types: Record<string, unknown>;
+    message: Record<string, unknown>;
+};
+/**
+ * `(address, network) -> target | true | false | null`.
+ *
+ * Four answers, richer than a boolean on purpose: a resolver MAY return the
+ * delegate **target address** (a string) instead of just `true` — that is what
+ * lets the caller pick the right signing dialect (SMA wrap vs plain). `true` =
+ * delegated, target unknown; `false` = not delegated; `null` = UNKNOWN
+ * (unreadable chain), never "no".
+ */
+type DelegationResolver = (address: string, network: string) => Promise<string | boolean | null> | (string | boolean | null);
+/**
+ * A default resolver over plain JSON-RPC `eth_getCode`, using `fetch`.
+ *
+ * Rotates through `urls` and returns `null` when **every** endpoint failed: an
+ * unreadable chain is not a "not delegated" verdict.
+ *
+ * A caller with its own RPC policy (a signed proxy, paid endpoints, per-chain
+ * routing) should pass its own resolver instead; that is the whole point of the
+ * injection.
+ */
+declare function rpcDelegationResolver(urls: string | string[], timeoutMs?: number): DelegationResolver;
+/** `{ delegated, target }` for one address on one network. */
+interface DelegationVerdict {
+    /** `null` = UNKNOWN. Never treat it as `false`. */
+    delegated: boolean | null;
+    /** The delegate implementation, when the resolver could name it. */
+    target: string | null;
+}
+/**
+ * Resolve one address's delegation on one network.
+ *
+ * - `{delegated: null, target: null}` — unknown (no resolver, or an unreadable
+ *   chain). NEVER "no".
+ * - `{delegated: false, target: null}` — a plain EOA.
+ * - `{delegated: true, target: '0x…'}` — delegated, and we know to WHAT (pick the
+ *   dialect from it).
+ * - `{delegated: true, target: null}` — delegated, target unknown (a legacy
+ *   boolean-only resolver).
+ */
+declare function resolveDelegation(address: string, network: string, resolver?: DelegationResolver): Promise<DelegationVerdict>;
+/**
+ * `true` / `false` / `null` (**unknown**) for one address on one network.
+ *
+ * Without a resolver the answer is `null`, never `false`: "nobody asked" and "the
+ * address is a plain EOA" are different facts and only one of them is safe to
+ * sign on.
+ */
+declare function isDelegated(address: string, network: string, resolver?: DelegationResolver): Promise<boolean | null>;
+
 /**
  * uvd-x402-sdk - Escrow Pre-Auth Builder (sign-on-assignment)
  *
@@ -892,6 +1049,7 @@ declare function buildSignatureParams(params: SignatureParamsInput): string;
  *     (production reference, derived from `uvd_x402_sdk.advanced_escrow`)
  *   - Browser (viem): Execution Market `dashboard/src/services/h2aSigning.ts`
  */
+
 /** AuthCaptureEscrow deposit condition: $100 max per deposit. */
 declare const ESCROW_DEPOSIT_LIMIT_USD = 100;
 /**
@@ -1001,6 +1159,20 @@ interface EscrowPreAuthParams {
      * publishes a different limit.
      */
     depositLimitUsd?: number;
+    /**
+     * How to find out whether `payerWallet` is EIP-7702-delegated, and to what.
+     *
+     * Optional, and its absence is honest rather than convenient: with no resolver
+     * the verdict is UNKNOWN and this function signs the ordinary way, exactly as
+     * it did before. Pass one — {@link rpcDelegationResolver} or your own — as soon
+     * as your payers can be delegated accounts, because a delegated payer signing
+     * the wrong dialect produces an authorization that **cannot settle on-chain**
+     * and only fails at lock time.
+     *
+     * When a resolver IS supplied and it reaches no verdict, this throws instead of
+     * guessing: an unreadable chain is not a "not delegated" answer.
+     */
+    delegationResolver?: DelegationResolver;
 }
 /**
  * Build + sign the escrow lock authorization AT ASSIGNMENT time and return
@@ -1015,4 +1187,4 @@ interface EscrowPreAuthParams {
  */
 declare function buildEscrowPreAuth(wallet: EscrowPreAuthSigner, params: EscrowPreAuthParams): Promise<string>;
 
-export { ANCHOR_MAX_REQUEST_BYTES, type AnchorOptions, type AnchoredEvidence, type BackendOffer, ContentHashMismatch, type CreateSignedFetchConfig, DX402Error, type ERC8128RequestOptions, ESCROW_DEPOSIT_LIMIT_USD, ESCROW_TIER_WINDOWS, EVENT_KINDS, EVIDENCE_HEADER, type EscrowNetworkConfig, type EscrowPaymentInfo, type EscrowPreAuthParams, type EscrowPreAuthSigner, type EscrowTierWindows, type EvidenceMode, EvidenceSkipped, FACILITATOR_ADDRESSES, type FacilitatorAddresses, KEEPALIVE_INTERVAL_MS, OPERATOR_FEE_BPS, type RecipientRole, type SSEFrame, SSEParser, type SignRequestOptions, type SignRequestWithSignerOptions, type SignatureBaseParams, type SignatureHeaders, type SignatureParamsInput, SigningWalletAdapter, type StreamTrafficEventsOptions, type TrafficEvent, type TrafficEventKind, TrafficStreamError, ZERO_ADDRESS, anchorDigest, anchorEvidence, availableBackends, buildEscrowPreAuth, buildSignatureBase, buildSignatureParams, computeEscrowNonce, contentHash, createSignedFetch, dereferencePointer, paymentId as dx402PaymentId, ed25519ToX25519, evidenceFromHeaders, evidenceHeader, fetchNonce, getFacilitatorAddress, isEndToEnd, matchesFilters, parseEvidenceHeader, parseSealed, parseTrafficEvent, payerKeyFromEvmSignature, payerKeyFromSolanaAddress, recoverEvidence, sealEvidence, sealEvidenceTo, sealedRoles, sellerDigestFor, signAnchorEd25519, signAnchorEvm, signRequest, signRequestWithSigner, signRequestWithWallet, streamTrafficEvents, unseal };
+export { ANCHOR_MAX_REQUEST_BYTES, type AnchorOptions, type AnchoredEvidence, type BackendOffer, ContentHashMismatch, type CreateSignedFetchConfig, DELEGATE_PREFIX, DX402Error, type DelegationResolver, type DelegationVerdict, type ERC8128RequestOptions, ESCROW_DEPOSIT_LIMIT_USD, ESCROW_TIER_WINDOWS, EVENT_KINDS, EVIDENCE_HEADER, type EscrowNetworkConfig, type EscrowPaymentInfo, type EscrowPreAuthParams, type EscrowPreAuthSigner, type EscrowTierWindows, type EvidenceMode, EvidenceSkipped, FACILITATOR_ADDRESSES, type FacilitatorAddresses, KEEPALIVE_INTERVAL_MS, OPERATOR_FEE_BPS, type RecipientRole, SMA_WRAP_TARGETS, type SSEFrame, SSEParser, type SignRequestOptions, type SignRequestWithSignerOptions, type SignatureBaseParams, type SignatureHeaders, type SignatureParamsInput, SigningWalletAdapter, type StreamTrafficEventsOptions, type TrafficEvent, type TrafficEventKind, TrafficStreamError, ZERO_ADDRESS, anchorDigest, anchorEvidence, availableBackends, buildEscrowPreAuth, buildSignatureBase, buildSignatureParams, computeEscrowNonce, contentHash, createSignedFetch, delegateTarget, dereferencePointer, paymentId as dx402PaymentId, ed25519ToX25519, evidenceFromHeaders, evidenceHeader, fetchNonce, getFacilitatorAddress, isDelegated, isEndToEnd, matchesFilters, needsAccountWrap, parseEvidenceHeader, parseSealed, parseTrafficEvent, payerKeyFromEvmSignature, payerKeyFromSolanaAddress, recoverEvidence, replaySafeTypedData, resolveDelegation, rpcDelegationResolver, sealEvidence, sealEvidenceTo, sealedRoles, sellerDigestFor, signAnchorEd25519, signAnchorEvm, signRequest, signRequestWithSigner, signRequestWithWallet, streamTrafficEvents, unseal, wrapSignature };

package/dist/index.js

@@ -3424,6 +3424,88 @@ function buildSignatureParams(params) {
   parts.push(`alg="${ALG}"`);
   return parts.join(";");
 }
+
+// src/erc7702.ts
+var DELEGATE_PREFIX = "ef0100";
+var SMA_WRAP_TARGETS = [
+  "0x69007702764179f14f51cdce752f4f775d74e139"
+  // Alchemy SemiModularAccount7702
+];
+function needsAccountWrap(target) {
+  return !!target && SMA_WRAP_TARGETS.includes(target.toLowerCase());
+}
+var WRAP_PREFIX = "0000000000ff00";
+function delegateTarget(code) {
+  if (!code) return null;
+  const h = (code.startsWith("0x") ? code.slice(2) : code).toLowerCase();
+  if (!h.startsWith(DELEGATE_PREFIX) || h.length < 46) return null;
+  return `0x${h.slice(6, 46)}`;
+}
+function wrapSignature(innerSignature) {
+  const s = innerSignature.startsWith("0x") ? innerSignature.slice(2) : innerSignature;
+  return `0x${WRAP_PREFIX}${s}`;
+}
+function replaySafeTypedData(innerDigest, chainId, account) {
+  return {
+    domain: { chainId, verifyingContract: account },
+    types: { ReplaySafeHash: [{ name: "hash", type: "bytes32" }] },
+    message: { hash: innerDigest }
+  };
+}
+function rpcDelegationResolver(urls, timeoutMs = 6e3) {
+  const endpoints = typeof urls === "string" ? [urls] : [...urls];
+  return async (address) => {
+    const addr = (address || "").trim();
+    if (!addr || endpoints.length === 0) return null;
+    for (const url of endpoints) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const res = await fetch(url, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "eth_getCode",
+            params: [addr.toLowerCase(), "latest"]
+          }),
+          signal: controller.signal
+        });
+        clearTimeout(timer);
+        if (!res.ok) continue;
+        const code = (await res.json())?.result;
+        if (typeof code === "string" && code.startsWith("0x")) {
+          return delegateTarget(code) ?? false;
+        }
+      } catch {
+        clearTimeout(timer);
+      }
+    }
+    return null;
+  };
+}
+async function resolveDelegation(address, network, resolver) {
+  if (!resolver) return { delegated: null, target: null };
+  let v;
+  try {
+    v = await resolver(address, network);
+  } catch {
+    return { delegated: null, target: null };
+  }
+  if (typeof v === "string") {
+    const t = v.trim();
+    if (/^0x[0-9a-fA-F]{40}$/.test(t)) return { delegated: true, target: t };
+    return { delegated: null, target: null };
+  }
+  if (typeof v === "boolean") return { delegated: v, target: null };
+  return { delegated: null, target: null };
+}
+async function isDelegated(address, network, resolver) {
+  return (await resolveDelegation(address, network, resolver)).delegated;
+}
+
+// src/escrow-preauth.ts
 var ZERO_ADDRESS2 = "0x0000000000000000000000000000000000000000";
 var USDC_DECIMALS = 6;
 var ESCROW_DEPOSIT_LIMIT_USD = 100;
@@ -3569,26 +3651,56 @@ async function buildEscrowPreAuth(wallet, params) {
   );
   const payer = ethers.ethers.getAddress(params.payerWallet);
   const tokenCollector = ethers.ethers.getAddress(cfg.token_collector);
-  const { signature } = await wallet.signTypedData(
-    JSON.stringify({
-      domain: {
-        name: cfg.usdc_domain_name,
-        version: cfg.usdc_domain_version,
-        chainId: cfg.chain_id,
-        verifyingContract: ethers.ethers.getAddress(cfg.usdc)
-      },
-      types: RECEIVE_WITH_AUTHORIZATION_TYPES,
-      primaryType: "ReceiveWithAuthorization",
-      message: {
-        from: payer,
-        to: tokenCollector,
-        value: maxAmount.toString(),
-        validAfter: "0",
-        validBefore: String(paymentInfo.preApprovalExpiry),
-        nonce
-      }
-    })
+  const typedData = {
+    domain: {
+      name: cfg.usdc_domain_name,
+      version: cfg.usdc_domain_version,
+      chainId: cfg.chain_id,
+      verifyingContract: ethers.ethers.getAddress(cfg.usdc)
+    },
+    types: RECEIVE_WITH_AUTHORIZATION_TYPES,
+    primaryType: "ReceiveWithAuthorization",
+    message: {
+      from: payer,
+      to: tokenCollector,
+      value: maxAmount.toString(),
+      validAfter: "0",
+      validBefore: String(paymentInfo.preApprovalExpiry),
+      nonce
+    }
+  };
+  const { delegated, target } = await resolveDelegation(
+    payer,
+    `eip155:${cfg.chain_id}`,
+    params.delegationResolver
   );
+  if (delegated === null && params.delegationResolver) {
+    throw new X402Error(
+      `Could not determine whether ${payer} is EIP-7702-delegated on chain ${cfg.chain_id} (the resolver gave no verdict) \u2014 refusing to sign an escrow authorization blindly: the wrong dialect is unsettleable on-chain and the failure only shows up at lock time. Retry when the chain is readable.`,
+      "INVALID_CONFIG"
+    );
+  }
+  let signature;
+  if (delegated && (needsAccountWrap(target) || target === null)) {
+    const innerDigest = ethers.ethers.TypedDataEncoder.hash(
+      typedData.domain,
+      typedData.types,
+      typedData.message
+    );
+    const replaySafe = replaySafeTypedData(innerDigest, cfg.chain_id, payer);
+    const wrapped = await wallet.signTypedData(
+      JSON.stringify({ ...replaySafe, primaryType: "ReplaySafeHash" })
+    );
+    if (!wrapped?.signature) {
+      throw new X402Error(
+        "The wallet returned no signature for the replay-safe wrap \u2014 refusing to build an unsettleable authorization.",
+        "INVALID_CONFIG"
+      );
+    }
+    signature = wrapSignature(wrapped.signature);
+  } else {
+    signature = (await wallet.signTypedData(JSON.stringify(typedData))).signature;
+  }
   return JSON.stringify({
     x402Version: 2,
     scheme: "escrow",
@@ -4404,6 +4516,7 @@ exports.DEFAULT_CHAIN = DEFAULT_CHAIN;
 exports.DEFAULT_CONFIG = DEFAULT_CONFIG;
 exports.DEFAULT_FACILITATOR_URL = DEFAULT_FACILITATOR_URL;
 exports.DEFAULT_PAYMENT_HEADER = DEFAULT_PAYMENT_HEADER;
+exports.DELEGATE_PREFIX = DELEGATE_PREFIX;
 exports.DX402Error = DX402Error;
 exports.ESCROW_DEPOSIT_LIMIT_USD = ESCROW_DEPOSIT_LIMIT_USD;
 exports.ESCROW_TIER_WINDOWS = ESCROW_TIER_WINDOWS;
@@ -4417,6 +4530,7 @@ exports.KEEPALIVE_INTERVAL_MS = KEEPALIVE_INTERVAL_MS;
 exports.OPERATOR_FEE_BPS = OPERATOR_FEE_BPS;
 exports.OWSWalletAdapter = OWSWalletAdapter;
 exports.PAYMENT_HEADER_NAMES = PAYMENT_HEADER_NAMES;
+exports.SMA_WRAP_TARGETS = SMA_WRAP_TARGETS;
 exports.SSEParser = SSEParser;
 exports.SUPPORTED_CHAINS = SUPPORTED_CHAINS;
 exports.TrafficStreamError = TrafficStreamError;
@@ -4452,6 +4566,7 @@ exports.createX402V1Header = createX402V1Header;
 exports.createX402V2Header = createX402V2Header;
 exports.decodeBase64Utf8 = decodeBase64Utf8;
 exports.decodeX402Header = decodeX402Header;
+exports.delegateTarget = delegateTarget;
 exports.dereferencePointer = dereferencePointer;
 exports.detectX402Version = detectX402Version;
 exports.dx402PaymentId = paymentId;
@@ -4486,12 +4601,14 @@ exports.getXRPLChains = getXRPLChains;
 exports.isAlgorandChain = isAlgorandChain;
 exports.isCAIP2Format = isCAIP2Format;
 exports.isChainSupported = isChainSupported;
+exports.isDelegated = isDelegated;
 exports.isEndToEnd = isEndToEnd;
 exports.isSVMChain = isSVMChain;
 exports.isSuiChain = isSuiChain;
 exports.isTokenSupported = isTokenSupported;
 exports.isXRPLChain = isXRPLChain;
 exports.matchesFilters = matchesFilters;
+exports.needsAccountWrap = needsAccountWrap;
 exports.parseEvidenceHeader = parseEvidenceHeader;
 exports.parseNetworkIdentifier = parseNetworkIdentifier;
 exports.parseSealed = parseSealed;
@@ -4500,6 +4617,9 @@ exports.payerKeyFromEvmSignature = payerKeyFromEvmSignature;
 exports.payerKeyFromSolanaAddress = payerKeyFromSolanaAddress;
 exports.paymentChallengeFrom = paymentChallengeFrom;
 exports.recoverEvidence = recoverEvidence;
+exports.replaySafeTypedData = replaySafeTypedData;
+exports.resolveDelegation = resolveDelegation;
+exports.rpcDelegationResolver = rpcDelegationResolver;
 exports.sealEvidence = sealEvidence;
 exports.sealEvidenceTo = sealEvidenceTo;
 exports.sealedRoles = sealedRoles;
@@ -4513,5 +4633,6 @@ exports.streamTrafficEvents = streamTrafficEvents;
 exports.unseal = unseal;
 exports.validateAmount = validateAmount;
 exports.validateRecipient = validateRecipient;
+exports.wrapSignature = wrapSignature;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map