# How the CloddsBot Trade Ledger Captures AI Decision Audit Trails with SHA-256 Integrity Hashing

> Discover how CloddsBot's trade ledger uses SHA-256 hashing to create tamper-evident AI decision audit trails, ensuring cryptographic verification of data integrity throughout its lifecycle.

- Repository: [AL/CloddsBot](https://github.com/alsk1992/CloddsBot)
- Tags: internals
- Published: 2026-09-13

---

**The CloddsBot trade ledger creates tamper-evident AI decision audit trails by generating deterministic SHA-256 hashes of decision data in [`src/ledger/hash.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/ledger/hash.ts) and persisting them through `LedgerStorage.capture()` in [`src/ledger/storage.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/ledger/storage.ts), enabling cryptographic verification of record integrity at any point in the data lifecycle.**

The CloddsBot repository implements a cryptographically secure logging system designed to preserve the integrity of automated trading decisions. By combining deterministic JSON serialization with Node.js native hashing primitives, the ledger ensures that every AI-driven action remains auditable and immutable, providing irrefutable proof of decision state at the time of execution.

## Deterministic Hash Generation for Decision Integrity

The foundation of the audit system rests on deterministic SHA-256 hashing that produces identical digests for identical decision inputs, regardless of serialization order or platform differences.

### The hashDecision Implementation

In [`src/ledger/hash.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/ledger/hash.ts), the **`hashDecision`** function constructs a cryptographic fingerprint of decision records by processing only the fields defined in the **`HASH_FIELDS`** array. This whitelist approach includes critical context such as user ID, session ID, timestamp, category, action, platform, market ID, inputs, analysis, constraints, confidence, decision, and reason.

The function filters undefined values to ensure consistency, then sorts all object keys alphabetically before stringification. This guarantees deterministic output: `JSON.stringify(data, Object.keys(data).sort())`. The resulting string feeds into Node’s native `crypto.createHash('sha256')` method, producing a standard 64-character hexadecimal digest that uniquely represents the decision state.

## Persisting Hashed Records to the Trade Ledger

Once generated, these cryptographic hashes anchor the decision data within persistent storage, creating an immutable bond between the record and its integrity proof.

### LedgerStorage.capture Method

The **`LedgerStorage.capture`** method in [`src/ledger/storage.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/ledger/storage.ts) (lines 95-102) accepts a decision record and an optional configuration object containing the **`hashIntegrity`** boolean flag. When this flag evaluates to `true`—typically driven by the global **`LedgerConfig.hashIntegrity`** setting—the method invokes `hashDecision` and persists the resulting hash in the dedicated `hash` column of the `trade_ledger` relational table.

This storage layer simultaneously persists the complete decision payload, operational constraints, and a generated UUID for the ledger entry, creating a comprehensive audit record that links the decision content directly to its integrity hash.

## Cryptographic Commitments and Verification Workflows

Beyond simple hashing, the system supports advanced cryptographic patterns for external verification and blockchain anchoring scenarios.

### Time-Anchored Commitments with createCommitment

The **`createCommitment`** function (also in [`src/ledger/hash.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/ledger/hash.ts)) constructs a composite integrity object containing both the decision data hash (`dataHash`) and a millisecond-resolution timestamp. This object undergoes a second round of SHA-256 hashing to produce a commitment hash suitable for off-chain proofs or on-chain anchoring, establishing cryptographic proof that the decision existed at a specific point in time.

### Runtime Integrity Verification

For audit scenarios, the **`verifyHash`** function recomputes the SHA-256 digest from stored decision fields and compares it against the persisted hash value. Any deviation—whether from data corruption, unauthorized modification, or serialization errors—results in an immediate mismatch, enabling instant detection of tampering. The companion **`shortHash`** utility provides the first eight characters of any full hash, offering human-readable identifiers for UI listings without compromising cryptographic security.

## Practical Implementation Example

The following implementation demonstrates configuring the ledger for hash integrity and capturing a verified decision:

```typescript
import { LedgerStorage } from './ledger/storage';
import { LedgerConfig } from './ledger/types';
import { createCommitment, verifyHash } from './ledger/hash';

// Initialize the ledger storage layer
const ledger = new LedgerStorage(dbInstance);
ledger.init();

// Configure cryptographic audit trails
const config: LedgerConfig = {
  enabled: true,
  captureAll: true,
  hashIntegrity: true,  // Enable SHA-256 hashing
  retentionDays: 90,
  onchainAnchor: false
};

// Define an AI trading decision
const decision = {
  userId: 'trader_001',
  category: 'trade',
  action: 'buy',
  inputs: { market: 'BTC-USD', side: 'buy', size: 0.5 },
  constraints: [{ type: 'max_slippage', value: 0.01 }],
  decision: 'approved',
  reason: 'Signal confidence exceeds 80% threshold'
};

// Capture with integrity hashing
const ledgerId = ledger.capture(decision, { 
  hashIntegrity: config.hashIntegrity 
});

// Generate optional commitment for external anchoring
const commitment = createCommitment(decision);
console.log('Commitment hash:', commitment.hash);

// Later verification workflow
const stored = ledger.get(ledgerId);
if (stored?.hash) {
  const isValid = verifyHash(stored, stored.hash);
  console.log(isValid ? 'Integrity verified' : 'Tampering detected');
}

```

## Summary

- **Deterministic serialization** in [`src/ledger/hash.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/ledger/hash.ts) sorts JSON keys alphabetically and filters undefined values to guarantee identical SHA-256 hashes across all platforms.
- **White-listed fields** via `HASH_FIELDS` ensure only relevant decision context contributes to the cryptographic digest, excluding volatile metadata.
- **`LedgerStorage.capture`** conditionally persists hashes to the `trade_ledger` table when `hashIntegrity` is enabled in `LedgerConfig`.
- **`createCommitment`** binds decision hashes to millisecond timestamps, enabling off-chain verification and blockchain anchoring workflows.
- **Runtime verification** via `verifyHash` detects any data tampering by recomputing and comparing digests at retrieval time.

## Frequently Asked Questions

### How does the system prevent hash collisions between different decision records?

The **`hashDecision`** function incorporates high-entropy fields including user ID, session ID, millisecond timestamps, and unique market identifiers within the `HASH_FIELDS` schema. Combined with SHA-256’s 256-bit output space, this ensures that distinct decision records produce statistically unique digests, while identical decisions produce reproducible hashes for verification purposes.

### Can the hash integrity verification detect partial data corruption?

Yes. The **`verifyHash`** function recomputes the SHA-256 digest from the stored decision fields using the exact same deterministic serialization logic (alphabetically sorted keys, filtered undefined values). Any modification to whitelisted fields—whether bit-level corruption, truncation, or malicious alteration—results in a digest mismatch, triggering immediate integrity warnings during the verification workflow.

### What happens if the hashIntegrity flag is disabled in the configuration?

When **`LedgerConfig.hashIntegrity`** is set to `false`, the `LedgerStorage.capture` method skips the `hashDecision` invocation and stores records with a null `hash` column. The decision data persists normally, but the system provides no cryptographic proof of integrity, making the audit trail vulnerable to undetected tampering or data corruption.

### Is the commitment hash compatible with blockchain anchoring?

Yes. The **`createCommitment`** function generates a standardized JSON object containing the `dataHash` and `timestamp`, which is then hashed using SHA-256. This produces a compact 64-character digest suitable for inclusion in blockchain transactions, timestamping services, or distributed ledger anchors, providing immutable proof of decision existence without revealing sensitive underlying data.