@stablechain/sdk 1.0.6 → 1.0.8

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 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';
+import { Account, Transport, WalletClient, Address, Hex, BaseError } from 'viem';
 
 interface EarnConfig {
     /** MetaMorpho V2 vault address */
@@ -11,6 +11,17 @@ interface StableConfig {
     network?: Network;
     /** Optional RPC override — defaults to the public RPC for the selected network */
     rpc?: string;
+    /**
+     * Per-chain RPC overrides for the cross-chain bridge routes, e.g.
+     * `{ [Chain.Ethereum]: "https://..." }`.
+     *
+     * {@link StableConfig.rpc} covers the Stable chain only — transfers, earn and
+     * authorizations. A bridge reads and broadcasts on whichever chain it starts
+     * from, and by default that is this SDK's built-in public endpoint for that
+     * chain. Override the chains you quote on to keep a backend off a shared
+     * rate limit; chains left out keep the public endpoint.
+     */
+    rpcOverrides?: Partial<Record<Chain, string>>;
     /** Server-side signing: pass a viem Account, e.g. privateKeyToAccount("0x...") */
     account?: Account;
     /** Browser-wallet signing: pass a viem Transport, e.g. custom(window.ethereum) */
@@ -118,6 +129,16 @@ interface BridgeQuote {
      * destination native drop, bundled. `quoteSend` returns no breakdown of it.
      */
     nativeFee?: bigint;
+    /**
+     * The messaging fee a send built from this quote will actually carry, in wei:
+     * {@link BridgeQuote.nativeFee} padded by `feeBufferBps`.
+     *
+     * `nativeFee` is the honest quote and the number to show a user. This is the
+     * number to check a native balance against, because it is what leaves the
+     * wallet — the endpoint keeps what the pathway costs at inclusion time and
+     * refunds the rest. Only present for native OFT routes.
+     */
+    nativeFeeMax?: bigint;
     /** LayerZero fee paid in LZ token (wei) — only present for native OFT routes */
     lzTokenFee?: bigint;
     /**
@@ -201,17 +222,23 @@ interface BridgeGasEstimate {
 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.
+     * Which input produced `seconds`. `"formula"` normally; `"floor"` when the
+     * source chain's measured minimum exceeded it (Ethereum, Arbitrum, Polygon,
+     * Bera, Flare); `"observed"` only when the pathway's ULN config could not be read.
+     */
+    source: "formula" | "floor" | "observed";
+    /**
+     * Median delivery time of recent delivered messages on this exact pathway, from
+     * LayerZero Scan. Reported for comparison but no longer preferred: a 50-message
+     * window can reach back months, so it answers from a ULN config the pathway has
+     * since moved off.
      */
     observedSeconds?: number;
     /**
      * LayerZero's documented estimate:
-     * `srcBlockTime × confirmations + dstBlockTime × (2 + dvnCount)`.
+     * `srcBlockTime × confirmations + dstBlockTime × (2 + dvnCount)`. What `seconds`
+     * reports unless the source chain's measured floor is higher.
      */
     formulaSeconds?: number;
     /** Source-chain block confirmations the DVNs wait for before attesting */
@@ -254,7 +281,14 @@ interface BridgeParams {
     /** Destination token contract address */
     toToken: string;
     amount: number;
-    /** Source token decimals (default: 6) */
+    /**
+     * Source token decimals (default: 6). **LI.FI routes only.**
+     *
+     * Native OFT routes parse the amount with the decimals the token has on the
+     * source chain, which the SDK already knows from
+     * {@link BRIDGE_CHAIN_CONFIGS}. Passing a value that disagrees with those
+     * throws rather than silently sending a different amount.
+     */
     fromDecimals?: number;
     /** Recipient address — defaults to the signer */
     recipient?: string;
@@ -280,6 +314,91 @@ interface BridgeParams {
      * drop is part of what `nativeFee` pays for.
      */
     quote?: BridgeQuote;
+    /**
+     * How much to pad the quoted LayerZero messaging fee by when sending, in basis
+     * points (100 = 1%). Defaults to 500 (5%); 0 sends exactly the quoted fee.
+     * Native OFT routes only.
+     *
+     * The fee a send must carry is whatever the pathway costs at the moment it
+     * lands, and `send` demands an exact match: too little reverts, and the
+     * endpoint refunds the excess to the sender. Between the quote and the
+     * signature that number can only have moved, so the buffer trades a refund
+     * round trip for not reverting — and a revert costs the gas either way.
+     */
+    feeBufferBps?: number;
+    /**
+     * Where LayerZero returns messaging fee it did not need — the excess left over
+     * once the endpoint has taken what the pathway actually cost. Defaults to the
+     * sender. Native OFT routes only.
+     */
+    refundAddress?: string;
+}
+/**
+ * A bridge to build but not send — see
+ * {@link StableClient.prepareBridgeCalldata}.
+ */
+interface PrepareBridgeParams extends BridgeParams {
+    /**
+     * The address that will sign and send these transactions. Its allowance is
+     * what decides whether an approval step is needed, and it is the default
+     * recipient and — via {@link BridgeParams.refundAddress} — refund address.
+     */
+    from: string;
+}
+/** One transaction to sign and broadcast, as built by an unsigned-build helper. */
+interface BridgeCalldataStep {
+    /** The chain this must be sent on — always the bridge's source chain */
+    chainId: number;
+    to: string;
+    data: string;
+    /** Native token to attach, in wei: 0 for the approvals, the fee for the send */
+    value: bigint;
+}
+/**
+ * A built, unsigned bridge: the transactions, the quote behind them, and the send
+ * they encode in readable form.
+ */
+interface BridgeCalldata {
+    /**
+     * Transactions to send in order, each confirmed before the next: an allowance
+     * reset and an approve where the pathway needs them, then the OFT `send`.
+     *
+     * Approvals appear only when the source chain's adapter pulls the token with
+     * `transferFrom` and the current allowance is short. A short but non-zero
+     * allowance takes two of them — legacy USDT refuses to overwrite a non-zero
+     * allowance with another non-zero value — which is why this is a list and not
+     * an optional single approval.
+     */
+    steps: BridgeCalldataStep[];
+    /** The source chain every step must be sent on */
+    chainId: number;
+    /** Which OFT mesh this send moves through */
+    asset: "usdt0" | "xaut0";
+    /** The quote these steps were built from, whether supplied or freshly read */
+    quote: BridgeQuote;
+    /**
+     * The `send` step's arguments, decoded — enough to check the calldata against
+     * what was intended without re-deriving the ABI encoding.
+     */
+    send: {
+        /** LayerZero endpoint ID of the destination chain */
+        dstEid: number;
+        /** Recipient address on the destination chain */
+        recipient: string;
+        /** `recipient`, left-padded to the bytes32 the OFT takes */
+        to: string;
+        /** Amount debited on the source chain, in the token's smallest unit */
+        amountLD: bigint;
+        /** Slippage floor: what the adapter quoted it would deliver */
+        minAmountLD: bigint;
+        /** Encoded LayerZero executor options, including any destination native drop */
+        extraOptions: string;
+        /** Messaging fee the send carries as its `value`, buffer included */
+        nativeFee: bigint;
+        lzTokenFee: bigint;
+        /** Where the endpoint returns unused fee */
+        refundAddress: string;
+    };
 }
 interface EarnDepositParams {
     /** Amount of underlying assets to deposit (human-readable) */
@@ -510,6 +629,15 @@ interface StableClient {
     transfer(params: TransferParams): Promise<OperationResult>;
     quoteBridge(params: BridgeParams): Promise<BridgeQuote>;
     bridge(params: BridgeParams): Promise<OperationResult>;
+    /**
+     * Build a bridge's transactions without signing or sending them — for a
+     * backend that quotes, builds and checks while the holder's wallet only signs.
+     *
+     * Native OFT routes only: LI.FI hands back its own transaction request from
+     * its API, so a pair that resolves to LI.FI throws rather than returning
+     * something shaped the same but built elsewhere.
+     */
+    prepareBridgeCalldata(params: PrepareBridgeParams): Promise<BridgeCalldata>;
     /**
      * Expected delivery time for a native OFT (LayerZero) bridge, before sending.
      * Throws for chain pairs with no OFT adapter — LI.FI carries its own ETA.
@@ -570,7 +698,7 @@ interface StableReader {
         };
     };
 }
-declare function createStable({ network, rpc: rpcOverride, account, transport, walletClient, earn: earnConfig, merklApiBase, }: StableConfig): StableClient;
+declare function createStable({ network, rpc: rpcOverride, rpcOverrides, account, transport, walletClient, earn: earnConfig, merklApiBase, }: StableConfig): StableClient;
 declare function createStableReader(config: StableReaderConfig): StableReader;
 
 interface ChainConfig {
@@ -621,6 +749,26 @@ interface BridgeChainConfig extends ChainConfig {
      * requirement into a wall-clock estimate. Measured from mainnet, 2026-07-30.
      */
     blockTimeSec?: number;
+    /**
+     * Floor on delivery time, in seconds, for sends *from* this chain — set only
+     * where the confirmation count is demonstrably not the whole wait.
+     *
+     * Two things sit outside the formula: DVN attestation and destination execution,
+     * a roughly fixed overhead, and on Ethereum and Arbitrum a hold until the send
+     * finalizes on the beacon chain. Where confirmations are high the overhead is lost
+     * in the rounding — Optimism's 1000 and X Layer's 9000 both land within 0.5% of
+     * observed. Where they are low it dominates: Arbitrum's 60 confirmations compute
+     * to ~19s against a real ~18min, Ethereum's 65 to ~13min against ~17min, Polygon's
+     * 32 to ~52s against a real ~70s, Flare's 500 to ~9min against a real ~10min.
+     *
+     * Each figure is taken from deliveries LayerZero Scan held on 2026-08-27, no older
+     * than 45 days — the ceiling of that spread for the two finality-bound chains, so
+     * the estimate errs long, and the median for the rest. Flare's is a median across
+     * its destinations rather than one pathway's, since the hub pathway alone had only
+     * six recent sends to go on; those settled at ~9m30s and the busier pathways to
+     * Ethereum, Arbitrum, Plasma, Polygon and Optimism between ~9m20s and ~10m10s.
+     */
+    minDeliverySec?: number;
 }
 declare const BRIDGE_CHAIN_CONFIGS: Partial<Record<Chain, BridgeChainConfig>>;
 /**
@@ -628,8 +776,170 @@ declare const BRIDGE_CHAIN_CONFIGS: Partial<Record<Chain, BridgeChainConfig>>;
  * chain has no OFT deployment matching it.
  */
 declare function bridgeAssetFor(cfg: BridgeChainConfig, token: string): BridgeAsset | undefined;
+declare const OFT_ADAPTER_ABI: readonly [{
+    readonly name: "quoteSend";
+    readonly type: "function";
+    readonly inputs: readonly [{
+        readonly name: "_sendParam";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "dstEid";
+            readonly type: "uint32";
+        }, {
+            readonly name: "to";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "amountLD";
+            readonly type: "uint256";
+        }, {
+            readonly name: "minAmountLD";
+            readonly type: "uint256";
+        }, {
+            readonly name: "extraOptions";
+            readonly type: "bytes";
+        }, {
+            readonly name: "composeMsg";
+            readonly type: "bytes";
+        }, {
+            readonly name: "oftCmd";
+            readonly type: "bytes";
+        }];
+    }, {
+        readonly name: "_payInLzToken";
+        readonly type: "bool";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "msgFee";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "nativeFee";
+            readonly type: "uint256";
+        }, {
+            readonly name: "lzTokenFee";
+            readonly type: "uint256";
+        }];
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly name: "quoteOFT";
+    readonly type: "function";
+    readonly inputs: readonly [{
+        readonly name: "_sendParam";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "dstEid";
+            readonly type: "uint32";
+        }, {
+            readonly name: "to";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "amountLD";
+            readonly type: "uint256";
+        }, {
+            readonly name: "minAmountLD";
+            readonly type: "uint256";
+        }, {
+            readonly name: "extraOptions";
+            readonly type: "bytes";
+        }, {
+            readonly name: "composeMsg";
+            readonly type: "bytes";
+        }, {
+            readonly name: "oftCmd";
+            readonly type: "bytes";
+        }];
+    }];
+    readonly outputs: readonly [{
+        readonly name: "oftLimit";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "minAmountLD";
+            readonly type: "uint256";
+        }, {
+            readonly name: "maxAmountLD";
+            readonly type: "uint256";
+        }];
+    }, {
+        readonly name: "oftFeeDetails";
+        readonly type: "tuple[]";
+        readonly components: readonly [{
+            readonly name: "feeAmountLD";
+            readonly type: "int256";
+        }, {
+            readonly name: "description";
+            readonly type: "string";
+        }];
+    }, {
+        readonly name: "oftReceipt";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "amountSentLD";
+            readonly type: "uint256";
+        }, {
+            readonly name: "amountReceivedLD";
+            readonly type: "uint256";
+        }];
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly name: "send";
+    readonly type: "function";
+    readonly inputs: readonly [{
+        readonly name: "_sendParam";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "dstEid";
+            readonly type: "uint32";
+        }, {
+            readonly name: "to";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "amountLD";
+            readonly type: "uint256";
+        }, {
+            readonly name: "minAmountLD";
+            readonly type: "uint256";
+        }, {
+            readonly name: "extraOptions";
+            readonly type: "bytes";
+        }, {
+            readonly name: "composeMsg";
+            readonly type: "bytes";
+        }, {
+            readonly name: "oftCmd";
+            readonly type: "bytes";
+        }];
+    }, {
+        readonly name: "_fee";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "nativeFee";
+            readonly type: "uint256";
+        }, {
+            readonly name: "lzTokenFee";
+            readonly type: "uint256";
+        }];
+    }, {
+        readonly name: "_refundAddress";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "payable";
+}];
 /** Drop cached pathway configs and observed timings — forces the next estimate to refetch. */
 declare function clearBridgeEstimateCache(): void;
+/**
+ * Encode LayerZero V2 executor options.
+ *
+ * `gasLimit = 0` tells the executor to use its built-in minimum for lzReceive —
+ * matches the Stable bridge tutorial, and is what every plain token transfer wants.
+ *
+ * A non-zero `nativeDrop` appends the executor's native-drop option: that many wei
+ * of the *destination* chain's native token, airdropped to `dropReceiver` when the
+ * message is executed. The executor prices it into `quoteSend`'s `nativeFee`, and
+ * rejects a drop above the pathway's configured `nativeCap`.
+ */
+declare function buildLzOptions(gasLimit?: bigint, nativeDrop?: bigint, dropReceiver?: Address): Hex;
 
 declare const STABLE_USDT_ADDRESS: Address;
 declare const STABLE_VAULT_ADDRESS: Address;
@@ -691,4 +1001,4 @@ declare class StableBulkError extends StableError {
     });
 }
 
-export { BRIDGE_CHAIN_CONFIGS, type BridgeAsset, type BridgeChainConfig, type BridgeDeliveryState, type BridgeGasEstimate, type BridgeOftFee, type BridgeOftQuote, type BridgeParams, type BridgeQuote, type BridgeRoute, type BridgeStatus, type BridgeTimeEstimate, type BridgeTokenConfig, 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, bridgeAssetFor, clearBridgeEstimateCache, createStable, createStableReader, erc3009Actions };
+export { BRIDGE_CHAIN_CONFIGS, type BridgeAsset, type BridgeCalldata, type BridgeCalldataStep, type BridgeChainConfig, type BridgeDeliveryState, type BridgeGasEstimate, type BridgeOftFee, type BridgeOftQuote, type BridgeParams, type BridgeQuote, type BridgeRoute, type BridgeStatus, type BridgeTimeEstimate, type BridgeTokenConfig, 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, OFT_ADAPTER_ABI, type OperationResult, type PrepareBridgeParams, 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, bridgeAssetFor, buildLzOptions, clearBridgeEstimateCache, createStable, createStableReader, erc3009Actions };