Credit Ledger Integrity

Credits as a Financial Record

TurboPentest operates on a credit-based model. Users purchase credits, and each scan consumes credits based on the tier selected. This creates a financial ledger — a record of purchases, consumptions, refunds, and adjustments that must be accurate, complete, and tamper-proof.

Unlike traditional SaaS billing where a single monthly charge covers everything, a credit ledger has many individual transactions. Each scan start, each credit purchase, each refund, and each promotional credit grant is a separate event. The integrity of this ledger matters for billing disputes, financial audits, and user trust.

TurboPentest applies the same cryptographic principles used for report attestation to the credit ledger, creating a chain of hashed events that makes any unauthorized modification detectable.

Event-Based Ledger Architecture

The credit ledger is an append-only event log. Every action that affects a user's credit balance creates a new event rather than modifying an existing record. This is an event-sourcing pattern: the current balance is derived by replaying all events, and the event history is the source of truth.

Each ledger event contains:

• Event ID — A unique identifier for this specific event
• Event Type — Purchase, consumption, refund, adjustment, promotional grant, or expiration
• Amount — The number of credits involved (positive for additions, negative for consumptions)
• Balance After — The resulting balance after this event
• Timestamp — When the event occurred (server-side UTC)
• Reference — What triggered the event (Stripe payment ID, scan ID, admin action ID)
• Actor — Who or what initiated the event (user ID, system process, admin ID)

The append-only constraint is enforced at the database level. Ledger events have no UPDATE or DELETE operations — only INSERT. Historical records cannot be changed; corrections are made by appending new adjustment events that reference the original.

Hash Chain Construction

Each ledger event is cryptographically linked to the previous event, forming a hash chain similar to a blockchain. Here is how it works:

Event Hashing

When a new ledger event is created, TurboPentest computes its hash by combining:

1. The event's own data (ID, type, amount, balance, timestamp, reference, actor)
2. The hash of the immediately previous event in the same user's ledger

The hash is computed as:

event_hash = SHA-256(event_data + previous_event_hash)

This creates a chain: each event's hash depends on all previous events. If any historical event is modified, its hash changes, which breaks the chain for every subsequent event. You cannot tamper with a past event without invalidating every event that came after it.

The Genesis Event

The first event in every user's ledger is a genesis event with a predefined hash (all zeros or a system constant). This provides the starting anchor for the hash chain.

Chain Verification

To verify the integrity of a user's credit ledger:

1. Start with the genesis event and its known hash
2. For each subsequent event, compute SHA-256(event_data + previous_hash)
3. Compare the computed hash with the stored hash
4. If all hashes match, the chain is intact — no events have been modified, deleted, or reordered

This verification can be performed at any time, on any portion of the chain, without needing external data. The chain is self-verifying.

Tamper Detection Scenarios

The hash chain detects several categories of tampering:

Modified Event

If someone changes the amount of a past purchase event (for example, inflating a refund), the hash of that event changes. Every subsequent event's hash depends on this one, so the entire chain from that point forward becomes invalid. Verification immediately detects the break.

Deleted Event

If someone removes an event from the middle of the chain, the next event's previous_event_hash reference points to a hash that no longer matches the event before it. The gap is immediately detectable.

Inserted Event

If someone inserts a fraudulent event into the middle of the chain, the subsequent event's previous_event_hash will not match the inserted event's hash. The chain breaks at the insertion point.

Reordered Events

If events are swapped in order, their hashes will not match because each hash encodes the sequence through its dependency on the previous hash. Any reordering breaks the chain.

Periodic Anchoring

While the hash chain provides internal consistency, it does not prevent a scenario where the entire chain is rebuilt from scratch with altered data (all hashes recomputed to be internally consistent). To guard against this, TurboPentest periodically anchors ledger chain checkpoints using the same Merkle tree and Base L2 infrastructure used for report attestation.

At regular intervals:

1. The current head hash of every active user's ledger chain is collected
2. These hashes become leaves in a Merkle tree
3. The Merkle root is anchored on Base L2

This creates an external, immutable reference point. Even if someone with database access rebuilt an entire hash chain, the on-chain checkpoint would not match the fraudulent chain's head hash. The anchoring frequency balances cost with security — frequent enough that the window of unanchored events is small, infrequent enough that transaction costs remain negligible.

Audit and Dispute Resolution

The hash chain and periodic anchoring provide powerful tools for auditing:

• Self-service verification — Users can request a ledger integrity check from their account settings, which runs the full chain verification and reports the result
• Billing disputes — When a user disputes a charge, the complete event history with hash verification provides a cryptographic proof of every transaction that affected their balance
• Internal audits — Administrators can verify ledger integrity across all users, with the on-chain anchors providing external validation that the database has not been wholesale modified
• Regulatory compliance — The append-only, hash-chained, blockchain-anchored ledger satisfies audit trail requirements for financial record-keeping standards

Implementation Considerations

The hash chain adds minimal overhead to ledger operations. SHA-256 computation takes microseconds, and the previous event's hash is always available (it is stored with the event record). The only performance consideration is that event insertion is sequential per user — each event must know the previous hash — but since credit operations for a single user are low-frequency (at most a few per day), this is not a bottleneck.

The append-only model does mean the ledger grows indefinitely. TurboPentest handles this through efficient indexing: the current balance is cached and updated on each event, so reading the balance does not require replaying the full chain. Chain verification is an on-demand operation, not a per-request cost.