@stablechain/sdk 1.0.5 → 1.0.7

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,7 +80,8 @@ interface StableClient {
   transfer(params: TransferParams): Promise<OperationResult>;
   quoteBridge(params: BridgeParams): Promise<BridgeQuote>;
   bridge(params: BridgeParams): Promise<OperationResult>;
-  estimateBridgeTime(params: Pick<BridgeParams, "fromChain" | "toChain">): Promise<BridgeTimeEstimate>;
+  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>;
   swap(params: SwapParams): Promise<OperationResult>;
@@ -170,20 +172,93 @@ console.log("You receive:", quote.toAmount); // human units, on toChain
 
 `BridgeQuote.toAmount` is the expected destination-side amount in human units.
 
-On USDT0 (LayerZero OFT) routes the quote also carries `estimate` — how long delivery
-should take. See [`estimateBridgeTime`](#estimatebridgetimeparams--bridgetimeestimate).
+On native OFT routes the quote is fully costed — `toAmount` comes from the adapter's
+own `quoteOFT`, so it is the amount that actually lands, net of any OFT fee and of
+dust dropped by decimal conversion:
+
+| Field          | Type                | What it is                                                                    |
+|----------------|---------------------|-------------------------------------------------------------------------------|
+| `toAmount`     | `number`            | What the recipient receives, human units                                      |
+| `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`         |
+| `totalCostWei` | `bigint`            | `srcGas.costWei + nativeFee` — everything leaving the sender's native balance  |
+| `estimate`     | `BridgeTimeEstimate`| Delivery time — see [`estimateBridgeTime`](#estimatebridgetimeparams--bridgetimeestimate) |
 
 ```ts
+import { formatEther } from "viem";
+
+console.log("You receive:", quote.toAmount);
+for (const fee of quote.oft?.fees ?? []) {
+  // Empty on every pathway the SDK configures today; a deployment that charges an
+  // OFT-level fee reports it here. Negative means a credit to the sender.
+  console.log(`${fee.description}: ${fee.amount}`);
+}
+if (quote.totalCostWei) {
+  console.log(`Costs ${formatEther(quote.totalCostWei)} of native token to send`);
+}
 if (quote.estimate) {
   console.log(`Arrives in ~${Math.round(quote.estimate.seconds / 60)} min`);
 }
 ```
 
+`srcGas.source` says how much to trust the cost: `"simulated"` means the real `send`
+was simulated, `"fallback"` means the simulation reverted — which is what happens when
+you quote before approving the adapter — and `gas` is a typical-send constant instead.
+Every field above is absent on LI.FI routes, and `oft`/`srcGas` are also absent when
+the adapter or the RPC would not answer, so treat them as optional rather than assuming
+a native route populates them.
+
+Both `quoteBridge()` and `bridge()` accept `dstNativeDrop` — wei of the **destination**
+chain's native token to airdrop to the recipient, what bridge UIs call *gas on
+destination*. The executor prices it into `nativeFee`, so quote with the same value you
+send with:
+
+```ts
+const quote = await stable.quoteBridge({ ...params, dstNativeDrop: 10n ** 14n });
+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 via LI.FI. Handles ERC-20 approval automatically. Switches the wallet to the source chain (MetaMask will prompt) before sending.
+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. 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";
@@ -204,19 +279,155 @@ 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                |
-| `quote`        | `BridgeQuote` | *(optional)* Reserved for future use; the current implementation re-fetches a LI.FI quote regardless |
+| `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) |
 
 `txHash` is the **source-chain** transaction hash. Destination delivery is asynchronous —
 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:
+
+| Route    | What it is                          | Cost                            | Speed  |
+|----------|-------------------------------------|---------------------------------|--------|
+| `"oft"`  | The token's native LayerZero OFT    | No protocol fee — gas + LZ messaging fee | Slower |
+| `"lifi"` | The [LI.FI](https://li.fi) aggregator | Charges a fee                 | Fast   |
+
+`route` defaults to `"auto"`: the OFT path when both chains deploy the asset the token
+addresses name, LI.FI otherwise. Forcing `"oft"` on an unsupported pair throws
+`StableValidationError` rather than silently charging a LI.FI fee.
+
+> `route: "usdt0"` is a deprecated alias for `"oft"`. It does not restrict the route to
+> USDT0 — the token addresses decide the asset.
+
+#### Native OFT assets
+
+Two assets have their own OFT mesh, each with its own adapter and token address per
+chain. A bridge stays within one mesh: the OFT mints its own peer on the far side, so it
+cannot hand back a different token. A cross-asset request (USDT0 in, XAUt0 out) is a
+trade, not a bridge, and `"auto"` sends it to LI.FI.
+
+**USDT0** — Stable, Ethereum, Arbitrum, Bera, Flare, HyperEVM, Ink, MegaETH, Optimism,
+Plasma, Polygon, Rootstock, Sei, Unichain, XLayer.
+
+**XAUt0** (Tether Gold, 6 decimals) — Stable, Ethereum, Arbitrum, BSC, HyperEVM, Ink,
+Plasma, Polygon. Every pair among those eight is wired in both directions.
+
+```ts
+// XAUt0: Ethereum → Stable, over the native OFT mesh
+const { txHash } = await stable.bridge({
+  fromChain: Chain.Ethereum,
+  toChain: Chain.Stable,
+  fromToken: "0x68749665FF8D2d112Fa859AA293F07A622782F38", // XAUt on Ethereum
+  toToken:   "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb", // XAUt0 on Stable
+  amount: 2, // 2 XAUt0
+});
+```
+
+Ethereum is XAUt0's lockbox — canonical XAUt is escrowed there and minted elsewhere, so
+it is the only chain where a send needs an ERC-20 approve. Bridging XAUt0 from any other
+chain burns from the caller and skips the approval transaction entirely.
+
+BSC is XAUt0-only: it has no USDT0 deployment, so a BSC USDT bridge routes to LI.FI.
+
+Addresses per chain are in `BRIDGE_CHAIN_CONFIGS[chain].tokens`, keyed by asset:
+
+```ts
+import { BRIDGE_CHAIN_CONFIGS, bridgeAssetFor, Chain } from "@stablechain/sdk";
+
+const stableChain = BRIDGE_CHAIN_CONFIGS[Chain.Stable];
+stableChain.tokens.xaut0?.address;    // XAUt0 ERC-20 on Stable
+stableChain.tokens.xaut0?.oftAdapter; // its OFT
+
+// Which asset an address refers to on a chain, if any
+bridgeAssetFor(stableChain, someToken); // "usdt0" | "xaut0" | undefined
+```
+
+---
+
 ### `estimateBridgeTime(params)` → `BridgeTimeEstimate`
 
-How long a **USDT0 (LayerZero OFT)** bridge will take, before you send it. Throws for
-chain pairs with no USDT0 adapter — LI.FI routes carry their own ETA in the quote.
+How long a **native OFT (LayerZero)** bridge will take, before you send it. Throws for
+chain pairs with no OFT adapter — LI.FI routes carry their own ETA in the quote.
 
 ```ts
 const est = await stable.estimateBridgeTime({
@@ -227,6 +438,19 @@ const est = await stable.estimateBridgeTime({
 console.log(`~${Math.round(est.seconds / 60)} min`); // ~42 min
 ```
 
+Delivery time is per pathway, and USDT0 and XAUt0 are different pathways on the same
+chain pair. Omitting the tokens estimates the USDT0 pathway; pass `fromToken`/`toToken`
+to estimate a specific asset:
+
+```ts
+const est = await stable.estimateBridgeTime({
+  fromChain: Chain.Ethereum,
+  toChain: Chain.Stable,
+  fromToken: "0x68749665FF8D2d112Fa859AA293F07A622782F38", // XAUt on Ethereum
+  toToken:   "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb", // XAUt0 on Stable
+});
+```
+
 Nearly all of the wait is **source-chain finality**: the DVNs securing the pathway will
 not attest until the send transaction is buried under `confirmations` source blocks.
 Destination execution is a few blocks on top.
@@ -273,7 +497,7 @@ Roughly what to expect on mainnet, measured 2026-07-30:
 
 ### `trackBridge(srcTxHash)` → `BridgeStatus`
 
-Follow an in-flight USDT0 bridge, via LayerZero Scan. A message Scan has not indexed yet
+Follow an in-flight native OFT bridge, via LayerZero Scan. A message Scan has not indexed yet
 reports `"pending"` rather than throwing, so it is safe to call immediately after `bridge()`.
 
 ```ts