@mystars-tg/faas-wallet 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MyStars.tg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# @mystars-tg/faas-wallet
+
+[![npm](https://img.shields.io/npm/v/@mystars-tg/faas-wallet.svg)](https://www.npmjs.com/package/@mystars-tg/faas-wallet) [![license](https://img.shields.io/npm/l/@mystars-tg/faas-wallet.svg)](LICENSE)
+
+Opt-in TON wallet + payer for [`@mystars-tg/faas-sdk`](https://www.npmjs.com/package/@mystars-tg/faas-sdk).
+**Node only.** Generate or import a TON wallet, read balances, and pay a FaaS order invoice (TON or
+USDT) from **your own** wallet.
+
+📖 API reference: **[mystars.tg/docs](https://mystars.tg/docs)** · core client: [`@mystars-tg/faas-sdk`](https://www.npmjs.com/package/@mystars-tg/faas-sdk).
+
+> **Key custody:** keys live only in process memory. This package never writes a mnemonic or secret
+> key to disk, never logs it, and never sends it anywhere. `generate()` returns the mnemonic exactly
+> once — storing it securely is your responsibility. Payments move **your** funds from **your** wallet
+> to the MyStars treasury invoice; the SDK never touches your keys beyond signing in memory.
+
+## Install
+
+```bash
+npm install @mystars-tg/faas-sdk @mystars-tg/faas-wallet
+```
+
+## One-call fulfilment
+
+```ts
+import { MyStarsClient } from "@mystars-tg/faas-sdk";
+import { TonWallet, ToncenterRpc, fulfill } from "@mystars-tg/faas-wallet";
+
+// 1. Create (or import) a funding wallet and fund its address with TON/USDT.
+const { wallet, mnemonic } = await TonWallet.generate(); // STORE `mnemonic` securely
+console.log("Fund this address:", wallet.address);
+
+// 2. Wire a client + an RPC.
+const client = MyStarsClient.production(process.env.MYSTARS_API_KEY!);
+const rpc = new ToncenterRpc({ endpoint: "https://toncenter.com/api/v2/jsonRPC", apiKey: process.env.TONCENTER_KEY });
+
+// 3. create → pay → wait, in one call.
+//    A STABLE idempotencyKey is REQUIRED — see the retry-hazard note below.
+const order = await fulfill(
+  client, wallet,
+  { type: "stars", recipient: { username: "durov" }, quantity: 100 },
+  { rpc, idempotencyKey: `order-${myOrderId}` },
+);
+console.log(order.status, order.purchase_tx);
+```
+
+## ⚠️ Retry hazard — `fulfill()` moves real money
+
+`fulfill()` broadcasts a **real on-chain payment**. A naive retry of a `fulfill` that already paid
+would create a SECOND order and pay it AGAIN (double-spend). Two safeguards make retries safe, and the
+first is **mandatory**:
+
+1. **A stable `idempotencyKey` is required** (`opts.idempotencyKey`, or `createOptions.idempotencyKey`).
+   Derive it from your own order id so re-running `fulfill` reuses the same key — the server returns the
+   SAME order (idempotent replay) instead of minting a duplicate. `fulfill` throws a
+   `MyStarsValidationError` before creating or paying if you omit it.
+2. **It only broadcasts when the order still needs payment.** If the (replayed) order has already
+   advanced past `awaiting_payment`, `fulfill` skips the payment and just waits — so a retry never
+   double-pays an order whose first payment already landed.
+
+If anything throws after the order exists, the error carries `order_id` — read it with the type-safe
+`orderIdFromError(err)` accessor and re-attach instead of re-running `fulfill`:
+
+```ts
+import { fulfill, orderIdFromError } from "@mystars-tg/faas-wallet";
+
+try {
+  await fulfill(client, wallet, params, { rpc, idempotencyKey: `order-${myOrderId}` });
+} catch (err) {
+  const orderId = orderIdFromError(err);
+  if (orderId) {
+    // Payment may have been broadcast — re-attach, do NOT re-run fulfill.
+    await client.waitForOrder(orderId); // resolves once the order is terminal
+  }
+  throw err;
+}
+```
+
+## Step by step
+
+```ts
+import { TonWallet, OrderPayer, ToncenterRpc } from "@mystars-tg/faas-wallet";
+
+const wallet = await TonWallet.fromMnemonic(mnemonic);
+const rpc = new ToncenterRpc({ endpoint: "https://toncenter.com/api/v2/jsonRPC" });
+
+const balance = await wallet.getBalance(rpc);           // nanoTON
+const usdt = await wallet.getJettonBalance(rpc, USDT_MASTER); // micro-USDT
+
+const order = await client.createOrder({ type: "stars", recipient: { username: "durov" }, quantity: 100, payment_currency: "usdt_ton" });
+await new OrderPayer(wallet).payOrder(order, { rpc }); // signs once + broadcasts
+const final = await client.waitForOrder(order.order_id);
+```
+
+`TonWallet` currently creates **WalletContractV4** wallets — fund the `address` it produces. For a
+custom signer (keys in an HSM, never in the SDK), build the TON Connect message with the core SDK's
+`buildTonConnectMessages` instead and sign it yourself.

package/dist/index.cjs

@@ -0,0 +1,291 @@
+'use strict';
+
+var crypto = require('@ton/crypto');
+var ton = require('@ton/ton');
+var core = require('@ton/core');
+var faasSdk = require('@mystars-tg/faas-sdk');
+
+// src/wallet.ts
+var WalletError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var InsufficientBalanceError = class extends WalletError {
+};
+var TonWallet = class _TonWallet {
+  /** The in-memory key pair. Treat `secretKey` as a secret — never log or persist it. */
+  keyPair;
+  contract;
+  constructor(keyPair) {
+    const contract = ton.WalletContractV4.create({ workchain: 0, publicKey: keyPair.publicKey });
+    Object.defineProperty(this, "keyPair", { value: keyPair, enumerable: false });
+    Object.defineProperty(this, "contract", { value: contract, enumerable: false });
+  }
+  /** Redacted serialization — NEVER exposes the secret key. */
+  toJSON() {
+    return { address: this.address, publicKey: this.keyPair.publicKey.toString("hex") };
+  }
+  /** Redacted console.log/util.inspect output. */
+  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
+    return `TonWallet<${this.address}>`;
+  }
+  /**
+   * Generate a NEW wallet. Returns the 24-word mnemonic ONCE — store it securely;
+   * it is never persisted.
+   *
+   * @returns the in-memory `wallet` and its `mnemonic` (the only time you see it)
+   * @example
+   * ```ts
+   * const { wallet, mnemonic } = await TonWallet.generate();
+   * await secureVault.store(mnemonic);     // YOUR job — it is never written to disk by the SDK
+   * console.log("fund this:", wallet.address);
+   * ```
+   */
+  static async generate() {
+    const mnemonic = await crypto.mnemonicNew();
+    return { wallet: await _TonWallet.fromMnemonic(mnemonic), mnemonic };
+  }
+  /** Import a wallet from its 24-word mnemonic. */
+  static async fromMnemonic(words) {
+    if (!await crypto.mnemonicValidate(words)) throw new WalletError("invalid TON mnemonic");
+    const keyPair = await crypto.mnemonicToPrivateKey(words);
+    return new _TonWallet(keyPair);
+  }
+  /** Import a wallet from a raw Ed25519 key pair. */
+  static fromKeyPair(publicKey, secretKey) {
+    return new _TonWallet({ publicKey: Buffer.from(publicKey), secretKey: Buffer.from(secretKey) });
+  }
+  /** Friendly, non-bounceable (`UQ…`) address — FUND THIS to pay invoices. */
+  get address() {
+    return this.contract.address.toString({ bounceable: false });
+  }
+  /** Raw `0:hex` address form. */
+  get rawAddress() {
+    return this.contract.address.toRawString();
+  }
+  /** @internal The contract's StateInit, needed for the first (deploying) transfer. */
+  get init() {
+    return this.contract.init;
+  }
+  /** @internal The contract address as a TON `Address`. */
+  get tonAddress() {
+    return this.contract.address;
+  }
+  /** @internal Sign a transfer body. */
+  createTransfer(args) {
+    return this.contract.createTransfer({ ...args, secretKey: this.keyPair.secretKey });
+  }
+  /**
+   * This wallet's native TON balance.
+   *
+   * @param rpc - the RPC to query through
+   * @returns the balance in nanoTON
+   */
+  getBalance(rpc) {
+    return rpc.getBalance(this.address);
+  }
+  /**
+   * This wallet's current sequence number.
+   *
+   * @param rpc - the RPC to query through
+   * @returns the seqno (`0` when the wallet contract isn't deployed yet)
+   */
+  getSeqno(rpc) {
+    return rpc.getSeqno(this.address);
+  }
+  /**
+   * This wallet's balance of a given jetton (e.g. USDT).
+   *
+   * @param rpc - the RPC to query through
+   * @param jettonMaster - the jetton master address (e.g. `DEFAULT_USDT_MASTER` from `@mystars-tg/faas-wallet`)
+   * @returns the token balance in the jetton's smallest unit (micro-USDT for USDT)
+   */
+  async getJettonBalance(rpc, jettonMaster) {
+    const jettonWallet = await rpc.resolveJettonWallet(this.address, jettonMaster);
+    return rpc.getJettonBalance(jettonWallet);
+  }
+};
+var DEFAULT_USDT_MASTER = "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs";
+var DEFAULT_JETTON_GAS_TON = "0.05";
+var NETWORK_FEE_RESERVE = core.toNano("0.02");
+function commentCell(memo) {
+  return core.beginCell().storeUint(0, 32).storeStringTail(memo).endCell();
+}
+var OrderPayer = class {
+  wallet;
+  /** @param wallet - the funded {@link TonWallet} whose own funds will pay invoices */
+  constructor(wallet) {
+    this.wallet = wallet;
+  }
+  /**
+   * Plan the internal message(s) for an order WITHOUT signing or broadcasting.
+   * `ton` is pure; `usdt_ton` resolves the payer's jetton wallet via `rpc`.
+   */
+  async planMessages(payment, opts) {
+    if (!payment.pay_to_address) throw new WalletError("payment.pay_to_address is missing");
+    if (!payment.memo) throw new WalletError("payment.memo is missing");
+    if (payment.currency === "ton") {
+      const value = core.toNano(payment.amount);
+      if (value <= 0n) {
+        throw new faasSdk.MyStarsValidationError(`payment amount must be positive, got "${payment.amount}"`);
+      }
+      return [{ to: payment.pay_to_address, value, body: commentCell(payment.memo), bounce: false }];
+    }
+    const microAmount = faasSdk.toMicro(payment.amount);
+    if (microAmount <= 0n) {
+      throw new faasSdk.MyStarsValidationError(`payment amount must be positive, got "${payment.amount}"`);
+    }
+    const jettonMaster = opts.jettonMaster ?? DEFAULT_USDT_MASTER;
+    const jettonWallet = await opts.rpc.resolveJettonWallet(this.wallet.address, jettonMaster);
+    const body = core.beginCell().storeUint(faasSdk.JETTON_TRANSFER_OP, 32).storeUint(0n, 64).storeCoins(microAmount).storeAddress(core.Address.parse(payment.pay_to_address)).storeAddress(this.wallet.tonAddress).storeBit(false).storeCoins(0n).storeBit(true).storeRef(commentCell(payment.memo)).endCell();
+    return [
+      { to: jettonWallet, value: core.toNano(opts.jettonGasTon ?? DEFAULT_JETTON_GAS_TON), body, bounce: true }
+    ];
+  }
+  /** Throw `InsufficientBalanceError` if the wallet can't cover the planned payment + gas. */
+  async assertFunded(payment, planned, rpc) {
+    const tonBalance = await rpc.getBalance(this.wallet.address);
+    const first = planned[0];
+    if (payment.currency === "ton") {
+      const need = first.value + NETWORK_FEE_RESERVE;
+      if (tonBalance < need) {
+        throw new InsufficientBalanceError(`insufficient TON: balance ${tonBalance} < required ~${need} (nanoTON)`);
+      }
+      return;
+    }
+    const gasNeed = first.value + NETWORK_FEE_RESERVE;
+    if (tonBalance < gasNeed) {
+      throw new InsufficientBalanceError(`insufficient TON for jetton gas: balance ${tonBalance} < required ~${gasNeed} (nanoTON)`);
+    }
+    const jettonBalance = await rpc.getJettonBalance(first.to);
+    const micro = faasSdk.toMicro(payment.amount);
+    if (jettonBalance < micro) {
+      throw new InsufficientBalanceError(`insufficient USDT: balance ${jettonBalance} < required ${micro} (micro-USDT)`);
+    }
+  }
+  /**
+   * Build, sign, and broadcast the payment for an order. Signs exactly ONCE.
+   *
+   * MONEY: this broadcasts a real on-chain transfer of the wallet's OWN funds.
+   * It is not idempotent — calling it twice for the same order pays twice. Guard
+   * retries at the order layer (a stable `Idempotency-Key` on `createOrder`, or
+   * use `fulfill` which only pays an order still `awaiting_payment`).
+   *
+   * @param order - a `CreateOrderResult`, or any object carrying a `payment` block (and optional `order_id`)
+   * @param opts - the {@link PayOrderOptions} (at minimum `rpc`)
+   * @returns the {@link PayOrderResult} — `from`/`to` addresses and the smallest-unit amount sent
+   * @throws `WalletError` if the order's `payment` block is missing `pay_to_address`/`memo`
+   * @throws `MyStarsValidationError` if the amount is non-positive
+   * @throws {@link InsufficientBalanceError} if the wallet can't cover the payment + gas (unless `skipBalanceCheck`)
+   */
+  async payOrder(order, opts) {
+    const payment = order.payment;
+    const planned = await this.planMessages(payment, opts);
+    if (!opts.skipBalanceCheck) await this.assertFunded(payment, planned, opts.rpc);
+    const seqno = await opts.rpc.getSeqno(this.wallet.address);
+    const messages = planned.map(
+      (m) => core.internal({ to: core.Address.parse(m.to), value: m.value, body: m.body, bounce: m.bounce })
+    );
+    const timeout = Math.floor((opts.now ?? Date.now()) / 1e3) + (opts.validForSeconds ?? 120);
+    const transfer = this.wallet.createTransfer({ seqno, messages, sendMode: core.SendMode.PAY_GAS_SEPARATELY, timeout });
+    const ext = core.external({
+      to: this.wallet.tonAddress,
+      init: seqno === 0 ? this.wallet.init : void 0,
+      body: transfer
+    });
+    const boc = core.beginCell().store(core.storeMessage(ext)).endCell().toBoc();
+    await opts.rpc.sendBoc(boc);
+    const first = planned[0];
+    return {
+      orderId: order.order_id,
+      from: this.wallet.address,
+      to: first.to,
+      amountSmallestUnit: (payment.currency === "ton" ? core.toNano(payment.amount) : faasSdk.toMicro(payment.amount)).toString()
+    };
+  }
+};
+var ToncenterRpc = class {
+  client;
+  /** @param opts - the {@link ToncenterRpcOptions} (endpoint + optional API key) */
+  constructor(opts) {
+    this.client = new ton.TonClient(opts.apiKey ? { endpoint: opts.endpoint, apiKey: opts.apiKey } : { endpoint: opts.endpoint });
+  }
+  /** {@inheritDoc TonRpc.getBalance} */
+  getBalance(address) {
+    return this.client.getBalance(core.Address.parse(address));
+  }
+  /** {@inheritDoc TonRpc.getSeqno} */
+  async getSeqno(address) {
+    const addr = core.Address.parse(address);
+    if (!await this.client.isContractDeployed(addr)) return 0;
+    const res = await this.client.runMethod(addr, "seqno");
+    return res.stack.readNumber();
+  }
+  /** {@inheritDoc TonRpc.resolveJettonWallet} */
+  async resolveJettonWallet(owner, jettonMaster) {
+    const res = await this.client.runMethod(core.Address.parse(jettonMaster), "get_wallet_address", [
+      { type: "slice", cell: core.beginCell().storeAddress(core.Address.parse(owner)).endCell() }
+    ]);
+    return res.stack.readAddress().toString();
+  }
+  /** {@inheritDoc TonRpc.getJettonBalance} */
+  async getJettonBalance(jettonWallet) {
+    const res = await this.client.runMethod(core.Address.parse(jettonWallet), "get_wallet_data");
+    return res.stack.readBigNumber();
+  }
+  /** {@inheritDoc TonRpc.sendBoc} */
+  async sendBoc(boc) {
+    await this.client.sendFile(Buffer.from(boc));
+  }
+};
+function withOrderId(err, orderId) {
+  if (err && typeof err === "object" && err.order_id === void 0) {
+    try {
+      err.order_id = orderId;
+    } catch {
+    }
+  }
+  return err;
+}
+function orderIdFromError(err) {
+  if (err && typeof err === "object") {
+    const id = err.order_id;
+    if (typeof id === "string") return id;
+  }
+  return void 0;
+}
+async function fulfill(client, wallet, params, opts) {
+  const idempotencyKey = opts.idempotencyKey ?? opts.createOptions?.idempotencyKey;
+  if (!idempotencyKey) {
+    throw new faasSdk.MyStarsValidationError(
+      "fulfill() requires a stable idempotencyKey (opts.idempotencyKey or createOptions.idempotencyKey), derived from your own order id \u2014 without it a retry would create a duplicate order and broadcast a second payment"
+    );
+  }
+  const createOptions = { ...opts.createOptions, idempotencyKey };
+  const order = await client.createOrder(params, createOptions);
+  try {
+    if (order.status === "awaiting_payment") {
+      await new OrderPayer(wallet).payOrder(order, opts);
+    }
+  } catch (err) {
+    throw withOrderId(err, order.order_id);
+  }
+  try {
+    return await client.waitForOrder(order.order_id, opts.wait);
+  } catch (err) {
+    throw withOrderId(err, order.order_id);
+  }
+}
+
+exports.DEFAULT_JETTON_GAS_TON = DEFAULT_JETTON_GAS_TON;
+exports.DEFAULT_USDT_MASTER = DEFAULT_USDT_MASTER;
+exports.InsufficientBalanceError = InsufficientBalanceError;
+exports.OrderPayer = OrderPayer;
+exports.TonWallet = TonWallet;
+exports.ToncenterRpc = ToncenterRpc;
+exports.WalletError = WalletError;
+exports.fulfill = fulfill;
+exports.orderIdFromError = orderIdFromError;