@stablechain/sdk 1.0.3 → 1.0.5

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+import { erc3009Actions } from './erc3009.cjs';
+export { Authorization, AuthorizationUsage, CancelAuthorizationParameters, ERC3009_ABI, Erc3009DomainOverrides, GetAuthorizationStateParameters, GetAuthorizationUsageParameters, PreparedAuthorizationCall, ReceiveWithAuthorizationParameters, SignReceiveAuthorizationParameters, SignTransferAuthorizationParameters, SignedAuthorization, TransferWithAuthorizationParameters, VerifyAuthorizationParameters, VerifyAuthorizationResult, VerifyFailureReason, cancelAuthorization, getAuthorizationState, getAuthorizationUsage, prepareTransferWithAuthorization, receiveWithAuthorization, signReceiveAuthorization, signTransferAuthorization, transferWithAuthorization, verifyAuthorization } from './erc3009.cjs';
 import { Account, Transport, WalletClient, Address, BaseError } from 'viem';
 
 interface EarnConfig {
@@ -86,7 +88,15 @@ declare enum Chain {
     MegaETH = "megaeth",
     Base = "base",
     BSC = "bsc",
-    HyperEVM = "hyperevm"
+    HyperEVM = "hyperevm",
+    Polygon = "polygon",
+    Plasma = "plasma",
+    Optimism = "optimism",
+    Unichain = "unichain",
+    Sei = "sei",
+    Flare = "flare",
+    XLayer = "xlayer",
+    Rootstock = "rootstock"
 }
 declare enum Network {
     Mainnet = "mainnet",
@@ -95,7 +105,67 @@ declare enum Network {
 interface BridgeQuote {
     /** Estimated output amount on the destination chain */
     toAmount?: number;
+    /** LayerZero native messaging fee (wei) — only present for USDT0→USDT0 (OFT) routes */
+    nativeFee?: bigint;
+    /** LayerZero fee paid in LZ token (wei) — only present for USDT0→USDT0 (OFT) routes */
+    lzTokenFee?: bigint;
+    /**
+     * How long the bridge is expected to take. Only present for USDT0 (OFT) routes,
+     * and omitted if the estimate could not be resolved — never treat it as required.
+     */
+    estimate?: BridgeTimeEstimate;
 }
+/**
+ * Expected end-to-end delivery time for a USDT0 (LayerZero OFT) bridge.
+ *
+ * Almost all of the wait is source-chain finality: the DVNs securing the pathway
+ * refuse to attest until the send transaction is buried under `confirmations`
+ * source blocks. Destination execution is a few blocks on top of that.
+ */
+interface BridgeTimeEstimate {
+    /** Best available estimate, in seconds — prefer this for display */
+    seconds: number;
+    /** Which input produced `seconds` — see {@link BridgeTimeEstimate.observedSeconds} */
+    source: "observed" | "formula";
+    /**
+     * Median delivery time of recent delivered messages on this exact pathway,
+     * from LayerZero Scan. More trustworthy than `formulaSeconds` — notably on
+     * rollup sources, where DVNs wait for L1 finality rather than raw block count.
+     */
+    observedSeconds?: number;
+    /**
+     * LayerZero's documented estimate:
+     * `srcBlockTime × confirmations + dstBlockTime × (2 + dvnCount)`.
+     */
+    formulaSeconds?: number;
+    /** Source-chain block confirmations the DVNs wait for before attesting */
+    confirmations?: number;
+    /** Number of DVNs (required + optional) verifying this pathway */
+    dvnCount?: number;
+}
+/** Delivery state of an in-flight USDT0 bridge, normalized from LayerZero Scan. */
+type BridgeDeliveryState = "pending" | "inflight" | "delivered" | "failed";
+interface BridgeStatus {
+    state: BridgeDeliveryState;
+    /** Raw LayerZero Scan status, e.g. "INFLIGHT" | "DELIVERED" | "FAILED" | "BLOCKED" */
+    raw?: string;
+    srcTxHash: string;
+    /** Destination transaction hash — present once delivered */
+    dstTxHash?: string;
+    /** Seconds since the source transaction was mined */
+    elapsedSeconds?: number;
+    /** Human-facing tracking page */
+    scanUrl: string;
+}
+/**
+ * Bridge route selection:
+ * - `"usdt0"` — force the USDT0 LayerZero OFT path (no protocol fee, just gas + LZ
+ *   messaging fee; slower). Throws if the chain pair has no USDT0 adapter.
+ * - `"lifi"` — force the LI.FI aggregator path (fast, charges a fee).
+ * - `"auto"` — use USDT0 when both chains support it and tokens match, else LI.FI.
+ *   This is the default.
+ */
+type BridgeRoute = "auto" | "usdt0" | "lifi";
 interface BridgeParams {
     fromChain: Chain;
     toChain: Chain;
@@ -108,6 +178,11 @@ interface BridgeParams {
     fromDecimals?: number;
     /** Recipient address — defaults to the signer */
     recipient?: string;
+    /**
+     * Which bridge to use. Defaults to "auto" (USDT0 OFT when available, else LI.FI).
+     * See {@link BridgeRoute}.
+     */
+    route?: BridgeRoute;
     /** Pre-fetched quote from quoteBridge() — skips the quote fetch when passed to bridge() */
     quote?: BridgeQuote;
 }
@@ -340,8 +415,22 @@ interface StableClient {
     transfer(params: TransferParams): Promise<OperationResult>;
     quoteBridge(params: BridgeParams): Promise<BridgeQuote>;
     bridge(params: BridgeParams): Promise<OperationResult>;
+    /**
+     * Expected delivery time for a USDT0 (LayerZero OFT) bridge, before sending.
+     * Throws for chain pairs with no USDT0 adapter — LI.FI carries its own ETA.
+     */
+    estimateBridgeTime(params: Pick<BridgeParams, "fromChain" | "toChain">): Promise<BridgeTimeEstimate>;
+    /** Delivery status of an in-flight USDT0 bridge, by source transaction hash. */
+    trackBridge(srcTxHash: string): Promise<BridgeStatus>;
     quoteSwap(params: SwapParams): Promise<SwapQuote>;
     swap(params: SwapParams): Promise<OperationResult>;
+    /**
+     * ERC-3009 gasless transfers ("Transfer With Authorization"). Sign a portable
+     * authorization the payer can hand off, then have anyone (a relayer, the
+     * recipient, or the enterprise gas-waiver rail) settle it on-chain. See
+     * {@link erc3009Actions} for the individual viem-style actions.
+     */
+    authorization: ReturnType<typeof erc3009Actions>;
     earn: {
         deposit(params: EarnDepositParams): Promise<EarnResult>;
         bulkDeposit(items: EarnDepositParams[], options?: BulkDepositOptions): Promise<BulkEarnResult>;
@@ -395,6 +484,22 @@ interface ChainConfig {
 }
 declare const CHAIN_CONFIGS: Partial<Record<Chain, ChainConfig>>;
 
+interface BridgeChainConfig extends ChainConfig {
+    lzEid: number;
+    /** Only set on source chains that have an OFT Adapter deployed */
+    oftAdapter?: Address;
+    /** False when the OFT adapter exists but has no outbound send pathways configured */
+    lzOutbound?: boolean;
+    /**
+     * Average seconds per block, used to turn LayerZero's block-confirmation
+     * requirement into a wall-clock estimate. Measured from mainnet, 2026-07-30.
+     */
+    blockTimeSec?: number;
+}
+declare const BRIDGE_CHAIN_CONFIGS: Partial<Record<Chain, BridgeChainConfig>>;
+/** Drop cached pathway configs and observed timings — forces the next estimate to refetch. */
+declare function clearBridgeEstimateCache(): void;
+
 declare const STABLE_USDT_ADDRESS: Address;
 declare const STABLE_VAULT_ADDRESS: Address;
 
@@ -422,12 +527,12 @@ declare class StableQuoteError extends StableError {
     });
 }
 declare class StableTransactionError extends StableError {
-    phase: "approve" | "send" | "receipt" | "switch_chain";
+    phase: "approve" | "send" | "receipt" | "switch_chain" | "sign";
     txHash?: `0x${string}`;
     chainId?: number;
     revertReason?: string;
     constructor(args: {
-        phase: "approve" | "send" | "receipt" | "switch_chain";
+        phase: "approve" | "send" | "receipt" | "switch_chain" | "sign";
         shortMessage: string;
         txHash?: `0x${string}`;
         chainId?: number;
@@ -455,4 +560,4 @@ declare class StableBulkError extends StableError {
     });
 }
 
-export { type BridgeParams, type BridgeQuote, type BulkDepositOptions, type BulkEarnResult, type BulkEarnResultItem, type BulkWithdrawOptions, CHAIN_CONFIGS, Chain, type ChainConfig, type EarnConfig, type EarnDepositCalldata, type EarnDepositParams, type EarnRedeemParams, type EarnResult, type EarnWithdrawCalldata, type EarnWithdrawParams, type ForceDeallocation, type ForceRedeemParams, type ForceWithdrawParams, type MerklClaimCalldata, type MerklClaimResult, type MerklReward, type MerklRewardToken, type MerklRewardsResult, Network, type OperationResult, STABLE_USDT_ADDRESS, STABLE_VAULT_ADDRESS, StableBulkError, type StableClient, type StableConfig, StableError, StableNetworkError, StableQuoteError, type StableReader, type StableReaderConfig, StableTransactionError, StableValidationError, type SwapParams, type SwapQuote, type TransferParams, type VaultPosition, type VaultYield, type VaultYieldReward, type WithdrawStatus, type YieldPreview, createStable, createStableReader };
+export { BRIDGE_CHAIN_CONFIGS, type BridgeChainConfig, type BridgeDeliveryState, type BridgeParams, type BridgeQuote, type BridgeRoute, type BridgeStatus, type BridgeTimeEstimate, type BulkDepositOptions, type BulkEarnResult, type BulkEarnResultItem, type BulkWithdrawOptions, CHAIN_CONFIGS, Chain, type ChainConfig, type EarnConfig, type EarnDepositCalldata, type EarnDepositParams, type EarnRedeemParams, type EarnResult, type EarnWithdrawCalldata, type EarnWithdrawParams, type ForceDeallocation, type ForceRedeemParams, type ForceWithdrawParams, type MerklClaimCalldata, type MerklClaimResult, type MerklReward, type MerklRewardToken, type MerklRewardsResult, Network, type OperationResult, STABLE_USDT_ADDRESS, STABLE_VAULT_ADDRESS, StableBulkError, type StableClient, type StableConfig, StableError, StableNetworkError, StableQuoteError, type StableReader, type StableReaderConfig, StableTransactionError, StableValidationError, type SwapParams, type SwapQuote, type TransferParams, type VaultPosition, type VaultYield, type VaultYieldReward, type WithdrawStatus, type YieldPreview, clearBridgeEstimateCache, createStable, createStableReader, erc3009Actions };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { erc3009Actions } from './erc3009.js';
+export { Authorization, AuthorizationUsage, CancelAuthorizationParameters, ERC3009_ABI, Erc3009DomainOverrides, GetAuthorizationStateParameters, GetAuthorizationUsageParameters, PreparedAuthorizationCall, ReceiveWithAuthorizationParameters, SignReceiveAuthorizationParameters, SignTransferAuthorizationParameters, SignedAuthorization, TransferWithAuthorizationParameters, VerifyAuthorizationParameters, VerifyAuthorizationResult, VerifyFailureReason, cancelAuthorization, getAuthorizationState, getAuthorizationUsage, prepareTransferWithAuthorization, receiveWithAuthorization, signReceiveAuthorization, signTransferAuthorization, transferWithAuthorization, verifyAuthorization } from './erc3009.js';
 import { Account, Transport, WalletClient, Address, BaseError } from 'viem';
 
 interface EarnConfig {
@@ -86,7 +88,15 @@ declare enum Chain {
     MegaETH = "megaeth",
     Base = "base",
     BSC = "bsc",
-    HyperEVM = "hyperevm"
+    HyperEVM = "hyperevm",
+    Polygon = "polygon",
+    Plasma = "plasma",
+    Optimism = "optimism",
+    Unichain = "unichain",
+    Sei = "sei",
+    Flare = "flare",
+    XLayer = "xlayer",
+    Rootstock = "rootstock"
 }
 declare enum Network {
     Mainnet = "mainnet",
@@ -95,7 +105,67 @@ declare enum Network {
 interface BridgeQuote {
     /** Estimated output amount on the destination chain */
     toAmount?: number;
+    /** LayerZero native messaging fee (wei) — only present for USDT0→USDT0 (OFT) routes */
+    nativeFee?: bigint;
+    /** LayerZero fee paid in LZ token (wei) — only present for USDT0→USDT0 (OFT) routes */
+    lzTokenFee?: bigint;
+    /**
+     * How long the bridge is expected to take. Only present for USDT0 (OFT) routes,
+     * and omitted if the estimate could not be resolved — never treat it as required.
+     */
+    estimate?: BridgeTimeEstimate;
 }
+/**
+ * Expected end-to-end delivery time for a USDT0 (LayerZero OFT) bridge.
+ *
+ * Almost all of the wait is source-chain finality: the DVNs securing the pathway
+ * refuse to attest until the send transaction is buried under `confirmations`
+ * source blocks. Destination execution is a few blocks on top of that.
+ */
+interface BridgeTimeEstimate {
+    /** Best available estimate, in seconds — prefer this for display */
+    seconds: number;
+    /** Which input produced `seconds` — see {@link BridgeTimeEstimate.observedSeconds} */
+    source: "observed" | "formula";
+    /**
+     * Median delivery time of recent delivered messages on this exact pathway,
+     * from LayerZero Scan. More trustworthy than `formulaSeconds` — notably on
+     * rollup sources, where DVNs wait for L1 finality rather than raw block count.
+     */
+    observedSeconds?: number;
+    /**
+     * LayerZero's documented estimate:
+     * `srcBlockTime × confirmations + dstBlockTime × (2 + dvnCount)`.
+     */
+    formulaSeconds?: number;
+    /** Source-chain block confirmations the DVNs wait for before attesting */
+    confirmations?: number;
+    /** Number of DVNs (required + optional) verifying this pathway */
+    dvnCount?: number;
+}
+/** Delivery state of an in-flight USDT0 bridge, normalized from LayerZero Scan. */
+type BridgeDeliveryState = "pending" | "inflight" | "delivered" | "failed";
+interface BridgeStatus {
+    state: BridgeDeliveryState;
+    /** Raw LayerZero Scan status, e.g. "INFLIGHT" | "DELIVERED" | "FAILED" | "BLOCKED" */
+    raw?: string;
+    srcTxHash: string;
+    /** Destination transaction hash — present once delivered */
+    dstTxHash?: string;
+    /** Seconds since the source transaction was mined */
+    elapsedSeconds?: number;
+    /** Human-facing tracking page */
+    scanUrl: string;
+}
+/**
+ * Bridge route selection:
+ * - `"usdt0"` — force the USDT0 LayerZero OFT path (no protocol fee, just gas + LZ
+ *   messaging fee; slower). Throws if the chain pair has no USDT0 adapter.
+ * - `"lifi"` — force the LI.FI aggregator path (fast, charges a fee).
+ * - `"auto"` — use USDT0 when both chains support it and tokens match, else LI.FI.
+ *   This is the default.
+ */
+type BridgeRoute = "auto" | "usdt0" | "lifi";
 interface BridgeParams {
     fromChain: Chain;
     toChain: Chain;
@@ -108,6 +178,11 @@ interface BridgeParams {
     fromDecimals?: number;
     /** Recipient address — defaults to the signer */
     recipient?: string;
+    /**
+     * Which bridge to use. Defaults to "auto" (USDT0 OFT when available, else LI.FI).
+     * See {@link BridgeRoute}.
+     */
+    route?: BridgeRoute;
     /** Pre-fetched quote from quoteBridge() — skips the quote fetch when passed to bridge() */
     quote?: BridgeQuote;
 }
@@ -340,8 +415,22 @@ interface StableClient {
     transfer(params: TransferParams): Promise<OperationResult>;
     quoteBridge(params: BridgeParams): Promise<BridgeQuote>;
     bridge(params: BridgeParams): Promise<OperationResult>;
+    /**
+     * Expected delivery time for a USDT0 (LayerZero OFT) bridge, before sending.
+     * Throws for chain pairs with no USDT0 adapter — LI.FI carries its own ETA.
+     */
+    estimateBridgeTime(params: Pick<BridgeParams, "fromChain" | "toChain">): Promise<BridgeTimeEstimate>;
+    /** Delivery status of an in-flight USDT0 bridge, by source transaction hash. */
+    trackBridge(srcTxHash: string): Promise<BridgeStatus>;
     quoteSwap(params: SwapParams): Promise<SwapQuote>;
     swap(params: SwapParams): Promise<OperationResult>;
+    /**
+     * ERC-3009 gasless transfers ("Transfer With Authorization"). Sign a portable
+     * authorization the payer can hand off, then have anyone (a relayer, the
+     * recipient, or the enterprise gas-waiver rail) settle it on-chain. See
+     * {@link erc3009Actions} for the individual viem-style actions.
+     */
+    authorization: ReturnType<typeof erc3009Actions>;
     earn: {
         deposit(params: EarnDepositParams): Promise<EarnResult>;
         bulkDeposit(items: EarnDepositParams[], options?: BulkDepositOptions): Promise<BulkEarnResult>;
@@ -395,6 +484,22 @@ interface ChainConfig {
 }
 declare const CHAIN_CONFIGS: Partial<Record<Chain, ChainConfig>>;
 
+interface BridgeChainConfig extends ChainConfig {
+    lzEid: number;
+    /** Only set on source chains that have an OFT Adapter deployed */
+    oftAdapter?: Address;
+    /** False when the OFT adapter exists but has no outbound send pathways configured */
+    lzOutbound?: boolean;
+    /**
+     * Average seconds per block, used to turn LayerZero's block-confirmation
+     * requirement into a wall-clock estimate. Measured from mainnet, 2026-07-30.
+     */
+    blockTimeSec?: number;
+}
+declare const BRIDGE_CHAIN_CONFIGS: Partial<Record<Chain, BridgeChainConfig>>;
+/** Drop cached pathway configs and observed timings — forces the next estimate to refetch. */
+declare function clearBridgeEstimateCache(): void;
+
 declare const STABLE_USDT_ADDRESS: Address;
 declare const STABLE_VAULT_ADDRESS: Address;
 
@@ -422,12 +527,12 @@ declare class StableQuoteError extends StableError {
     });
 }
 declare class StableTransactionError extends StableError {
-    phase: "approve" | "send" | "receipt" | "switch_chain";
+    phase: "approve" | "send" | "receipt" | "switch_chain" | "sign";
     txHash?: `0x${string}`;
     chainId?: number;
     revertReason?: string;
     constructor(args: {
-        phase: "approve" | "send" | "receipt" | "switch_chain";
+        phase: "approve" | "send" | "receipt" | "switch_chain" | "sign";
         shortMessage: string;
         txHash?: `0x${string}`;
         chainId?: number;
@@ -455,4 +560,4 @@ declare class StableBulkError extends StableError {
     });
 }
 
-export { type BridgeParams, type BridgeQuote, type BulkDepositOptions, type BulkEarnResult, type BulkEarnResultItem, type BulkWithdrawOptions, CHAIN_CONFIGS, Chain, type ChainConfig, type EarnConfig, type EarnDepositCalldata, type EarnDepositParams, type EarnRedeemParams, type EarnResult, type EarnWithdrawCalldata, type EarnWithdrawParams, type ForceDeallocation, type ForceRedeemParams, type ForceWithdrawParams, type MerklClaimCalldata, type MerklClaimResult, type MerklReward, type MerklRewardToken, type MerklRewardsResult, Network, type OperationResult, STABLE_USDT_ADDRESS, STABLE_VAULT_ADDRESS, StableBulkError, type StableClient, type StableConfig, StableError, StableNetworkError, StableQuoteError, type StableReader, type StableReaderConfig, StableTransactionError, StableValidationError, type SwapParams, type SwapQuote, type TransferParams, type VaultPosition, type VaultYield, type VaultYieldReward, type WithdrawStatus, type YieldPreview, createStable, createStableReader };
+export { BRIDGE_CHAIN_CONFIGS, type BridgeChainConfig, type BridgeDeliveryState, type BridgeParams, type BridgeQuote, type BridgeRoute, type BridgeStatus, type BridgeTimeEstimate, type BulkDepositOptions, type BulkEarnResult, type BulkEarnResultItem, type BulkWithdrawOptions, CHAIN_CONFIGS, Chain, type ChainConfig, type EarnConfig, type EarnDepositCalldata, type EarnDepositParams, type EarnRedeemParams, type EarnResult, type EarnWithdrawCalldata, type EarnWithdrawParams, type ForceDeallocation, type ForceRedeemParams, type ForceWithdrawParams, type MerklClaimCalldata, type MerklClaimResult, type MerklReward, type MerklRewardToken, type MerklRewardsResult, Network, type OperationResult, STABLE_USDT_ADDRESS, STABLE_VAULT_ADDRESS, StableBulkError, type StableClient, type StableConfig, StableError, StableNetworkError, StableQuoteError, type StableReader, type StableReaderConfig, StableTransactionError, StableValidationError, type SwapParams, type SwapQuote, type TransferParams, type VaultPosition, type VaultYield, type VaultYieldReward, type WithdrawStatus, type YieldPreview, clearBridgeEstimateCache, createStable, createStableReader, erc3009Actions };