@stablechain/sdk 1.0.6 → 1.0.8

package/README.md

@@ -64,6 +64,7 @@ const stable = createStable({
 |-----------------|----------------|----------------------------------------------------------------------|
 | `network`       | `Network`      | `Network.Mainnet` (default) or `Network.Testnet`                     |
 | `rpc`           | `string`       | *(optional)* RPC override for the Stable chain                       |
+| `rpcOverrides`  | `Partial<Record<Chain, string>>` | *(optional)* Per-chain RPC endpoints for the bridge routes, e.g. `{ [Chain.Ethereum]: "https://..." }`. `rpc` covers the Stable chain only; a bridge reads and broadcasts on whichever chain it starts from, and defaults to this SDK's built-in public endpoint there |
 | `account`       | `Account`      | *(optional)* viem `Account` for server-side signing                  |
 | `transport`     | `Transport`    | *(optional)* viem `Transport` (e.g. `custom(window.ethereum)`)       |
 | `walletClient`  | `WalletClient` | *(optional)* Pre-built viem `WalletClient` — takes precedence        |
@@ -79,6 +80,7 @@ interface StableClient {
   transfer(params: TransferParams): Promise<OperationResult>;
   quoteBridge(params: BridgeParams): Promise<BridgeQuote>;
   bridge(params: BridgeParams): Promise<OperationResult>;
+  prepareBridgeCalldata(params: PrepareBridgeParams): Promise<BridgeCalldata>;
   estimateBridgeTime(params: Pick<BridgeParams, "fromChain" | "toChain"> & Partial<Pick<BridgeParams, "fromToken" | "toToken">>): Promise<BridgeTimeEstimate>;
   trackBridge(srcTxHash: string): Promise<BridgeStatus>;
   quoteSwap(params: SwapParams): Promise<SwapQuote>;
@@ -177,7 +179,8 @@ dust dropped by decimal conversion:
 | Field          | Type                | What it is                                                                    |
 |----------------|---------------------|-------------------------------------------------------------------------------|
 | `toAmount`     | `number`            | What the recipient receives, human units                                      |
-| `nativeFee`    | `bigint`            | LayerZero messaging fee (wei), paid as the `send` call's `value`               |
+| `nativeFee`    | `bigint`            | LayerZero messaging fee (wei) as quoted — the number to show a user            |
+| `nativeFeeMax` | `bigint`            | What a send built from this quote carries as its `value`: `nativeFee` padded by `feeBufferBps`. Check native balances against this |
 | `lzTokenFee`   | `bigint`            | Same fee if paid in LZ token instead — `0n` on every route the SDK sends       |
 | `oft`          | `BridgeOftQuote`    | The adapter's own accounting: `amountSentLD`, `amountReceivedLD`, `fees[]`, and the pathway's `minAmountLD`/`maxAmountLD` |
 | `srcGas`       | `BridgeGasEstimate` | Source-chain execution cost: `gas`, `gasPriceWei`, `costWei`, `source`         |
@@ -221,14 +224,41 @@ await stable.bridge({ ...params, dstNativeDrop: 10n ** 14n, quote });
 Each pathway's executor caps the drop it will accept; asking for more makes the quote
 throw `StableQuoteError` rather than silently clamping.
 
+#### The messaging fee is padded before sending
+
+A send has to carry the fee the pathway costs **at the moment it lands**, and `send`
+demands an exact match: `msg.value` must equal `_fee.nativeFee`, the endpoint reverts
+with `LZ_InsufficientFee` when that falls short of what it needs, and refunds the
+excess to the sender when it does not. Gas moves between a quote and a signature, and
+only one direction of that costs anything — a fee that rose reverts the send with the
+gas already spent, while a fee that was padded comes back.
+
+So `bridge()` and `prepareBridgeCalldata()` send `nativeFee` padded by `feeBufferBps`,
+5% by default:
+
+```ts
+await stable.bridge({ ...params, feeBufferBps: 1_000 }); // 10%
+await stable.bridge({ ...params, feeBufferBps: 0 });     // exactly the quoted fee
+```
+
+`quoteBridge()` reports both numbers and pads neither: `nativeFee` is the honest quote
+to display, `nativeFeeMax` is what will actually leave the wallet.
+
 ---
 
 ### `bridge(params)`
 
 Bridge tokens cross-chain, over the native LayerZero OFT mesh where the pair supports
 it and LI.FI otherwise — see [Bridge routes](#bridge-routes). Handles ERC-20 approval
-automatically (and skips it where the OFT does not need one). Switches the wallet to
-the source chain (MetaMask will prompt) before sending.
+automatically. Switches the wallet to the source chain (MetaMask will prompt) before
+sending.
+
+Only a lockbox pathway needs an allowance at all — Ethereum for USDT0 and XAUt0, and
+Sepolia on testnet. Every other deployment is an OFT that burns from the caller, so no
+approve and no allowance read is issued there. Where one is needed and the current
+allowance is short but not zero, it takes **two** approvals: legacy USDT refuses to
+overwrite a non-zero allowance with another non-zero value, so the SDK sends
+`approve(0)` first.
 
 ```ts
 import { Chain } from "@stablechain/sdk";
@@ -249,9 +279,11 @@ const { txHash, toAmount } = await stable.bridge({
 | `fromToken`    | `string`      | Source token contract address                                            |
 | `toToken`      | `string`      | Destination token contract address                                       |
 | `amount`       | `number`      | Amount to bridge (human-readable)                                        |
-| `fromDecimals` | `number`      | *(optional)* Source token decimals — defaults to `6`                     |
+| `fromDecimals` | `number`      | *(optional)* Source token decimals — defaults to `6`. **LI.FI routes only:** native OFT routes parse the amount with the decimals the token has on the source chain, and a value disagreeing with those throws |
 | `recipient`    | `string`      | *(optional)* Destination address — defaults to the signer                |
 | `dstNativeDrop`| `bigint`      | *(optional)* Destination native token (wei) to airdrop to the recipient — native OFT routes only |
+| `feeBufferBps` | `number`      | *(optional)* Padding on the quoted messaging fee, in basis points — defaults to `500` (5%). Native OFT routes only |
+| `refundAddress`| `string`      | *(optional)* Where LayerZero returns messaging fee it did not need — defaults to the sender. Native OFT routes only |
 | `quote`        | `BridgeQuote` | *(optional)* On native OFT routes, a quote from `quoteBridge()` is reused as-is: it supplies the messaging fee and the slippage floor, skipping two reads. LI.FI routes re-fetch regardless |
 | `route`        | `BridgeRoute` | *(optional)* `"auto"` (default), `"oft"`, or `"lifi"` — see [Bridge routes](#bridge-routes) |
 
@@ -260,6 +292,77 @@ poll [`trackBridge(txHash)`](#trackbridgesrctxhash--bridgestatus) to follow it.
 
 ---
 
+### `prepareBridgeCalldata(params)` → `BridgeCalldata`
+
+Build a bridge's transactions without signing or sending any of them — for the split
+where a backend quotes, builds and checks while the holder's wallet only signs. Native
+OFT routes only: a pair that resolves to LI.FI throws, because LI.FI hands back its own
+transaction request from its API.
+
+```ts
+import { Chain } from "@stablechain/sdk";
+
+const built = await stable.prepareBridgeCalldata({
+  from: "0xUserWallet",          // whose allowance decides the approvals
+  fromChain: Chain.Ethereum,
+  toChain: Chain.Stable,
+  fromToken: "0xdAC17F958D2ee523a2206206994597C13D831ec7",
+  toToken:   "0x779Ded0c9e1022225f8E0630b35a9b54bE713736",
+  amount: 100,
+});
+
+for (const step of built.steps) {
+  // Send in order, each confirmed before the next.
+  await walletClient.sendTransaction(step);
+}
+```
+
+Takes everything [`bridge()`](#bridgeparams) does, plus:
+
+| Param           | Type     | Description                                                                       |
+|-----------------|----------|-----------------------------------------------------------------------------------|
+| `from`          | `string` | The address that will sign these transactions. Its allowance decides whether an approval step is needed, and it is the default recipient and refund address |
+
+`steps` is ordered and must be sent in order, each confirmed before the next:
+
+| Step        | When                                                                                  |
+|-------------|---------------------------------------------------------------------------------------|
+| `approve(0)`| The pathway needs an allowance, and the current one is short **but not zero** — legacy USDT refuses to overwrite a non-zero allowance with another non-zero value |
+| `approve(n)`| The pathway needs an allowance and the current one is short                            |
+| `send`      | Always. Carries the buffered messaging fee as its `value`                              |
+
+Each step is `{ chainId, to, data, value }`, and `chainId` is the source chain on every
+one of them. Alongside them:
+
+| Field     | Type            | What it is                                                          |
+|-----------|-----------------|---------------------------------------------------------------------|
+| `chainId` | `number`        | The source chain every step must be sent on                         |
+| `asset`   | `"usdt0" \| "xaut0"` | Which OFT mesh this send moves through                        |
+| `quote`   | `BridgeQuote`   | The quote the steps were built from — supplied or freshly read        |
+| `send`    | `object`        | The `send` step's arguments decoded: `dstEid`, `recipient`, `to`, `amountLD`, `minAmountLD`, `extraOptions`, `nativeFee`, `lzTokenFee`, `refundAddress` |
+
+`send` is there so a backend can check what it built without re-deriving the ABI
+encoding — and `OFT_ADAPTER_ABI` and `buildLzOptions` are exported for the checks that
+do want the encoding:
+
+```ts
+import { OFT_ADAPTER_ABI } from "@stablechain/sdk";
+import { decodeFunctionData } from "viem";
+
+const { args } = decodeFunctionData({
+  abi: OFT_ADAPTER_ABI,
+  data: built.steps.at(-1)!.data as `0x${string}`,
+});
+```
+
+This refuses to build when the adapter will not answer `quoteOFT`: its receipt is what
+floors the send at the amount it would actually deliver, and there is no safe stand-in
+for that floor — the full input amount reverts with `SlippageExceeded` on any pathway
+that charges a fee. `quoteBridge()` still degrades to a fee-only quote in that case;
+only the paths that build a send refuse.
+
+---
+
 ### Bridge routes
 
 `bridge()` and `quoteBridge()` pick between two paths:
@@ -352,44 +455,57 @@ Nearly all of the wait is **source-chain finality**: the DVNs securing the pathw
 not attest until the send transaction is buried under `confirmations` source blocks.
 Destination execution is a few blocks on top.
 
-The SDK resolves this from two independent inputs and reports both:
+`estimateBridgeTime` reports that breakdown:
 
 | Field             | Meaning                                                                                          |
 |-------------------|--------------------------------------------------------------------------------------------------|
-| `seconds`         | Best available estimate — display this                                                            |
-| `source`          | `"observed"` or `"formula"`, whichever produced `seconds`                                          |
+| `seconds`         | The estimate — display this                                                                       |
+| `source`          | `"formula"`, `"floor"`, or `"observed"` — which input produced `seconds`                           |
 | `observedSeconds` | Median delivery time of recent messages on this exact pathway, from LayerZero Scan                 |
 | `formulaSeconds`  | LayerZero's documented estimate: `srcBlockTime × confirmations + dstBlockTime × (2 + dvnCount)`     |
 | `confirmations`   | Source blocks the DVNs wait for, read live from the pathway's ULN config                           |
 | `dvnCount`        | DVNs verifying the pathway                                                                        |
 
-`observed` wins when available. The formula assumes block confirmations are the whole
-wait, which holds for L1 sources but understates rollups badly — Arbitrum→Stable computes
-to ~19 s (60 blocks × 0.25 s) against a real median of ~18 min, because the DVNs wait for
-the L2 batch to finalize on Ethereum.
+`seconds` comes from the formula — the pathway's live ULN config is what the DVNs are
+actually bound by, so a config change is reflected the moment it lands. On every pathway
+that is purely confirmation-bound it agrees with both usdt0.to's own estimate and the
+delivery times LayerZero Scan reports to well under a percent.
+
+Some source chains carry a floor. DVN attestation and destination execution sit outside the
+formula, and on Ethereum and Arbitrum the DVNs additionally hold until the send finalizes on
+the beacon chain. Where confirmations are high that overhead vanishes into the rounding;
+where they are low it dominates — Arbitrum's 60 confirmations compute to ~19 s against a real
+~18 min. Those chains are floored at a measured minimum, and `source` reports `"floor"`.
+
+`observedSeconds` is fetched alongside and reported for comparison, but does not drive
+`seconds`: a 50-message window can reach back months, so on a pathway that has been
+reconfigured or has gone quiet it answers from a config that no longer exists.
 
 Pathway configs and observed medians are cached for 5 minutes; call
 `clearBridgeEstimateCache()` to force a refetch.
 
-Roughly what to expect on mainnet, measured 2026-07-30:
+Roughly what to expect on mainnet, from configs read 2026-08-27:
 
 | Pathway             | Confirmations | Typical delivery |
 |---------------------|---------------|------------------|
-| Polygon → Stable    | 32            | ~1 min           |
-| Bera → Stable       | 60            | ~2 min           |
-| Unichain → Stable   | 1600          | ~8 min           |
-| Flare → Stable      | 500           | ~11 min          |
-| Optimism → Stable   | 1000          | ~15 min          |
-| Ethereum → Stable   | 65            | ~17 min          |
+| Polygon → Stable    | 32            | ~1 min ᶠ         |
+| Bera → Stable       | 60            | ~2 min ᶠ         |
+| Flare → Stable      | 500           | ~10 min ᶠ        |
 | Sei → Stable        | 2000          | ~17 min          |
-| Arbitrum → Stable   | 60            | ~18 min          |
+| Ethereum → Stable   | 65            | ~19.5 min ᶠ      |
+| Arbitrum → Stable   | 60            | ~22.5 min ᶠ      |
+| Unichain → Stable   | 1600          | ~27 min          |
 | Plasma → Stable     | 1800          | ~30 min          |
+| Optimism → Stable   | 1000          | ~33 min          |
 | Stable → any        | 3600          | ~42 min          |
 | Rootstock → Stable  | 120           | ~62 min          |
 | MegaETH → Stable    | 5400          | ~90 min          |
 | X Layer → Stable    | 9000          | ~2.5 h           |
 | HyperEVM → Stable   | 43200         | ~12 h            |
 
+ᶠ Floored at the source chain's measured minimum, because its confirmation count is not the
+whole wait — Ethereum and Arbitrum would otherwise compute to ~13 min and ~19 s.
+
 ---
 
 ### `trackBridge(srcTxHash)` → `BridgeStatus`