@hbar-kit/payments 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksandr Ostrovskyi
+
+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,23 @@
+# @hbar-kit/payments
+
+Verify HBAR and HTS payments against the Hedera Mirror Node in a few lines. Read-only,
+backend-safe, non-custodial. Built on `@hbar-kit/mirror`.
+
+```ts
+import { verifyHbarPayment } from "@hbar-kit/payments"
+
+const result = await verifyHbarPayment({
+  network: "testnet",
+  receiver: "0.0.12345",
+  amount: "25",
+  memo: "order_6471727153206",
+  after: new Date(Date.now() - 30 * 60 * 1000),
+})
+if (result.matched) {
+  // status === "confirmed"; result.transactionId, result.explorerUrl, ...
+}
+```
+
+Statuses: `confirmed | pending | underpaid | overpaid | duplicate | mismatch | expired | failed`.
+A non-match is a result (with `reason`), not a thrown error. See the
+[docs](https://github.com/devwhodevs/hbar-kit).

package/dist/index.cjs

@@ -0,0 +1,191 @@
+'use strict';
+
+var core = require('@hbar-kit/core');
+var mirror = require('@hbar-kit/mirror');
+
+// src/verify.ts
+
+// src/match.ts
+function netToReceiver(tx, receiver, asset) {
+  if (asset === "HBAR") {
+    return tx.transfers.filter((t) => t.account === receiver).reduce((s, t) => s + t.amount, 0n);
+  }
+  return tx.tokenTransfers.filter((t) => t.tokenId === asset.tokenId && t.account === receiver).reduce((s, t) => s + t.amount, 0n);
+}
+function memoMatches(actual, expected, cmp = {}) {
+  const mode = cmp.mode ?? "exact";
+  if (mode === "trim") return actual.trim() === expected.trim();
+  if (mode === "caseInsensitive") return actual.toLowerCase() === expected.toLowerCase();
+  return actual === expected;
+}
+function classifyAmount(net, expected) {
+  if (net === expected) return "exact";
+  return net < expected ? "underpaid" : "overpaid";
+}
+function hashscanTxUrl(network, consensusTimestamp, transactionId) {
+  return `${core.NETWORKS[network].hashscan}/transaction/${consensusTimestamp}?tid=${core.txIdToMirror(transactionId)}`;
+}
+
+// src/verify.ts
+var tokenDecimalsCache = /* @__PURE__ */ new Map();
+function resolveClient(p) {
+  return {
+    client: p.client ?? mirror.createMirrorClient(p),
+    network: p.network ?? "mainnet"
+  };
+}
+async function runVerify(p, asset, expectedBase, decimals) {
+  if (p.after && p.before && new Date(p.after) > new Date(p.before)) {
+    throw new core.InvalidParamsError("`after` must be before `before`");
+  }
+  const { client, network } = resolveClient(p);
+  const tokenId = asset === "HBAR" ? void 0 : asset.tokenId;
+  const candidates = [];
+  const collect = (items) => {
+    for (const tx of items) {
+      if (tx.result !== "SUCCESS") continue;
+      const net = netToReceiver(tx, p.receiver, asset);
+      if (net <= 0n) continue;
+      if (tokenId && !tx.tokenTransfers.some((t) => t.tokenId === tokenId)) continue;
+      const payer = tx.transfers.find((t) => t.amount < 0n)?.account ?? tx.tokenTransfers.find((t) => t.amount < 0n)?.account;
+      const match = {
+        transactionId: tx.transactionId,
+        consensusTimestamp: tx.consensusTimestamp.raw,
+        netBase: net,
+        net: core.formatUnits(net, decimals),
+        memo: tx.memo,
+        transaction: tx
+      };
+      if (payer !== void 0) match.payer = payer;
+      candidates.push(match);
+    }
+  };
+  const findParams = {
+    accountId: p.receiver,
+    transactionType: "cryptotransfer",
+    result: "success",
+    order: "desc"
+  };
+  if (p.after !== void 0) findParams.after = p.after;
+  if (p.before !== void 0) findParams.before = p.before;
+  let page = await client.transactions.find(findParams);
+  collect(page.items);
+  while (page.next) {
+    const body = await client.transport.get(page.next);
+    collect((body.transactions ?? []).map(mirror.normalizeTransaction));
+    page = { items: [], next: body.links?.next ?? null };
+  }
+  const memoFiltered = p.memo ? candidates.filter((c) => memoMatches(c.memo, p.memo, p.memoComparison)) : candidates;
+  const fail = (status, reason) => ({
+    matched: false,
+    status,
+    receiver: p.receiver,
+    asset,
+    matches: memoFiltered,
+    reason
+  });
+  if (candidates.length === 0)
+    return fail("pending", "no matching transactions for receiver in window");
+  if (p.memo && memoFiltered.length === 0)
+    return fail("mismatch", "no transaction matched the expected memo");
+  const wantAtLeast = p.comparison === "atLeast";
+  const satisfying = memoFiltered.filter(
+    (c) => wantAtLeast ? c.netBase >= expectedBase : c.netBase === expectedBase
+  );
+  const resultFrom = (m, status, matched, matches, reason) => {
+    const result = {
+      matched,
+      status,
+      receiver: p.receiver,
+      asset,
+      transactionId: m.transactionId,
+      amountBase: m.netBase,
+      amount: m.net,
+      memo: m.memo,
+      consensusTimestamp: m.consensusTimestamp,
+      explorerUrl: hashscanTxUrl(network, m.consensusTimestamp, m.transactionId),
+      matches
+    };
+    if (m.payer !== void 0) result.payer = m.payer;
+    if (reason !== void 0) result.reason = reason;
+    return result;
+  };
+  if (satisfying.length === 0) {
+    const best = memoFiltered[0];
+    const cls = classifyAmount(best.netBase, expectedBase);
+    return resultFrom(
+      best,
+      cls === "exact" ? "confirmed" : cls,
+      false,
+      memoFiltered,
+      `amount ${cls}`
+    );
+  }
+  if (satisfying.length > 1) {
+    return resultFrom(
+      satisfying[0],
+      "duplicate",
+      false,
+      satisfying,
+      `${satisfying.length} transactions satisfy this request`
+    );
+  }
+  return resultFrom(satisfying[0], "confirmed", true, satisfying);
+}
+async function verifyHbarPayment(p) {
+  return runVerify(p, "HBAR", core.parseHbar(p.amount), 8);
+}
+async function verifyHtsPayment(p) {
+  let decimals = p.decimals;
+  if (decimals === void 0) {
+    const cached = tokenDecimalsCache.get(p.tokenId);
+    if (cached !== void 0) decimals = cached;
+    else {
+      const { client } = resolveClient(p);
+      decimals = (await client.tokens.get(p.tokenId)).decimals;
+      tokenDecimalsCache.set(p.tokenId, decimals);
+    }
+  }
+  return runVerify(p, { tokenId: p.tokenId, decimals }, core.parseUnits(p.amount, decimals), decimals);
+}
+
+// src/wait.ts
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function poll(verify, opts) {
+  const timeoutMs = opts.timeoutMs ?? 10 * 60 * 1e3;
+  const pollIntervalMs = opts.pollIntervalMs ?? 3e3;
+  const deadline = Date.now() + timeoutMs;
+  let last;
+  while (Date.now() < deadline) {
+    if (opts.signal?.aborted) break;
+    last = await verify();
+    if (last.matched) return last;
+    if (last.status === "duplicate" || last.status === "overpaid") return last;
+    await sleep(pollIntervalMs);
+  }
+  return last && last.status !== "pending" ? { ...last, status: "expired" } : {
+    matched: false,
+    status: "expired",
+    receiver: last?.receiver ?? "",
+    asset: last?.asset ?? "HBAR",
+    matches: [],
+    reason: "timed out waiting for payment"
+  };
+}
+function waitForHbarPayment(p) {
+  return poll(() => verifyHbarPayment(p), p);
+}
+function waitForHtsPayment(p) {
+  return poll(() => verifyHtsPayment(p), p);
+}
+
+exports.classifyAmount = classifyAmount;
+exports.hashscanTxUrl = hashscanTxUrl;
+exports.memoMatches = memoMatches;
+exports.netToReceiver = netToReceiver;
+exports.verifyHbarPayment = verifyHbarPayment;
+exports.verifyHtsPayment = verifyHtsPayment;
+exports.waitForHbarPayment = waitForHbarPayment;
+exports.waitForHtsPayment = waitForHtsPayment;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/match.ts","../src/explorer.ts","../src/verify.ts","../src/wait.ts"],"names":["NETWORKS","txIdToMirror","createMirrorClient","InvalidParamsError","formatUnits","normalizeTransaction","parseHbar","parseUnits"],"mappings":";;;;;;;;AAIO,SAAS,aAAA,CAAc,EAAA,EAAiB,QAAA,EAAkB,KAAA,EAA6B;AAC5F,EAAA,IAAI,UAAU,MAAA,EAAQ;AACpB,IAAA,OAAO,GAAG,SAAA,CAAU,MAAA,CAAO,CAAC,CAAA,KAAM,EAAE,OAAA,KAAY,QAAQ,CAAA,CAAE,MAAA,CAAO,CAAC,CAAA,EAAG,CAAA,KAAM,CAAA,GAAI,CAAA,CAAE,QAAQ,EAAE,CAAA;AAAA,EAC7F;AACA,EAAA,OAAO,EAAA,CAAG,eACP,MAAA,CAAO,CAAC,MAAM,CAAA,CAAE,OAAA,KAAY,MAAM,OAAA,IAAW,CAAA,CAAE,YAAY,QAAQ,CAAA,CACnE,OAAO,CAAC,CAAA,EAAG,MAAM,CAAA,GAAI,CAAA,CAAE,QAAQ,EAAE,CAAA;AACtC;AAEO,SAAS,WAAA,CAAY,MAAA,EAAgB,QAAA,EAAkB,GAAA,GAAsB,EAAC,EAAY;AAC/F,EAAA,MAAM,IAAA,GAAO,IAAI,IAAA,IAAQ,OAAA;AACzB,EAAA,IAAI,SAAS,MAAA,EAAQ,OAAO,OAAO,IAAA,EAAK,KAAM,SAAS,IAAA,EAAK;AAC5D,EAAA,IAAI,SAAS,iBAAA,EAAmB,OAAO,OAAO,WAAA,EAAY,KAAM,SAAS,WAAA,EAAY;AACrF,EAAA,OAAO,MAAA,KAAW,QAAA;AACpB;AAGO,SAAS,cAAA,CAAe,KAAa,QAAA,EAA+B;AACzE,EAAA,IAAI,GAAA,KAAQ,UAAU,OAAO,OAAA;AAC7B,EAAA,OAAO,GAAA,GAAM,WAAW,WAAA,GAAc,UAAA;AACxC;ACrBO,SAAS,aAAA,CACd,OAAA,EACA,kBAAA,EACA,aAAA,EACQ;AACR,EAAA,OAAO,CAAA,EAAGA,aAAA,CAAS,OAAO,CAAA,CAAE,QAAQ,gBAAgB,kBAAkB,CAAA,KAAA,EAAQC,iBAAA,CAAa,aAAa,CAAC,CAAA,CAAA;AAC3G;;;AC0BA,IAAM,kBAAA,uBAAyB,GAAA,EAAoB;AAEnD,SAAS,cAAc,CAAA,EAAuE;AAC5F,EAAA,OAAO;AAAA,IACL,MAAA,EAAQ,CAAA,CAAE,MAAA,IAAUC,yBAAA,CAAmB,CAAC,CAAA;AAAA,IACxC,OAAA,EAAU,EAAE,OAAA,IAAW;AAAA,GACzB;AACF;AAEA,eAAe,SAAA,CACb,CAAA,EACA,KAAA,EACA,YAAA,EACA,QAAA,EACwB;AACxB,EAAA,IAAI,CAAA,CAAE,KAAA,IAAS,CAAA,CAAE,MAAA,IAAU,IAAI,IAAA,CAAK,CAAA,CAAE,KAAK,CAAA,GAAI,IAAI,IAAA,CAAK,CAAA,CAAE,MAAM,CAAA,EAAG;AACjE,IAAA,MAAM,IAAIC,wBAAmB,iCAAiC,CAAA;AAAA,EAChE;AACA,EAAA,MAAM,EAAE,MAAA,EAAQ,OAAA,EAAQ,GAAI,cAAc,CAAC,CAAA;AAC3C,EAAA,MAAM,OAAA,GAAU,KAAA,KAAU,MAAA,GAAS,MAAA,GAAY,KAAA,CAAM,OAAA;AAErD,EAAA,MAAM,aAA6B,EAAC;AACpC,EAAA,MAAM,OAAA,GAAU,CAAC,KAAA,KAAyB;AACxC,IAAA,KAAA,MAAW,MAAM,KAAA,EAAO;AACtB,MAAA,IAAI,EAAA,CAAG,WAAW,SAAA,EAAW;AAC7B,MAAA,MAAM,GAAA,GAAM,aAAA,CAAc,EAAA,EAAI,CAAA,CAAE,UAAU,KAAK,CAAA;AAC/C,MAAA,IAAI,OAAO,EAAA,EAAI;AACf,MAAA,IAAI,OAAA,IAAW,CAAC,EAAA,CAAG,cAAA,CAAe,IAAA,CAAK,CAAC,CAAA,KAAM,CAAA,CAAE,OAAA,KAAY,OAAO,CAAA,EAAG;AACtE,MAAA,MAAM,QACJ,EAAA,CAAG,SAAA,CAAU,KAAK,CAAC,CAAA,KAAM,EAAE,MAAA,GAAS,EAAE,GAAG,OAAA,IACzC,EAAA,CAAG,eAAe,IAAA,CAAK,CAAC,MAAM,CAAA,CAAE,MAAA,GAAS,EAAE,CAAA,EAAG,OAAA;AAChD,MAAA,MAAM,KAAA,GAAsB;AAAA,QAC1B,eAAe,EAAA,CAAG,aAAA;AAAA,QAClB,kBAAA,EAAoB,GAAG,kBAAA,CAAmB,GAAA;AAAA,QAC1C,OAAA,EAAS,GAAA;AAAA,QACT,GAAA,EAAKC,gBAAA,CAAY,GAAA,EAAK,QAAQ,CAAA;AAAA,QAC9B,MAAM,EAAA,CAAG,IAAA;AAAA,QACT,WAAA,EAAa;AAAA,OACf;AACA,MAAA,IAAI,KAAA,KAAU,MAAA,EAAW,KAAA,CAAM,KAAA,GAAQ,KAAA;AACvC,MAAA,UAAA,CAAW,KAAK,KAAK,CAAA;AAAA,IACvB;AAAA,EACF,CAAA;AAEA,EAAA,MAAM,UAAA,GAA6D;AAAA,IACjE,WAAW,CAAA,CAAE,QAAA;AAAA,IACb,eAAA,EAAiB,gBAAA;AAAA,IACjB,MAAA,EAAQ,SAAA;AAAA,IACR,KAAA,EAAO;AAAA,GACT;AACA,EAAA,IAAI,CAAA,CAAE,KAAA,KAAU,MAAA,EAAW,UAAA,CAAW,QAAQ,CAAA,CAAE,KAAA;AAChD,EAAA,IAAI,CAAA,CAAE,MAAA,KAAW,MAAA,EAAW,UAAA,CAAW,SAAS,CAAA,CAAE,MAAA;AAClD,EAAA,IAAI,IAAA,GAAO,MAAM,MAAA,CAAO,YAAA,CAAa,KAAK,UAAU,CAAA;AACpD,EAAA,OAAA,CAAQ,KAAK,KAAK,CAAA;AAClB,EAAA,OAAO,KAAK,IAAA,EAAM;AAChB,IAAA,MAAM,OAAQ,MAAM,MAAA,CAAO,SAAA,CAAU,GAAA,CAAI,KAAK,IAAI,CAAA;AAIlD,IAAA,OAAA,CAAA,CAAS,KAAK,YAAA,IAAgB,EAAC,EAAG,GAAA,CAAIC,2BAAoB,CAAC,CAAA;AAC3D,IAAA,IAAA,GAAO,EAAE,OAAO,EAAC,EAAG,MAAM,IAAA,CAAK,KAAA,EAAO,QAAQ,IAAA,EAAK;AAAA,EACrD;AAEA,EAAA,MAAM,YAAA,GAAe,CAAA,CAAE,IAAA,GACnB,UAAA,CAAW,OAAO,CAAC,CAAA,KAAM,WAAA,CAAY,CAAA,CAAE,MAAM,CAAA,CAAE,IAAA,EAAO,CAAA,CAAE,cAAc,CAAC,CAAA,GACvE,UAAA;AAEJ,EAAA,MAAM,IAAA,GAAO,CAAC,MAAA,EAAiC,MAAA,MAAmC;AAAA,IAChF,OAAA,EAAS,KAAA;AAAA,IACT,MAAA;AAAA,IACA,UAAU,CAAA,CAAE,QAAA;AAAA,IACZ,KAAA;AAAA,IACA,OAAA,EAAS,YAAA;AAAA,IACT;AAAA,GACF,CAAA;AACA,EAAA,IAAI,WAAW,MAAA,KAAW,CAAA;AACxB,IAAA,OAAO,IAAA,CAAK,WAAW,iDAAiD,CAAA;AAC1E,EAAA,IAAI,CAAA,CAAE,IAAA,IAAQ,YAAA,CAAa,MAAA,KAAW,CAAA;AACpC,IAAA,OAAO,IAAA,CAAK,YAAY,0CAA0C,CAAA;AAEpE,EAAA,MAAM,WAAA,GAAc,EAAE,UAAA,KAAe,SAAA;AACrC,EAAA,MAAM,aAAa,YAAA,CAAa,MAAA;AAAA,IAAO,CAAC,CAAA,KACtC,WAAA,GAAc,EAAE,OAAA,IAAW,YAAA,GAAe,EAAE,OAAA,KAAY;AAAA,GAC1D;AAEA,EAAA,MAAM,aAAa,CACjB,CAAA,EACA,MAAA,EACA,OAAA,EACA,SACA,MAAA,KACkB;AAClB,IAAA,MAAM,MAAA,GAAwB;AAAA,MAC5B,OAAA;AAAA,MACA,MAAA;AAAA,MACA,UAAU,CAAA,CAAE,QAAA;AAAA,MACZ,KAAA;AAAA,MACA,eAAe,CAAA,CAAE,aAAA;AAAA,MACjB,YAAY,CAAA,CAAE,OAAA;AAAA,MACd,QAAQ,CAAA,CAAE,GAAA;AAAA,MACV,MAAM,CAAA,CAAE,IAAA;AAAA,MACR,oBAAoB,CAAA,CAAE,kBAAA;AAAA,MACtB,aAAa,aAAA,CAAc,OAAA,EAAS,CAAA,CAAE,kBAAA,EAAoB,EAAE,aAAa,CAAA;AAAA,MACzE;AAAA,KACF;AACA,IAAA,IAAI,CAAA,CAAE,KAAA,KAAU,MAAA,EAAW,MAAA,CAAO,QAAQ,CAAA,CAAE,KAAA;AAC5C,IAAA,IAAI,MAAA,KAAW,MAAA,EAAW,MAAA,CAAO,MAAA,GAAS,MAAA;AAC1C,IAAA,OAAO,MAAA;AAAA,EACT,CAAA;AAEA,EAAA,IAAI,UAAA,CAAW,WAAW,CAAA,EAAG;AAC3B,IAAA,MAAM,IAAA,GAAO,aAAa,CAAC,CAAA;AAC3B,IAAA,MAAM,GAAA,GAAM,cAAA,CAAe,IAAA,CAAK,OAAA,EAAS,YAAY,CAAA;AACrD,IAAA,OAAO,UAAA;AAAA,MACL,IAAA;AAAA,MACA,GAAA,KAAQ,UAAU,WAAA,GAAc,GAAA;AAAA,MAChC,KAAA;AAAA,MACA,YAAA;AAAA,MACA,UAAU,GAAG,CAAA;AAAA,KACf;AAAA,EACF;AACA,EAAA,IAAI,UAAA,CAAW,SAAS,CAAA,EAAG;AACzB,IAAA,OAAO,UAAA;AAAA,MACL,WAAW,CAAC,CAAA;AAAA,MACZ,WAAA;AAAA,MACA,KAAA;AAAA,MACA,UAAA;AAAA,MACA,CAAA,EAAG,WAAW,MAAM,CAAA,kCAAA;AAAA,KACtB;AAAA,EACF;AACA,EAAA,OAAO,WAAW,UAAA,CAAW,CAAC,CAAA,EAAI,WAAA,EAAa,MAAM,UAAU,CAAA;AACjE;AAEA,eAAsB,kBAAkB,CAAA,EAA6C;AACnF,EAAA,OAAO,UAAU,CAAA,EAAG,MAAA,EAAQC,eAAU,CAAA,CAAE,MAAM,GAAG,CAAC,CAAA;AACpD;AAEA,eAAsB,iBAAiB,CAAA,EAA4C;AACjF,EAAA,IAAI,WAAW,CAAA,CAAE,QAAA;AACjB,EAAA,IAAI,aAAa,MAAA,EAAW;AAC1B,IAAA,MAAM,MAAA,GAAS,kBAAA,CAAmB,GAAA,CAAI,CAAA,CAAE,OAAO,CAAA;AAC/C,IAAA,IAAI,MAAA,KAAW,QAAW,QAAA,GAAW,MAAA;AAAA,SAChC;AACH,MAAA,MAAM,EAAE,MAAA,EAAO,GAAI,aAAA,CAAc,CAAC,CAAA;AAClC,MAAA,QAAA,GAAA,CAAY,MAAM,MAAA,CAAO,MAAA,CAAO,GAAA,CAAI,CAAA,CAAE,OAAO,CAAA,EAAG,QAAA;AAChD,MAAA,kBAAA,CAAmB,GAAA,CAAI,CAAA,CAAE,OAAA,EAAS,QAAQ,CAAA;AAAA,IAC5C;AAAA,EACF;AACA,EAAA,OAAO,SAAA,CAAU,CAAA,EAAG,EAAE,OAAA,EAAS,CAAA,CAAE,OAAA,EAAS,QAAA,EAAS,EAAGC,eAAA,CAAW,CAAA,CAAE,MAAA,EAAQ,QAAQ,GAAG,QAAQ,CAAA;AAChG;;;AC3KA,IAAM,KAAA,GAAQ,CAAC,EAAA,KAAe,IAAI,OAAA,CAAQ,CAAC,CAAA,KAAM,UAAA,CAAW,CAAA,EAAG,EAAE,CAAC,CAAA;AAElE,eAAe,IAAA,CACb,QACA,IAAA,EACwB;AACxB,EAAA,MAAM,SAAA,GAAY,IAAA,CAAK,SAAA,IAAa,EAAA,GAAK,EAAA,GAAK,GAAA;AAC9C,EAAA,MAAM,cAAA,GAAiB,KAAK,cAAA,IAAkB,GAAA;AAC9C,EAAA,MAAM,QAAA,GAAW,IAAA,CAAK,GAAA,EAAI,GAAI,SAAA;AAC9B,EAAA,IAAI,IAAA;AACJ,EAAA,OAAO,IAAA,CAAK,GAAA,EAAI,GAAI,QAAA,EAAU;AAC5B,IAAA,IAAI,IAAA,CAAK,QAAQ,OAAA,EAAS;AAC1B,IAAA,IAAA,GAAO,MAAM,MAAA,EAAO;AACpB,IAAA,IAAI,IAAA,CAAK,SAAS,OAAO,IAAA;AACzB,IAAA,IAAI,KAAK,MAAA,KAAW,WAAA,IAAe,IAAA,CAAK,MAAA,KAAW,YAAY,OAAO,IAAA;AACtE,IAAA,MAAM,MAAM,cAAc,CAAA;AAAA,EAC5B;AACA,EAAA,OAAO,IAAA,IAAQ,KAAK,MAAA,KAAW,SAAA,GAC3B,EAAE,GAAG,IAAA,EAAM,MAAA,EAAQ,SAAA,EAAU,GAC7B;AAAA,IACE,OAAA,EAAS,KAAA;AAAA,IACT,MAAA,EAAQ,SAAA;AAAA,IACR,QAAA,EAAU,MAAM,QAAA,IAAY,EAAA;AAAA,IAC5B,KAAA,EAAO,MAAM,KAAA,IAAS,MAAA;AAAA,IACtB,SAAS,EAAC;AAAA,IACV,MAAA,EAAQ;AAAA,GACV;AACN;AAEO,SAAS,mBAAmB,CAAA,EAA2D;AAC5F,EAAA,OAAO,IAAA,CAAK,MAAM,iBAAA,CAAkB,CAAC,GAAG,CAAC,CAAA;AAC3C;AACO,SAAS,kBAAkB,CAAA,EAA0D;AAC1F,EAAA,OAAO,IAAA,CAAK,MAAM,gBAAA,CAAiB,CAAC,GAAG,CAAC,CAAA;AAC1C","file":"index.cjs","sourcesContent":["import type { Transaction } from \"@hbar-kit/mirror\"\nimport type { MemoComparison, PaymentAsset } from \"./types.js\"\n\n/** Signed sum of ALL the receiver's legs (HBAR transfers or a specific token's transfers). */\nexport function netToReceiver(tx: Transaction, receiver: string, asset: PaymentAsset): bigint {\n  if (asset === \"HBAR\") {\n    return tx.transfers.filter((t) => t.account === receiver).reduce((s, t) => s + t.amount, 0n)\n  }\n  return tx.tokenTransfers\n    .filter((t) => t.tokenId === asset.tokenId && t.account === receiver)\n    .reduce((s, t) => s + t.amount, 0n)\n}\n\nexport function memoMatches(actual: string, expected: string, cmp: MemoComparison = {}): boolean {\n  const mode = cmp.mode ?? \"exact\"\n  if (mode === \"trim\") return actual.trim() === expected.trim()\n  if (mode === \"caseInsensitive\") return actual.toLowerCase() === expected.toLowerCase()\n  return actual === expected\n}\n\nexport type AmountClass = \"exact\" | \"underpaid\" | \"overpaid\"\nexport function classifyAmount(net: bigint, expected: bigint): AmountClass {\n  if (net === expected) return \"exact\"\n  return net < expected ? \"underpaid\" : \"overpaid\"\n}\n","import { NETWORKS, txIdToMirror, type HederaNetwork } from \"@hbar-kit/core\"\n\n/** HashScan transaction link: consensus timestamp in path, tx id as ?tid query param. */\nexport function hashscanTxUrl(\n  network: HederaNetwork,\n  consensusTimestamp: string,\n  transactionId: string,\n): string {\n  return `${NETWORKS[network].hashscan}/transaction/${consensusTimestamp}?tid=${txIdToMirror(transactionId)}`\n}\n","import {\n  parseUnits,\n  parseHbar,\n  formatUnits,\n  type HederaNetwork,\n  type NetworkInput,\n  InvalidParamsError,\n} from \"@hbar-kit/core\"\nimport {\n  createMirrorClient,\n  normalizeTransaction,\n  type MirrorClient,\n  type RawTransaction,\n  type Transaction,\n} from \"@hbar-kit/mirror\"\nimport { netToReceiver, memoMatches, classifyAmount } from \"./match.js\"\nimport { hashscanTxUrl } from \"./explorer.js\"\nimport type { MemoComparison, PaymentAsset, PaymentMatch, PaymentResult } from \"./types.js\"\n\nexport interface VerifyBaseParams extends NetworkInput {\n  client?: MirrorClient\n  receiver: string\n  amount: string\n  memo?: string\n  memoComparison?: MemoComparison\n  comparison?: \"exact\" | \"atLeast\"\n  after?: Date | string\n  before?: Date | string\n}\nexport type VerifyHbarParams = VerifyBaseParams\nexport interface VerifyHtsParams extends VerifyBaseParams {\n  tokenId: string\n  decimals?: number\n}\n\nconst tokenDecimalsCache = new Map<string, number>()\n\nfunction resolveClient(p: VerifyBaseParams): { client: MirrorClient; network: HederaNetwork } {\n  return {\n    client: p.client ?? createMirrorClient(p),\n    network: (p.network ?? \"mainnet\") as HederaNetwork,\n  }\n}\n\nasync function runVerify(\n  p: VerifyBaseParams,\n  asset: PaymentAsset,\n  expectedBase: bigint,\n  decimals: number,\n): Promise<PaymentResult> {\n  if (p.after && p.before && new Date(p.after) > new Date(p.before)) {\n    throw new InvalidParamsError(\"`after` must be before `before`\")\n  }\n  const { client, network } = resolveClient(p)\n  const tokenId = asset === \"HBAR\" ? undefined : asset.tokenId\n\n  const candidates: PaymentMatch[] = []\n  const collect = (items: Transaction[]) => {\n    for (const tx of items) {\n      if (tx.result !== \"SUCCESS\") continue\n      const net = netToReceiver(tx, p.receiver, asset)\n      if (net <= 0n) continue\n      if (tokenId && !tx.tokenTransfers.some((t) => t.tokenId === tokenId)) continue\n      const payer =\n        tx.transfers.find((t) => t.amount < 0n)?.account ??\n        tx.tokenTransfers.find((t) => t.amount < 0n)?.account\n      const match: PaymentMatch = {\n        transactionId: tx.transactionId,\n        consensusTimestamp: tx.consensusTimestamp.raw,\n        netBase: net,\n        net: formatUnits(net, decimals),\n        memo: tx.memo,\n        transaction: tx,\n      }\n      if (payer !== undefined) match.payer = payer\n      candidates.push(match)\n    }\n  }\n\n  const findParams: Parameters<typeof client.transactions.find>[0] = {\n    accountId: p.receiver,\n    transactionType: \"cryptotransfer\",\n    result: \"success\",\n    order: \"desc\",\n  }\n  if (p.after !== undefined) findParams.after = p.after\n  if (p.before !== undefined) findParams.before = p.before\n  let page = await client.transactions.find(findParams)\n  collect(page.items)\n  while (page.next) {\n    const body = (await client.transport.get(page.next)) as {\n      transactions?: RawTransaction[]\n      links?: { next: string | null }\n    }\n    collect((body.transactions ?? []).map(normalizeTransaction))\n    page = { items: [], next: body.links?.next ?? null }\n  }\n\n  const memoFiltered = p.memo\n    ? candidates.filter((c) => memoMatches(c.memo, p.memo!, p.memoComparison))\n    : candidates\n\n  const fail = (status: PaymentResult[\"status\"], reason: string): PaymentResult => ({\n    matched: false,\n    status,\n    receiver: p.receiver,\n    asset,\n    matches: memoFiltered,\n    reason,\n  })\n  if (candidates.length === 0)\n    return fail(\"pending\", \"no matching transactions for receiver in window\")\n  if (p.memo && memoFiltered.length === 0)\n    return fail(\"mismatch\", \"no transaction matched the expected memo\")\n\n  const wantAtLeast = p.comparison === \"atLeast\"\n  const satisfying = memoFiltered.filter((c) =>\n    wantAtLeast ? c.netBase >= expectedBase : c.netBase === expectedBase,\n  )\n\n  const resultFrom = (\n    m: PaymentMatch,\n    status: PaymentResult[\"status\"],\n    matched: boolean,\n    matches: PaymentMatch[],\n    reason?: string,\n  ): PaymentResult => {\n    const result: PaymentResult = {\n      matched,\n      status,\n      receiver: p.receiver,\n      asset,\n      transactionId: m.transactionId,\n      amountBase: m.netBase,\n      amount: m.net,\n      memo: m.memo,\n      consensusTimestamp: m.consensusTimestamp,\n      explorerUrl: hashscanTxUrl(network, m.consensusTimestamp, m.transactionId),\n      matches,\n    }\n    if (m.payer !== undefined) result.payer = m.payer\n    if (reason !== undefined) result.reason = reason\n    return result\n  }\n\n  if (satisfying.length === 0) {\n    const best = memoFiltered[0]!\n    const cls = classifyAmount(best.netBase, expectedBase)\n    return resultFrom(\n      best,\n      cls === \"exact\" ? \"confirmed\" : cls,\n      false,\n      memoFiltered,\n      `amount ${cls}`,\n    )\n  }\n  if (satisfying.length > 1) {\n    return resultFrom(\n      satisfying[0]!,\n      \"duplicate\",\n      false,\n      satisfying,\n      `${satisfying.length} transactions satisfy this request`,\n    )\n  }\n  return resultFrom(satisfying[0]!, \"confirmed\", true, satisfying)\n}\n\nexport async function verifyHbarPayment(p: VerifyHbarParams): Promise<PaymentResult> {\n  return runVerify(p, \"HBAR\", parseHbar(p.amount), 8)\n}\n\nexport async function verifyHtsPayment(p: VerifyHtsParams): Promise<PaymentResult> {\n  let decimals = p.decimals\n  if (decimals === undefined) {\n    const cached = tokenDecimalsCache.get(p.tokenId)\n    if (cached !== undefined) decimals = cached\n    else {\n      const { client } = resolveClient(p)\n      decimals = (await client.tokens.get(p.tokenId)).decimals\n      tokenDecimalsCache.set(p.tokenId, decimals)\n    }\n  }\n  return runVerify(p, { tokenId: p.tokenId, decimals }, parseUnits(p.amount, decimals), decimals)\n}\n","import {\n  verifyHbarPayment,\n  verifyHtsPayment,\n  type VerifyHbarParams,\n  type VerifyHtsParams,\n} from \"./verify.js\"\nimport type { PaymentResult } from \"./types.js\"\n\nexport interface WaitOptions {\n  timeoutMs?: number\n  pollIntervalMs?: number\n  signal?: AbortSignal\n}\nconst sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))\n\nasync function poll(\n  verify: () => Promise<PaymentResult>,\n  opts: WaitOptions,\n): Promise<PaymentResult> {\n  const timeoutMs = opts.timeoutMs ?? 10 * 60 * 1000\n  const pollIntervalMs = opts.pollIntervalMs ?? 3000\n  const deadline = Date.now() + timeoutMs\n  let last: PaymentResult | undefined\n  while (Date.now() < deadline) {\n    if (opts.signal?.aborted) break\n    last = await verify()\n    if (last.matched) return last\n    if (last.status === \"duplicate\" || last.status === \"overpaid\") return last\n    await sleep(pollIntervalMs)\n  }\n  return last && last.status !== \"pending\"\n    ? { ...last, status: \"expired\" }\n    : {\n        matched: false,\n        status: \"expired\",\n        receiver: last?.receiver ?? \"\",\n        asset: last?.asset ?? \"HBAR\",\n        matches: [],\n        reason: \"timed out waiting for payment\",\n      }\n}\n\nexport function waitForHbarPayment(p: VerifyHbarParams & WaitOptions): Promise<PaymentResult> {\n  return poll(() => verifyHbarPayment(p), p)\n}\nexport function waitForHtsPayment(p: VerifyHtsParams & WaitOptions): Promise<PaymentResult> {\n  return poll(() => verifyHtsPayment(p), p)\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,72 @@
+import { NetworkInput, HederaNetwork } from '@hbar-kit/core';
+import { Transaction, MirrorClient } from '@hbar-kit/mirror';
+
+type PaymentStatus = "confirmed" | "pending" | "underpaid" | "overpaid" | "duplicate" | "mismatch" | "expired" | "failed";
+type PaymentAsset = "HBAR" | {
+    tokenId: string;
+    decimals: number;
+};
+interface PaymentMatch {
+    transactionId: string;
+    payer?: string;
+    consensusTimestamp: string;
+    netBase: bigint;
+    net: string;
+    memo: string;
+    transaction: Transaction;
+}
+interface PaymentResult {
+    matched: boolean;
+    status: PaymentStatus;
+    receiver: string;
+    asset: PaymentAsset;
+    transactionId?: string;
+    payer?: string;
+    amount?: string;
+    amountBase?: bigint;
+    memo?: string;
+    consensusTimestamp?: string;
+    explorerUrl?: string;
+    matches: PaymentMatch[];
+    reason?: string;
+}
+interface MemoComparison {
+    mode?: "exact" | "trim" | "caseInsensitive";
+}
+
+interface VerifyBaseParams extends NetworkInput {
+    client?: MirrorClient;
+    receiver: string;
+    amount: string;
+    memo?: string;
+    memoComparison?: MemoComparison;
+    comparison?: "exact" | "atLeast";
+    after?: Date | string;
+    before?: Date | string;
+}
+type VerifyHbarParams = VerifyBaseParams;
+interface VerifyHtsParams extends VerifyBaseParams {
+    tokenId: string;
+    decimals?: number;
+}
+declare function verifyHbarPayment(p: VerifyHbarParams): Promise<PaymentResult>;
+declare function verifyHtsPayment(p: VerifyHtsParams): Promise<PaymentResult>;
+
+interface WaitOptions {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
+}
+declare function waitForHbarPayment(p: VerifyHbarParams & WaitOptions): Promise<PaymentResult>;
+declare function waitForHtsPayment(p: VerifyHtsParams & WaitOptions): Promise<PaymentResult>;
+
+/** HashScan transaction link: consensus timestamp in path, tx id as ?tid query param. */
+declare function hashscanTxUrl(network: HederaNetwork, consensusTimestamp: string, transactionId: string): string;
+
+/** Signed sum of ALL the receiver's legs (HBAR transfers or a specific token's transfers). */
+declare function netToReceiver(tx: Transaction, receiver: string, asset: PaymentAsset): bigint;
+declare function memoMatches(actual: string, expected: string, cmp?: MemoComparison): boolean;
+type AmountClass = "exact" | "underpaid" | "overpaid";
+declare function classifyAmount(net: bigint, expected: bigint): AmountClass;
+
+export { type MemoComparison, type PaymentAsset, type PaymentMatch, type PaymentResult, type PaymentStatus, type VerifyBaseParams, type VerifyHbarParams, type VerifyHtsParams, type WaitOptions, classifyAmount, hashscanTxUrl, memoMatches, netToReceiver, verifyHbarPayment, verifyHtsPayment, waitForHbarPayment, waitForHtsPayment };

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+import { NetworkInput, HederaNetwork } from '@hbar-kit/core';
+import { Transaction, MirrorClient } from '@hbar-kit/mirror';
+
+type PaymentStatus = "confirmed" | "pending" | "underpaid" | "overpaid" | "duplicate" | "mismatch" | "expired" | "failed";
+type PaymentAsset = "HBAR" | {
+    tokenId: string;
+    decimals: number;
+};
+interface PaymentMatch {
+    transactionId: string;
+    payer?: string;
+    consensusTimestamp: string;
+    netBase: bigint;
+    net: string;
+    memo: string;
+    transaction: Transaction;
+}
+interface PaymentResult {
+    matched: boolean;
+    status: PaymentStatus;
+    receiver: string;
+    asset: PaymentAsset;
+    transactionId?: string;
+    payer?: string;
+    amount?: string;
+    amountBase?: bigint;
+    memo?: string;
+    consensusTimestamp?: string;
+    explorerUrl?: string;
+    matches: PaymentMatch[];
+    reason?: string;
+}
+interface MemoComparison {
+    mode?: "exact" | "trim" | "caseInsensitive";
+}
+
+interface VerifyBaseParams extends NetworkInput {
+    client?: MirrorClient;
+    receiver: string;
+    amount: string;
+    memo?: string;
+    memoComparison?: MemoComparison;
+    comparison?: "exact" | "atLeast";
+    after?: Date | string;
+    before?: Date | string;
+}
+type VerifyHbarParams = VerifyBaseParams;
+interface VerifyHtsParams extends VerifyBaseParams {
+    tokenId: string;
+    decimals?: number;
+}
+declare function verifyHbarPayment(p: VerifyHbarParams): Promise<PaymentResult>;
+declare function verifyHtsPayment(p: VerifyHtsParams): Promise<PaymentResult>;
+
+interface WaitOptions {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
+}
+declare function waitForHbarPayment(p: VerifyHbarParams & WaitOptions): Promise<PaymentResult>;
+declare function waitForHtsPayment(p: VerifyHtsParams & WaitOptions): Promise<PaymentResult>;
+
+/** HashScan transaction link: consensus timestamp in path, tx id as ?tid query param. */
+declare function hashscanTxUrl(network: HederaNetwork, consensusTimestamp: string, transactionId: string): string;
+
+/** Signed sum of ALL the receiver's legs (HBAR transfers or a specific token's transfers). */
+declare function netToReceiver(tx: Transaction, receiver: string, asset: PaymentAsset): bigint;
+declare function memoMatches(actual: string, expected: string, cmp?: MemoComparison): boolean;
+type AmountClass = "exact" | "underpaid" | "overpaid";
+declare function classifyAmount(net: bigint, expected: bigint): AmountClass;
+
+export { type MemoComparison, type PaymentAsset, type PaymentMatch, type PaymentResult, type PaymentStatus, type VerifyBaseParams, type VerifyHbarParams, type VerifyHtsParams, type WaitOptions, classifyAmount, hashscanTxUrl, memoMatches, netToReceiver, verifyHbarPayment, verifyHtsPayment, waitForHbarPayment, waitForHtsPayment };

package/dist/index.js

@@ -0,0 +1,182 @@
+import { NETWORKS, txIdToMirror, parseHbar, parseUnits, InvalidParamsError, formatUnits } from '@hbar-kit/core';
+import { normalizeTransaction, createMirrorClient } from '@hbar-kit/mirror';
+
+// src/verify.ts
+
+// src/match.ts
+function netToReceiver(tx, receiver, asset) {
+  if (asset === "HBAR") {
+    return tx.transfers.filter((t) => t.account === receiver).reduce((s, t) => s + t.amount, 0n);
+  }
+  return tx.tokenTransfers.filter((t) => t.tokenId === asset.tokenId && t.account === receiver).reduce((s, t) => s + t.amount, 0n);
+}
+function memoMatches(actual, expected, cmp = {}) {
+  const mode = cmp.mode ?? "exact";
+  if (mode === "trim") return actual.trim() === expected.trim();
+  if (mode === "caseInsensitive") return actual.toLowerCase() === expected.toLowerCase();
+  return actual === expected;
+}
+function classifyAmount(net, expected) {
+  if (net === expected) return "exact";
+  return net < expected ? "underpaid" : "overpaid";
+}
+function hashscanTxUrl(network, consensusTimestamp, transactionId) {
+  return `${NETWORKS[network].hashscan}/transaction/${consensusTimestamp}?tid=${txIdToMirror(transactionId)}`;
+}
+
+// src/verify.ts
+var tokenDecimalsCache = /* @__PURE__ */ new Map();
+function resolveClient(p) {
+  return {
+    client: p.client ?? createMirrorClient(p),
+    network: p.network ?? "mainnet"
+  };
+}
+async function runVerify(p, asset, expectedBase, decimals) {
+  if (p.after && p.before && new Date(p.after) > new Date(p.before)) {
+    throw new InvalidParamsError("`after` must be before `before`");
+  }
+  const { client, network } = resolveClient(p);
+  const tokenId = asset === "HBAR" ? void 0 : asset.tokenId;
+  const candidates = [];
+  const collect = (items) => {
+    for (const tx of items) {
+      if (tx.result !== "SUCCESS") continue;
+      const net = netToReceiver(tx, p.receiver, asset);
+      if (net <= 0n) continue;
+      if (tokenId && !tx.tokenTransfers.some((t) => t.tokenId === tokenId)) continue;
+      const payer = tx.transfers.find((t) => t.amount < 0n)?.account ?? tx.tokenTransfers.find((t) => t.amount < 0n)?.account;
+      const match = {
+        transactionId: tx.transactionId,
+        consensusTimestamp: tx.consensusTimestamp.raw,
+        netBase: net,
+        net: formatUnits(net, decimals),
+        memo: tx.memo,
+        transaction: tx
+      };
+      if (payer !== void 0) match.payer = payer;
+      candidates.push(match);
+    }
+  };
+  const findParams = {
+    accountId: p.receiver,
+    transactionType: "cryptotransfer",
+    result: "success",
+    order: "desc"
+  };
+  if (p.after !== void 0) findParams.after = p.after;
+  if (p.before !== void 0) findParams.before = p.before;
+  let page = await client.transactions.find(findParams);
+  collect(page.items);
+  while (page.next) {
+    const body = await client.transport.get(page.next);
+    collect((body.transactions ?? []).map(normalizeTransaction));
+    page = { items: [], next: body.links?.next ?? null };
+  }
+  const memoFiltered = p.memo ? candidates.filter((c) => memoMatches(c.memo, p.memo, p.memoComparison)) : candidates;
+  const fail = (status, reason) => ({
+    matched: false,
+    status,
+    receiver: p.receiver,
+    asset,
+    matches: memoFiltered,
+    reason
+  });
+  if (candidates.length === 0)
+    return fail("pending", "no matching transactions for receiver in window");
+  if (p.memo && memoFiltered.length === 0)
+    return fail("mismatch", "no transaction matched the expected memo");
+  const wantAtLeast = p.comparison === "atLeast";
+  const satisfying = memoFiltered.filter(
+    (c) => wantAtLeast ? c.netBase >= expectedBase : c.netBase === expectedBase
+  );
+  const resultFrom = (m, status, matched, matches, reason) => {
+    const result = {
+      matched,
+      status,
+      receiver: p.receiver,
+      asset,
+      transactionId: m.transactionId,
+      amountBase: m.netBase,
+      amount: m.net,
+      memo: m.memo,
+      consensusTimestamp: m.consensusTimestamp,
+      explorerUrl: hashscanTxUrl(network, m.consensusTimestamp, m.transactionId),
+      matches
+    };
+    if (m.payer !== void 0) result.payer = m.payer;
+    if (reason !== void 0) result.reason = reason;
+    return result;
+  };
+  if (satisfying.length === 0) {
+    const best = memoFiltered[0];
+    const cls = classifyAmount(best.netBase, expectedBase);
+    return resultFrom(
+      best,
+      cls === "exact" ? "confirmed" : cls,
+      false,
+      memoFiltered,
+      `amount ${cls}`
+    );
+  }
+  if (satisfying.length > 1) {
+    return resultFrom(
+      satisfying[0],
+      "duplicate",
+      false,
+      satisfying,
+      `${satisfying.length} transactions satisfy this request`
+    );
+  }
+  return resultFrom(satisfying[0], "confirmed", true, satisfying);
+}
+async function verifyHbarPayment(p) {
+  return runVerify(p, "HBAR", parseHbar(p.amount), 8);
+}
+async function verifyHtsPayment(p) {
+  let decimals = p.decimals;
+  if (decimals === void 0) {
+    const cached = tokenDecimalsCache.get(p.tokenId);
+    if (cached !== void 0) decimals = cached;
+    else {
+      const { client } = resolveClient(p);
+      decimals = (await client.tokens.get(p.tokenId)).decimals;
+      tokenDecimalsCache.set(p.tokenId, decimals);
+    }
+  }
+  return runVerify(p, { tokenId: p.tokenId, decimals }, parseUnits(p.amount, decimals), decimals);
+}
+
+// src/wait.ts
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function poll(verify, opts) {
+  const timeoutMs = opts.timeoutMs ?? 10 * 60 * 1e3;
+  const pollIntervalMs = opts.pollIntervalMs ?? 3e3;
+  const deadline = Date.now() + timeoutMs;
+  let last;
+  while (Date.now() < deadline) {
+    if (opts.signal?.aborted) break;
+    last = await verify();
+    if (last.matched) return last;
+    if (last.status === "duplicate" || last.status === "overpaid") return last;
+    await sleep(pollIntervalMs);
+  }
+  return last && last.status !== "pending" ? { ...last, status: "expired" } : {
+    matched: false,
+    status: "expired",
+    receiver: last?.receiver ?? "",
+    asset: last?.asset ?? "HBAR",
+    matches: [],
+    reason: "timed out waiting for payment"
+  };
+}
+function waitForHbarPayment(p) {
+  return poll(() => verifyHbarPayment(p), p);
+}
+function waitForHtsPayment(p) {
+  return poll(() => verifyHtsPayment(p), p);
+}
+
+export { classifyAmount, hashscanTxUrl, memoMatches, netToReceiver, verifyHbarPayment, verifyHtsPayment, waitForHbarPayment, waitForHtsPayment };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/match.ts","../src/explorer.ts","../src/verify.ts","../src/wait.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { Transaction } from \"@hbar-kit/mirror\"\nimport type { MemoComparison, PaymentAsset } from \"./types.js\"\n\n/** Signed sum of ALL the receiver's legs (HBAR transfers or a specific token's transfers). */\nexport function netToReceiver(tx: Transaction, receiver: string, asset: PaymentAsset): bigint {\n  if (asset === \"HBAR\") {\n    return tx.transfers.filter((t) => t.account === receiver).reduce((s, t) => s + t.amount, 0n)\n  }\n  return tx.tokenTransfers\n    .filter((t) => t.tokenId === asset.tokenId && t.account === receiver)\n    .reduce((s, t) => s + t.amount, 0n)\n}\n\nexport function memoMatches(actual: string, expected: string, cmp: MemoComparison = {}): boolean {\n  const mode = cmp.mode ?? \"exact\"\n  if (mode === \"trim\") return actual.trim() === expected.trim()\n  if (mode === \"caseInsensitive\") return actual.toLowerCase() === expected.toLowerCase()\n  return actual === expected\n}\n\nexport type AmountClass = \"exact\" | \"underpaid\" | \"overpaid\"\nexport function classifyAmount(net: bigint, expected: bigint): AmountClass {\n  if (net === expected) return \"exact\"\n  return net < expected ? \"underpaid\" : \"overpaid\"\n}\n","import { NETWORKS, txIdToMirror, type HederaNetwork } from \"@hbar-kit/core\"\n\n/** HashScan transaction link: consensus timestamp in path, tx id as ?tid query param. */\nexport function hashscanTxUrl(\n  network: HederaNetwork,\n  consensusTimestamp: string,\n  transactionId: string,\n): string {\n  return `${NETWORKS[network].hashscan}/transaction/${consensusTimestamp}?tid=${txIdToMirror(transactionId)}`\n}\n","import {\n  parseUnits,\n  parseHbar,\n  formatUnits,\n  type HederaNetwork,\n  type NetworkInput,\n  InvalidParamsError,\n} from \"@hbar-kit/core\"\nimport {\n  createMirrorClient,\n  normalizeTransaction,\n  type MirrorClient,\n  type RawTransaction,\n  type Transaction,\n} from \"@hbar-kit/mirror\"\nimport { netToReceiver, memoMatches, classifyAmount } from \"./match.js\"\nimport { hashscanTxUrl } from \"./explorer.js\"\nimport type { MemoComparison, PaymentAsset, PaymentMatch, PaymentResult } from \"./types.js\"\n\nexport interface VerifyBaseParams extends NetworkInput {\n  client?: MirrorClient\n  receiver: string\n  amount: string\n  memo?: string\n  memoComparison?: MemoComparison\n  comparison?: \"exact\" | \"atLeast\"\n  after?: Date | string\n  before?: Date | string\n}\nexport type VerifyHbarParams = VerifyBaseParams\nexport interface VerifyHtsParams extends VerifyBaseParams {\n  tokenId: string\n  decimals?: number\n}\n\nconst tokenDecimalsCache = new Map<string, number>()\n\nfunction resolveClient(p: VerifyBaseParams): { client: MirrorClient; network: HederaNetwork } {\n  return {\n    client: p.client ?? createMirrorClient(p),\n    network: (p.network ?? \"mainnet\") as HederaNetwork,\n  }\n}\n\nasync function runVerify(\n  p: VerifyBaseParams,\n  asset: PaymentAsset,\n  expectedBase: bigint,\n  decimals: number,\n): Promise<PaymentResult> {\n  if (p.after && p.before && new Date(p.after) > new Date(p.before)) {\n    throw new InvalidParamsError(\"`after` must be before `before`\")\n  }\n  const { client, network } = resolveClient(p)\n  const tokenId = asset === \"HBAR\" ? undefined : asset.tokenId\n\n  const candidates: PaymentMatch[] = []\n  const collect = (items: Transaction[]) => {\n    for (const tx of items) {\n      if (tx.result !== \"SUCCESS\") continue\n      const net = netToReceiver(tx, p.receiver, asset)\n      if (net <= 0n) continue\n      if (tokenId && !tx.tokenTransfers.some((t) => t.tokenId === tokenId)) continue\n      const payer =\n        tx.transfers.find((t) => t.amount < 0n)?.account ??\n        tx.tokenTransfers.find((t) => t.amount < 0n)?.account\n      const match: PaymentMatch = {\n        transactionId: tx.transactionId,\n        consensusTimestamp: tx.consensusTimestamp.raw,\n        netBase: net,\n        net: formatUnits(net, decimals),\n        memo: tx.memo,\n        transaction: tx,\n      }\n      if (payer !== undefined) match.payer = payer\n      candidates.push(match)\n    }\n  }\n\n  const findParams: Parameters<typeof client.transactions.find>[0] = {\n    accountId: p.receiver,\n    transactionType: \"cryptotransfer\",\n    result: \"success\",\n    order: \"desc\",\n  }\n  if (p.after !== undefined) findParams.after = p.after\n  if (p.before !== undefined) findParams.before = p.before\n  let page = await client.transactions.find(findParams)\n  collect(page.items)\n  while (page.next) {\n    const body = (await client.transport.get(page.next)) as {\n      transactions?: RawTransaction[]\n      links?: { next: string | null }\n    }\n    collect((body.transactions ?? []).map(normalizeTransaction))\n    page = { items: [], next: body.links?.next ?? null }\n  }\n\n  const memoFiltered = p.memo\n    ? candidates.filter((c) => memoMatches(c.memo, p.memo!, p.memoComparison))\n    : candidates\n\n  const fail = (status: PaymentResult[\"status\"], reason: string): PaymentResult => ({\n    matched: false,\n    status,\n    receiver: p.receiver,\n    asset,\n    matches: memoFiltered,\n    reason,\n  })\n  if (candidates.length === 0)\n    return fail(\"pending\", \"no matching transactions for receiver in window\")\n  if (p.memo && memoFiltered.length === 0)\n    return fail(\"mismatch\", \"no transaction matched the expected memo\")\n\n  const wantAtLeast = p.comparison === \"atLeast\"\n  const satisfying = memoFiltered.filter((c) =>\n    wantAtLeast ? c.netBase >= expectedBase : c.netBase === expectedBase,\n  )\n\n  const resultFrom = (\n    m: PaymentMatch,\n    status: PaymentResult[\"status\"],\n    matched: boolean,\n    matches: PaymentMatch[],\n    reason?: string,\n  ): PaymentResult => {\n    const result: PaymentResult = {\n      matched,\n      status,\n      receiver: p.receiver,\n      asset,\n      transactionId: m.transactionId,\n      amountBase: m.netBase,\n      amount: m.net,\n      memo: m.memo,\n      consensusTimestamp: m.consensusTimestamp,\n      explorerUrl: hashscanTxUrl(network, m.consensusTimestamp, m.transactionId),\n      matches,\n    }\n    if (m.payer !== undefined) result.payer = m.payer\n    if (reason !== undefined) result.reason = reason\n    return result\n  }\n\n  if (satisfying.length === 0) {\n    const best = memoFiltered[0]!\n    const cls = classifyAmount(best.netBase, expectedBase)\n    return resultFrom(\n      best,\n      cls === \"exact\" ? \"confirmed\" : cls,\n      false,\n      memoFiltered,\n      `amount ${cls}`,\n    )\n  }\n  if (satisfying.length > 1) {\n    return resultFrom(\n      satisfying[0]!,\n      \"duplicate\",\n      false,\n      satisfying,\n      `${satisfying.length} transactions satisfy this request`,\n    )\n  }\n  return resultFrom(satisfying[0]!, \"confirmed\", true, satisfying)\n}\n\nexport async function verifyHbarPayment(p: VerifyHbarParams): Promise<PaymentResult> {\n  return runVerify(p, \"HBAR\", parseHbar(p.amount), 8)\n}\n\nexport async function verifyHtsPayment(p: VerifyHtsParams): Promise<PaymentResult> {\n  let decimals = p.decimals\n  if (decimals === undefined) {\n    const cached = tokenDecimalsCache.get(p.tokenId)\n    if (cached !== undefined) decimals = cached\n    else {\n      const { client } = resolveClient(p)\n      decimals = (await client.tokens.get(p.tokenId)).decimals\n      tokenDecimalsCache.set(p.tokenId, decimals)\n    }\n  }\n  return runVerify(p, { tokenId: p.tokenId, decimals }, parseUnits(p.amount, decimals), decimals)\n}\n","import {\n  verifyHbarPayment,\n  verifyHtsPayment,\n  type VerifyHbarParams,\n  type VerifyHtsParams,\n} from \"./verify.js\"\nimport type { PaymentResult } from \"./types.js\"\n\nexport interface WaitOptions {\n  timeoutMs?: number\n  pollIntervalMs?: number\n  signal?: AbortSignal\n}\nconst sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))\n\nasync function poll(\n  verify: () => Promise<PaymentResult>,\n  opts: WaitOptions,\n): Promise<PaymentResult> {\n  const timeoutMs = opts.timeoutMs ?? 10 * 60 * 1000\n  const pollIntervalMs = opts.pollIntervalMs ?? 3000\n  const deadline = Date.now() + timeoutMs\n  let last: PaymentResult | undefined\n  while (Date.now() < deadline) {\n    if (opts.signal?.aborted) break\n    last = await verify()\n    if (last.matched) return last\n    if (last.status === \"duplicate\" || last.status === \"overpaid\") return last\n    await sleep(pollIntervalMs)\n  }\n  return last && last.status !== \"pending\"\n    ? { ...last, status: \"expired\" }\n    : {\n        matched: false,\n        status: \"expired\",\n        receiver: last?.receiver ?? \"\",\n        asset: last?.asset ?? \"HBAR\",\n        matches: [],\n        reason: \"timed out waiting for payment\",\n      }\n}\n\nexport function waitForHbarPayment(p: VerifyHbarParams & WaitOptions): Promise<PaymentResult> {\n  return poll(() => verifyHbarPayment(p), p)\n}\nexport function waitForHtsPayment(p: VerifyHtsParams & WaitOptions): Promise<PaymentResult> {\n  return poll(() => verifyHtsPayment(p), p)\n}\n"]}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@hbar-kit/payments",
+  "version": "0.1.0",
+  "description": "Business-level HBAR/HTS payment verification on top of @hbar-kit/mirror.",
+  "license": "MIT",
+  "homepage": "https://devwhodevs.github.io/hbar-kit/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devwhodevs/hbar-kit.git",
+    "directory": "packages/payments"
+  },
+  "bugs": "https://github.com/devwhodevs/hbar-kit/issues",
+  "keywords": [
+    "hedera",
+    "hbar",
+    "hts",
+    "payments",
+    "payment-verification",
+    "mirror-node",
+    "typescript"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@hbar-kit/core": "0.1.0",
+    "@hbar-kit/mirror": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "check:publish": "publint --strict && attw --pack ."
+  }
+}

package/src/explorer.ts

@@ -0,0 +1,10 @@
+import { NETWORKS, txIdToMirror, type HederaNetwork } from "@hbar-kit/core"
+
+/** HashScan transaction link: consensus timestamp in path, tx id as ?tid query param. */
+export function hashscanTxUrl(
+  network: HederaNetwork,
+  consensusTimestamp: string,
+  transactionId: string,
+): string {
+  return `${NETWORKS[network].hashscan}/transaction/${consensusTimestamp}?tid=${txIdToMirror(transactionId)}`
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export { verifyHbarPayment, verifyHtsPayment } from "./verify.js"
+export type { VerifyHbarParams, VerifyHtsParams, VerifyBaseParams } from "./verify.js"
+export { waitForHbarPayment, waitForHtsPayment } from "./wait.js"
+export type { WaitOptions } from "./wait.js"
+export { hashscanTxUrl } from "./explorer.js"
+export { netToReceiver, memoMatches, classifyAmount } from "./match.js"
+export type {
+  PaymentResult,
+  PaymentStatus,
+  PaymentMatch,
+  PaymentAsset,
+  MemoComparison,
+} from "./types.js"

package/src/match.ts

@@ -0,0 +1,25 @@
+import type { Transaction } from "@hbar-kit/mirror"
+import type { MemoComparison, PaymentAsset } from "./types.js"
+
+/** Signed sum of ALL the receiver's legs (HBAR transfers or a specific token's transfers). */
+export function netToReceiver(tx: Transaction, receiver: string, asset: PaymentAsset): bigint {
+  if (asset === "HBAR") {
+    return tx.transfers.filter((t) => t.account === receiver).reduce((s, t) => s + t.amount, 0n)
+  }
+  return tx.tokenTransfers
+    .filter((t) => t.tokenId === asset.tokenId && t.account === receiver)
+    .reduce((s, t) => s + t.amount, 0n)
+}
+
+export function memoMatches(actual: string, expected: string, cmp: MemoComparison = {}): boolean {
+  const mode = cmp.mode ?? "exact"
+  if (mode === "trim") return actual.trim() === expected.trim()
+  if (mode === "caseInsensitive") return actual.toLowerCase() === expected.toLowerCase()
+  return actual === expected
+}
+
+export type AmountClass = "exact" | "underpaid" | "overpaid"
+export function classifyAmount(net: bigint, expected: bigint): AmountClass {
+  if (net === expected) return "exact"
+  return net < expected ? "underpaid" : "overpaid"
+}

package/src/types.ts

@@ -0,0 +1,43 @@
+import type { Transaction } from "@hbar-kit/mirror"
+
+export type PaymentStatus =
+  | "confirmed"
+  | "pending"
+  | "underpaid"
+  | "overpaid"
+  | "duplicate"
+  | "mismatch"
+  | "expired"
+  | "failed"
+
+export type PaymentAsset = "HBAR" | { tokenId: string; decimals: number }
+
+export interface PaymentMatch {
+  transactionId: string
+  payer?: string
+  consensusTimestamp: string
+  netBase: bigint
+  net: string
+  memo: string
+  transaction: Transaction
+}
+
+export interface PaymentResult {
+  matched: boolean
+  status: PaymentStatus
+  receiver: string
+  asset: PaymentAsset
+  transactionId?: string
+  payer?: string
+  amount?: string
+  amountBase?: bigint
+  memo?: string
+  consensusTimestamp?: string
+  explorerUrl?: string
+  matches: PaymentMatch[]
+  reason?: string
+}
+
+export interface MemoComparison {
+  mode?: "exact" | "trim" | "caseInsensitive"
+}

package/src/verify.ts

@@ -0,0 +1,185 @@
+import {
+  parseUnits,
+  parseHbar,
+  formatUnits,
+  type HederaNetwork,
+  type NetworkInput,
+  InvalidParamsError,
+} from "@hbar-kit/core"
+import {
+  createMirrorClient,
+  normalizeTransaction,
+  type MirrorClient,
+  type RawTransaction,
+  type Transaction,
+} from "@hbar-kit/mirror"
+import { netToReceiver, memoMatches, classifyAmount } from "./match.js"
+import { hashscanTxUrl } from "./explorer.js"
+import type { MemoComparison, PaymentAsset, PaymentMatch, PaymentResult } from "./types.js"
+
+export interface VerifyBaseParams extends NetworkInput {
+  client?: MirrorClient
+  receiver: string
+  amount: string
+  memo?: string
+  memoComparison?: MemoComparison
+  comparison?: "exact" | "atLeast"
+  after?: Date | string
+  before?: Date | string
+}
+export type VerifyHbarParams = VerifyBaseParams
+export interface VerifyHtsParams extends VerifyBaseParams {
+  tokenId: string
+  decimals?: number
+}
+
+const tokenDecimalsCache = new Map<string, number>()
+
+function resolveClient(p: VerifyBaseParams): { client: MirrorClient; network: HederaNetwork } {
+  return {
+    client: p.client ?? createMirrorClient(p),
+    network: (p.network ?? "mainnet") as HederaNetwork,
+  }
+}
+
+async function runVerify(
+  p: VerifyBaseParams,
+  asset: PaymentAsset,
+  expectedBase: bigint,
+  decimals: number,
+): Promise<PaymentResult> {
+  if (p.after && p.before && new Date(p.after) > new Date(p.before)) {
+    throw new InvalidParamsError("`after` must be before `before`")
+  }
+  const { client, network } = resolveClient(p)
+  const tokenId = asset === "HBAR" ? undefined : asset.tokenId
+
+  const candidates: PaymentMatch[] = []
+  const collect = (items: Transaction[]) => {
+    for (const tx of items) {
+      if (tx.result !== "SUCCESS") continue
+      const net = netToReceiver(tx, p.receiver, asset)
+      if (net <= 0n) continue
+      if (tokenId && !tx.tokenTransfers.some((t) => t.tokenId === tokenId)) continue
+      const payer =
+        tx.transfers.find((t) => t.amount < 0n)?.account ??
+        tx.tokenTransfers.find((t) => t.amount < 0n)?.account
+      const match: PaymentMatch = {
+        transactionId: tx.transactionId,
+        consensusTimestamp: tx.consensusTimestamp.raw,
+        netBase: net,
+        net: formatUnits(net, decimals),
+        memo: tx.memo,
+        transaction: tx,
+      }
+      if (payer !== undefined) match.payer = payer
+      candidates.push(match)
+    }
+  }
+
+  const findParams: Parameters<typeof client.transactions.find>[0] = {
+    accountId: p.receiver,
+    transactionType: "cryptotransfer",
+    result: "success",
+    order: "desc",
+  }
+  if (p.after !== undefined) findParams.after = p.after
+  if (p.before !== undefined) findParams.before = p.before
+  let page = await client.transactions.find(findParams)
+  collect(page.items)
+  while (page.next) {
+    const body = (await client.transport.get(page.next)) as {
+      transactions?: RawTransaction[]
+      links?: { next: string | null }
+    }
+    collect((body.transactions ?? []).map(normalizeTransaction))
+    page = { items: [], next: body.links?.next ?? null }
+  }
+
+  const memoFiltered = p.memo
+    ? candidates.filter((c) => memoMatches(c.memo, p.memo!, p.memoComparison))
+    : candidates
+
+  const fail = (status: PaymentResult["status"], reason: string): PaymentResult => ({
+    matched: false,
+    status,
+    receiver: p.receiver,
+    asset,
+    matches: memoFiltered,
+    reason,
+  })
+  if (candidates.length === 0)
+    return fail("pending", "no matching transactions for receiver in window")
+  if (p.memo && memoFiltered.length === 0)
+    return fail("mismatch", "no transaction matched the expected memo")
+
+  const wantAtLeast = p.comparison === "atLeast"
+  const satisfying = memoFiltered.filter((c) =>
+    wantAtLeast ? c.netBase >= expectedBase : c.netBase === expectedBase,
+  )
+
+  const resultFrom = (
+    m: PaymentMatch,
+    status: PaymentResult["status"],
+    matched: boolean,
+    matches: PaymentMatch[],
+    reason?: string,
+  ): PaymentResult => {
+    const result: PaymentResult = {
+      matched,
+      status,
+      receiver: p.receiver,
+      asset,
+      transactionId: m.transactionId,
+      amountBase: m.netBase,
+      amount: m.net,
+      memo: m.memo,
+      consensusTimestamp: m.consensusTimestamp,
+      explorerUrl: hashscanTxUrl(network, m.consensusTimestamp, m.transactionId),
+      matches,
+    }
+    if (m.payer !== undefined) result.payer = m.payer
+    if (reason !== undefined) result.reason = reason
+    return result
+  }
+
+  if (satisfying.length === 0) {
+    const best = memoFiltered[0]!
+    const cls = classifyAmount(best.netBase, expectedBase)
+    return resultFrom(
+      best,
+      cls === "exact" ? "confirmed" : cls,
+      false,
+      memoFiltered,
+      `amount ${cls}`,
+    )
+  }
+  if (satisfying.length > 1) {
+    return resultFrom(
+      satisfying[0]!,
+      "duplicate",
+      false,
+      satisfying,
+      `${satisfying.length} transactions satisfy this request`,
+    )
+  }
+  return resultFrom(satisfying[0]!, "confirmed", true, satisfying)
+}
+
+export async function verifyHbarPayment(p: VerifyHbarParams): Promise<PaymentResult> {
+  return runVerify(p, "HBAR", parseHbar(p.amount), 8)
+}
+
+export async function verifyHtsPayment(p: VerifyHtsParams): Promise<PaymentResult> {
+  let decimals = p.decimals
+  if (decimals === undefined) {
+    const cached = tokenDecimalsCache.get(p.tokenId)
+    if (cached !== undefined) decimals = cached
+    else {
+      const { client } = resolveClient(p)
+      decimals = (await client.tokens.get(p.tokenId)).decimals
+      tokenDecimalsCache.set(p.tokenId, decimals)
+    }
+  }
+  return runVerify(p, { tokenId: p.tokenId, decimals }, parseUnits(p.amount, decimals), decimals)
+}

package/src/wait.ts

@@ -0,0 +1,48 @@
+import {
+  verifyHbarPayment,
+  verifyHtsPayment,
+  type VerifyHbarParams,
+  type VerifyHtsParams,
+} from "./verify.js"
+import type { PaymentResult } from "./types.js"
+
+export interface WaitOptions {
+  timeoutMs?: number
+  pollIntervalMs?: number
+  signal?: AbortSignal
+}
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+async function poll(
+  verify: () => Promise<PaymentResult>,
+  opts: WaitOptions,
+): Promise<PaymentResult> {
+  const timeoutMs = opts.timeoutMs ?? 10 * 60 * 1000
+  const pollIntervalMs = opts.pollIntervalMs ?? 3000
+  const deadline = Date.now() + timeoutMs
+  let last: PaymentResult | undefined
+  while (Date.now() < deadline) {
+    if (opts.signal?.aborted) break
+    last = await verify()
+    if (last.matched) return last
+    if (last.status === "duplicate" || last.status === "overpaid") return last
+    await sleep(pollIntervalMs)
+  }
+  return last && last.status !== "pending"
+    ? { ...last, status: "expired" }
+    : {
+        matched: false,
+        status: "expired",
+        receiver: last?.receiver ?? "",
+        asset: last?.asset ?? "HBAR",
+        matches: [],
+        reason: "timed out waiting for payment",
+      }
+}
+
+export function waitForHbarPayment(p: VerifyHbarParams & WaitOptions): Promise<PaymentResult> {
+  return poll(() => verifyHbarPayment(p), p)
+}
+export function waitForHtsPayment(p: VerifyHtsParams & WaitOptions): Promise<PaymentResult> {
+  return poll(() => verifyHtsPayment(p), p)
+}