@stablechain/sdk 1.0.4 → 1.0.6

package/README.md

@@ -0,0 +1,878 @@
+<div align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="../../.github/assets/stable-logotype-light.svg">
+    <img alt="Stable" src="../../.github/assets/stable-logotype-dark.svg" width="96" height="96">
+  </picture>
+
+  <h1>@stablechain/sdk</h1>
+
+  <p><strong>TypeScript SDK for <a href="https://stable.xyz">Stable</a> — a USDT-native EVM blockchain.</strong></p>
+</div>
+
+Transfer, bridge, swap, and earn yield on Stable from a browser wallet or a
+server-side key. For gasless relaying and premium blockspace, see
+[`@stablechain/enterprise`](../enterprise).
+
+## Installation
+
+```bash
+bun add @stablechain/sdk viem
+# or
+npm install @stablechain/sdk viem
+```
+
+`viem` is a peer dependency (>= 2.0.0).
+
+## Quick start
+
+**Server-side (private key):**
+
+```ts
+import { createStable, Network } from "@stablechain/sdk";
+import { privateKeyToAccount } from "viem/accounts";
+
+const stable = createStable({
+  network: Network.Mainnet,
+  account: privateKeyToAccount("0x..."),
+});
+```
+
+**Browser wallet (MetaMask, etc.):**
+
+```ts
+import { createStable, Network } from "@stablechain/sdk";
+import { custom } from "viem";
+
+const stable = createStable({
+  network: Network.Mainnet,
+  transport: custom(window.ethereum),
+});
+```
+
+**Pre-built viem `WalletClient`:**
+
+```ts
+const stable = createStable({
+  network: Network.Mainnet,
+  walletClient: myWalletClient,
+});
+```
+
+### `StableConfig`
+
+| Param           | Type           | Description                                                          |
+|-----------------|----------------|----------------------------------------------------------------------|
+| `network`       | `Network`      | `Network.Mainnet` (default) or `Network.Testnet`                     |
+| `rpc`           | `string`       | *(optional)* RPC override for the Stable chain                       |
+| `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        |
+| `earn`          | `EarnConfig`   | *(optional)* `{ vault: "0x..." }` — required for `stable.earn.*`     |
+| `merklApiBase`  | `string`       | *(optional)* Base URL for the Merkl rewards API — override to proxy through your own server and avoid CORS restrictions in browser environments (default: `https://api.merkl.xyz`) |
+
+---
+
+## API
+
+```ts
+interface StableClient {
+  transfer(params: TransferParams): Promise<OperationResult>;
+  quoteBridge(params: BridgeParams): Promise<BridgeQuote>;
+  bridge(params: BridgeParams): Promise<OperationResult>;
+  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>;
+  authorization: { /* ERC-3009 — see below */ };
+  earn: {
+    deposit(params: EarnDepositParams): Promise<EarnResult>;
+    bulkDeposit(items: EarnDepositParams[], options?: BulkDepositOptions): Promise<BulkEarnResult>;
+    withdraw(params: EarnWithdrawParams): Promise<EarnResult>;
+    bulkWithdraw(items: EarnWithdrawParams[], options?: BulkWithdrawOptions): Promise<BulkEarnResult>;
+    redeem(params: EarnRedeemParams): Promise<EarnResult>;
+    incentiveRewards: {
+      fetch(): Promise<MerklRewardsResult>;
+      claim(): Promise<MerklClaimResult>;
+    };
+  };
+}
+```
+
+All write methods resolve to `OperationResult` or `EarnResult`:
+
+```ts
+interface OperationResult {
+  txHash: string;
+  toAmount?: number; // destination-side amount, when a conversion occurred
+}
+
+interface EarnResult {
+  txHash: string;
+  idempotencyKey?: string;
+}
+```
+
+---
+
+### `transfer(params)`
+
+Send tokens on Stable. Native USDT0 transfers use 18 decimals; ERC-20 decimals are fetched on-chain when not provided.
+
+**Native USDT0**
+
+```ts
+const { txHash } = await stable.transfer({
+  to: "0xRecipient",
+  amount: 10, // 10 USDT0
+});
+```
+
+**ERC-20 (USDC, EURC, …)**
+
+```ts
+const { txHash } = await stable.transfer({
+  to: "0xRecipient",
+  amount: 100,
+  token: "0xUSDCAddress",   // ERC-20 contract address on Stable
+  tokenDecimals: 6,          // optional — fetched on-chain if omitted
+});
+```
+
+| Param           | Type     | Description                                                                       |
+|-----------------|----------|-----------------------------------------------------------------------------------|
+| `to`            | `string` | Recipient address                                                                 |
+| `amount`        | `number` | Amount in human-readable units                                                    |
+| `token`         | `string` | *(optional)* ERC-20 contract address. Omit for native USDT0.                      |
+| `tokenDecimals` | `number` | *(optional)* Token decimals — fetched on-chain if not provided                    |
+| `from`          | `string` | *(optional, advisory)* Sender label. The signer is taken from `walletClient`/`account`; this field does **not** override it. |
+
+`transfer` switches the wallet to the configured Stable network, sends the tx, waits for the receipt, and throws a `StableTransactionError` if it reverts.
+
+---
+
+### `quoteBridge(params)` → `BridgeQuote`
+
+Preview a bridge before sending. Quotes are fetched from [LI.FI](https://li.fi).
+
+```ts
+import { Chain } from "@stablechain/sdk";
+
+const quote = await stable.quoteBridge({
+  fromChain: Chain.Ethereum,
+  toChain: Chain.Stable,
+  fromToken: "0xdAC17F958D2ee523a2206206994597C13D831ec7", // USDT on Ethereum
+  toToken:   "0x779Ded0c9e1022225f8E0630b35a9b54bE713736", // USDT0 on Stable
+  amount: 100,
+});
+
+console.log("You receive:", quote.toAmount); // human units, on toChain
+```
+
+`BridgeQuote.toAmount` is the expected destination-side amount in human units.
+
+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, 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";
+
+const { txHash, toAmount } = await stable.bridge({
+  fromChain: Chain.Ethereum,
+  toChain: Chain.Stable,
+  fromToken: "0xdAC17F958D2ee523a2206206994597C13D831ec7",
+  toToken:   "0x779Ded0c9e1022225f8E0630b35a9b54bE713736",
+  amount: 100,
+});
+```
+
+| Param          | Type          | Description                                                              |
+|----------------|---------------|--------------------------------------------------------------------------|
+| `fromChain`    | `Chain`       | Source chain                                                             |
+| `toChain`      | `Chain`       | Destination chain                                                        |
+| `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`                     |
+| `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 |
+| `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 **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({
+  fromChain: Chain.Stable,
+  toChain: Chain.Arbitrum,
+});
+
+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.
+
+The SDK resolves this from two independent inputs and reports both:
+
+| Field             | Meaning                                                                                          |
+|-------------------|--------------------------------------------------------------------------------------------------|
+| `seconds`         | Best available estimate — display this                                                            |
+| `source`          | `"observed"` or `"formula"`, whichever 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.
+
+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:
+
+| 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          |
+| Sei → Stable        | 2000          | ~17 min          |
+| Arbitrum → Stable   | 60            | ~18 min          |
+| Plasma → Stable     | 1800          | ~30 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            |
+
+---
+
+### `trackBridge(srcTxHash)` → `BridgeStatus`
+
+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
+const { txHash } = await stable.bridge({ /* … */ });
+
+const status = await stable.trackBridge(txHash);
+// { state: "inflight", elapsedSeconds: 1027, scanUrl: "https://layerzeroscan.com/tx/0x…" }
+
+if (status.state === "delivered") console.log("Landed:", status.dstTxHash);
+```
+
+`state` is one of `"pending" | "inflight" | "delivered" | "failed"`. `raw` carries the
+underlying LayerZero Scan status when you need the exact value.
+
+---
+
+### `quoteSwap(params)` → `SwapQuote`
+
+Fetch a LI.FI swap quote on Stable without sending a transaction.
+
+```ts
+const quote = await stable.quoteSwap({
+  fromToken: "0x8a2B28364102Bea189D99A475C494330Ef2bDD0B", // e.g. USDCe
+  toToken:   "0x779Ded0c9e1022225f8E0630b35a9b54bE713736", // USDT0
+  amount: 100,
+  fromDecimals: 6,
+});
+
+console.log("You'll receive:", quote.toAmount, "USDT0");
+```
+
+```ts
+interface SwapQuote {
+  toAmount: number;              // human-readable, formatted with toToken decimals
+  fromAmount: bigint;            // raw source-side amount
+  fromToken: string;             // ERC-20 to approve (or native sentinel)
+  approvalAddress?: string;      // spender for ERC-20 approval (omitted for native)
+  transactionRequest: {
+    to: string;
+    data: string;
+    value: string;
+    gasLimit: string;
+    chainId: number;
+  };
+}
+```
+
+---
+
+### `swap(params)`
+
+Swap tokens on Stable via [LI.FI](https://li.fi). Handles ERC-20 approval automatically; MetaMask is asked to switch to Stable if needed.
+
+Pass a pre-fetched `quote` from `quoteSwap()` to skip the LI.FI quote call.
+
+```ts
+const quote = await stable.quoteSwap({ fromToken, toToken, amount: 100, fromDecimals: 6 });
+const { txHash, toAmount } = await stable.swap({
+  fromToken,
+  toToken,
+  amount: 100,
+  fromDecimals: 6,
+  quote,
+});
+```
+
+| Param          | Type        | Default | Description                                       |
+|----------------|-------------|---------|---------------------------------------------------|
+| `fromToken`    | `string`    |         | Token address on Stable                           |
+| `toToken`      | `string`    |         | Token address on Stable                           |
+| `amount`       | `number`    |         | Human-readable amount                             |
+| `fromDecimals` | `number`    | `6`     | Source token decimals                             |
+| `toAddress`    | `string`    |         | *(optional)* Recipient — defaults to signer       |
+| `quote`        | `SwapQuote` |         | *(optional)* Pre-fetched quote — skips LI.FI call |
+
+---
+
+### `authorization.*` — ERC-3009 gasless transfers
+
+[ERC-3009](https://docs.stable.xyz/en/explanation/erc-3009/) ("Transfer With Authorization") lets a payer **sign** a transfer offline; anyone else **submits** it on-chain later. The payer pays no gas and needn't be the submitter — the primitive behind x402 payments and net-30 invoicing. USDT0 on Stable implements it natively.
+
+The actions are viem-style and fully standalone — 3009 works with **nothing but viem**, no `createStable` and no payment module required. Import the primitives directly, attach them to any viem client via `.extend(erc3009Actions)`, or use the `stable.authorization.*` convenience below.
+
+```ts
+// Isolated subpath — pulls in zero bridge/earn/swap code.
+import { signTransferAuthorization, erc3009Actions } from "@stablechain/sdk/erc3009";
+
+const signed = await signTransferAuthorization(walletClient, { to, value, validBefore });
+// or: const client = walletClient.extend(erc3009Actions);
+```
+
+> This module is a **leaf**: it depends only on viem. Any higher-level payments module is a *consumer* of it, never the reverse — so you can adopt 3009 à la carte.
+
+```ts
+// Payer side — sign offline, hand the result off over HTTP / QR / x402
+const signed = await stable.authorization.signTransferAuthorization({
+  to: "0xVendor",
+  value: 1_250_000n,                              // raw units — 1.25 USDT0 (6 dp)
+  validBefore: BigInt(Math.floor(Date.now() / 1000) + 3600),
+});
+
+// Submitter side — screen it gas-free, then settle (or hand off to a relayer)
+const check = await stable.authorization.verifyAuthorization({ signed });
+if (check.ok) await stable.authorization.transferWithAuthorization({ signed });
+```
+
+| Method                                         | Returns                     | Description                                                                 |
+|------------------------------------------------|-----------------------------|-----------------------------------------------------------------------------|
+| `signTransferAuthorization(p)`                 | `SignedAuthorization`       | Sign a portable `TransferWithAuthorization` (offline, gas-free)             |
+| `signReceiveAuthorization(p)`                  | `SignedAuthorization`       | Same, but only the recipient (`to`) can submit it                           |
+| `transferWithAuthorization(p)`                 | `Hash`                      | Submit a signed (or freshly-signed) authorization — anyone may submit       |
+| `receiveWithAuthorization(p)`                  | `Hash`                      | Submit as the recipient (enforced on-chain via `msg.sender`)                |
+| `cancelAuthorization(p)`                       | `Hash`                      | Revoke an unused nonce (best-effort — can race an in-flight settle)         |
+| `prepareTransferWithAuthorization(p)`          | `PreparedAuthorizationCall` | Sign + return `{ to, data, value, chainId, signed }` for a relayer to submit |
+| `verifyAuthorization(p)`                        | `VerifyAuthorizationResult` | Gas-free preflight: signer, nonce state, time window, solvency, `eth_call`  |
+| `getAuthorizationState(p)`                     | `boolean`                   | `true` once the nonce is used or cancelled                                  |
+| `getAuthorizationUsage(p)`                     | `AuthorizationUsage`        | Resolve the consuming tx from the `AuthorizationUsed` event (no indexer)    |
+
+`value` is a **raw `bigint`** in the token's smallest unit (USDT0 is 6 decimals) — this is the 6-dp ERC-20 path, not the 18-dp native one. `token` defaults to USDT0; `nonce` defaults to a cryptographically-random 32 bytes; the EIP-712 `domain` is read from the token (EIP-5267 `eip712Domain()`, falling back to `name()` + version `"1"`) unless overridden.
+
+To relay gaslessly, pass `prepareTransferWithAuthorization`'s output to the [`@stablechain/enterprise`](../enterprise) gas-waiver rail.
+
+> **Contract signers:** canonical ERC-3009 uses `ecrecover`, so Safe / EIP-1271 accounts cannot sign an authorization. Use an EOA (optionally a 7702 session key) for the payer.
+
+---
+
+### `earn.deposit(params)` → `EarnResult`
+
+Deposit USDT0 into the Stable vault to earn yield, powered by [Morpho](https://morpho.org). Handles ERC-20 approval and permit signatures automatically.
+
+```ts
+import { createStable, Network, STABLE_VAULT_ADDRESS } from "@stablechain/sdk";
+
+const stable = createStable({
+  network: Network.Mainnet,
+  earn: { vault: STABLE_VAULT_ADDRESS },
+  walletClient: myWalletClient,
+});
+
+const { txHash } = await stable.earn.deposit({ amount: 100 }); // 100 USDT0
+```
+
+| Param               | Type     | Description                                                       |
+|---------------------|----------|-------------------------------------------------------------------|
+| `amount`            | `number` | Amount in human-readable units                                    |
+| `vault`             | `string` | *(optional)* Vault address — overrides the one set in config      |
+| `tokenDecimals`     | `number` | *(optional)* Token decimals — fetched on-chain if omitted         |
+| `slippageTolerance` | `number` | *(optional)* Max slippage as a decimal (e.g. `0.01` = 1%)        |
+| `idempotencyKey`    | `string` | *(optional)* Dedup key — concurrent calls with the same key return the same Promise |
+| `depositBuffer`     | `number` | *(optional)* Max fraction of vault idle liquidity to consume (e.g. `0.8` = 80%). Throws `StableValidationError` before sending if exceeded. Must be `> 0` and `≤ 1`. |
+
+---
+
+### `earn.withdraw(params)` / `earn.redeem(params)` → `EarnResult`
+
+Exit the vault by asset amount (`withdraw`) or by share count (`redeem`).
+
+```ts
+// Withdraw by asset amount — most common
+const { txHash } = await stable.earn.withdraw({ amount: 100 });
+
+// Redeem by share count — use reader.earn.position() to get sharesFormatted
+const { sharesFormatted } = await reader.earn.position();
+const { txHash } = await stable.earn.redeem({ shares: sharesFormatted });
+```
+
+> **Shares ≠ assets.** The exchange rate increases over time as yield accrues. Use `withdraw` when you want a specific USDT0 amount back; use `redeem` when you want to exit by share count (e.g. close 100% of a position). Use `reader.earn.position()` to get the human-readable share balance (`sharesFormatted`).
+
+When idle vault liquidity is insufficient, `withdraw` and `redeem` automatically pull liquidity from the underlying market adapters. No extra configuration needed.
+
+---
+
+### `earn.bulkDeposit(items, options?)` → `BulkEarnResult`
+
+Execute multiple deposits sequentially from one signer. Each item can target a different vault — useful for distributing across vaults in a single call. Failures are isolated: a failed item is recorded in `results` without halting the rest (unless `stopOnError` is set).
+
+```ts
+import { type BulkEarnResult } from "@stablechain/sdk";
+
+const result: BulkEarnResult = await stable.earn.bulkDeposit([
+  { amount: 50, vault: "0xVaultA" },
+  { amount: 30, vault: "0xVaultB" },
+  { amount: 20 }, // falls back to the vault set in config
+]);
+
+console.log(`${result.succeeded} succeeded, ${result.failed} failed`);
+result.results.forEach((r, i) => {
+  if (r.status === "fulfilled") console.log(`#${i + 1} [${r.vault}] txHash:`, r.txHash);
+  else console.error(`#${i + 1} [${r.vault}] error:`, r.error);
+});
+```
+
+**`BulkDepositOptions`**
+
+| Option           | Type      | Default | Description                                                   |
+|------------------|-----------|---------|---------------------------------------------------------------|
+| `stopOnError`    | `boolean` | `false` | Halt on first failure and throw `StableBulkError`            |
+| `idempotencyKey` | `string`  |         | Batch-level dedup key                                         |
+
+**`BulkEarnResultItem`**
+
+| Field             | Type     | Description                              |
+|-------------------|----------|------------------------------------------|
+| `status`          | `string` | `"fulfilled"` or `"rejected"`            |
+| `txHash`          | `string` | *(fulfilled only)* Transaction hash      |
+| `error`           | `string` | *(rejected only)* Error message          |
+| `vault`           | `string` | *(optional)* Vault address for this item |
+| `idempotencyKey`  | `string` | *(optional)* Item-level dedup key        |
+
+---
+
+### `earn.bulkWithdraw(items, options?)` → `BulkEarnResult`
+
+Execute multiple withdrawals sequentially from one signer. Same failure-isolation semantics as `bulkDeposit`.
+
+```ts
+const result = await stable.earn.bulkWithdraw([
+  { amount: 50 },
+  { amount: 30 },
+]);
+
+console.log(`${result.succeeded} succeeded, ${result.failed} failed`);
+```
+
+**`BulkWithdrawOptions`**
+
+| Option           | Type      | Default | Description                                    |
+|------------------|-----------|---------|------------------------------------------------|
+| `stopOnError`    | `boolean` | `false` | Halt on first failure and throw `StableBulkError` |
+| `idempotencyKey` | `string`  |         | Batch-level dedup key                          |
+
+---
+
+### `earn.incentiveRewards.fetch()` → `MerklRewardsResult`
+
+Fetch pending [Merkl](https://merkl.xyz) incentive rewards for the signer on the configured chain.
+
+```ts
+const { rewards } = await stable.earn.incentiveRewards.fetch();
+
+rewards.forEach((r) => {
+  console.log(`${r.token.symbol}: ${r.amount} (${r.rawAmount} raw)`);
+});
+```
+
+**`MerklRewardsResult`**
+
+| Field     | Type           | Description                              |
+|-----------|----------------|------------------------------------------|
+| `chainId` | `number`       | Chain ID the rewards are from            |
+| `rewards` | `MerklReward[]`| Pending rewards, one entry per token     |
+
+**`MerklReward`**
+
+| Field       | Type               | Description                                          |
+|-------------|--------------------|------------------------------------------------------|
+| `token`     | `MerklRewardToken` | Reward token info (`address`, `symbol`, `decimals`)  |
+| `amount`    | `number`           | Cumulative claimable amount (human-readable)         |
+| `rawAmount` | `string`           | Cumulative claimable amount as a raw string (pass to `BigInt` for contract args) |
+| `proofs`    | `string[]`         | Merkle proofs required for on-chain claiming         |
+
+> Merkl updates reward distributions roughly every 2 hours.
+
+---
+
+### `earn.incentiveRewards.claim()` → `MerklClaimResult`
+
+Claim all pending Merkl rewards for the signer in a single transaction.
+
+```ts
+const { txHash, tokenCount } = await stable.earn.incentiveRewards.claim();
+console.log(`Claimed ${tokenCount} reward token(s). Tx: ${txHash}`);
+```
+
+Throws `StableValidationError` if there are no pending rewards to claim.
+
+**`MerklClaimResult`**
+
+| Field        | Type     | Description                              |
+|--------------|----------|------------------------------------------|
+| `txHash`     | `string` | Transaction hash                         |
+| `tokenCount` | `number` | Number of distinct reward tokens claimed |
+
+#### CORS in browser environments
+
+Merkl's API does not send `Access-Control-Allow-Origin` headers for all chains. When calling from a browser, proxy the Merkl API through your own server and pass the proxy URL via `merklApiBase`:
+
+```ts
+// In your backend — forward /merkl-proxy/* to https://api.merkl.xyz/*
+const stable = createStable({
+  merklApiBase: "/merkl-proxy",
+  // ...
+});
+```
+
+With Vite, add a dev-server proxy to `vite.config.ts`:
+
+```ts
+server: {
+  proxy: {
+    "/merkl-proxy": {
+      target: "https://api.merkl.xyz",
+      changeOrigin: true,
+      rewrite: (path) => path.replace(/^\/merkl-proxy/, ""),
+    },
+  },
+},
+```
+
+---
+
+### `createStableReader(config)` — read vault state
+
+Read-only client for fetching position, yield, and rewards data — no wallet required.
+
+```ts
+import { createStableReader, Network, STABLE_VAULT_ADDRESS } from "@stablechain/sdk";
+
+const reader = createStableReader({
+  network: Network.Mainnet,
+  earn: { vault: STABLE_VAULT_ADDRESS },
+  address: "0xYourAddress",
+});
+
+// Current vault position
+const { assets, sharesFormatted, shareDecimals } = await reader.earn.position();
+console.log("Position:", assets, "USDT0");
+console.log("Shares:", sharesFormatted); // human-readable share balance
+
+// APY breakdown — native yield + per-token reward boosts
+const { apy, native, rewards, performanceFee } = await reader.earn.getYield();
+console.log("Net APY:", (apy * 100).toFixed(2) + "%");
+console.log("Native:", (native * 100).toFixed(2) + "%");
+rewards.forEach((r) => console.log(`${r.symbol} boost:`, (r.apr * 100).toFixed(2) + "%"));
+
+// Projected yield over a horizon
+const { projectedYield } = await reader.earn.preview({ amount: 1000, horizonDays: 365 });
+console.log("Projected yield over 1 year:", projectedYield, "USDT0");
+
+// Check instant withdrawability
+const { isInstant, availableLiquidity } = await reader.earn.withdrawability({ amount: 500 });
+
+// Pending Merkl rewards (read-only, no signer needed)
+const { rewards: incentives } = await reader.earn.incentiveRewards.fetch();
+```
+
+**`StableReaderConfig`**
+
+| Param          | Type     | Description                                                          |
+|----------------|----------|----------------------------------------------------------------------|
+| `network`      | `Network`| `Network.Mainnet` (default) or `Network.Testnet`                     |
+| `rpc`          | `string` | *(optional)* RPC override                                            |
+| `earn`         | `object` | *(optional)* `{ vault: "0x..." }` — required for `reader.earn.*`     |
+| `address`      | `string` | Address of the user whose position to read                           |
+| `merklApiBase` | `string` | *(optional)* Base URL for the Merkl rewards API — see `StableConfig.merklApiBase` |
+
+**`reader.earn` methods**
+
+| Method                             | Returns          | Description                                             |
+|------------------------------------|------------------|---------------------------------------------------------|
+| `getYield()`                       | `VaultYield`     | Current APY breakdown — native yield + per-token rewards |
+| `position()`                       | `VaultPosition`  | User's current shares and asset value                   |
+| `preview({ amount, horizonDays })` | `YieldPreview`   | Projected yield over a given horizon using live net APY |
+| `withdrawability({ amount })`      | `WithdrawStatus` | Whether the amount can be withdrawn from idle liquidity |
+| `incentiveRewards.fetch()`         | `MerklRewardsResult` | Pending Merkl rewards for the configured address    |
+
+**`VaultPosition`**
+
+| Field             | Type     | Description                                        |
+|-------------------|----------|----------------------------------------------------|
+| `assets`          | `number` | Position value in USDT0 (human-readable)           |
+| `shares`          | `bigint` | Raw vault share balance                            |
+| `sharesFormatted` | `number` | Human-readable share balance (use this for `redeem`) |
+| `shareDecimals`   | `number` | Vault share token decimals                         |
+| `tokenDecimals`   | `number` | Underlying asset decimals                          |
+| `assetAddress`    | `string` | Underlying asset contract address                  |
+
+**`VaultYield`**
+
+| Field            | Type                | Description                                                          |
+|------------------|---------------------|----------------------------------------------------------------------|
+| `apy`            | `number`            | Total net APY after fees, including all rewards (e.g. `0.072` = 7.2%) |
+| `native`         | `number`            | Base lending yield after fees, excluding reward boosts               |
+| `rewards`        | `VaultYieldReward[]`| Per-token reward boosts (empty when no active incentive programs)    |
+| `performanceFee` | `number`            | Performance fee as a decimal (e.g. `0.05` = 5%)                     |
+| `managementFee`  | `number`            | Management fee as a decimal                                          |
+
+**`VaultYieldReward`**
+
+| Field     | Type     | Description                                          |
+|-----------|----------|------------------------------------------------------|
+| `symbol`  | `string` | Reward token symbol (e.g. `"MORPHO"`)                |
+| `address` | `string` | Reward token contract address                        |
+| `apr`     | `number` | APR contribution from this token (e.g. `0.02` = 2%) |
+
+**`YieldPreview`**
+
+| Field            | Type     | Description                             |
+|------------------|----------|-----------------------------------------|
+| `apy`            | `number` | Current net APY (e.g. `0.065` = 6.5%)  |
+| `projectedYield` | `number` | Expected yield over `horizonDays`       |
+| `horizonDays`    | `number` | Horizon used for the projection         |
+
+> Earn is only available on Mainnet (`Network.Mainnet`).
+
+---
+
+## Supported chains
+
+`bridge` and `quoteBridge` accept any of these via the `Chain` enum:
+
+| Enum                  | Network          | Chain ID  | USDT decimals |
+|-----------------------|------------------|-----------|---------------|
+| `Chain.Sepolia`       | Ethereum Sepolia | 11155111  | 6             |
+| `Chain.StableTestnet` | Stable Testnet   | 2201      | 6             |
+| `Chain.Stable`        | Stable Mainnet   | 988       | 6             |
+| `Chain.Ethereum`      | Ethereum         | 1         | 6             |
+| `Chain.Arbitrum`      | Arbitrum One     | 42161     | 6             |
+| `Chain.Ink`           | Ink              | 57073     | 6             |
+| `Chain.Bera`          | Berachain        | 80094     | 6             |
+| `Chain.MegaETH`       | MegaETH          | 4326      | 6             |
+| `Chain.Base`          | Base             | 8453      | 6             |
+| `Chain.BSC`           | BSC              | 56        | 18            |
+| `Chain.HyperEVM`      | HyperEVM         | 999       | 6             |
+| `Chain.Polygon`       | Polygon          | 137       | 6             |
+| `Chain.Plasma`        | Plasma           | 9745      | 6             |
+| `Chain.Optimism`      | Optimism         | 10        | 6             |
+| `Chain.Unichain`      | Unichain         | 130       | 6             |
+| `Chain.Sei`           | Sei              | 1329      | 6             |
+| `Chain.Flare`         | Flare            | 14        | 6             |
+| `Chain.XLayer`        | X Layer          | 196       | 6             |
+| `Chain.Rootstock`     | Rootstock        | 30        | 6             |
+
+Per-chain RPC and USDT contract addresses are exported as `CHAIN_CONFIGS` (`ChainConfig` type) from the package.
+
+---
+
+## Errors
+
+All thrown errors extend `StableError` (which extends viem's `BaseError`). Catch by class to branch on the failure mode.
+
+| Class                     | Thrown when                                                                  |
+|---------------------------|------------------------------------------------------------------------------|
+| `StableValidationError`   | Invalid input (bad address, non-positive amount, unsupported chain, missing signer). Carries `field` and `value`. |
+| `StableQuoteError`        | LI.FI quote rejected (4xx) or returned an unexpected shape / chain mismatch. Carries `provider`, `httpStatus`, `providerCode`, `body`. |
+| `StableTransactionError`  | Wallet or on-chain failure. Carries `phase: "switch_chain" \| "approve" \| "send" \| "receipt" \| "sign"`, optional `txHash`, `chainId`. |
+| `StableNetworkError`      | Transport-level failure reaching an external API (LI.FI, Merkl) after retries. |
+
+LI.FI quote fetches retry automatically on 429 and 5xx responses with exponential backoff before surfacing.
+
+---
+
+## Testnet
+
+```ts
+import { createStable, Network } from "@stablechain/sdk";
+import { custom } from "viem";
+
+const stable = createStable({
+  network: Network.Testnet,
+  transport: custom(window.ethereum),
+});
+```
+
+---
+
+## Examples
+
+Everything lives in [`examples/core`](../../examples/core). From the repo root:
+
+```bash
+cd examples/core
+bun install
+
+# React + Vite app — transfer, bridge (with quote), swap, and earn
+# (deposit / withdraw / redeem / bulk deposit / incentive rewards)
+bun dev
+
+# Zero-setup Node script — the ERC-3009 sign → verify → settle flow
+bun run erc3009
+```