@stablechain/sdk 1.0.6 → 1.0.7

package/dist/index.js

@@ -1730,6 +1730,7 @@ import {
   concat,
   createPublicClient as createPublicClient5,
   createWalletClient as createWalletClient4,
+  encodeFunctionData as encodeFunctionData2,
   erc20Abi as erc20Abi4,
   http as http5,
   isAddress as isAddress4,
@@ -1749,11 +1750,17 @@ var XAUT0_DEPLOYMENTS = {
   ["plasma" /* Plasma */]: { address: "0x1B64B9025EEbb9A6239575dF9Ea4b9Ac46D4d193", decimals: 6, oftAdapter: "0x63aB93cBC9d4ecD9c4947b1A38F458147C08E6F7", approvalRequired: false },
   ["bsc" /* BSC */]: { address: "0x21cAef8A43163Eea865baeE23b9C2E327696A3bf", decimals: 6, oftAdapter: "0x53C3A64c8942288e12813C1F8457Db45980BcfC2", approvalRequired: false }
 };
+var USDT0_LOCKBOX_CHAINS = /* @__PURE__ */ new Set(["ethereum" /* Ethereum */, "sepolia" /* Sepolia */]);
 function bridgeChain(chain, lzEid, blockTimeSec, usdt0Adapter) {
   const base = C[chain];
   const tokens = {};
   if (usdt0Adapter) {
-    tokens.usdt0 = { address: base.usdt, decimals: base.decimals, oftAdapter: usdt0Adapter };
+    tokens.usdt0 = {
+      address: base.usdt,
+      decimals: base.decimals,
+      oftAdapter: usdt0Adapter,
+      approvalRequired: USDT0_LOCKBOX_CHAINS.has(chain)
+    };
   }
   const xaut0 = XAUT0_DEPLOYMENTS[chain];
   if (xaut0) tokens.xaut0 = xaut0;
@@ -1998,6 +2005,22 @@ function buildLzOptions(gasLimit = 0n, nativeDrop = 0n, dropReceiver) {
   ]);
 }
 var FALLBACK_SEND_GAS = 400000n;
+var DEFAULT_FEE_BUFFER_BPS = 500;
+var MAX_FEE_BUFFER_BPS = 1e4;
+function padFee(nativeFee, bufferBps) {
+  return nativeFee * BigInt(1e4 + bufferBps) / 10000n;
+}
+function resolveFeeBuffer(feeBufferBps, method) {
+  if (feeBufferBps === void 0) return DEFAULT_FEE_BUFFER_BPS;
+  if (!Number.isInteger(feeBufferBps) || feeBufferBps < 0 || feeBufferBps > MAX_FEE_BUFFER_BPS) {
+    throw new StableValidationError(
+      "feeBufferBps",
+      feeBufferBps,
+      `${method}: feeBufferBps must be an integer between 0 and ${MAX_FEE_BUFFER_BPS}`
+    );
+  }
+  return feeBufferBps;
+}
 function usableQuote(quote, amountLD) {
   if (!quote?.oft) return quote;
   return quote.oft.amountSentLD <= amountLD ? quote : void 0;
@@ -2006,16 +2029,42 @@ var ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
 var LayerZeroService = class {
   constructor(config) {
     this.config = config;
+    this.rpcById = new Map(
+      Object.entries(config.rpcOverrides ?? {}).flatMap(([chain, rpc]) => {
+        const id = CHAIN_CONFIGS[chain]?.id;
+        return id === void 0 || !rpc ? [] : [[id, rpc.replace(/\/$/, "")]];
+      })
+    );
+  }
+  /**
+   * The RPC to read and broadcast on for a chain: the caller's override when they
+   * gave one, else the built-in public endpoint. Every bridge read goes through
+   * here — a backend quoting on a loop needs an endpoint it controls.
+   */
+  rpcFor(cfg) {
+    return this.rpcById.get(cfg.id) ?? cfg.rpc;
   }
   async quoteBridge(params) {
-    const plan = this.plan(params, "quoteBridge");
+    return this.buildQuote(this.plan(params, "quoteBridge"), params, "quoteBridge");
+  }
+  /**
+   * The full quote for a planned send. `quoteBridge` reports one; the unsigned
+   * build needs the same numbers and must not disagree with what a caller was
+   * shown, so both come from here.
+   *
+   * `account` is who the gas simulation runs as — this service's signer when it
+   * has one, and the address a prepared send will be signed by when it does not.
+   */
+  async buildQuote(plan, params, method, opts = {}) {
     const [{ fee, oft }, estimate] = await Promise.all([
-      this.quotePathway(plan, "quoteBridge"),
+      this.quotePathway(plan, method, opts.requireOft),
       this.estimateBridgeTime(params).catch(() => void 0)
     ]);
-    const srcGas = await this.estimateSendGas(plan, fee, oft);
+    const srcGas = await this.estimateSendGas(plan, fee, oft, opts.account);
     return {
       ...fee,
+      // What a send built from this quote will actually carry as its `value`.
+      nativeFeeMax: padFee(fee.nativeFee, plan.feeBufferBps),
       oft,
       // What the recipient is actually credited: input minus any OFT fee and
       // minus dust. Falls back to the input when quoteOFT could not be read.
@@ -2029,10 +2078,15 @@ var LayerZeroService = class {
    * The LayerZero messaging fee for a send, plus the OFT's own accounting.
    *
    * The fee is required — a send cannot be built without it. The OFT accounting is
-   * best-effort: an adapter that does not answer `quoteOFT` costs us the fee
-   * breakdown and the exact output amount, not the whole quote.
+   * best-effort for a quote: an adapter that does not answer `quoteOFT` costs a
+   * caller the fee breakdown and the exact output amount, not the whole quote.
+   *
+   * `requireOft` flips that for the paths that go on to build a send. Without the
+   * receipt the only slippage floor left is the full input amount, which reverts
+   * with `SlippageExceeded` the moment a pathway charges a fee — so a send that
+   * cannot read `quoteOFT` is one to refuse loudly rather than assemble blind.
    */
-  async quotePathway(plan, method) {
+  async quotePathway(plan, method, requireOft = false) {
     const sendParam = this.buildSendParams(plan, 0n);
     const [msgFee, oft] = await Promise.all([
       plan.pc.readContract({
@@ -2047,39 +2101,43 @@ var LayerZeroService = class {
           cause: err
         });
       }),
-      this.readOftQuote(plan, sendParam)
+      this.readOftQuote(plan, sendParam).catch((err) => {
+        if (!requireOft) return void 0;
+        throw new StableQuoteError({
+          provider: "layerzero",
+          shortMessage: `${method}: quoteOFT call failed \u2014 the adapter's receipt is what floors the send at what it would actually deliver, and there is no safe default for it`,
+          cause: err
+        });
+      })
     ]);
     const { nativeFee, lzTokenFee } = msgFee;
     return { fee: { nativeFee, lzTokenFee }, oft };
   }
   /**
    * The adapter's own view of a send: accepted range, its fees, and what lands on
-   * the far side. Resolves to `undefined` rather than throwing — see `quoteSend`.
+   * the far side. Throws when the adapter will not answer; `quotePathway` decides
+   * whether that is fatal for the caller it is serving.
    */
   async readOftQuote(plan, sendParam) {
-    try {
-      const [limit, feeDetails, receipt] = await plan.pc.readContract({
-        address: plan.oftAdapter,
-        abi: OFT_ADAPTER_ABI,
-        functionName: "quoteOFT",
-        args: [sendParam]
-      });
-      const decimals = plan.srcToken.decimals;
-      return {
-        amountSentLD: receipt.amountSentLD,
-        amountReceivedLD: receipt.amountReceivedLD,
-        amountReceived: Number(formatUnits5(receipt.amountReceivedLD, decimals)),
-        fees: feeDetails.map((detail) => ({
-          amountLD: detail.feeAmountLD,
-          amount: Number(formatUnits5(detail.feeAmountLD, decimals)),
-          description: detail.description
-        })),
-        minAmountLD: limit.minAmountLD,
-        maxAmountLD: limit.maxAmountLD
-      };
-    } catch {
-      return void 0;
-    }
+    const [limit, feeDetails, receipt] = await plan.pc.readContract({
+      address: plan.oftAdapter,
+      abi: OFT_ADAPTER_ABI,
+      functionName: "quoteOFT",
+      args: [sendParam]
+    });
+    const decimals = plan.srcToken.decimals;
+    return {
+      amountSentLD: receipt.amountSentLD,
+      amountReceivedLD: receipt.amountReceivedLD,
+      amountReceived: Number(formatUnits5(receipt.amountReceivedLD, decimals)),
+      fees: feeDetails.map((detail) => ({
+        amountLD: detail.feeAmountLD,
+        amount: Number(formatUnits5(detail.feeAmountLD, decimals)),
+        description: detail.description
+      })),
+      minAmountLD: limit.minAmountLD,
+      maxAmountLD: limit.maxAmountLD
+    };
   }
   /**
    * Source-chain cost of the `send` transaction.
@@ -2089,13 +2147,17 @@ var LayerZeroService = class {
    * before approving does not have. When the simulation reverts, fall back to a
    * measured constant so the caller still has a cost to show, flagged as such.
    */
-  async estimateSendGas(plan, fee, oft) {
+  async estimateSendGas(plan, fee, oft, sender) {
     const gasPriceWei = await this.gasPrice(plan);
     if (gasPriceWei === void 0) return void 0;
     let gas = FALLBACK_SEND_GAS;
     let source = "fallback";
-    const account = this.signerAddress();
+    const account = sender ?? this.signerAddress();
     if (account) {
+      const sendFee = {
+        nativeFee: padFee(fee.nativeFee, plan.feeBufferBps),
+        lzTokenFee: fee.lzTokenFee
+      };
       try {
         gas = await plan.pc.estimateContractGas({
           address: plan.oftAdapter,
@@ -2103,11 +2165,11 @@ var LayerZeroService = class {
           functionName: "send",
           args: [
             this.buildSendParams(plan, oft?.amountReceivedLD ?? plan.amountLD),
-            fee,
+            sendFee,
             account
           ],
           account,
-          value: fee.nativeFee
+          value: sendFee.nativeFee
         });
         source = "simulated";
       } catch {
@@ -2130,32 +2192,49 @@ var LayerZeroService = class {
     }
   }
   /**
-   * Top the adapter's allowance up to `amountLD` when it is short. Only the
-   * lockbox chain reaches here — remote deployments burn from the caller.
+   * The `approve` amounts to send, in order, before `send` can pull `amountLD` —
+   * empty when the adapter needs no allowance or the existing one already covers
+   * the send.
+   *
+   * A short but non-zero allowance takes two approvals, not one. Legacy USDT on
+   * Ethereum — the only token a lockbox pathway ever approves — refuses to
+   * overwrite a non-zero allowance with another non-zero value:
+   *
+   *     require(!((_value != 0) && (allowed[msg.sender][_spender] != 0)))
+   *
+   * so a holder who once approved 5 USDT and now bridges 10 gets a reverted
+   * approve and pays the gas for nothing. Zeroing first is harmless on every
+   * other ERC-20, so it is unconditional rather than sniffed per token.
    */
-  async ensureAllowance(plan, wc, owner, amountLD) {
-    const { src, asset, srcToken, oftAdapter, pc, chain: srcChain } = plan;
-    const allowance = await pc.readContract({
-      address: srcToken.address,
+  async approvalPlan(plan, owner, amountLD) {
+    if (plan.srcToken.approvalRequired === false) return [];
+    const allowance = await plan.pc.readContract({
+      address: plan.srcToken.address,
       abi: erc20Abi4,
       functionName: "allowance",
-      args: [owner, oftAdapter]
+      args: [owner, plan.oftAdapter]
     });
-    if (allowance >= amountLD) return;
+    if (allowance >= amountLD) return [];
+    return allowance > 0n ? [0n, amountLD] : [amountLD];
+  }
+  /** Send one `approve` and wait for it to land. */
+  async sendApprove(plan, wc, value) {
+    const { src, asset, srcToken, oftAdapter, pc, chain: srcChain } = plan;
+    const what = value === 0n ? "allowance reset" : "approve";
     let approveHash;
     try {
       approveHash = await wc.writeContract({
         address: srcToken.address,
         abi: erc20Abi4,
         functionName: "approve",
-        args: [oftAdapter, amountLD],
+        args: [oftAdapter, value],
         account: wc.account,
         chain: srcChain
       });
     } catch (err) {
       throw new StableTransactionError({
         phase: "approve",
-        shortMessage: `bridge: ${asset} approve failed`,
+        shortMessage: `bridge: ${asset} ${what} failed`,
         chainId: src.id,
         cause: err
       });
@@ -2164,7 +2243,7 @@ var LayerZeroService = class {
     if (approveReceipt.status === "reverted") {
       throw new StableTransactionError({
         phase: "approve",
-        shortMessage: `bridge: ${asset} approve reverted on-chain`,
+        shortMessage: `bridge: ${asset} ${what} reverted on-chain`,
         txHash: approveReceipt.transactionHash,
         chainId: src.id
       });
@@ -2180,11 +2259,18 @@ var LayerZeroService = class {
       );
     }
     const plan = this.plan({ ...params, recipient: params.recipient ?? from }, "bridge");
-    const { src, srcToken, oftAdapter, amountLD, chain: srcChain } = plan;
+    const { src, oftAdapter, amountLD, chain: srcChain } = plan;
+    const refundAddress = this.resolveRefundAddress(params.refundAddress, from, "bridge");
     const wc = this.config.walletClient ?? createWalletClient4({
       account: this.config.account,
       chain: srcChain,
-      transport: this.config.transport ?? http5(src.rpc)
+      // `config.transport` is the caller's *Stable-chain* transport. A browser
+      // wallet transport is chain-agnostic — the wallet holds the keys and picks
+      // the network — but an HTTP one is a broadcast channel bound to a single
+      // chain, and broadcasting an Ethereum send to the Stable RPC fails. With a
+      // local account we sign here and only need somewhere to broadcast, so the
+      // source chain's own endpoint is always the right answer.
+      transport: this.config.account ? http5(plan.rpc) : this.config.transport ?? http5(plan.rpc)
     });
     try {
       await wc.switchChain({ id: src.id });
@@ -2197,18 +2283,19 @@ var LayerZeroService = class {
       });
     }
     const quote = usableQuote(params.quote, amountLD);
-    const { nativeFee, lzTokenFee, oft } = quote?.nativeFee !== void 0 && quote?.lzTokenFee !== void 0 ? { nativeFee: quote.nativeFee, lzTokenFee: quote.lzTokenFee, oft: quote.oft } : await this.quotePathway(plan, "bridge").then((r) => ({ ...r.fee, oft: r.oft }));
+    const { nativeFee, lzTokenFee, oft } = quote?.nativeFee !== void 0 && quote?.lzTokenFee !== void 0 ? { nativeFee: quote.nativeFee, lzTokenFee: quote.lzTokenFee, oft: quote.oft } : await this.quotePathway(plan, "bridge", true).then((r) => ({ ...r.fee, oft: r.oft }));
     const sendParams = this.buildSendParams(plan, oft?.amountReceivedLD ?? amountLD);
-    if (srcToken.approvalRequired !== false) {
-      await this.ensureAllowance(plan, wc, from, amountLD);
+    const sendFee = padFee(nativeFee, plan.feeBufferBps);
+    for (const value of await this.approvalPlan(plan, from, amountLD)) {
+      await this.sendApprove(plan, wc, value);
     }
     try {
       const hash = await wc.writeContract({
         address: oftAdapter,
         abi: OFT_ADAPTER_ABI,
         functionName: "send",
-        args: [sendParams, { nativeFee, lzTokenFee }, from],
-        value: nativeFee,
+        args: [sendParams, { nativeFee: sendFee, lzTokenFee }, refundAddress],
+        value: sendFee,
         account: wc.account,
         chain: srcChain
       });
@@ -2222,6 +2309,77 @@ var LayerZeroService = class {
       });
     }
   }
+  /**
+   * Everything needed to send a bridge, without signing or sending any of it: the
+   * ordered transactions, the quote they were built from, and the `SendParam` the
+   * send step encodes, decoded.
+   *
+   * This is the split-responsibility shape — a backend quotes, builds and checks
+   * while the holder's wallet only signs — and the only way to inspect a bridge
+   * before it exists. Send `steps` in order from `from`, each one confirmed before
+   * the next: an allowance reset and an approve where the lockbox pathway needs
+   * them, then the OFT `send` carrying its fee as `value`.
+   *
+   * Refuses to build when the adapter will not answer `quoteOFT`: the receipt is
+   * what floors the send at what it would actually deliver, and guessing the floor
+   * is how a send reverts with `SlippageExceeded` after the gas is spent.
+   */
+  async prepareBridgeCalldata(params) {
+    const method = "prepareBridgeCalldata";
+    const from = params.from;
+    if (!isAddress4(from)) {
+      throw new StableValidationError(
+        "from",
+        params.from,
+        `${method}: invalid from address "${params.from}" \u2014 the address that will sign these transactions`
+      );
+    }
+    const refundAddress = this.resolveRefundAddress(params.refundAddress, from, method);
+    const plan = this.plan({ ...params, recipient: params.recipient ?? from }, method);
+    const supplied = usableQuote(params.quote, plan.amountLD);
+    const quote = supplied?.oft && supplied.nativeFee !== void 0 && supplied.lzTokenFee !== void 0 ? supplied : await this.buildQuote(plan, params, method, { account: from, requireOft: true });
+    const oft = quote.oft;
+    const nativeFee = padFee(quote.nativeFee, plan.feeBufferBps);
+    const lzTokenFee = quote.lzTokenFee;
+    const sendParam = this.buildSendParams(plan, oft.amountReceivedLD);
+    const steps = (await this.approvalPlan(plan, from, plan.amountLD)).map((value) => ({
+      chainId: plan.src.id,
+      to: plan.srcToken.address,
+      data: encodeFunctionData2({
+        abi: erc20Abi4,
+        functionName: "approve",
+        args: [plan.oftAdapter, value]
+      }),
+      value: 0n
+    }));
+    steps.push({
+      chainId: plan.src.id,
+      to: plan.oftAdapter,
+      data: encodeFunctionData2({
+        abi: OFT_ADAPTER_ABI,
+        functionName: "send",
+        args: [sendParam, { nativeFee, lzTokenFee }, refundAddress]
+      }),
+      value: nativeFee
+    });
+    return {
+      steps,
+      chainId: plan.src.id,
+      asset: plan.asset,
+      quote,
+      send: {
+        dstEid: sendParam.dstEid,
+        recipient: plan.recipient,
+        to: sendParam.to,
+        amountLD: sendParam.amountLD,
+        minAmountLD: sendParam.minAmountLD,
+        extraOptions: sendParam.extraOptions,
+        nativeFee,
+        lzTokenFee,
+        refundAddress
+      }
+    };
+  }
   /**
    * Estimate how long a USDT0 bridge will take, end to end.
    *
@@ -2318,7 +2476,8 @@ var LayerZeroService = class {
   /** Effective ULN config the DVNs enforce for this pathway, read from the source chain. */
   async getUlnConfig(src, dst, oapp) {
     return cached(`uln:${src.lzEid}-${dst.lzEid}-${oapp.toLowerCase()}`, CACHE_TTL_MS, async () => {
-      const pc = createPublicClient5({ chain: makeChain(src.id, src.rpc), transport: http5(src.rpc) });
+      const rpc = this.rpcFor(src);
+      const pc = createPublicClient5({ chain: makeChain(src.id, rpc), transport: http5(rpc) });
       const endpoint = await pc.readContract({ address: oapp, abi: OAPP_ABI, functionName: "endpoint" });
       const sendLib = await pc.readContract({
         address: endpoint,
@@ -2424,13 +2583,22 @@ var LayerZeroService = class {
         `${method}: dstNativeDrop must not be negative`
       );
     }
+    const feeBufferBps = resolveFeeBuffer(params.feeBufferBps, method);
     const { src, dst, asset, srcToken, dstToken } = this.resolveRoute(
       fromChain,
       toChain,
       fromToken,
       toToken
     );
-    const chain = makeChain(src.id, src.rpc);
+    if (params.fromDecimals !== void 0 && params.fromDecimals !== srcToken.decimals) {
+      throw new StableValidationError(
+        "fromDecimals",
+        params.fromDecimals,
+        `${method}: ${asset} has ${srcToken.decimals} decimals on "${fromChain}", not ${params.fromDecimals}. The native OFT route parses the amount with the token's own decimals; fromDecimals applies to LI.FI routes only.`
+      );
+    }
+    const rpc = this.rpcFor(src);
+    const chain = makeChain(src.id, rpc);
     return {
       src,
       dst,
@@ -2441,10 +2609,28 @@ var LayerZeroService = class {
       amountLD: parseUnits4(String(amount), srcToken.decimals),
       recipient: recipientAddr,
       nativeDrop: dstNativeDrop ?? 0n,
+      rpc,
+      feeBufferBps,
       chain,
-      pc: createPublicClient5({ chain, transport: http5(src.rpc) })
+      pc: createPublicClient5({ chain, transport: http5(rpc) })
     };
   }
+  /**
+   * Where `send` returns messaging fee it did not need. Defaults to the sender,
+   * which is what a caller wants unless they are routing refunds somewhere of
+   * their own — a backend paying the fee on a user's behalf, say.
+   */
+  resolveRefundAddress(refundAddress, sender, method) {
+    if (refundAddress === void 0) return sender;
+    if (!isAddress4(refundAddress)) {
+      throw new StableValidationError(
+        "refundAddress",
+        refundAddress,
+        `${method}: invalid refundAddress "${refundAddress}"`
+      );
+    }
+    return refundAddress;
+  }
   /** The address that will sign, or undefined when this service has no signer. */
   signerAddress() {
     return this.config.walletClient?.account?.address ?? this.config.account?.address;
@@ -2576,6 +2762,7 @@ async function executeTokenTransfer(wc, publicClient, token, to, amount, tokenDe
 function createStable({
   network = "mainnet" /* Mainnet */,
   rpc: rpcOverride,
+  rpcOverrides,
   account,
   transport,
   walletClient,
@@ -2589,7 +2776,7 @@ function createStable({
   );
   const signerConfig = { account, transport, walletClient };
   const lifi = new LiFiService({ ...signerConfig, rpc, chainId: chain.id });
-  const lz = new LayerZeroService(signerConfig);
+  const lz = new LayerZeroService({ ...signerConfig, rpcOverrides });
   const merkl = new MerklService({ ...signerConfig, rpc, chainId: chain.id, merklApiBase });
   const morpho = earnConfig ? new MorphoService({
     ...signerConfig,
@@ -2683,6 +2870,16 @@ function createStable({
     // promise like every other validation error, not a synchronous throw.
     quoteBridge: async (params) => selectBridge(params) === "oft" ? lz.quoteBridge(params) : lifi.quoteBridge(params),
     bridge: async (params) => selectBridge(params) === "oft" ? lz.bridge(params) : lifi.bridge(params),
+    prepareBridgeCalldata: async (params) => {
+      if (selectBridge(params) !== "oft") {
+        throw new StableValidationError(
+          "route",
+          params.route ?? "auto",
+          `prepareBridgeCalldata: only the native OFT route can be built unsigned, and ${params.fromChain}\u2192${params.toChain} resolved to LI.FI`
+        );
+      }
+      return lz.prepareBridgeCalldata(params);
+    },
     estimateBridgeTime: (params) => lz.estimateBridgeTime(params),
     trackBridge: (srcTxHash) => lz.trackBridge(srcTxHash),
     quoteSwap: (params) => lifi.quoteSwap(params),
@@ -2729,6 +2926,7 @@ export {
   Chain,
   ERC3009_ABI,
   Network,
+  OFT_ADAPTER_ABI,
   STABLE_USDT_ADDRESS,
   STABLE_VAULT_ADDRESS,
   StableBulkError,
@@ -2738,6 +2936,7 @@ export {
   StableTransactionError,
   StableValidationError,
   bridgeAssetFor,
+  buildLzOptions,
   cancelAuthorization,
   clearBridgeEstimateCache,
   createStable,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@stablechain/sdk",
-    "version": "1.0.6",
+    "version": "1.0.7",
     "description": "Stable SDK",
     "keywords": ["stable", "usdt", "gasless", "web3", "yield"],
     "license": "MIT",