@stablechain/sdk 1.0.5 → 1.0.6

package/README.md

@@ -79,7 +79,7 @@ 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>;
+  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 +170,65 @@ 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), paid as the `send` call's `value`               |
+| `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.
+
 ---
 
 ### `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 (and skips it where the OFT does not need one). Switches the wallet to
+the source chain (MetaMask will prompt) before sending.
 
 ```ts
 import { Chain } from "@stablechain/sdk";
@@ -206,17 +251,80 @@ const { txHash, toAmount } = await stable.bridge({
 | `amount`       | `number`      | Amount to bridge (human-readable)                                        |
 | `fromDecimals` | `number`      | *(optional)* Source token decimals — defaults to `6`                     |
 | `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 |
+| `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.
 
 ---
 
+### 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 +335,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 +394,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