@stablechain/sdk 1.0.4 → 1.0.6

package/dist/erc3009.d.ts

@@ -0,0 +1,429 @@
+import { Address, Hex, Account, Client, Hash } from 'viem';
+
+/**
+ * Overrides for the EIP-712 domain used when signing an authorization.
+ *
+ * When omitted, the domain is resolved from the token contract at runtime:
+ * `eip712Domain()` (EIP-5267) is tried first, falling back to reading `name()`
+ * with `version` defaulting to `"1"`. `chainId` falls back to the client chain
+ * and `verifyingContract` to the token address.
+ */
+interface Erc3009DomainOverrides {
+    name?: string;
+    version?: string;
+    chainId?: number;
+    verifyingContract?: Address;
+}
+/** A fully-specified ERC-3009 authorization message. */
+interface Authorization {
+    from: Address;
+    to: Address;
+    /** Token amount in the token's smallest unit (raw, not human-scaled). */
+    value: bigint;
+    /** Unix seconds after which the authorization becomes valid (0 = immediately). */
+    validAfter: bigint;
+    /** Unix seconds after which the authorization is no longer valid. */
+    validBefore: bigint;
+    /** 32-byte unique nonce. */
+    nonce: Hex;
+}
+/** A signed authorization, with the signature split for `(v, r, s)` contract calls. */
+interface SignedAuthorization {
+    authorization: Authorization;
+    /** 65-byte serialized signature. */
+    signature: Hex;
+    v: number;
+    r: Hex;
+    s: Hex;
+}
+interface SignTransferAuthorizationParameters {
+    /** ERC-3009 token contract. Defaults to STABLE_USDT_ADDRESS. */
+    token?: Address;
+    /** Authorizer/sender. Defaults to the client/parameters account address. */
+    from?: Address;
+    to: Address;
+    /** Token amount in the token's smallest unit (raw, not human-scaled). */
+    value: bigint;
+    /** Unix seconds; defaults to 0 (valid immediately). */
+    validAfter?: bigint;
+    /** Unix seconds after which the authorization expires. Required. */
+    validBefore: bigint;
+    /** 32-byte unique nonce. Defaults to a cryptographically random value. */
+    nonce?: Hex;
+    /** EIP-712 domain overrides — resolved from the token when omitted. */
+    domain?: Erc3009DomainOverrides;
+    /** Signing account — defaults to the client's account. */
+    account?: Account | Address;
+}
+/** Same shape as {@link SignTransferAuthorizationParameters}. */
+type SignReceiveAuthorizationParameters = SignTransferAuthorizationParameters;
+/**
+ * Submit a `transferWithAuthorization`. Pass a pre-signed authorization
+ * (`{ authorization, v, r, s }`) to relay one signed elsewhere, or the raw
+ * sign parameters to sign-and-submit in one call.
+ */
+type TransferWithAuthorizationParameters = {
+    signed: SignedAuthorization;
+    token?: Address;
+} | SignTransferAuthorizationParameters;
+type ReceiveWithAuthorizationParameters = {
+    signed: SignedAuthorization;
+    token?: Address;
+} | SignReceiveAuthorizationParameters;
+interface CancelAuthorizationParameters {
+    /** ERC-3009 token contract. Defaults to STABLE_USDT_ADDRESS. */
+    token?: Address;
+    /** Authorizer whose nonce is being cancelled. Defaults to the client account. */
+    authorizer?: Address;
+    /** The nonce to cancel. */
+    nonce: Hex;
+    /** EIP-712 domain overrides — resolved from the token when omitted. */
+    domain?: Erc3009DomainOverrides;
+    /** Signing account — defaults to the client's account. */
+    account?: Account | Address;
+}
+interface GetAuthorizationStateParameters {
+    /** ERC-3009 token contract. Defaults to STABLE_USDT_ADDRESS. */
+    token?: Address;
+    authorizer: Address;
+    nonce: Hex;
+}
+type VerifyFailureReason = "invalid_signature" | "signer_mismatch" | "already_used" | "not_yet_valid" | "expired" | "expiring_soon" | "insufficient_funds" | "would_revert";
+interface VerifyAuthorizationParameters {
+    /** ERC-3009 token contract. Defaults to STABLE_USDT_ADDRESS. */
+    token?: Address;
+    signed: SignedAuthorization;
+    /** Primary type the authorization was signed with. Default "TransferWithAuthorization". */
+    primaryType?: "TransferWithAuthorization" | "ReceiveWithAuthorization";
+    /** EIP-712 domain overrides — resolved from the token when omitted. */
+    domain?: Erc3009DomainOverrides;
+    /** Flag as `expiring_soon` if it expires within this many seconds. Default 0. */
+    expiryMarginSeconds?: number;
+    /** Unix seconds to check the time window against. Defaults to the latest block timestamp. */
+    now?: bigint;
+}
+/**
+ * Result of a gas-free preflight. `ok` is true only when `reasons` is empty.
+ * ERC-3009 does not reserve funds, so `insufficient_funds` is advisory — the
+ * balance can change before settlement.
+ */
+interface VerifyAuthorizationResult {
+    ok: boolean;
+    reasons: VerifyFailureReason[];
+    /** Recovered signer — present when the signature is structurally valid. */
+    signer?: Address;
+    /** `balanceOf(from)` at check time. */
+    balance?: bigint;
+    /** `value - balance` when the sender is short. */
+    shortfall?: bigint;
+    /** Decoded revert reason from the `eth_call` dry-run, when it would revert. */
+    revertReason?: string;
+}
+interface GetAuthorizationUsageParameters {
+    /** ERC-3009 token contract. Defaults to STABLE_USDT_ADDRESS. */
+    token?: Address;
+    authorizer: Address;
+    nonce: Hex;
+    /**
+     * Block range to scan for the `AuthorizationUsed` event. Both `authorizer`
+     * and `nonce` are indexed, so the filter is cheap, but public RPCs may
+     * reject unbounded ranges — pass a `fromBlock` floor (e.g. the token's
+     * deploy block) for large chains. Defaults to `earliest`..`latest`.
+     */
+    fromBlock?: bigint | "earliest";
+    toBlock?: bigint | "latest";
+}
+interface AuthorizationUsage {
+    used: boolean;
+    /** Transaction that consumed the authorization, when found. */
+    txHash?: Hex;
+    blockNumber?: bigint;
+}
+/**
+ * Encoded call ready for a relayer or the enterprise gas-waiver rail to submit.
+ * Includes the signed authorization so callers can inspect/store it.
+ */
+interface PreparedAuthorizationCall {
+    to: Address;
+    data: Hex;
+    value: bigint;
+    chainId: number;
+    signed: SignedAuthorization;
+}
+
+/**
+ * Sign an ERC-3009 `TransferWithAuthorization` (EIP-712). Produces a portable,
+ * serializable authorization that anyone can later submit on-chain — the signer
+ * pays no gas and need not be the submitter.
+ *
+ * @example
+ * const signed = await signTransferAuthorization(walletClient, {
+ *   to: vendor,
+ *   value: 1_250_000n,               // 1.25 USDT0 (6 decimals)
+ *   validBefore: BigInt(nowSeconds + 3600),
+ * });
+ */
+declare function signTransferAuthorization(client: Client, parameters: SignTransferAuthorizationParameters): Promise<SignedAuthorization>;
+
+/**
+ * Sign an ERC-3009 `ReceiveWithAuthorization` (EIP-712). Identical to
+ * {@link signTransferAuthorization} except the resulting authorization can only
+ * be submitted by the recipient (`to`), which prevents front-running when `to`
+ * is a contract that reacts on receipt.
+ */
+declare function signReceiveAuthorization(client: Client, parameters: SignReceiveAuthorizationParameters): Promise<SignedAuthorization>;
+
+/**
+ * Submit a `transferWithAuthorization`. Pass a pre-signed authorization
+ * (`{ signed }`) to relay one produced elsewhere, or the raw sign parameters to
+ * sign-and-submit in one call. Anyone may submit this variant.
+ *
+ * Returns the transaction hash without waiting for a receipt (like viem's
+ * `writeContract`).
+ */
+declare function transferWithAuthorization(client: Client, parameters: TransferWithAuthorizationParameters): Promise<Hash>;
+
+/**
+ * Submit a `receiveWithAuthorization`. Unlike `transferWithAuthorization`, the
+ * caller MUST be the recipient (`to`) — enforced on-chain via `msg.sender`, and
+ * checked here up front so callers get a clear error before broadcasting.
+ *
+ * Returns the transaction hash without waiting for a receipt.
+ */
+declare function receiveWithAuthorization(client: Client, parameters: ReceiveWithAuthorizationParameters): Promise<Hash>;
+
+/**
+ * Sign and submit a `cancelAuthorization`, revoking an unused nonce. Requires
+ * the authorizer's signature. Best-effort: a cancel can lose a race to an
+ * in-flight settlement of the same nonce, in which case the cancel reverts.
+ *
+ * Returns the transaction hash without waiting for a receipt.
+ */
+declare function cancelAuthorization(client: Client, parameters: CancelAuthorizationParameters): Promise<Hash>;
+
+/**
+ * Sign a transfer authorization and return the encoded call WITHOUT submitting
+ * it — ready for a relayer or the enterprise gas-waiver rail to broadcast. This
+ * is the seam between core (produces the signed call) and any external
+ * submission path (consumes `{ to, data, value, chainId }`).
+ */
+declare function prepareTransferWithAuthorization(client: Client, parameters: SignTransferAuthorizationParameters): Promise<PreparedAuthorizationCall>;
+
+/**
+ * Gas-free preflight over a signed authorization, cheapest checks first:
+ * signature recovery → on-chain nonce state → time window → payer solvency →
+ * `eth_call` dry-run. Returns structured reasons instead of throwing, so a payee
+ * can screen a queue of authorizations before spending gas on any of them.
+ *
+ * Note: ERC-3009 does not reserve funds, so `insufficient_funds` is advisory —
+ * the sender's balance can change before settlement actually lands.
+ */
+declare function verifyAuthorization(client: Client, parameters: VerifyAuthorizationParameters): Promise<VerifyAuthorizationResult>;
+
+/**
+ * Read `authorizationState(authorizer, nonce)` — `true` once the nonce has been
+ * used or cancelled. A cheap gas-free check before relaying.
+ */
+declare function getAuthorizationState(client: Client, parameters: GetAuthorizationStateParameters): Promise<boolean>;
+
+/**
+ * Resolve whether (and in which transaction) an authorization was consumed, by
+ * querying the `AuthorizationUsed(authorizer, nonce)` event. Both fields are
+ * indexed, so this needs no indexer — one `eth_getLogs`.
+ *
+ * Doubles as the idempotency primitive: if a settle is retried and the nonce
+ * already landed, this returns the original transaction instead of a revert.
+ */
+declare function getAuthorizationUsage(client: Client, parameters: GetAuthorizationUsageParameters): Promise<AuthorizationUsage>;
+
+/**
+ * viem client decorator — attach the ERC-3009 actions to any client:
+ *
+ * @example
+ * const client = createWalletClient({ account, chain, transport: http() })
+ *   .extend(erc3009Actions);
+ * const signed = await client.signTransferAuthorization({ to, value, validBefore });
+ */
+declare function erc3009Actions(client: Client): {
+    signTransferAuthorization: (p: SignTransferAuthorizationParameters) => Promise<SignedAuthorization>;
+    signReceiveAuthorization: (p: SignReceiveAuthorizationParameters) => Promise<SignedAuthorization>;
+    transferWithAuthorization: (p: TransferWithAuthorizationParameters) => Promise<`0x${string}`>;
+    receiveWithAuthorization: (p: ReceiveWithAuthorizationParameters) => Promise<`0x${string}`>;
+    cancelAuthorization: (p: CancelAuthorizationParameters) => Promise<`0x${string}`>;
+    prepareTransferWithAuthorization: (p: SignTransferAuthorizationParameters) => Promise<PreparedAuthorizationCall>;
+    verifyAuthorization: (p: VerifyAuthorizationParameters) => Promise<VerifyAuthorizationResult>;
+    getAuthorizationState: (p: GetAuthorizationStateParameters) => Promise<boolean>;
+    getAuthorizationUsage: (p: GetAuthorizationUsageParameters) => Promise<AuthorizationUsage>;
+};
+
+/**
+ * ERC-3009 "Transfer With Authorization" surface, plus EIP-5267 `eip712Domain()`
+ * used to resolve the signing domain at runtime. Signatures are passed in the
+ * canonical `(v, r, s)` form, which USDT0 and USDC-style tokens both accept.
+ */
+declare const ERC3009_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "transferWithAuthorization";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validBefore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "v";
+        readonly type: "uint8";
+    }, {
+        readonly name: "r";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "s";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "receiveWithAuthorization";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validBefore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "v";
+        readonly type: "uint8";
+    }, {
+        readonly name: "r";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "s";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "cancelAuthorization";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "authorizer";
+        readonly type: "address";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "v";
+        readonly type: "uint8";
+    }, {
+        readonly name: "r";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "s";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "authorizationState";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "authorizer";
+        readonly type: "address";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "balanceOf";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "AuthorizationUsed";
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly name: "authorizer";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+        readonly indexed: true;
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "eip712Domain";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "fields";
+        readonly type: "bytes1";
+    }, {
+        readonly name: "name";
+        readonly type: "string";
+    }, {
+        readonly name: "version";
+        readonly type: "string";
+    }, {
+        readonly name: "chainId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "verifyingContract";
+        readonly type: "address";
+    }, {
+        readonly name: "salt";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "extensions";
+        readonly type: "uint256[]";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "name";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "string";
+    }];
+}];
+
+export { type Authorization, type AuthorizationUsage, type CancelAuthorizationParameters, ERC3009_ABI, type Erc3009DomainOverrides, type GetAuthorizationStateParameters, type GetAuthorizationUsageParameters, type PreparedAuthorizationCall, type ReceiveWithAuthorizationParameters, type SignReceiveAuthorizationParameters, type SignTransferAuthorizationParameters, type SignedAuthorization, type TransferWithAuthorizationParameters, type VerifyAuthorizationParameters, type VerifyAuthorizationResult, type VerifyFailureReason, cancelAuthorization, erc3009Actions, getAuthorizationState, getAuthorizationUsage, prepareTransferWithAuthorization, receiveWithAuthorization, signReceiveAuthorization, signTransferAuthorization, transferWithAuthorization, verifyAuthorization };

package/dist/erc3009.js

@@ -0,0 +1,26 @@
+import {
+  ERC3009_ABI,
+  cancelAuthorization,
+  erc3009Actions,
+  getAuthorizationState,
+  getAuthorizationUsage,
+  prepareTransferWithAuthorization,
+  receiveWithAuthorization,
+  signReceiveAuthorization,
+  signTransferAuthorization,
+  transferWithAuthorization,
+  verifyAuthorization
+} from "./chunk-VS6GBRDF.js";
+export {
+  ERC3009_ABI,
+  cancelAuthorization,
+  erc3009Actions,
+  getAuthorizationState,
+  getAuthorizationUsage,
+  prepareTransferWithAuthorization,
+  receiveWithAuthorization,
+  signReceiveAuthorization,
+  signTransferAuthorization,
+  transferWithAuthorization,
+  verifyAuthorization
+};