@blockwavelabs/receipt-proof

Verify receipt inclusion proofs and settlement anchors without importing private packages.

Npm package: https://www.npmjs.com/package/@blockwavelabs/receipt-proof

Package Contents

The npm artifact is intentionally dist-only: dist/*.js, dist/*.d.ts, README.md, LICENSE, NOTICE, and package.json. TypeScript src/ files and source maps are not published.

Quickstart

npm install @blockwavelabs/receipt-proof

CLI

For the normal proof check, you need a receipt ID and the proof JSON evidence. No API URL or RPC is required.

receipt-proof rcpt_... --proof proof.json --json

The --proof file can be a raw proof object or a @blockwavelabs/demo-payer JSON/JSONL result containing a nested proof object:

receipt-proof rcpt_... --proof receipts.jsonl --json

JavaScript API

Verify a proof object or a @blockwavelabs/demo-payer result bundle:

import { verifyReceiptProofInput } from '@blockwavelabs/receipt-proof';

const result = verifyReceiptProofInput(demoPayerResult, 'rcpt_...');
console.log(result.checks.verified);

Fetch proof evidence from an API when you are building an operator-side tool:

import { SettlementVerifier } from '@blockwavelabs/receipt-proof';

const verifier = new SettlementVerifier({
  baseUrl: 'https://api.example.com',
  apiKey: process.env.RECEIPT_API_KEY,
});

const result = await verifier.verifyReceipt('rcpt_...');
console.log(result.verified, result.checks, result.evidence);

Offline Proof JSON

The proof JSON is the evidence object returned by the proof API or exported by an operator. You can verify it without API or RPC access:

receipt-proof proof proof.json rcpt_... --json

Low-level API:

import { verifyReceiptProof } from '@blockwavelabs/receipt-proof';

const result = verifyReceiptProof(proofJson, 'rcpt_...');

Optional On-Chain Anchor Check

If you want the CLI to fetch the proof JSON for you, pass an API URL. While the proof endpoint is API-key gated, pass an auditor/operator key.

receipt-proof receipt rcpt_... \
  --api-url https://api.example.com \
  --api-key "$RECEIPT_API_KEY" \
  --json

For a stronger check, the fetch mode can also verify the on-chain anchor if you add your own RPC and the deployed SettlementManager address. These are optional; no default RPC is baked in.

receipt-proof receipt rcpt_... \
  --api-url https://api.example.com \
  --api-key "$RECEIPT_API_KEY" \
  --rpc-url "$SETTLEMENT_RPC_URL" \
  --contract "$SETTLEMENT_CONTRACT_ADDRESS" \
  --confirmations 3 \
  --require-anchor \
  --json

Verification Model

The verifier checks:

• the proof response is bound to the requested receiptId
• the Merkle proof recomputes to merkleRoot
• merkleRoot equals the batch payloadHash
• when RPC + contract address are configured, the anchor tx emitted SettlementBatchCommitted(batchId, payloadHash, ...)

No default RPC endpoint is baked in. External auditors should provide their own RPC.

Current v0.1 Limits

• Leaf scheme is receipt-id-keccak-v1: leafHash = keccak256(utf8(receiptId)). It proves receipt ID inclusion, not payload binding. Payload-bound leaves require the ADR-035 leaf-scheme v2 migration.
• The current proof endpoint is API-key gated. Public anonymous or ownership-scoped proof access is separate server work.
• Current receipt IDs are timestamp/random strings, not UUIDv4. Public proof exposure should resolve sibling-hash leakage with UUIDv4 IDs or a batch-scoped salt before anonymous access.
• Dist-only publishing does not make the verifier algorithm private. Published JavaScript remains inspectable, which is expected for the external verification path.