ReceiptLedger: Read and Audit On-Chain Payment Receipts

Every time a seller settles a payment, it writes a signed Receipt message to a dedicated HCS topic. The ReceiptLedger class reads those messages and, when you call audit(), cross-checks each receipt against the actual Hedera transaction on the mirror node. This gives both buyers and sellers a tamper-evident, on-chain billing trail that neither party can retroactively alter — without storing any data in a centralised database.

Installation and Import

import { ReceiptLedger } from '@agora402/registry';

Constructor

const ledger = new ReceiptLedger({
  network: 'testnet',
  topicId: process.env.RECEIPTS_TOPIC_ID!,
});

Options

'testnet' | 'mainnet'

required

The Hedera network the receipts topic lives on. Controls which mirror node is queried when mirrorUrl is not set.

string

required

The HCS topic ID where the seller publishes receipts, in shard.realm.num format. You can find this value in the seller’s ServiceListing.receiptsTopicId field.

string

Override the Hedera mirror node REST base URL. Defaults to the standard Hashio endpoint for the chosen network.

typeof fetch

Custom fetch implementation. Defaults to the global fetch. Useful in test environments or when routing through a proxy.

Methods

`list(opts?)`

await ledger.list({ timestamp? }): Promise<Array<{
  receipt: Receipt;
  consensusTimestamp: string;
  sequenceNumber: number;
  payerAccountId: string;
}>>

Reads all valid Receipt messages from the HCS topic. Messages that do not parse as a Receipt are skipped silently.

string

Filter to messages whose HCS consensus timestamp is strictly after this value. Use the ISO-style consensus timestamp string returned by a previous call (e.g. "1700000000.123456789") to page forward through the log incrementally.

Each item in the returned array contains:

Receipt

The parsed receipt object. See the Receipt fields reference below.

string

The HCS consensus timestamp at which the receipt message was finalised, in Hedera’s seconds.nanoseconds format.

number

The topic sequence number of this message. Sequence numbers are monotonically increasing, so you can use them to detect gaps.

string

The Hedera account that paid for the HCS message. Cross-check this against receipt.payTo to verify that the seller, not an impersonator, wrote this receipt.

`audit(opts?)`

await ledger.audit({ timestamp?, expectedSellerAccount? }): Promise<VerifiedReceipt[]>

Calls list() internally, then fetches the corresponding Hedera transaction from the mirror node for each receipt and verifies that the on-chain transfer matches the receipt’s claimed payer, payTo, asset, and amount. Use this method for reconciliation, dispute resolution, or automated billing checks.

string

Passed through to list(). Limits the audit to receipts after the given consensus timestamp.

string

When set, flags any receipt written by an HCS payer that is not this account ID. Catches receipts that were injected by a third party into the topic.

`VerifiedReceipt` Fields

Receipt

The original parsed receipt. See the Receipt fields reference below.

string

The HCS consensus timestamp of the receipt message.

number

The topic sequence number of the receipt message.

MirrorTransaction | null

The settlement transaction as returned by the mirror node, or null if the transaction was not found. A null here means the transaction has not been indexed yet or the transactionId in the receipt is incorrect.

boolean

true when the on-chain transfer fully matches the receipt: the correct asset was transferred, the right amount was credited to payTo, and the right amount was debited from payer. false if any check failed or the transaction was not found.

string[]

A human-readable list of every discrepancy found during verification. An empty array means the receipt is clean. Possible entries include credit shortfall amounts, debit shortfall amounts, unexpected transaction results, and missing transactions.

A matchesChain: false result means the on-chain Hedera transfer does not match what the receipt claims. This could indicate a data error, a race condition (the transaction has not propagated to the mirror node yet), or deliberate fraud. Always inspect the problems array for the specific discrepancies before taking action, and re-run the audit a few seconds later before concluding the receipt is fraudulent.

`Receipt` Fields

Show Receipt object shape

Schema version. Always 1 in the current protocol.

'receipt'

Message type discriminant. Always 'receipt'.

string

The HCS-14 UAID of the seller that issued this receipt, e.g. uaid:aid:....

string

The Hedera transaction ID of the settlement, in the format shard.realm.num@seconds.nanoseconds, e.g. 0.0.12345@1700000000.123456789.

'hedera:testnet' | 'hedera:mainnet'

The CAIP-2 network identifier on which the payment was settled.

string

The Hedera account ID of the buyer that made the payment, in shard.realm.num format.

string

The Hedera account ID that received the payment — the seller’s receiving account.

string

The asset used for payment. '0.0.0' for native HBAR; an HTS token ID (e.g. '0.0.4567') for token payments.

string

The payment amount in atomic units as a decimal string — tinybars for HBAR, or the token’s smallest unit for HTS tokens. Stored as a string to avoid floating-point precision loss.

string

The endpoint path that was paid for, e.g. /v1/infer or /v1/rates/hbar. Provides a human-readable record of what service was delivered.

string

Optional. The quote ID from the negotiation handshake, if a quote was used. Links this receipt back to the agreed price.

object

Metering evidence recorded by the seller, e.g. { prompt_tokens: 80, completion_tokens: 120 }. The shape is service-defined.

string

Optional. A SHA-256 hex digest of the response body. Allows a buyer to prove the exact content that was delivered in exchange for the payment.

string

ISO 8601 timestamp at which the seller generated the receipt.

Example: Audit All Receipts for a Seller Account

const ledger = new ReceiptLedger({
  network: 'testnet',
  topicId: process.env.RECEIPTS_TOPIC_ID!,
});

const results = await ledger.audit({
  expectedSellerAccount: '0.0.54321',
});

for (const r of results) {
  const status = r.matchesChain ? 'OK' : 'FAIL';
  console.log(
    `${status} #${r.sequenceNumber} ${r.receipt.transactionId}  ${r.receipt.amount} ${r.receipt.asset}`
  );
  if (r.problems.length > 0) console.log('  Problems:', r.problems);
}

Overview

Discovery

Negotiation

Paid services

Trust

Receipts

SDK reference

ReceiptLedger: Read and Audit On-Chain Payment Receipts

Installation and Import

Constructor

Options

Methods

`list(opts?)`

`audit(opts?)`

`VerifiedReceipt` Fields

`Receipt` Fields

Example: Audit All Receipts for a Seller Account

​Installation and Import

​Constructor

​Options

​Methods

​list(opts?)

​audit(opts?)

​VerifiedReceipt Fields

​Receipt Fields

​Example: Audit All Receipts for a Seller Account

Installation and Import

Constructor

Options

Methods

`list(opts?)`

`audit(opts?)`

`VerifiedReceipt` Fields

`Receipt` Fields

Example: Audit All Receipts for a Seller Account