@mystars-tg/faas-wallet 0.1.2

package/dist/index.js

@@ -0,0 +1,281 @@
+import { mnemonicNew, mnemonicValidate, mnemonicToPrivateKey } from '@ton/crypto';
+import { WalletContractV4, TonClient } from '@ton/ton';
+import { toNano, beginCell, Address, internal, SendMode, external, storeMessage } from '@ton/core';
+import { MyStarsValidationError, toMicro, JETTON_TRANSFER_OP } from '@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 = 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 mnemonicNew();
+    return { wallet: await _TonWallet.fromMnemonic(mnemonic), mnemonic };
+  }
+  /** Import a wallet from its 24-word mnemonic. */
+  static async fromMnemonic(words) {
+    if (!await mnemonicValidate(words)) throw new WalletError("invalid TON mnemonic");
+    const keyPair = await 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 = toNano("0.02");
+function commentCell(memo) {
+  return 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 = toNano(payment.amount);
+      if (value <= 0n) {
+        throw new MyStarsValidationError(`payment amount must be positive, got "${payment.amount}"`);
+      }
+      return [{ to: payment.pay_to_address, value, body: commentCell(payment.memo), bounce: false }];
+    }
+    const microAmount = toMicro(payment.amount);
+    if (microAmount <= 0n) {
+      throw new 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 = beginCell().storeUint(JETTON_TRANSFER_OP, 32).storeUint(0n, 64).storeCoins(microAmount).storeAddress(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: 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 = 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) => internal({ to: 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: SendMode.PAY_GAS_SEPARATELY, timeout });
+    const ext = external({
+      to: this.wallet.tonAddress,
+      init: seqno === 0 ? this.wallet.init : void 0,
+      body: transfer
+    });
+    const boc = beginCell().store(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" ? toNano(payment.amount) : toMicro(payment.amount)).toString()
+    };
+  }
+};
+var ToncenterRpc = class {
+  client;
+  /** @param opts - the {@link ToncenterRpcOptions} (endpoint + optional API key) */
+  constructor(opts) {
+    this.client = new TonClient(opts.apiKey ? { endpoint: opts.endpoint, apiKey: opts.apiKey } : { endpoint: opts.endpoint });
+  }
+  /** {@inheritDoc TonRpc.getBalance} */
+  getBalance(address) {
+    return this.client.getBalance(Address.parse(address));
+  }
+  /** {@inheritDoc TonRpc.getSeqno} */
+  async getSeqno(address) {
+    const addr = 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(Address.parse(jettonMaster), "get_wallet_address", [
+      { type: "slice", cell: beginCell().storeAddress(Address.parse(owner)).endCell() }
+    ]);
+    return res.stack.readAddress().toString();
+  }
+  /** {@inheritDoc TonRpc.getJettonBalance} */
+  async getJettonBalance(jettonWallet) {
+    const res = await this.client.runMethod(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 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);
+  }
+}
+
+export { DEFAULT_JETTON_GAS_TON, DEFAULT_USDT_MASTER, InsufficientBalanceError, OrderPayer, TonWallet, ToncenterRpc, WalletError, fulfill, orderIdFromError };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@mystars-tg/faas-wallet",
+  "version": "0.1.2",
+  "description": "Opt-in TON wallet + payer for @mystars-tg/faas-sdk — generate/import a wallet and pay a FaaS order invoice (TON or USDT) from your OWN wallet. Node only. Holds keys only in memory; never persists/logs/transmits them.",
+  "license": "MIT",
+  "author": "MyStars.tg",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["ton", "usdt", "telegram", "stars", "mystars", "faas", "wallet", "payments"],
+  "homepage": "https://mystars.tg/docs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mystars-tg/faas-ts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mystars-tg/faas-ts/issues"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --root ../..",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@mystars-tg/faas-sdk": "^0.1.2",
+    "@ton/core": "^0.62.0",
+    "@ton/crypto": "^3.3.0",
+    "@ton/ton": "^15.1.0"
+  }
+}