@stablechain/sdk 1.0.6 → 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,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: