Skip to main content
Early Release (v0.1.x) — Trailproof is under active development. The core API is functional and tested, but interfaces may change between minor versions. Pin your dependency to a specific version in production.
Trailproof = Trail + Proof. Every event is cryptographically chained — tamper one, and the entire chain proves it.

​
Why Trailproof?

AI agents make autonomous decisions — approving requests, writing to memory, calling external APIs. Regulators (EU AI Act Article 19) and customers increasingly demand proof that these actions were logged faithfully and that nothing was altered after the fact. Traditional logging can’t provide that guarantee.
CapabilityBasic LoggingTrailproof
Tamper detectionNone — anyone with DB access can editSHA-256 hash chain; modify one event, every subsequent hash breaks
Cross-SDK parityManual effort to keep in syncPython + TypeScript produce identical hashes for same data
DependenciesOften pulls in heavy ORMs or cloud SDKsZero runtime deps — stdlib only
ProvenanceNo proof of originOptional HMAC-SHA256 proves who created the event
Multi-tenancyManual tenant isolationBuilt-in tenant_id on every event
VerificationManual spot-checkstp.verify() walks entire chain in one call

​
The Trailproof Pipeline

Every event flows through a validation, hashing, optional signing, and append-only storage pipeline. Verification walks the chain backwards to check integrity. Trailproof pipeline: Your App → Event Builder (validate + envelope) → Hash Chain Engine (SHA-256) → Optional HMAC Signer → Append-Only Store (Memory or JSONL) → Verify + Query

​
Core Pillars

Tamper-Evident Chain

SHA-256 hash chain links every event to the previous one. Modify event 5 in a chain of 100 — events 5 through 100 all fail verification. You can’t silently tamper with history.

Dual SDK Parity

Native libraries for Python and TypeScript with identical behavior. Same canonical JSON algorithm, same genesis hash, same test vectors. Emit in Python, verify in TypeScript.

Zero Dependencies

Stdlib-only in Python (hashlib, json, uuid), Node.js built-ins only in TypeScript (crypto, fs). No supply chain risk from your audit trail.

HMAC Signing

Optional HMAC-SHA256 signatures prove event provenance — that events were created by the holder of a specific secret key. Uses timing-safe comparison to prevent timing attacks.

​
Quick Example

from trailproof import Trailproof

tp = Trailproof()

# Record an event
event = tp.emit(
    event_type="myapp.user.login",
    actor_id="user-42",
    tenant_id="acme-corp",
    payload={"ip": "1.2.3.4", "method": "oauth"},
)

# Verify the entire chain is intact
result = tp.verify()
print(result.intact)  # True

​
The 10-Field Event Envelope

FieldTypeDescription
event_idstringUUID v4, auto-generated
event_typestringNamespaced type (e.g., myapp.user.login)
timestampstringISO-8601 UTC, auto-generated
actor_idstringWho performed the action
tenant_idstringTenant/org isolation key
trace_idstring?Cross-system correlation
session_idstring?Session grouping
payloadobjectDomain-specific data (opaque to Trailproof)
prev_hashstringHash of the previous event
hashstringSHA-256 of this event
signaturestring?HMAC-SHA256 if signer configured

​
Next Steps

Quickstart

Install and emit your first event in 5 minutes.

Event Envelope

Deep dive into the 10-field event structure.

Hash Chain

How events are cryptographically linked.

API Reference

Full API documentation for both SDKs.