@piprail/sdk 2.16.2 → 3.0.0

package/dist/{ton-J7TQWRN4.cjs → ton-AGTKLQA5.cjs}

@@ -1,4 +1,4 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } } function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
 
 var _chunkCQREG5LEcjs = require('./chunk-CQREG5LE.cjs');
 
@@ -9,7 +9,9 @@ var _chunkCQREG5LEcjs = require('./chunk-CQREG5LE.cjs');
 
 
 
-var _chunkQONQSZHJcjs = require('./chunk-QONQSZHJ.cjs');
+
+
+var _chunk6XTNI2OQcjs = require('./chunk-6XTNI2OQ.cjs');
 
 // src/drivers/ton/index.ts
 var _core = require('@ton/core');
@@ -76,7 +78,7 @@ async function waitForSeqno(opened, from, { tries = 30, intervalMs = 2e3 } = {})
     }
     if (current > from) return;
   }
-  throw new (0, _chunkQONQSZHJcjs.ConfirmationTimeoutError)(
+  throw new (0, _chunk6XTNI2OQcjs.ConfirmationTimeoutError)(
     `TON wallet seqno did not advance past ${from} \u2014 the payment may not have been accepted.`
   );
 }
@@ -202,18 +204,193 @@ function notFound(nonce) {
   };
 }
 
+// src/drivers/ton/swap.ts
+var STONFI_API = "https://api.ston.fi";
+var PTON_MASTER_V2_1 = "EQBnGWMCf3-FZZq1W4IWcWiGAc3PHuZ0_H-7sad2oY00o83S";
+function sourceFor(feePercent) {
+  const pct = feePercent ? `${(Number(feePercent) * 100).toFixed(4)}%` : "the underlying pool fee";
+  return {
+    kind: "provider",
+    name: "STON.fi",
+    note: `Third-party TON DEX (ston.fi), used keyless. It prices the route and returns the router to message; your own wallet signs and sends, and STON.fi never holds your funds. Cost on this route: ${pct}, which is the pool fee. PipRail adds nothing.`
+  };
+}
+function masterFor(t) {
+  return t.asset === "native" ? PTON_MASTER_V2_1 : t.asset;
+}
+function side(t, amount) {
+  const decimals = t.asset === "native" ? TON_DECIMALS : t.decimals;
+  return {
+    asset: t.asset,
+    symbol: _nullishCoalesce(t.symbol, () => ( (t.asset === "native" ? TON_NATIVE_SYMBOL : t.asset))),
+    decimals,
+    amount: amount.toString(),
+    amountFormatted: _chunk6XTNI2OQcjs.formatUnits.call(void 0, amount, decimals)
+  };
+}
+async function postJson(url) {
+  try {
+    const res = await fetch(url, { method: "POST" });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch (e6) {
+    return null;
+  }
+}
+async function quoteTonSwap(p) {
+  if (p.wantAmount <= 0n) return null;
+  const offerMaster = masterFor(p.from);
+  const askMaster = masterFor(p.to);
+  if (offerMaster === askMaster) return null;
+  const tolerance = (p.slippageBps / 1e4).toFixed(6);
+  const bps = BigInt(Math.max(0, Math.min(p.slippageBps, 9999)));
+  const askUnits = (p.wantAmount * 10000n + (10000n - bps) - 1n) / (10000n - bps);
+  const url = `${STONFI_API}/v1/reverse_swap/simulate?offer_address=${encodeURIComponent(offerMaster)}&ask_address=${encodeURIComponent(askMaster)}&units=${askUnits.toString()}&slippage_tolerance=${tolerance}`;
+  const sim = await postJson(url);
+  if (!_optionalChain([sim, 'optionalAccess', _ => _.offer_units]) || !sim.router_address) return null;
+  const num = (v) => {
+    if (typeof v !== "string" && typeof v !== "number") return null;
+    try {
+      const n = BigInt(v);
+      return n >= 0n ? n : null;
+    } catch (e7) {
+      return null;
+    }
+  };
+  const offerUnits = num(sim.offer_units);
+  if (offerUnits === null || offerUnits <= 0n) return null;
+  const minAsk = num(sim.min_ask_units);
+  if (minAsk === null || minAsk < p.wantAmount) return null;
+  const forwardGas = _nullishCoalesce(num(_optionalChain([sim, 'access', _2 => _2.gas_params, 'optionalAccess', _3 => _3.forward_gas])), () => ( 300000000n));
+  const major = _nullishCoalesce(_optionalChain([sim, 'access', _4 => _4.router, 'optionalAccess', _5 => _5.major_version]), () => ( 2));
+  const minor = _nullishCoalesce(_optionalChain([sim, 'access', _6 => _6.router, 'optionalAccess', _7 => _7.minor_version]), () => ( 1));
+  const routerVersion = major === 1 ? "v1" : `v${major}_${minor}`;
+  return {
+    source: sourceFor(sim.fee_percent),
+    network: p.network,
+    from: side(p.from, offerUnits),
+    to: side(p.to, p.wantAmount),
+    // The offer side is fixed by the simulation, so it IS the ceiling.
+    maxSpend: offerUnits.toString(),
+    maxSpendFormatted: _chunk6XTNI2OQcjs.formatUnits.call(void 0, offerUnits, p.from.asset === "native" ? TON_DECIMALS : p.from.decimals),
+    slippageBps: p.slippageBps,
+    route: {
+      routerAddress: sim.router_address,
+      routerVersion,
+      ptonMaster: _nullishCoalesce(_optionalChain([sim, 'access', _8 => _8.router, 'optionalAccess', _9 => _9.pton_master_address]), () => ( PTON_MASTER_V2_1)),
+      ptonVersion: _nullishCoalesce(_optionalChain([sim, 'access', _10 => _10.router, 'optionalAccess', _11 => _11.pton_version]), () => ( "2.1")),
+      offerMaster,
+      askMaster,
+      askJettonWallet: sim.ask_jetton_wallet,
+      // 🔴 The on-chain floor, checked above to be ≥ the invoice. The router refuses the swap
+      // below it, so "at least the invoice" is enforced by the contract, not by this quote.
+      minAskUnits: minAsk.toString(),
+      forwardGas: forwardGas.toString(),
+      fromIsNative: p.from.asset === "native",
+      toIsNative: p.to.asset === "native"
+    }
+  };
+}
+async function swapTon(p) {
+  const route = p.quote.route;
+  if (!_optionalChain([route, 'optionalAccess', _12 => _12.routerAddress]) || !route.offerMaster || !route.askMaster) {
+    throw new Error("TON: swap quote is missing its STON.fi routing data \u2014 re-quote before swapping.");
+  }
+  const [{ DEX, pTON }, { Address: Address3 }] = await Promise.all([
+    Promise.resolve().then(() => _interopRequireWildcard(require("@ston-fi/sdk"))),
+    Promise.resolve().then(() => _interopRequireWildcard(require("@ton/core")))
+  ]);
+  const dex = DEX[route.routerVersion];
+  if (!_optionalChain([dex, 'optionalAccess', _13 => _13.Router])) {
+    throw new Error(
+      `TON: STON.fi router version ${route.routerVersion} is not supported by the installed @ston-fi/sdk.`
+    );
+  }
+  const ptonNs = pTON[route.ptonVersion.startsWith("2") ? "v2_1" : "v1"];
+  if (!_optionalChain([ptonNs, 'optionalAccess', _14 => _14.create])) {
+    throw new Error(`TON: STON.fi pTON version ${route.ptonVersion} is not supported by the installed SDK.`);
+  }
+  const router = p.client.open(dex.Router.create(Address3.parse(route.routerAddress)));
+  const call = (name, args) => {
+    const fn = router[name];
+    if (typeof fn !== "function") {
+      throw new Error(`TON: the installed @ston-fi/sdk router has no ${name} \u2014 is it a supported version?`);
+    }
+    return fn.call(router, args);
+  };
+  const proxyTon = ptonNs.create(Address3.parse(route.ptonMaster));
+  const userWalletAddress = p.wallet.contract.address;
+  const offerAmount = BigInt(p.quote.from.amount);
+  const minAskAmount = BigInt(route.minAskUnits);
+  let txParams;
+  try {
+    if (route.fromIsNative) {
+      txParams = await call("getSwapTonToJettonTxParams", {
+        userWalletAddress,
+        proxyTon,
+        offerAmount,
+        askJettonAddress: Address3.parse(route.askMaster),
+        minAskAmount
+      });
+    } else if (route.toIsNative) {
+      txParams = await call("getSwapJettonToTonTxParams", {
+        userWalletAddress,
+        proxyTon,
+        offerJettonAddress: Address3.parse(route.offerMaster),
+        offerAmount,
+        minAskAmount
+      });
+    } else {
+      txParams = await call("getSwapJettonToJettonTxParams", {
+        userWalletAddress,
+        offerJettonAddress: Address3.parse(route.offerMaster),
+        askJettonAddress: Address3.parse(route.askMaster),
+        offerAmount,
+        minAskAmount
+      });
+    }
+  } catch (err) {
+    throw new Error(`TON: STON.fi could not build this swap message. Nothing was sent. (${String(err).slice(0, 160)})`, {
+      cause: err
+    });
+  }
+  try {
+    const hash = await p.send({
+      to: String(txParams.to),
+      value: BigInt(txParams.value),
+      body: txParams.body
+    });
+    return {
+      transaction: hash,
+      network: p.quote.network,
+      source: p.quote.source,
+      from: p.quote.from,
+      to: p.quote.to
+    };
+  } catch (err) {
+    const msg = String(_nullishCoalesce(_optionalChain([err, 'optionalAccess', _15 => _15.message]), () => ( err)));
+    if (/not enough|insufficient|balance|inbound message/i.test(msg)) {
+      throw new (0, _chunk6XTNI2OQcjs.InsufficientFundsError)(
+        `TON swap could not be sent: the wallet cannot cover the offer plus the attached forward gas (${_chunk6XTNI2OQcjs.formatUnits.call(void 0, BigInt(route.forwardGas), TON_DECIMALS)} TON is attached, most of which bounces back). (${msg.slice(0, 140)})`,
+        { cause: err }
+      );
+    }
+    throw err;
+  }
+}
+
 // src/drivers/ton/wallet.ts
 var _crypto = require('@ton/crypto');
 
 function assertTonWallet(wallet, network) {
   if (typeof wallet !== "object" || wallet === null) {
-    throw new (0, _chunkQONQSZHJcjs.WrongFamilyError)(
+    throw new (0, _chunk6XTNI2OQcjs.WrongFamilyError)(
       `chain ${network} is TON; wallet must be { key } (24-word mnemonic) or { keyPair }.`
     );
   }
-  _chunkQONQSZHJcjs.assertNoLegacyWalletKey.call(void 0, wallet, "TON");
+  _chunk6XTNI2OQcjs.assertNoLegacyWalletKey.call(void 0, wallet, "TON");
   if (!("key" in wallet) && !("keyPair" in wallet)) {
-    throw new (0, _chunkQONQSZHJcjs.WrongFamilyError)(
+    throw new (0, _chunk6XTNI2OQcjs.WrongFamilyError)(
       `chain ${network} is TON; wallet must be { key } (24-word mnemonic) or { keyPair }.`
     );
   }
@@ -224,13 +401,13 @@ async function resolveTonWallet(config) {
   let keyPair;
   if (config.key) {
     if (typeof config.key !== "string" && !Array.isArray(config.key)) {
-      throw new (0, _chunkQONQSZHJcjs.WrongFamilyError)(
+      throw new (0, _chunk6XTNI2OQcjs.WrongFamilyError)(
         "chain is TON; the wallet { key } must be a 24-word mnemonic (a string or string[])."
       );
     }
     const words = Array.isArray(config.key) ? config.key : config.key.trim().split(/\s+/);
     if (!await _crypto.mnemonicValidate.call(void 0, words)) {
-      throw new (0, _chunkQONQSZHJcjs.WrongFamilyError)(
+      throw new (0, _chunk6XTNI2OQcjs.WrongFamilyError)(
         "chain is TON; the wallet { key } is not a valid TON mnemonic (expected 24 words from the TON/BIP-39 wordlist)."
       );
     }
@@ -238,7 +415,7 @@ async function resolveTonWallet(config) {
   } else if (config.keyPair) {
     keyPair = config.keyPair;
   } else {
-    throw new (0, _chunkQONQSZHJcjs.WrongFamilyError)("TON wallet needs { key } (24-word mnemonic) or { keyPair }.");
+    throw new (0, _chunk6XTNI2OQcjs.WrongFamilyError)("TON wallet needs { key } (24-word mnemonic) or { keyPair }.");
   }
   const contract = version === "v5r1" ? _ton.WalletContractV5R1.create({ workchain: 0, publicKey: keyPair.publicKey }) : _ton.WalletContractV4.create({ workchain: 0, publicKey: keyPair.publicKey });
   return { keyPair, contract };
@@ -287,15 +464,15 @@ function makeTonNetwork(preset, rpcUrl) {
         const info = preset.tokens[token.toUpperCase()];
         if (!info) {
           const known = Object.keys(preset.tokens).join(", ") || "(none built in)";
-          throw new (0, _chunkQONQSZHJcjs.UnknownTokenError)(
+          throw new (0, _chunk6XTNI2OQcjs.UnknownTokenError)(
             `token "${token}" isn't built in for TON (known: ${known}). Note: native USDC doesn't exist on TON. Pass { master, decimals } for a custom jetton, or use 'native'.`
           );
         }
         return { asset: info.master, decimals: info.decimals, symbol: info.symbol };
       }
-      _chunkQONQSZHJcjs.rejectForeignToken.call(void 0, token, "ton", network);
+      _chunk6XTNI2OQcjs.rejectForeignToken.call(void 0, token, "ton", network);
       if (!("master" in token)) {
-        throw new (0, _chunkQONQSZHJcjs.WrongFamilyError)(
+        throw new (0, _chunk6XTNI2OQcjs.WrongFamilyError)(
           `chain ${network} is TON; a custom token must be { master, decimals }.`
         );
       }
@@ -314,14 +491,14 @@ function makeTonNetwork(preset, rpcUrl) {
     },
     assertValidPayTo(payTo) {
       if (payTo.startsWith("0x")) {
-        throw new (0, _chunkQONQSZHJcjs.WrongFamilyError)(
+        throw new (0, _chunk6XTNI2OQcjs.WrongFamilyError)(
           `chain ${network} is TON, but payTo "${payTo}" looks like an EVM address.`
         );
       }
       try {
         _core.Address.parse(payTo);
-      } catch (e6) {
-        throw new (0, _chunkQONQSZHJcjs.WrongFamilyError)(
+      } catch (e8) {
+        throw new (0, _chunk6XTNI2OQcjs.WrongFamilyError)(
           `chain ${network} is TON, but payTo "${payTo}" is not a valid TON address.`
         );
       }
@@ -337,7 +514,7 @@ function makeTonNetwork(preset, rpcUrl) {
         const watch = await watchAccountFor(accept);
         return encodeRef(watch, accept.extra.nonce);
       } catch (err) {
-        throw _nullishCoalesce(_chunkQONQSZHJcjs.toInsufficientFundsError.call(void 0, err), () => ( err));
+        throw _nullishCoalesce(_chunk6XTNI2OQcjs.toInsufficientFundsError.call(void 0, err), () => ( err));
       }
     },
     async confirm(ref) {
@@ -348,7 +525,7 @@ function makeTonNetwork(preset, rpcUrl) {
         let txs;
         try {
           txs = await client.getTransactions(account, { limit: 16, archival: true });
-        } catch (e7) {
+        } catch (e9) {
           continue;
         }
         for (const tx of txs) {
@@ -356,18 +533,38 @@ function makeTonNetwork(preset, rpcUrl) {
           if (inc && inc.comment === nonce) return { height: tx.lt.toString() };
         }
       }
-      throw new (0, _chunkQONQSZHJcjs.ConfirmationTimeoutError)(`TON payment for nonce ${nonce} did not settle in time.`);
+      throw new (0, _chunk6XTNI2OQcjs.ConfirmationTimeoutError)(`TON payment for nonce ${nonce} did not settle in time.`);
     },
     async estimateCost(accept) {
       const fee = accept.asset === "native" ? 10000000n : 50000000n;
       const detail = accept.asset === "native" ? `~0.01 ${TON_NATIVE_SYMBOL} network fee` : `~0.05 ${TON_NATIVE_SYMBOL} attached for the jetton transfer (leftover refunded)`;
-      return _chunkQONQSZHJcjs.nativeCost.call(void 0, { symbol: TON_NATIVE_SYMBOL, decimals: TON_DECIMALS, fee, basis: "heuristic", detail });
+      return _chunk6XTNI2OQcjs.nativeCost.call(void 0, { symbol: TON_NATIVE_SYMBOL, decimals: TON_DECIMALS, fee, basis: "heuristic", detail });
+    },
+    /**
+     * The bound wallet's own address — where THIS wallet gets paid. Derived from the key
+     * material only: no RPC, nothing moved. See {@link ResolvedNetwork.addressOf}.
+     *
+     * 🔴 NON-BOUNCEABLE (`UQ…`), which is not the default `toString()` gives.
+     *
+     * TON encodes one account two ways. A bounceable `EQ…` address returns the funds to the
+     * sender if the destination contract is not initialised, and a wallet contract is not
+     * initialised until it has sent its first transaction. So a freshly generated agent wallet
+     * advertising `EQ…` would have its FIRST payment bounce, which is exactly the payment a new
+     * seller most needs to land. `UQ…` is also what every TON wallet shows you as your receive
+     * address, so this matches what the operator sees and what the wallet file records.
+     *
+     * Verification is unaffected either way: `Address.parse` accepts both forms and they are the
+     * same account.
+     */
+    async addressOf(wallet) {
+      const { contract } = await resolveTonWallet(wallet._native);
+      return contract.address.toString({ bounceable: false });
     },
     async balanceOf(wallet, asset) {
       let owner;
       try {
         owner = (await resolveTonWallet(wallet._native)).contract.address.toString();
-      } catch (e8) {
+      } catch (e10) {
         return { token: null, native: null };
       }
       const native = await client.getBalance(_core.Address.parse(owner)).then((b) => BigInt(b)).catch(() => null);
@@ -377,7 +574,7 @@ function makeTonNetwork(preset, rpcUrl) {
         const jw = await jettonWalletFor(asset, owner);
         const { stack } = await client.runMethod(jw, "get_wallet_data");
         token = stack.readBigNumber();
-      } catch (e9) {
+      } catch (e11) {
         token = null;
       }
       return { token, native };
@@ -386,11 +583,56 @@ function makeTonNetwork(preset, rpcUrl) {
     async recipientReady() {
       return { ready: "n/a" };
     },
+    /* ---- swap (OPTIONAL, opt-in): via STON.fi, keyless + no added fee. See ./swap.ts ---- */
+    async quoteSwap({ from, to, wantAmount, slippageBps }) {
+      return quoteTonSwap({ network, from, to, wantAmount, slippageBps });
+    },
+    async swap(wallet, quote) {
+      const tw = await resolveTonWallet(wallet._native);
+      return swapTon({
+        client,
+        wallet: tw,
+        quote,
+        /*
+         * TON settles asynchronously, so "sent" and "arrived" are different questions. This
+         * waits for the WALLET's seqno to advance (its external message was accepted and
+         * sent), then reports the resulting wallet transaction hash so the caller has a real,
+         * checkable reference. Whether the ask side landed is a balance question, exactly as
+         * it is on the payment path.
+         */
+        send: async ({ to, value, body }) => {
+          const opened = client.open(tw.contract);
+          const seqno = await opened.getSeqno();
+          await opened.sendTransfer({
+            seqno,
+            secretKey: tw.keyPair.secretKey,
+            sendMode: _core.SendMode.PAY_GAS_SEPARATELY | _core.SendMode.IGNORE_ERRORS,
+            messages: [_core.internal.call(void 0, { to: _core.Address.parse(to), value, bounce: true, body })]
+          });
+          for (let i = 0; i < 30; i += 1) {
+            await new Promise((r) => setTimeout(r, 2e3));
+            try {
+              if (await opened.getSeqno() > seqno) break;
+            } catch (e12) {
+              continue;
+            }
+          }
+          try {
+            const txs = await client.getTransactions(tw.contract.address, { limit: 10 });
+            const mine = _optionalChain([txs, 'optionalAccess', _16 => _16.find, 'call', _17 => _17((t) => _optionalChain([t, 'optionalAccess', _18 => _18.inMessage, 'optionalAccess', _19 => _19.info, 'optionalAccess', _20 => _20.type]) === "external-in")]);
+            const h = _optionalChain([mine, 'optionalAccess', _21 => _21.hash, 'optionalCall', _22 => _22()]);
+            if (h) return Buffer.from(h).toString("hex");
+          } catch (e13) {
+          }
+          return `ton:${tw.contract.address.toString()}|seqno:${seqno}`;
+        }
+      });
+    },
     async verify(_ref, accept) {
       let watch;
       try {
         watch = await watchAccountFor(accept);
-      } catch (e10) {
+      } catch (e14) {
         return { ok: false, error: "tx_not_found", detail: `Could not derive/read the TON jetton wallet (transient RPC failure) \u2014 retry.` };
       }
       return verifyTon({ client, watch, accept });

package/dist/{ton-WH2JVQOO.js → ton-OZKFNRLT.js}

@@ -3,16 +3,18 @@ import {
 } from "./chunk-FURB5RP7.js";
 import {
   ConfirmationTimeoutError,
+  InsufficientFundsError,
   UnknownTokenError,
   WrongFamilyError,
   assertNoLegacyWalletKey,
+  formatUnits,
   nativeCost,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-QU25LSVS.js";
+} from "./chunk-5GRBEMCA.js";
 
 // src/drivers/ton/index.ts
-import { Address as Address2 } from "@ton/core";
+import { Address as Address2, internal as internal2, SendMode as SendMode2 } from "@ton/core";
 import { JettonMaster, TonClient } from "@ton/ton";
 
 // src/drivers/ton/chains.ts
@@ -202,6 +204,181 @@ function notFound(nonce) {
   };
 }
 
+// src/drivers/ton/swap.ts
+var STONFI_API = "https://api.ston.fi";
+var PTON_MASTER_V2_1 = "EQBnGWMCf3-FZZq1W4IWcWiGAc3PHuZ0_H-7sad2oY00o83S";
+function sourceFor(feePercent) {
+  const pct = feePercent ? `${(Number(feePercent) * 100).toFixed(4)}%` : "the underlying pool fee";
+  return {
+    kind: "provider",
+    name: "STON.fi",
+    note: `Third-party TON DEX (ston.fi), used keyless. It prices the route and returns the router to message; your own wallet signs and sends, and STON.fi never holds your funds. Cost on this route: ${pct}, which is the pool fee. PipRail adds nothing.`
+  };
+}
+function masterFor(t) {
+  return t.asset === "native" ? PTON_MASTER_V2_1 : t.asset;
+}
+function side(t, amount) {
+  const decimals = t.asset === "native" ? TON_DECIMALS : t.decimals;
+  return {
+    asset: t.asset,
+    symbol: t.symbol ?? (t.asset === "native" ? TON_NATIVE_SYMBOL : t.asset),
+    decimals,
+    amount: amount.toString(),
+    amountFormatted: formatUnits(amount, decimals)
+  };
+}
+async function postJson(url) {
+  try {
+    const res = await fetch(url, { method: "POST" });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+async function quoteTonSwap(p) {
+  if (p.wantAmount <= 0n) return null;
+  const offerMaster = masterFor(p.from);
+  const askMaster = masterFor(p.to);
+  if (offerMaster === askMaster) return null;
+  const tolerance = (p.slippageBps / 1e4).toFixed(6);
+  const bps = BigInt(Math.max(0, Math.min(p.slippageBps, 9999)));
+  const askUnits = (p.wantAmount * 10000n + (10000n - bps) - 1n) / (10000n - bps);
+  const url = `${STONFI_API}/v1/reverse_swap/simulate?offer_address=${encodeURIComponent(offerMaster)}&ask_address=${encodeURIComponent(askMaster)}&units=${askUnits.toString()}&slippage_tolerance=${tolerance}`;
+  const sim = await postJson(url);
+  if (!sim?.offer_units || !sim.router_address) return null;
+  const num = (v) => {
+    if (typeof v !== "string" && typeof v !== "number") return null;
+    try {
+      const n = BigInt(v);
+      return n >= 0n ? n : null;
+    } catch {
+      return null;
+    }
+  };
+  const offerUnits = num(sim.offer_units);
+  if (offerUnits === null || offerUnits <= 0n) return null;
+  const minAsk = num(sim.min_ask_units);
+  if (minAsk === null || minAsk < p.wantAmount) return null;
+  const forwardGas = num(sim.gas_params?.forward_gas) ?? 300000000n;
+  const major = sim.router?.major_version ?? 2;
+  const minor = sim.router?.minor_version ?? 1;
+  const routerVersion = major === 1 ? "v1" : `v${major}_${minor}`;
+  return {
+    source: sourceFor(sim.fee_percent),
+    network: p.network,
+    from: side(p.from, offerUnits),
+    to: side(p.to, p.wantAmount),
+    // The offer side is fixed by the simulation, so it IS the ceiling.
+    maxSpend: offerUnits.toString(),
+    maxSpendFormatted: formatUnits(offerUnits, p.from.asset === "native" ? TON_DECIMALS : p.from.decimals),
+    slippageBps: p.slippageBps,
+    route: {
+      routerAddress: sim.router_address,
+      routerVersion,
+      ptonMaster: sim.router?.pton_master_address ?? PTON_MASTER_V2_1,
+      ptonVersion: sim.router?.pton_version ?? "2.1",
+      offerMaster,
+      askMaster,
+      askJettonWallet: sim.ask_jetton_wallet,
+      // 🔴 The on-chain floor, checked above to be ≥ the invoice. The router refuses the swap
+      // below it, so "at least the invoice" is enforced by the contract, not by this quote.
+      minAskUnits: minAsk.toString(),
+      forwardGas: forwardGas.toString(),
+      fromIsNative: p.from.asset === "native",
+      toIsNative: p.to.asset === "native"
+    }
+  };
+}
+async function swapTon(p) {
+  const route = p.quote.route;
+  if (!route?.routerAddress || !route.offerMaster || !route.askMaster) {
+    throw new Error("TON: swap quote is missing its STON.fi routing data \u2014 re-quote before swapping.");
+  }
+  const [{ DEX, pTON }, { Address: Address3 }] = await Promise.all([
+    import("@ston-fi/sdk"),
+    import("@ton/core")
+  ]);
+  const dex = DEX[route.routerVersion];
+  if (!dex?.Router) {
+    throw new Error(
+      `TON: STON.fi router version ${route.routerVersion} is not supported by the installed @ston-fi/sdk.`
+    );
+  }
+  const ptonNs = pTON[route.ptonVersion.startsWith("2") ? "v2_1" : "v1"];
+  if (!ptonNs?.create) {
+    throw new Error(`TON: STON.fi pTON version ${route.ptonVersion} is not supported by the installed SDK.`);
+  }
+  const router = p.client.open(dex.Router.create(Address3.parse(route.routerAddress)));
+  const call = (name, args) => {
+    const fn = router[name];
+    if (typeof fn !== "function") {
+      throw new Error(`TON: the installed @ston-fi/sdk router has no ${name} \u2014 is it a supported version?`);
+    }
+    return fn.call(router, args);
+  };
+  const proxyTon = ptonNs.create(Address3.parse(route.ptonMaster));
+  const userWalletAddress = p.wallet.contract.address;
+  const offerAmount = BigInt(p.quote.from.amount);
+  const minAskAmount = BigInt(route.minAskUnits);
+  let txParams;
+  try {
+    if (route.fromIsNative) {
+      txParams = await call("getSwapTonToJettonTxParams", {
+        userWalletAddress,
+        proxyTon,
+        offerAmount,
+        askJettonAddress: Address3.parse(route.askMaster),
+        minAskAmount
+      });
+    } else if (route.toIsNative) {
+      txParams = await call("getSwapJettonToTonTxParams", {
+        userWalletAddress,
+        proxyTon,
+        offerJettonAddress: Address3.parse(route.offerMaster),
+        offerAmount,
+        minAskAmount
+      });
+    } else {
+      txParams = await call("getSwapJettonToJettonTxParams", {
+        userWalletAddress,
+        offerJettonAddress: Address3.parse(route.offerMaster),
+        askJettonAddress: Address3.parse(route.askMaster),
+        offerAmount,
+        minAskAmount
+      });
+    }
+  } catch (err) {
+    throw new Error(`TON: STON.fi could not build this swap message. Nothing was sent. (${String(err).slice(0, 160)})`, {
+      cause: err
+    });
+  }
+  try {
+    const hash = await p.send({
+      to: String(txParams.to),
+      value: BigInt(txParams.value),
+      body: txParams.body
+    });
+    return {
+      transaction: hash,
+      network: p.quote.network,
+      source: p.quote.source,
+      from: p.quote.from,
+      to: p.quote.to
+    };
+  } catch (err) {
+    const msg = String(err?.message ?? err);
+    if (/not enough|insufficient|balance|inbound message/i.test(msg)) {
+      throw new InsufficientFundsError(
+        `TON swap could not be sent: the wallet cannot cover the offer plus the attached forward gas (${formatUnits(BigInt(route.forwardGas), TON_DECIMALS)} TON is attached, most of which bounces back). (${msg.slice(0, 140)})`,
+        { cause: err }
+      );
+    }
+    throw err;
+  }
+}
+
 // src/drivers/ton/wallet.ts
 import { mnemonicToWalletKey, mnemonicValidate } from "@ton/crypto";
 import { WalletContractV4, WalletContractV5R1 } from "@ton/ton";
@@ -363,6 +540,26 @@ function makeTonNetwork(preset, rpcUrl) {
       const detail = accept.asset === "native" ? `~0.01 ${TON_NATIVE_SYMBOL} network fee` : `~0.05 ${TON_NATIVE_SYMBOL} attached for the jetton transfer (leftover refunded)`;
       return nativeCost({ symbol: TON_NATIVE_SYMBOL, decimals: TON_DECIMALS, fee, basis: "heuristic", detail });
     },
+    /**
+     * The bound wallet's own address — where THIS wallet gets paid. Derived from the key
+     * material only: no RPC, nothing moved. See {@link ResolvedNetwork.addressOf}.
+     *
+     * 🔴 NON-BOUNCEABLE (`UQ…`), which is not the default `toString()` gives.
+     *
+     * TON encodes one account two ways. A bounceable `EQ…` address returns the funds to the
+     * sender if the destination contract is not initialised, and a wallet contract is not
+     * initialised until it has sent its first transaction. So a freshly generated agent wallet
+     * advertising `EQ…` would have its FIRST payment bounce, which is exactly the payment a new
+     * seller most needs to land. `UQ…` is also what every TON wallet shows you as your receive
+     * address, so this matches what the operator sees and what the wallet file records.
+     *
+     * Verification is unaffected either way: `Address.parse` accepts both forms and they are the
+     * same account.
+     */
+    async addressOf(wallet) {
+      const { contract } = await resolveTonWallet(wallet._native);
+      return contract.address.toString({ bounceable: false });
+    },
     async balanceOf(wallet, asset) {
       let owner;
       try {
@@ -386,6 +583,51 @@ function makeTonNetwork(preset, rpcUrl) {
     async recipientReady() {
       return { ready: "n/a" };
     },
+    /* ---- swap (OPTIONAL, opt-in): via STON.fi, keyless + no added fee. See ./swap.ts ---- */
+    async quoteSwap({ from, to, wantAmount, slippageBps }) {
+      return quoteTonSwap({ network, from, to, wantAmount, slippageBps });
+    },
+    async swap(wallet, quote) {
+      const tw = await resolveTonWallet(wallet._native);
+      return swapTon({
+        client,
+        wallet: tw,
+        quote,
+        /*
+         * TON settles asynchronously, so "sent" and "arrived" are different questions. This
+         * waits for the WALLET's seqno to advance (its external message was accepted and
+         * sent), then reports the resulting wallet transaction hash so the caller has a real,
+         * checkable reference. Whether the ask side landed is a balance question, exactly as
+         * it is on the payment path.
+         */
+        send: async ({ to, value, body }) => {
+          const opened = client.open(tw.contract);
+          const seqno = await opened.getSeqno();
+          await opened.sendTransfer({
+            seqno,
+            secretKey: tw.keyPair.secretKey,
+            sendMode: SendMode2.PAY_GAS_SEPARATELY | SendMode2.IGNORE_ERRORS,
+            messages: [internal2({ to: Address2.parse(to), value, bounce: true, body })]
+          });
+          for (let i = 0; i < 30; i += 1) {
+            await new Promise((r) => setTimeout(r, 2e3));
+            try {
+              if (await opened.getSeqno() > seqno) break;
+            } catch {
+              continue;
+            }
+          }
+          try {
+            const txs = await client.getTransactions(tw.contract.address, { limit: 10 });
+            const mine = txs?.find((t) => t?.inMessage?.info?.type === "external-in");
+            const h = mine?.hash?.();
+            if (h) return Buffer.from(h).toString("hex");
+          } catch {
+          }
+          return `ton:${tw.contract.address.toString()}|seqno:${seqno}`;
+        }
+      });
+    },
     async verify(_ref, accept) {
       let watch;
       try {