Crate argus_ledger 

argus-ledger

Tamper-evident append-only SHA-256 provenance and audit ledger for autonomous agents.

When autonomous agents execute commands, invoke external APIs, or mutate persistent memory, post-incident investigations require cryptographic certainty regarding what actions occurred and in what sequence. Standard application logs can be rewritten, reordered, or truncated.

Argus provides an immutable append-only hash chain where each event records:

1. A strictly sequential sequence integer.
2. A cryptographic digest binding the payload to the previous event’s hash (prev_hash).
3. Deterministic chain verification that validates integrity in linear time.

Architecture Overview

• AuditEvent: The individual structured log record containing event metadata, payload, monotonic sequence number, and SHA-256 digests.
• ChainVerificationReport: Audit summary produced by traversing the hash chain from genesis to head, validating sequence ordering and hash consistency.
• AuditLedgerWriter: Trait for appending new events to the audit log.
• AuditLedgerReader: Trait for querying events by sequence or reading the chain head.
• AuditVerifier: Trait for verifying cryptographic integrity across the chain.
• InMemoryLedger: Thread-safe reference ledger implementation.

Quick Start

use argus_ledger::{AuditLedgerReader, AuditLedgerWriter, AuditVerifier, InMemoryLedger, GENESIS_PREV_HASH};

// Create an in-memory audit ledger
let mut ledger = InMemoryLedger::new();

// 1. Record an initial initialization event
let ev1 = ledger.append("agent.startup", "coordinator", "{\"status\":\"initialized\"}")
    .expect("First event must succeed");
assert_eq!(ev1.sequence, 1);
assert_eq!(ev1.prev_hash, GENESIS_PREV_HASH);

// 2. Record a tool call event cryptographically chained to ev1
let ev2 = ledger.append("tool.exec", "worker_1", "{\"command\":\"build\"}")
    .expect("Second event must succeed");
assert_eq!(ev2.sequence, 2);
assert_eq!(ev2.prev_hash, ev1.event_hash);

// 3. Verify cryptographic chain integrity
let report = ledger.verify_chain().expect("Verification must complete");
assert!(report.valid);
assert_eq!(report.total_events, 2);
assert_eq!(report.head_hash, ev2.event_hash);

Structs

AuditEvent

An immutable event record committed to the audit chain.

ChainVerificationReport

Cryptographic integrity verification report for an event chain.

InMemoryLedger

Thread-safe in-memory reference implementation of an append-only audit ledger.

Enums

LedgerError

Errors returned during ledger append, retrieval, or verification operations.

Constants

GENESIS_PREV_HASH

The fixed 64-character hexadecimal previous hash for genesis events.

VERSION

Traits

AuditLedgerReader

Trait defining read and query operations for audit ledgers.

AuditLedgerWriter

Trait defining append operations for audit ledgers.

AuditVerifier

Trait defining full-chain cryptographic audit verification.

Functions

compute_event_hash

Compute the canonical SHA-256 event hash across all event metadata and payload fields.

sha256_hex

Standalone, pure-Rust SHA-256 implementation (FIPS 180-4 compliant, zero external dependencies).