Credit Ledger Integrity

Credits as a Financial Record

TurboPentest operates on a credit-based model. Users purchase pentest credits, and each pentest consumes one credit of the selected tier (Recon, Audit-Ready, Threat-Hunt, or Adversarial-Depth, each with its own agent-hours allotment). This creates a financial record - a history of issuance, transfers, consumption, and expiry that must be accurate, complete, and tamper-evident.

Unlike traditional SaaS billing where a single monthly charge covers everything, a credit system has many individual lifecycle events. Each credit purchase, each pentest launch, each transfer, and each expiration is a separate event. The integrity of this history matters for billing disputes, financial audits, and user trust.

TurboPentest applies the same cryptographic infrastructure used for report attestation to the credit ledger: every event is hashed, and the hashes are anchored on-chain.

Event-Based Ledger Architecture

The credit ledger is an append-only event log. Every action that affects a credit creates a new ledger event rather than modifying an existing record. Each credit itself is an individual record with a tier, agent-hours, and a status (available, scheduled, used, or expired); the ledger records the events that move credits through that lifecycle.

Each ledger event contains:

• Event ID - A unique identifier for this specific event
• Credit ID - The credit this event applies to
• Event Type - One of: issued, transferred, consumed, or expired
• From/To User - For transfers, the sending and receiving user IDs
• Metadata - What the event relates to (for example, the pentest ID, tier, and attestation hash for a consumed event)
• Timestamp - When the event occurred (server-side UTC)
• Event Hash - The SHA-256 hash of the event (see below)
• Anchor reference - Set once the event has been included in an on-chain Merkle anchor

The ledger is treated as append-only: events are only ever inserted, and corrections are made by appending new events rather than editing history. The only field written after creation is the anchor reference that links the event to its Merkle anchor.

Event Hashing

When a ledger event is created, TurboPentest computes its hash over a canonical JSON serialization of the event's fields:

event_hash = SHA-256(canonical_json({
  creditId, eventType, fromUserId, toUserId, metadata, createdAt
}))

Because SHA-256 is deterministic and collision-resistant, the event hash is a fingerprint of exactly what happened: which credit, what kind of event, who was involved, what it referenced, and when. If any field of a recorded event were later altered - say, changing which pentest consumed a credit - recomputing the hash would produce a different value than the one stored and anchored.

When a pentest completes and its attestation is created, a consumed event is appended to the ledger with metadata linking the credit to the pentest and its attestation hash. This ties the billing record to the attested results: the credit's consumption and the pentest's attestation reference each other.

On-Chain Anchoring

A hash stored next to the data it protects is not enough on its own: an attacker with full database access could alter an event and recompute its hash. Tamper evidence comes from anchoring the hashes somewhere the attacker cannot rewrite.

TurboPentest's daily anchoring job (the same one that anchors pentest attestations, covered in Module 4) does the following:

1. Collects every ledger event hash and attestation hash that has not yet been anchored
2. Builds a Merkle tree from all collected hashes
3. Submits the Merkle root to Base L2 in a single transaction
4. Records the anchor (root hash, transaction hash, chain ID, block number, event count, and the batch's time period) and links every event in the batch to it

This creates an external, immutable reference point. If someone with database access altered an anchored ledger event - even recomputing its event hash to look internally consistent - the recomputed hashes could no longer produce the Merkle root that is permanently recorded on Base. The anchoring frequency balances cost with security: a daily batch keeps the window of unanchored events small while keeping transaction costs negligible.

Tamper Detection Scenarios

The combination of event hashing and on-chain anchoring makes several attack scenarios detectable:

Modified Event

If someone changes a field of an anchored event (for example, redirecting a consumed event to a different pentest), the stored event hash no longer matches a recomputation from the event's fields. If they also recompute the stored hash, the Merkle root built from the batch's hashes no longer matches the root anchored on Base.

Deleted Event

If someone removes an anchored event, the anchor's recorded event count and the set of leaf hashes no longer reproduce the anchored Merkle root.

Inserted Event

If someone back-dates a fraudulent event into an already-anchored period, that event has no anchor reference, and it cannot be added to a historical batch - the on-chain root for that period is already fixed.

Why the Anchor Matters

Without anchoring, a database-level attacker could rewrite events and hashes consistently. The on-chain Merkle root is the piece the attacker cannot touch: it is recorded on a public blockchain that TurboPentest itself cannot modify after the fact.

Audit and Dispute Resolution

The hashed, anchored ledger provides powerful tools for auditing:

• Billing disputes - When a user disputes a charge, the event history shows every issuance, transfer, consumption, and expiry for their credits, each with a hash that is committed to an on-chain anchor
• Attestation linkage - Consumed events carry the pentest's attestation hash in their metadata, tying each spent credit to cryptographically attested results
• Internal audits - Administrators can recompute event hashes and Merkle roots and compare them against the anchors recorded on Base, providing external validation that history has not been rewritten
• Financial record-keeping - The append-only, hashed, blockchain-anchored ledger is built to meet audit trail expectations for financial record-keeping standards

Implementation Considerations

Event hashing adds minimal overhead to ledger operations: SHA-256 computation takes microseconds, and hashing happens once at event creation. Anchoring is a single daily batch job, so it adds no per-request cost.

Reading a user's credit balance does not require replaying the ledger: balances are computed from the credit records themselves (counts of available, scheduled, used, and expired credits by tier). The ledger exists as the audit trail layered on top - integrity verification is an on-demand operation, not a per-request cost.