Skip to main content
Blnk makes your transaction history 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.
LayerWhat it protectsWhere you see itWhen it’s on
Per-row hashA single transaction’s core detailsTransaction API responses (hash field)Always
Global hash chainYour full transaction history in orderVerify with blnk verify-chainOptional, disabled by default
The global hash chain is available in Blnk Core 0.15.0 and later. It is disabled by default.

​
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 :
  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.
Diagram showing transactions sealed into an ordered hash chain from genesis to chain head
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

1

Enable the hash chain

Set on the server service, then restart.
BLNK_TRANSACTION_HASHCHAIN_ENABLED=true
See Hash chain settings for all options.
2

Wait for sealing

Existing transaction rows are sealed automatically. New ones seal after the trailing delay, default: 30s.
3

Verify the chain

To verify the chain, run in the same directory as your docker-compose.yaml:
docker compose run --rm server blnk verify-chain
Exit code 0 means the chain is intact.
Success
chain verified: 153 transactions sealed, head 18526b69d80e7c0b200da69cfc0f9a4e661a55c724b4f984ebf4ebd9b32e92f9 at seq 153
verify-chain is a Core CLI command, not an HTTP API. The one-off container uses the same Postgres connection and config as your server.
4

Monitor sealing progress

Track backlog and sealing delay over time through Monitoring in Blnk. When the hash chain is enabled, these gauges appear on the metrics endpoint:
MetricDescription
blnk_chain_backlogTransactions not yet sealed into the hash chain
blnk_chain_head_seqSequence number of the hash-chain head
blnk_chain_lag_secondsSeconds since the hash chain last advanced
See Metrics reference for attribute details and other Core metrics.

​
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.
The per-row hash uses amount (the display float), not precise_amount. Fields such as description, status, and meta_data are not included.
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.
Diagram showing a hash chain with a broken link where verification fails
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.
Fields such as description and meta_data are not integrity-protected by the chain. Changing them does not fail verification. Protected transaction fields are also guarded by the database immutability trigger.
Chain seals are not returned in transaction API or search 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.
ResultWhat it means
PassThe full transaction history is intact. Output states how many transactions are sealed.
FailHistory was tampered with or broken. Output names the position where verification stopped.
When verification passes, output looks like this:
Success
chain verified: 153 transactions sealed, head 18526b69d80e7c0b200da69cfc0f9a4e661a55c724b4f984ebf4ebd9b32e92f9 at seq 153

Hash chain settings

Full config and env vars.

Metrics reference

Chain backlog, head sequence, and lag gauges.

About transactions

Immutability and recording basics.

​
Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.