Transactions

Transaction integrity and hashing

Check that recorded transaction history still matches what Blnk sealed.

Blnk makes your transaction history tamper-evidentYou can detect if protected fields were changed after recording. Any change leaves a visible sign in the hash or chain. through hashing.

Every transaction gets a fingerprint you can check on its own; optionally, your full transaction history can also be sealed into one ordered chain you verify on demand.

Why hashing matters

Transaction records are the audit trail of your ledger. If amount, balance, currency, status, or reference changes after recording, your balances and reports can no longer be trusted.

Blnk uses hashing to make that history tamper-evidentYou can detect if protected fields were changed after recording. Any change leaves a visible sign in the hash or chain.:

1. Per-row hash - fingerprints important fields on each transaction.
2. Global hash chain - links sealed transactions together in order.
3. blnk verify-chain - replays the chain and reports the first broken link if protected data changed.

Hashing does not replace database security, backups, access controls, or audit logs. It gives operators a way to verify that ledger history still matches what Blnk originally sealed.

Quick start

BLNK_TRANSACTION_HASHCHAIN_ENABLED=true

{
  "transaction": {
    "hash_chain": {
      "enabled": true
    }
  }
}

docker compose run --rm server blnk verify-chain

chain verified: 153 transactions sealed, head 18526b69d80e7c0b200da69cfc0f9a4e661a55c724b4f984ebf4ebd9b32e92f9 at seq 153

Per-row hash

Every transaction in Blnk gets a hash - a SHA-256 fingerprint built from five fields. If any of them change after recording, the fingerprint no longer matches.

Blnk concatenates these values in order, hashes the string with SHA-256, and returns the hex digest as hash: amount, reference, currency, source, destination.

Compare the hash from when you first recorded a transaction with the hash on a later fetch to confirm those fingerprinted fields are unchanged. Built-in integrity verification is handled by the global hash chain and blnk verify-chain.

Global hash chain

When you enable the hash chain, transaction rows are linked in order. Each seal depends on the previous one, so your full history acts as one tamper-evident record.

This is stronger than checking rows independently because every sealed transaction depends on the previous chain head. If a transaction is changed, removed, or reordered, verification fails where the history breaks.

1. Existing transactions seal automatically when you turn the chain on.
2. New transactions seal after a short trailing delay so recent writes can finish.
3. The chain includes all statuses: queued, inflight, applied, voided, rejected, and refund.

The chain checks these fields: transaction_id, source, destination, amount, precise_amount, currency, status, reference, created_at. Change any after sealing and verification fails.

Chain seals are not returned in transaction API or filter responses. Check integrity with blnk verify-chain, not by reading a response field.

Verification

blnk verify-chain tells you whether your full sealed history is intact or where it broke.

Exit code 0 means the chain passed; any other exit code means it failed.

chain verified: 153 transactions sealed, head 18526b69d80e7c0b200da69cfc0f9a4e661a55c724b4f984ebf4ebd9b32e92f9 at seq 153

chain BROKEN at seq 6 (txn txn_c1dfaf42-93c1-4371-8918-4d3d6ed2d2be): non-contiguous chain_seq: expected 5, got 6