tusdt-sdk 0.1.0

package/dist/server.js

@@ -0,0 +1,204 @@
+import { tusdt_erc20_default, ZERO_ADDRESS } from './chunk-5HS7VSOA.js';
+export { ConnectionError, ContractError, DispatchError, DryRunError, InsufficientAllowanceError, InsufficientBalanceError, NotControllerError, TimeoutError, TusdtContract, TusdtSdkError, U64_MAX, ValidationError, ZERO_BALANCE, executeApprove, executeTransfer, executeTransferFrom, getSignerAddress, isKeyringPair, mapContractError, queryAllowance, queryBalanceOf, queryController, queryTotalSupply, safeApprove, subscribeApproval, subscribeTransfer, subscribeTransferFrom, subscribeTransferTo, validateAddress, validateBalance, validateOverflowSafe, watchFinalizedTransfers, watchFinalizedTransfersTo } from './chunk-5HS7VSOA.js';
+import { Contract } from 'dedot/contracts';
+
+var DEFAULT_RECONNECT = {
+  maxRetries: Infinity,
+  baseDelayMs: 1e3,
+  maxDelayMs: 3e4
+};
+var DEDUP_SET_MAX = 1e4;
+function parseBlockNumber(raw) {
+  if (typeof raw === "number") return raw;
+  return Number(String(raw ?? 0));
+}
+function backoffDelay(attempt, base, max) {
+  const exponential = base * Math.pow(2, attempt);
+  const capped = Math.min(exponential, max);
+  const jitter = capped * (0.75 + Math.random() * 0.5);
+  return Math.round(jitter);
+}
+var TusdtPaymentListener = class {
+  client;
+  contract;
+  config;
+  reconnectConfig;
+  _running = false;
+  _lastBlockNumber = 0;
+  _unsub = null;
+  _reconnectTimer = null;
+  _reconnectAttempt = 0;
+  _stopped = false;
+  // Deduplication: set of `${blockHash}:${txIndex}` keys
+  _seen = /* @__PURE__ */ new Set();
+  constructor(client, contractAddress, config) {
+    this.client = client;
+    this.config = config;
+    if (config.reconnect === false) {
+      this.reconnectConfig = null;
+    } else {
+      this.reconnectConfig = {
+        ...DEFAULT_RECONNECT,
+        ...config.reconnect ?? {}
+      };
+    }
+    this.contract = new Contract(
+      client,
+      tusdt_erc20_default,
+      contractAddress,
+      { defaultCaller: ZERO_ADDRESS }
+    );
+  }
+  /** Whether the listener is currently subscribed and processing blocks. */
+  get isRunning() {
+    return this._running;
+  }
+  /** The last finalized block number processed by this listener. */
+  get lastBlockNumber() {
+    return this._lastBlockNumber;
+  }
+  /**
+   * Start listening for finalized Transfer events to the configured receiver wallet.
+   *
+   * Subscribes to `chain_subscribeFinalizedHeads` and filters for Transfer events.
+   * If the listener is already running, this is a no-op.
+   *
+   * @throws If the initial subscription fails and reconnection is disabled.
+   */
+  async start() {
+    if (this._running) return;
+    this._stopped = false;
+    this._reconnectAttempt = 0;
+    await this._subscribe();
+  }
+  /**
+   * Stop the listener, unsubscribe, and clean up all timers.
+   *
+   * Safe to call multiple times. After stopping, the listener can be restarted with `start()`.
+   */
+  async stop() {
+    this._stopped = true;
+    this._running = false;
+    if (this._reconnectTimer !== null) {
+      clearTimeout(this._reconnectTimer);
+      this._reconnectTimer = null;
+    }
+    if (this._unsub) {
+      try {
+        this._unsub();
+      } catch {
+      }
+      this._unsub = null;
+    }
+  }
+  // ─── Internal ────────────────────────────────────────────────
+  async _subscribe() {
+    if (this._stopped) return;
+    try {
+      const unsub = await this.client.rpc.chain_subscribeFinalizedHeads(
+        async (header) => {
+          await this._processHeader(header);
+        }
+      );
+      this._unsub = typeof unsub === "function" ? unsub : () => {
+      };
+      this._running = true;
+      this._reconnectAttempt = 0;
+    } catch (error) {
+      this._running = false;
+      const err = error instanceof Error ? error : new Error(String(error));
+      if (this.reconnectConfig && !this._stopped) {
+        this._reportError(new Error(`Subscription failed, will reconnect: ${err.message}`));
+        this._scheduleReconnect();
+      } else {
+        throw err;
+      }
+    }
+  }
+  async _processHeader(header) {
+    try {
+      const blockHash = header.hash?.toString() ?? header.parentHash?.toString() ?? "";
+      const blockNumber = parseBlockNumber(header.number);
+      if (blockNumber <= this._lastBlockNumber && this._lastBlockNumber > 0) {
+        return;
+      }
+      const events = await this.client.query.system.events.at(blockHash);
+      const transferEvents = this.contract.events.Transfer.filter(events);
+      for (let i = 0; i < transferEvents.length; i++) {
+        const evt = transferEvents[i];
+        const data = evt.data ?? evt;
+        const to = data.to?.toString() ?? null;
+        if (to !== this.config.receiverWallet) continue;
+        const dedupKey = `${blockHash}:${i}`;
+        if (this._seen.has(dedupKey)) continue;
+        this._seen.add(dedupKey);
+        if (this._seen.size > DEDUP_SET_MAX) {
+          const entries = Array.from(this._seen);
+          for (let j = 0; j < entries.length / 2; j++) {
+            this._seen.delete(entries[j]);
+          }
+        }
+        const event = {
+          from: data.from?.toString() ?? null,
+          to,
+          value: BigInt(data.value ?? 0),
+          blockHash,
+          blockNumber,
+          txIndex: i
+        };
+        try {
+          await this.config.onPayment(event);
+        } catch (callbackError) {
+          this._reportError(
+            callbackError instanceof Error ? callbackError : new Error(`Payment callback error: ${String(callbackError)}`)
+          );
+        }
+      }
+      this._lastBlockNumber = blockNumber;
+    } catch (error) {
+      this._reportError(
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+  }
+  _scheduleReconnect() {
+    if (this._stopped || !this.reconnectConfig) return;
+    const { maxRetries, baseDelayMs, maxDelayMs } = this.reconnectConfig;
+    if (this._reconnectAttempt >= maxRetries) {
+      this._reportError(
+        new Error(`Max reconnection attempts (${maxRetries}) reached. Giving up.`)
+      );
+      this._running = false;
+      return;
+    }
+    const delay = backoffDelay(this._reconnectAttempt, baseDelayMs, maxDelayMs);
+    this._reconnectAttempt++;
+    this._reconnectTimer = setTimeout(async () => {
+      this._reconnectTimer = null;
+      if (!this._stopped) {
+        await this._subscribe();
+      }
+    }, delay);
+  }
+  _reportError(error) {
+    if (this.config.onError) {
+      try {
+        this.config.onError(error);
+      } catch {
+      }
+    }
+  }
+};
+
+// src/server.ts
+async function createSigner(suri, type = "sr25519") {
+  const { Keyring } = await import('@polkadot/keyring');
+  const { cryptoWaitReady } = await import('@polkadot/util-crypto');
+  await cryptoWaitReady();
+  const keyring = new Keyring({ type });
+  return keyring.addFromUri(suri);
+}
+
+export { TusdtPaymentListener, createSigner };
+//# sourceMappingURL=server.js.map
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/contract/payment-listener.ts","../src/server.ts"],"names":[],"mappings":";;;;AAyCA,IAAM,iBAAA,GAA+C;AAAA,EACnD,UAAA,EAAY,QAAA;AAAA,EACZ,WAAA,EAAa,GAAA;AAAA,EACb,UAAA,EAAY;AACd,CAAA;AAEA,IAAM,aAAA,GAAgB,GAAA;AAGtB,SAAS,iBAAiB,GAAA,EAAsB;AAC9C,EAAA,IAAI,OAAO,GAAA,KAAQ,QAAA,EAAU,OAAO,GAAA;AACpC,EAAA,OAAO,MAAA,CAAO,MAAA,CAAO,GAAA,IAAO,CAAC,CAAC,CAAA;AAChC;AAGA,SAAS,YAAA,CAAa,OAAA,EAAiB,IAAA,EAAc,GAAA,EAAqB;AACxE,EAAA,MAAM,WAAA,GAAc,IAAA,GAAO,IAAA,CAAK,GAAA,CAAI,GAAG,OAAO,CAAA;AAC9C,EAAA,MAAM,MAAA,GAAS,IAAA,CAAK,GAAA,CAAI,WAAA,EAAa,GAAG,CAAA;AAExC,EAAA,MAAM,MAAA,GAAS,MAAA,IAAU,IAAA,GAAO,IAAA,CAAK,QAAO,GAAI,GAAA,CAAA;AAChD,EAAA,OAAO,IAAA,CAAK,MAAM,MAAM,CAAA;AAC1B;AAkCO,IAAM,uBAAN,MAA2B;AAAA,EACf,MAAA;AAAA,EACA,QAAA;AAAA,EACA,MAAA;AAAA,EACA,eAAA;AAAA,EAET,QAAA,GAAW,KAAA;AAAA,EACX,gBAAA,GAAmB,CAAA;AAAA,EACnB,MAAA,GAA6B,IAAA;AAAA,EAC7B,eAAA,GAAwD,IAAA;AAAA,EACxD,iBAAA,GAAoB,CAAA;AAAA,EACpB,QAAA,GAAW,KAAA;AAAA;AAAA,EAGF,KAAA,uBAAY,GAAA,EAAY;AAAA,EAEzC,WAAA,CACE,MAAA,EACA,eAAA,EACA,MAAA,EACA;AACA,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AACd,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AAGd,IAAA,IAAI,MAAA,CAAO,cAAc,KAAA,EAAO;AAC9B,MAAA,IAAA,CAAK,eAAA,GAAkB,IAAA;AAAA,IACzB,CAAA,MAAO;AACL,MAAA,IAAA,CAAK,eAAA,GAAkB;AAAA,QACrB,GAAG,iBAAA;AAAA,QACH,GAAI,MAAA,CAAO,SAAA,IAAa;AAAC,OAC3B;AAAA,IACF;AAGA,IAAA,IAAA,CAAK,WAAW,IAAI,QAAA;AAAA,MAClB,MAAA;AAAA,MACA,mBAAA;AAAA,MACA,eAAA;AAAA,MACA,EAAE,eAAe,YAAA;AAAa,KAChC;AAAA,EACF;AAAA;AAAA,EAGA,IAAI,SAAA,GAAqB;AACvB,IAAA,OAAO,IAAA,CAAK,QAAA;AAAA,EACd;AAAA;AAAA,EAGA,IAAI,eAAA,GAA0B;AAC5B,IAAA,OAAO,IAAA,CAAK,gBAAA;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,MAAM,KAAA,GAAuB;AAC3B,IAAA,IAAI,KAAK,QAAA,EAAU;AACnB,IAAA,IAAA,CAAK,QAAA,GAAW,KAAA;AAChB,IAAA,IAAA,CAAK,iBAAA,GAAoB,CAAA;AACzB,IAAA,MAAM,KAAK,UAAA,EAAW;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,IAAA,GAAsB;AAC1B,IAAA,IAAA,CAAK,QAAA,GAAW,IAAA;AAChB,IAAA,IAAA,CAAK,QAAA,GAAW,KAAA;AAEhB,IAAA,IAAI,IAAA,CAAK,oBAAoB,IAAA,EAAM;AACjC,MAAA,YAAA,CAAa,KAAK,eAAe,CAAA;AACjC,MAAA,IAAA,CAAK,eAAA,GAAkB,IAAA;AAAA,IACzB;AAEA,IAAA,IAAI,KAAK,MAAA,EAAQ;AACf,MAAA,IAAI;AACF,QAAA,IAAA,CAAK,MAAA,EAAO;AAAA,MACd,CAAA,CAAA,MAAQ;AAAA,MAER;AACA,MAAA,IAAA,CAAK,MAAA,GAAS,IAAA;AAAA,IAChB;AAAA,EACF;AAAA;AAAA,EAIA,MAAc,UAAA,GAA4B;AACxC,IAAA,IAAI,KAAK,QAAA,EAAU;AAEnB,IAAA,IAAI;AACF,MAAA,MAAM,KAAA,GAAQ,MAAM,IAAA,CAAK,MAAA,CAAO,GAAA,CAAI,6BAAA;AAAA,QAClC,OAAO,MAAA,KAAgB;AACrB,UAAA,MAAM,IAAA,CAAK,eAAe,MAAM,CAAA;AAAA,QAClC;AAAA,OACF;AAEA,MAAA,IAAA,CAAK,MAAA,GAAS,OAAO,KAAA,KAAU,UAAA,GAAa,QAAQ,MAAM;AAAA,MAAC,CAAA;AAC3D,MAAA,IAAA,CAAK,QAAA,GAAW,IAAA;AAChB,MAAA,IAAA,CAAK,iBAAA,GAAoB,CAAA;AAAA,IAC3B,SAAS,KAAA,EAAO;AACd,MAAA,IAAA,CAAK,QAAA,GAAW,KAAA;AAChB,MAAA,MAAM,GAAA,GAAM,iBAAiB,KAAA,GAAQ,KAAA,GAAQ,IAAI,KAAA,CAAM,MAAA,CAAO,KAAK,CAAC,CAAA;AAEpE,MAAA,IAAI,IAAA,CAAK,eAAA,IAAmB,CAAC,IAAA,CAAK,QAAA,EAAU;AAC1C,QAAA,IAAA,CAAK,aAAa,IAAI,KAAA,CAAM,wCAAwC,GAAA,CAAI,OAAO,EAAE,CAAC,CAAA;AAClF,QAAA,IAAA,CAAK,kBAAA,EAAmB;AAAA,MAC1B,CAAA,MAAO;AACL,QAAA,MAAM,GAAA;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAAA,EAEA,MAAc,eAAe,MAAA,EAA4B;AACvD,IAAA,IAAI;AACF,MAAA,MAAM,SAAA,GACJ,OAAO,IAAA,EAAM,QAAA,MAAc,MAAA,CAAO,UAAA,EAAY,UAAS,IAAK,EAAA;AAC9D,MAAA,MAAM,WAAA,GAAc,gBAAA,CAAiB,MAAA,CAAO,MAAM,CAAA;AAGlD,MAAA,IAAI,WAAA,IAAe,IAAA,CAAK,gBAAA,IAAoB,IAAA,CAAK,mBAAmB,CAAA,EAAG;AACrE,QAAA;AAAA,MACF;AAEA,MAAA,MAAM,MAAA,GAAS,MAAM,IAAA,CAAK,MAAA,CAAO,MAAM,MAAA,CAAO,MAAA,CAAO,GAAG,SAAS,CAAA;AACjE,MAAA,MAAM,iBAAiB,IAAA,CAAK,QAAA,CAAS,MAAA,CAAO,QAAA,CAAS,OAAO,MAAM,CAAA;AAElE,MAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,cAAA,CAAe,QAAQ,CAAA,EAAA,EAAK;AAC9C,QAAA,MAAM,GAAA,GAAM,eAAe,CAAC,CAAA;AAC5B,QAAA,MAAM,IAAA,GAAO,IAAI,IAAA,IAAQ,GAAA;AACzB,QAAA,MAAM,EAAA,GAAK,IAAA,CAAK,EAAA,EAAI,QAAA,EAAS,IAAK,IAAA;AAGlC,QAAA,IAAI,EAAA,KAAO,IAAA,CAAK,MAAA,CAAO,cAAA,EAAgB;AAGvC,QAAA,MAAM,QAAA,GAAW,CAAA,EAAG,SAAS,CAAA,CAAA,EAAI,CAAC,CAAA,CAAA;AAClC,QAAA,IAAI,IAAA,CAAK,KAAA,CAAM,GAAA,CAAI,QAAQ,CAAA,EAAG;AAC9B,QAAA,IAAA,CAAK,KAAA,CAAM,IAAI,QAAQ,CAAA;AAGvB,QAAA,IAAI,IAAA,CAAK,KAAA,CAAM,IAAA,GAAO,aAAA,EAAe;AACnC,UAAA,MAAM,OAAA,GAAU,KAAA,CAAM,IAAA,CAAK,IAAA,CAAK,KAAK,CAAA;AAErC,UAAA,KAAA,IAAS,IAAI,CAAA,EAAG,CAAA,GAAI,OAAA,CAAQ,MAAA,GAAS,GAAG,CAAA,EAAA,EAAK;AAC3C,YAAA,IAAA,CAAK,KAAA,CAAM,MAAA,CAAO,OAAA,CAAQ,CAAC,CAAC,CAAA;AAAA,UAC9B;AAAA,QACF;AAEA,QAAA,MAAM,KAAA,GAAgC;AAAA,UACpC,IAAA,EAAM,IAAA,CAAK,IAAA,EAAM,QAAA,EAAS,IAAK,IAAA;AAAA,UAC/B,EAAA;AAAA,UACA,KAAA,EAAO,MAAA,CAAO,IAAA,CAAK,KAAA,IAAS,CAAC,CAAA;AAAA,UAC7B,SAAA;AAAA,UACA,WAAA;AAAA,UACA,OAAA,EAAS;AAAA,SACX;AAGA,QAAA,IAAI;AACF,UAAA,MAAM,IAAA,CAAK,MAAA,CAAO,SAAA,CAAU,KAAK,CAAA;AAAA,QACnC,SAAS,aAAA,EAAe;AACtB,UAAA,IAAA,CAAK,YAAA;AAAA,YACH,aAAA,YAAyB,QACrB,aAAA,GACA,IAAI,MAAM,CAAA,wBAAA,EAA2B,MAAA,CAAO,aAAa,CAAC,CAAA,CAAE;AAAA,WAClE;AAAA,QACF;AAAA,MACF;AAEA,MAAA,IAAA,CAAK,gBAAA,GAAmB,WAAA;AAAA,IAC1B,SAAS,KAAA,EAAO;AAEd,MAAA,IAAA,CAAK,YAAA;AAAA,QACH,iBAAiB,KAAA,GAAQ,KAAA,GAAQ,IAAI,KAAA,CAAM,MAAA,CAAO,KAAK,CAAC;AAAA,OAC1D;AAAA,IACF;AAAA,EACF;AAAA,EAEQ,kBAAA,GAA2B;AACjC,IAAA,IAAI,IAAA,CAAK,QAAA,IAAY,CAAC,IAAA,CAAK,eAAA,EAAiB;AAE5C,IAAA,MAAM,EAAE,UAAA,EAAY,WAAA,EAAa,UAAA,KAAe,IAAA,CAAK,eAAA;AAErD,IAAA,IAAI,IAAA,CAAK,qBAAqB,UAAA,EAAY;AACxC,MAAA,IAAA,CAAK,YAAA;AAAA,QACH,IAAI,KAAA,CAAM,CAAA,2BAAA,EAA8B,UAAU,CAAA,qBAAA,CAAuB;AAAA,OAC3E;AACA,MAAA,IAAA,CAAK,QAAA,GAAW,KAAA;AAChB,MAAA;AAAA,IACF;AAEA,IAAA,MAAM,KAAA,GAAQ,YAAA,CAAa,IAAA,CAAK,iBAAA,EAAmB,aAAa,UAAU,CAAA;AAC1E,IAAA,IAAA,CAAK,iBAAA,EAAA;AAEL,IAAA,IAAA,CAAK,eAAA,GAAkB,WAAW,YAAY;AAC5C,MAAA,IAAA,CAAK,eAAA,GAAkB,IAAA;AACvB,MAAA,IAAI,CAAC,KAAK,QAAA,EAAU;AAClB,QAAA,MAAM,KAAK,UAAA,EAAW;AAAA,MACxB;AAAA,IACF,GAAG,KAAK,CAAA;AAAA,EACV;AAAA,EAEQ,aAAa,KAAA,EAAoB;AACvC,IAAA,IAAI,IAAA,CAAK,OAAO,OAAA,EAAS;AACvB,MAAA,IAAI;AACF,QAAA,IAAA,CAAK,MAAA,CAAO,QAAQ,KAAK,CAAA;AAAA,MAC3B,CAAA,CAAA,MAAQ;AAAA,MAER;AAAA,IACF;AAAA,EACF;AACF;;;ACrSA,eAAsB,YAAA,CACpB,IAAA,EACA,IAAA,GAA8B,SAAA,EACwB;AACtD,EAAA,MAAM,EAAE,OAAA,EAAQ,GAAI,MAAM,OAAO,mBAAmB,CAAA;AACpD,EAAA,MAAM,EAAE,eAAA,EAAgB,GAAI,MAAM,OAAO,uBAAuB,CAAA;AAChE,EAAA,MAAM,eAAA,EAAgB;AACtB,EAAA,MAAM,OAAA,GAAU,IAAI,OAAA,CAAQ,EAAE,MAAM,CAAA;AACpC,EAAA,OAAO,OAAA,CAAQ,WAAW,IAAI,CAAA;AAChC","file":"server.js","sourcesContent":["import { Contract } from 'dedot/contracts';\nimport type { SubstrateClient } from './tusdt-contract.js';\nimport type {\n  AccountId,\n  FinalizedTransferEvent,\n  Unsubscribe,\n} from '../core/types.js';\nimport { ZERO_ADDRESS } from '../core/constants.js';\n\nimport tusdtErc20Metadata from '../../metadata/tusdt_erc20.json';\n\n// ---------------------------------------------------------------------------\n// Public configuration types\n// ---------------------------------------------------------------------------\n\n/** Reconnection strategy configuration. */\nexport interface ReconnectConfig {\n  /** Maximum reconnection attempts before giving up. Default: Infinity (never give up). */\n  maxRetries?: number;\n  /** Base delay in milliseconds for the first retry. Default: 1000. */\n  baseDelayMs?: number;\n  /** Maximum delay cap in milliseconds. Default: 30000. */\n  maxDelayMs?: number;\n}\n\n/** Configuration for TusdtPaymentListener. */\nexport interface PaymentListenerConfig {\n  /** SS58 address of the wallet to watch for incoming transfers. */\n  receiverWallet: AccountId;\n  /** Called for each incoming transfer to the receiver wallet (finalized). */\n  onPayment: (event: FinalizedTransferEvent) => void | Promise<void>;\n  /** Called when an error occurs during block processing or callback execution. */\n  onError?: (error: Error) => void;\n  /** Reconnection strategy. Pass `false` to disable reconnection entirely. */\n  reconnect?: ReconnectConfig | false;\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nconst DEFAULT_RECONNECT: Required<ReconnectConfig> = {\n  maxRetries: Infinity,\n  baseDelayMs: 1_000,\n  maxDelayMs: 30_000,\n};\n\nconst DEDUP_SET_MAX = 10_000;\n\n/** Safely parse block number from header, which may be a number, bigint, or stringifiable object. */\nfunction parseBlockNumber(raw: unknown): number {\n  if (typeof raw === 'number') return raw;\n  return Number(String(raw ?? 0));\n}\n\n/** Compute delay with exponential backoff and jitter. */\nfunction backoffDelay(attempt: number, base: number, max: number): number {\n  const exponential = base * Math.pow(2, attempt);\n  const capped = Math.min(exponential, max);\n  // Add ±25% jitter to prevent thundering herd\n  const jitter = capped * (0.75 + Math.random() * 0.5);\n  return Math.round(jitter);\n}\n\n// ---------------------------------------------------------------------------\n// TusdtPaymentListener\n// ---------------------------------------------------------------------------\n\n/**\n * Production-grade listener for incoming TUSDT transfers on finalized blocks.\n *\n * Designed for backend payment detection and reconciliation:\n * - **Finalized blocks only** -- immutable, no reorg risk\n * - **Automatic reconnection** with exponential backoff\n * - **Event deduplication** -- monotonic block tracking + bounded event ID set\n * - **Error isolation** -- callback errors don't kill the listener\n *\n * Usage:\n * ```ts\n * import { DedotClient, WsProvider } from 'dedot';\n * import { TusdtPaymentListener, createSigner } from 'tusdt-sdk/server';\n *\n * const client = await DedotClient.legacy(new WsProvider('wss://...'));\n * const listener = new TusdtPaymentListener(client, '5Cp7...', {\n *   receiverWallet: '5HhJ...',\n *   onPayment: (event) => {\n *     console.log(`Received ${event.value} from ${event.from} at block ${event.blockNumber}`);\n *   },\n *   onError: (err) => console.error('Listener error:', err),\n * });\n *\n * await listener.start();\n * // ... later ...\n * await listener.stop();\n * ```\n */\nexport class TusdtPaymentListener {\n  private readonly client: SubstrateClient;\n  private readonly contract: Contract<any>;\n  private readonly config: PaymentListenerConfig;\n  private readonly reconnectConfig: Required<ReconnectConfig> | null;\n\n  private _running = false;\n  private _lastBlockNumber = 0;\n  private _unsub: Unsubscribe | null = null;\n  private _reconnectTimer: ReturnType<typeof setTimeout> | null = null;\n  private _reconnectAttempt = 0;\n  private _stopped = false;\n\n  // Deduplication: set of `${blockHash}:${txIndex}` keys\n  private readonly _seen = new Set<string>();\n\n  constructor(\n    client: SubstrateClient,\n    contractAddress: AccountId,\n    config: PaymentListenerConfig,\n  ) {\n    this.client = client;\n    this.config = config;\n\n    // Build reconnect config\n    if (config.reconnect === false) {\n      this.reconnectConfig = null;\n    } else {\n      this.reconnectConfig = {\n        ...DEFAULT_RECONNECT,\n        ...(config.reconnect ?? {}),\n      };\n    }\n\n    // Construct contract from bundled metadata (same pattern as TusdtContract)\n    this.contract = new Contract(\n      client as any,\n      tusdtErc20Metadata as any,\n      contractAddress,\n      { defaultCaller: ZERO_ADDRESS },\n    );\n  }\n\n  /** Whether the listener is currently subscribed and processing blocks. */\n  get isRunning(): boolean {\n    return this._running;\n  }\n\n  /** The last finalized block number processed by this listener. */\n  get lastBlockNumber(): number {\n    return this._lastBlockNumber;\n  }\n\n  /**\n   * Start listening for finalized Transfer events to the configured receiver wallet.\n   *\n   * Subscribes to `chain_subscribeFinalizedHeads` and filters for Transfer events.\n   * If the listener is already running, this is a no-op.\n   *\n   * @throws If the initial subscription fails and reconnection is disabled.\n   */\n  async start(): Promise<void> {\n    if (this._running) return;\n    this._stopped = false;\n    this._reconnectAttempt = 0;\n    await this._subscribe();\n  }\n\n  /**\n   * Stop the listener, unsubscribe, and clean up all timers.\n   *\n   * Safe to call multiple times. After stopping, the listener can be restarted with `start()`.\n   */\n  async stop(): Promise<void> {\n    this._stopped = true;\n    this._running = false;\n\n    if (this._reconnectTimer !== null) {\n      clearTimeout(this._reconnectTimer);\n      this._reconnectTimer = null;\n    }\n\n    if (this._unsub) {\n      try {\n        this._unsub();\n      } catch {\n        // Ignore unsubscribe errors during shutdown\n      }\n      this._unsub = null;\n    }\n  }\n\n  // ─── Internal ────────────────────────────────────────────────\n\n  private async _subscribe(): Promise<void> {\n    if (this._stopped) return;\n\n    try {\n      const unsub = await this.client.rpc.chain_subscribeFinalizedHeads(\n        async (header: any) => {\n          await this._processHeader(header);\n        },\n      );\n\n      this._unsub = typeof unsub === 'function' ? unsub : () => {};\n      this._running = true;\n      this._reconnectAttempt = 0; // Reset on successful subscription\n    } catch (error) {\n      this._running = false;\n      const err = error instanceof Error ? error : new Error(String(error));\n\n      if (this.reconnectConfig && !this._stopped) {\n        this._reportError(new Error(`Subscription failed, will reconnect: ${err.message}`));\n        this._scheduleReconnect();\n      } else {\n        throw err;\n      }\n    }\n  }\n\n  private async _processHeader(header: any): Promise<void> {\n    try {\n      const blockHash =\n        header.hash?.toString() ?? header.parentHash?.toString() ?? '';\n      const blockNumber = parseBlockNumber(header.number);\n\n      // Monotonic block dedup: skip blocks we've already processed\n      if (blockNumber <= this._lastBlockNumber && this._lastBlockNumber > 0) {\n        return;\n      }\n\n      const events = await this.client.query.system.events.at(blockHash);\n      const transferEvents = this.contract.events.Transfer.filter(events);\n\n      for (let i = 0; i < transferEvents.length; i++) {\n        const evt = transferEvents[i];\n        const data = evt.data ?? evt;\n        const to = data.to?.toString() ?? null;\n\n        // Filter: only events to our receiver wallet\n        if (to !== this.config.receiverWallet) continue;\n\n        // Event-level dedup\n        const dedupKey = `${blockHash}:${i}`;\n        if (this._seen.has(dedupKey)) continue;\n        this._seen.add(dedupKey);\n\n        // Prune dedup set if it grows too large\n        if (this._seen.size > DEDUP_SET_MAX) {\n          const entries = Array.from(this._seen);\n          // Remove the oldest half\n          for (let j = 0; j < entries.length / 2; j++) {\n            this._seen.delete(entries[j]);\n          }\n        }\n\n        const event: FinalizedTransferEvent = {\n          from: data.from?.toString() ?? null,\n          to,\n          value: BigInt(data.value ?? 0),\n          blockHash,\n          blockNumber,\n          txIndex: i,\n        };\n\n        // Invoke callback with error isolation\n        try {\n          await this.config.onPayment(event);\n        } catch (callbackError) {\n          this._reportError(\n            callbackError instanceof Error\n              ? callbackError\n              : new Error(`Payment callback error: ${String(callbackError)}`),\n          );\n        }\n      }\n\n      this._lastBlockNumber = blockNumber;\n    } catch (error) {\n      // Block processing error -- report but don't kill the subscription\n      this._reportError(\n        error instanceof Error ? error : new Error(String(error)),\n      );\n    }\n  }\n\n  private _scheduleReconnect(): void {\n    if (this._stopped || !this.reconnectConfig) return;\n\n    const { maxRetries, baseDelayMs, maxDelayMs } = this.reconnectConfig;\n\n    if (this._reconnectAttempt >= maxRetries) {\n      this._reportError(\n        new Error(`Max reconnection attempts (${maxRetries}) reached. Giving up.`),\n      );\n      this._running = false;\n      return;\n    }\n\n    const delay = backoffDelay(this._reconnectAttempt, baseDelayMs, maxDelayMs);\n    this._reconnectAttempt++;\n\n    this._reconnectTimer = setTimeout(async () => {\n      this._reconnectTimer = null;\n      if (!this._stopped) {\n        await this._subscribe();\n      }\n    }, delay);\n  }\n\n  private _reportError(error: Error): void {\n    if (this.config.onError) {\n      try {\n        this.config.onError(error);\n      } catch {\n        // Swallow errors from the error handler itself\n      }\n    }\n  }\n}\n","// Node.js entrypoint: \"./server\"\n// Re-exports everything from the root plus backend-specific helpers.\nexport * from './index.js';\n\n// ─── Payment Listener ────────────────────────────────────────────\nexport { TusdtPaymentListener } from './contract/payment-listener.js';\nexport type { PaymentListenerConfig, ReconnectConfig } from './contract/payment-listener.js';\n\n/**\n * Create an IKeyringPair signer from a secret URI (e.g., \"//Alice\", \"//Bob\").\n *\n * This is a convenience helper for backend and testing environments.\n * Uses dynamic imports to avoid hard errors when @polkadot/keyring is not installed.\n *\n * Requires peer dependencies:\n * - @polkadot/keyring\n * - @polkadot/util-crypto\n *\n * @param suri - Secret URI (e.g., \"//Alice\", \"//Bob\", or a mnemonic)\n * @param type - Key type. Default: 'sr25519'\n * @returns An IKeyringPair that can be passed as a TusdtSigner\n */\nexport async function createSigner(\n  suri: string,\n  type: 'sr25519' | 'ed25519' = 'sr25519',\n): Promise<import('./core/types.js').KeyringPairSigner> {\n  const { Keyring } = await import('@polkadot/keyring');\n  const { cryptoWaitReady } = await import('@polkadot/util-crypto');\n  await cryptoWaitReady();\n  const keyring = new Keyring({ type });\n  return keyring.addFromUri(suri) as unknown as import('./core/types.js').KeyringPairSigner;\n}\n"]}

package/dist/signer/types.d.ts

@@ -0,0 +1,2 @@
+export type { TusdtSigner, KeyringPairSigner, InjectedWalletSigner, } from '../core/types.js';
+//# sourceMappingURL=types.d.ts.map

package/dist/signer/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/signer/types.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,WAAW,EACX,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC"}