Skip to main content

​
Attestations

An attestation is a cryptographically signed record of an action performed by an AI agent.

​
What Gets Signed

Every attestation contains:
FieldDescription
attestation_idUnique UUID for this attestation
agent_slugIdentifier for the agent
actionHuman-readable description of what happened
inputs_hashSHA256 hash of the inputs used
timestampISO 8601 timestamp (UTC)
metadataOptional key-value pairs

​
The Signing Process

  1. Canonical JSON: Fields are serialized to canonical JSON (sorted keys, no whitespace)
  2. Hash: The canonical JSON is hashed with SHA256
  3. Sign: The hash is signed with Ed25519
  4. Store: The attestation and signature are stored
payload = {
  "action": "Approved loan",
  "agent_slug": "loan-agent",
  "attestation_id": "abc-123",
  "inputs_hash": "sha256...",
  "timestamp": "2024-01-15T10:00:00.000Z"
}

canonical = '{"action":"Approved loan","agent_slug":"loan-agent",...}'
payload_hash = sha256(canonical)
signature = ed25519_sign(private_key, canonical)

​
Best Practices

​
Action Descriptions

Be specific and human-readable: 
# Good
action = "Approved loan application #12345 for $50,000"
action = "Rejected trade: insufficient margin"
action = "Generated report for Q4 2024"

# Bad
action = "processed"
action = "done"
action = "action_type_7"

​
Input Hashing

Hash all relevant inputs to create a fingerprint: 
inputs = {
    "user_query": query,
    "context_docs": [doc.id for doc in context],
    "model_config": {"temperature": 0.7, "model": "gpt-4"}
}
inputs_hash = ts.hash(inputs)

​
Metadata

Use metadata for structured data you want queryable: 
ts.attest(
    action="Classified support ticket",
    inputs_hash=...,
    metadata={
        "ticket_id": "TICK-123",
        "category": "billing",
        "confidence": 0.95
    }
)

​
Attestation Lifecycle

Agent performs action
        ↓
Create attestation request
        ↓
API signs with private key
        ↓
Store in database
        ↓
Return signed attestation
        ↓
Anyone can verify forever