@anywalletkit/wallet-ton 0.2.5 → 0.3.0

package/README.md

@@ -56,10 +56,18 @@ const tk = await WalletManagerTon.fromTonMnemonic(words, { tonClient })
    an aborted transaction, a failed action phase or a failed **first-hop**
    internal message (the operation would bounce) throws `SimulationError`
    **before signing**; failures deeper in the trace are `warnings`. tonapi's
-   `risk` is returned as `risk` and a body that would carry the whole balance
-   (send mode 128) is refused with `UnsafeTransactionError('drain')` unless
-   `allowDrainingTransactions`. `emulate: false` keeps only `estimateFee`;
-   `simulate: false` skips the preflight entirely.
+   `risk` is returned as `risk`. A message with send mode 128 (the whole
+   remaining balance) or 32 (the account destroyed once empty) is refused with
+   `UnsafeTransactionError('drain')` unless `allowDrainingTransactions` — checked
+   locally before any emulation, prebuilt bodies too, and again on tonapi's risk.
+   `describeTransaction` shows each message's `mode`. `emulate: false` keeps only
+   `estimateFee`; `simulate: false` skips the preflight entirely (not the mode check).
+   A jetton transfer's recipient and response destination get the same network
+   (test-only flag) and workchain checks as a native transfer.
+   A broadcast with no definitive answer (no response, a timeout, a non-JSON body)
+   throws `BroadcastUnknownError` (`maybeSent`, `hash` = the body hash): do not sign
+   again (the next seqno would pay twice); a node's `ok: false` stays a `NetworkError`.
+   A custom `TonRpc` should mark refusals `answered: true` (`isAnsweredRefusal`).
 4. noble ed25519 over the body hash; the 32-byte seed is the only key material
    and `dispose()` zeroizes it.
 5. `sendBoc` of the external (with StateInit when the wallet is not deployed).

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  BroadcastUnknownError: () => BroadcastUnknownError,
   CAIP2: () => CAIP2,
   DEFAULT_SEND_MODE: () => DEFAULT_SEND_MODE,
   DEFAULT_TONAPI: () => DEFAULT_TONAPI,
@@ -53,6 +54,7 @@ __export(src_exports, {
   emulateViaTonapi: () => emulateViaTonapi,
   encodeHistoryCursor: () => encodeCursor,
   installBufferGlobal: () => installBufferGlobal,
+  isAnsweredRefusal: () => isAnsweredRefusal,
   mapTonapiActions: () => mapActions,
   mapTonapiEvent: () => mapTonapiEvent,
   mapToncenterTransaction: () => mapToncenterTransaction,
@@ -118,6 +120,17 @@ var SimulationError = class extends Error {
     this.aborted = details.aborted ?? false;
   }
 };
+var BroadcastUnknownError = class extends Error {
+  /** Always true: the transaction may be on its way. */
+  maybeSent = true;
+  /** Hex hash of the signed body. */
+  hash;
+  constructor(hash, cause) {
+    super(`Broadcast outcome unknown for ${hash}: ${cause instanceof Error ? cause.message.slice(0, 200) : String(cause).slice(0, 200)}`, { cause });
+    this.name = "BroadcastUnknownError";
+    this.hash = hash;
+  }
+};
 
 // src/toncenter.ts
 var import_core2 = require("@anywalletkit/core");
@@ -155,12 +168,15 @@ function tonCenterEndpoint(endpoint, opts = {}) {
       }
       if (!res.ok || json.ok !== true) {
         const detail = typeof json.error === "string" ? json.error : JSON.stringify(json.error ?? json);
-        throw new import_core2.NetworkError(`${method}: ${detail} (HTTP ${res.status})`, { provider: url });
+        throw Object.assign(new import_core2.NetworkError(`${method}: ${detail} (HTTP ${res.status})`, { provider: url }), { answered: true });
       }
       return json.result;
     }
   };
 }
+function isAnsweredRefusal(e) {
+  return e?.answered === true;
+}
 function createTonRpc(config) {
   const target = config.tonClient ?? config.provider;
   if (target === void 0) return void 0;
@@ -173,14 +189,17 @@ function createTonRpc(config) {
   return {
     async call(method, params) {
       let lastError;
+      let answered = true;
       for (let i = 0; i < attempts; i++) {
         try {
           return await list[i % list.length].call(method, params);
         } catch (e) {
           lastError = e;
+          answered &&= isAnsweredRefusal(e);
         }
       }
-      throw new import_core2.NetworkError(`All TON endpoints failed for ${method}`, { cause: lastError });
+      const err = new import_core2.NetworkError(`All TON endpoints failed for ${method}`, { cause: lastError });
+      throw answered ? Object.assign(err, { answered: true }) : err;
     }
   };
 }
@@ -707,6 +726,19 @@ function describeOne(i, to, value, body, hasStateInit, bounceableOverride, warni
   return item;
 }
 var hex = (n) => `0x${n.toString(16).padStart(8, "0")}`;
+var IGNORE_ERRORS = 2;
+function sendModeOf(sendMode) {
+  return (sendMode ?? DEFAULT_SEND_MODE) | IGNORE_ERRORS;
+}
+function drainModes(mode) {
+  return [...(mode & 128) !== 0 ? ["carries-all-balance"] : [], ...(mode & 32) !== 0 ? ["destroys-account"] : []];
+}
+function withMode(i, item, mode, warnings) {
+  for (const code of drainModes(mode)) {
+    warnings.push({ code, message: code === "carries-all-balance" ? "send mode 128: the message carries the whole remaining balance" : "send mode 32: the wallet account is destroyed once it is empty", index: i });
+  }
+  return { ...item, mode };
+}
 function describeMessageRelaxed(i, m, warnings, ctx = {}) {
   if (m.info.type !== "internal") {
     warnings.push({ code: "unknown-body", message: "not an internal message", index: i });
@@ -728,7 +760,7 @@ function describeTransaction(tx, ctx = {}) {
       return { kind: "contract-call", items, warnings };
     }
     external2 = { seqno: parsed.seqno, validUntil: parsed.validUntil, walletId: parsed.walletId, signed: parsed.signed };
-    parsed.messages.forEach((m, i) => items.push(describeMessageRelaxed(i, m.message, warnings, ctx)));
+    parsed.messages.forEach((m, i) => items.push(withMode(i, describeMessageRelaxed(i, m.message, warnings, ctx), m.mode, warnings)));
   } else {
     const list = Array.isArray(tx) ? tx : [tx];
     list.forEach((t, i) => {
@@ -746,7 +778,7 @@ function describeTransaction(tx, ctx = {}) {
       } catch {
         warnings.push({ code: "unknown-body", message: "bodyBoc is not a valid BoC", index: i });
       }
-      items.push(describeOne(i, to, BigInt(t.value), body, t.stateInit !== void 0, t.bounceable, warnings, ctx));
+      items.push(withMode(i, describeOne(i, to, BigInt(t.value), body, t.stateInit !== void 0, t.bounceable, warnings, ctx), sendModeOf(t.sendMode), warnings));
     });
   }
   const kinds = new Set(items.map((x) => x.kind));
@@ -852,25 +884,34 @@ var WalletAccountReadOnlyTon = class {
     if (src instanceof import_core8.Cell) return (0, import_core8.loadStateInit)(src.beginParse());
     return src;
   }
-  transactionMessage(tx) {
-    const value = big(tx.value);
-    if (value <= 0n) throw new UnsafeTransactionError("zero-value", "TON message value must be positive.");
+  /**
+   * A destination address with the checks every payment gets: workchain 0 or -1, and a friendly
+   * address's test-only flag matching the wallet's network. Used for a native message's `to` and a
+   * jetton transfer's recipient and response destination (round 3, L8).
+   */
+  checkedAddress(to) {
     let address;
     let bounceable = true;
     let testOnly;
-    if (import_core8.Address.isFriendly(tx.to)) {
-      const f = import_core8.Address.parseFriendly(tx.to);
+    if (import_core8.Address.isFriendly(to)) {
+      const f = import_core8.Address.parseFriendly(to);
       address = f.address;
       bounceable = f.isBounceable;
       testOnly = f.isTestOnly;
     } else {
-      address = import_core8.Address.parse(tx.to);
+      address = import_core8.Address.parse(to);
     }
     if (address.workChain !== 0 && address.workChain !== -1) throw new UnsafeTransactionError("exotic-workchain", `Refusing to send to workchain ${address.workChain}.`);
     const testnet = this._config.network === "testnet";
     if (testOnly !== void 0 && testOnly !== testnet) {
       throw new UnsafeTransactionError("network-mismatch", testOnly ? "Test-only address on a mainnet wallet." : "Mainnet address on a testnet wallet.");
     }
+    return { address, bounceable };
+  }
+  transactionMessage(tx) {
+    const value = big(tx.value);
+    if (value <= 0n) throw new UnsafeTransactionError("zero-value", "TON message value must be positive.");
+    const { address, bounceable } = this.checkedAddress(tx.to);
     const body = tx.body instanceof import_core8.Cell ? tx.body : typeof tx.body === "string" ? tx.body === "" ? void 0 : commentCell(tx.body) : tx.bodyBoc ? import_core8.Cell.fromBase64(tx.bodyBoc) : void 0;
     const init = this.stateInitOf(tx.stateInit);
     const message = (0, import_core8.internal)({ to: address, value, bounce: tx.bounceable ?? bounceable, ...body ? { body } : {}, ...init ? { init } : {} });
@@ -879,14 +920,15 @@ var WalletAccountReadOnlyTon = class {
   async jettonTransferMessage(o) {
     const amount = big(o.amount);
     if (amount <= 0n) throw new UnsafeTransactionError("zero-value", "Jetton amount must be positive.");
-    const recipient = import_core8.Address.parse(o.recipient);
+    const recipient = this.checkedAddress(o.recipient).address;
+    const response = o.responseDestination ? this.checkedAddress(o.responseDestination).address : void 0;
     const jw = await this.getJettonWalletAddress(o.token);
     await this.jettonWalletData(o.token, jw);
     const forwardTonAmount = o.forwardTonAmount !== void 0 ? big(o.forwardTonAmount) : 1n;
     if (o.memo !== void 0 && o.forwardPayload !== void 0) throw new UnsafeTransactionError("memo-and-payload", "Pass either memo or forwardPayload, not both: a jetton transfer carries one forward payload.");
     const payload = o.forwardPayload ?? o.memo;
     const forwardPayload = payload === void 0 ? null : typeof payload === "string" ? commentCell(payload) : payload;
-    const body = (0, import_core8.beginCell)().storeUint(JETTON_TRANSFER_OP2, 32).storeUint(o.queryId !== void 0 ? BigInt(o.queryId) : randomQueryId(), 64).storeCoins(amount).storeAddress(recipient).storeAddress(o.responseDestination ? import_core8.Address.parse(o.responseDestination) : this._address).storeMaybeRef(o.customPayload ?? null).storeCoins(forwardTonAmount).storeMaybeRef(forwardPayload).endCell();
+    const body = (0, import_core8.beginCell)().storeUint(JETTON_TRANSFER_OP2, 32).storeUint(o.queryId !== void 0 ? BigInt(o.queryId) : randomQueryId(), 64).storeCoins(amount).storeAddress(recipient).storeAddress(response ?? this._address).storeMaybeRef(o.customPayload ?? null).storeCoins(forwardTonAmount).storeMaybeRef(forwardPayload).endCell();
     const attached = o.attachedValue !== void 0 ? big(o.attachedValue) : (this._config.jettonAttachedValue !== void 0 ? big(this._config.jettonAttachedValue) : DEFAULT_JETTON_ATTACHED) + forwardTonAmount;
     return { message: (0, import_core8.internal)({ to: jw, value: attached, bounce: true, body }) };
   }
@@ -1143,7 +1185,22 @@ var WalletAccountTon = class _WalletAccountTon extends WalletAccountReadOnlyTon
    * Checks → seqno → preflight → signed body. The preflight runs on the
    * zero-signed body (ignore_chksig), so nothing is signed before it passes.
    */
+  /**
+   * Refuse send modes that drain the wallet — 128 (the whole remaining balance) and 32 (the account
+   * destroyed once empty) — unless `allowDrainingTransactions`. Checked locally, before any seqno or
+   * emulation, so it holds with `simulate: false` too (round 3, M11); the emulation check stays.
+   */
+  assertNoDrain(modes) {
+    if (this._config.allowDrainingTransactions === true) return;
+    const found = modes.flatMap(drainModes);
+    if (found.length) throw new UnsafeTransactionError("drain", `Refusing a message with send mode ${found.includes("carries-all-balance") ? "128 (it carries the whole remaining balance)" : "32 (it destroys the wallet account once empty)"}; set allowDrainingTransactions to override.`);
+  }
+  /** The send modes of a prebuilt V5R1 body; an unreadable body is left to the emulation and the node. */
+  bodyModes(body) {
+    return parseV5R1Body(body)?.messages.map((m) => m.mode) ?? [];
+  }
   async signMessages(messages, limit, op) {
+    this.assertNoDrain(messages.map((m) => sendModeOf(m.mode)));
     const want = messages.reduce((sum, m) => sum + (m.message.info.type === "internal" ? m.message.info.value.coins : 0n), 0n);
     if (want > 0n) {
       const balance = await this.getBalance();
@@ -1175,6 +1232,7 @@ var WalletAccountTon = class _WalletAccountTon extends WalletAccountReadOnlyTon
   /** Sign without broadcasting. Returns the external-message BODY as base64 BoC (pass it back to sendTransaction as a Cell). */
   async signTransaction(tx, options = {}) {
     if (tx instanceof import_core10.Cell) {
+      this.assertNoDrain(this.bodyModes(tx));
       await this.preflight(tx, (0, import_core9.feeLimit)(this._config.transactionMaxFee, options), "transaction");
       return tx.toBoc().toString("base64");
     }
@@ -1184,12 +1242,19 @@ var WalletAccountTon = class _WalletAccountTon extends WalletAccountReadOnlyTon
   async broadcast(body) {
     const rpc = this.requireRpc("send transactions");
     const init = await this.initIfNeeded();
-    await rpc.sendBoc(v5r1ExternalMessage(this._address, body, init));
-    return body.hash().toString("hex");
+    const hash = body.hash().toString("hex");
+    try {
+      await rpc.sendBoc(v5r1ExternalMessage(this._address, body, init));
+    } catch (e) {
+      if (isAnsweredRefusal(e)) throw e;
+      throw new BroadcastUnknownError(hash, e);
+    }
+    return hash;
   }
   /** Sign and broadcast; `hash` is the body hash (hex) — resolve it with getTransactionReceipt. */
   async sendTransaction(tx, options = {}) {
     this.requireRpc("send transactions");
+    if (tx instanceof import_core10.Cell) this.assertNoDrain(this.bodyModes(tx));
     const { body, fee } = tx instanceof import_core10.Cell ? { body: tx, fee: await this.preflight(tx, (0, import_core9.feeLimit)(this._config.transactionMaxFee, options), "transaction") } : await this.signMessages(this.toMessages(tx), (0, import_core9.feeLimit)(this._config.transactionMaxFee, options), "transaction");
     return { hash: await this.broadcast(body), fee };
   }
@@ -1228,6 +1293,7 @@ var WalletManagerTon = class _WalletManagerTon extends import_core11.WalletManag
   static async fromTonMnemonic(words, config = {}) {
     const list = (Array.isArray(words) ? words : words.trim().split(/\s+/)).map((w) => w.toLowerCase());
     if (list.length !== 24) throw new Error("A TON mnemonic has 24 words.");
+    if (!await (0, import_crypto.mnemonicValidate)(list)) throw new Error("Not a valid TON mnemonic: check the words (a typo would open a different, empty wallet).");
     const pair = await (0, import_crypto.mnemonicToPrivateKey)(list);
     const privateKey = new Uint8Array(pair.secretKey.subarray(0, 32));
     const publicKey = new Uint8Array(pair.publicKey);