vtr-core [ VERIFIABLE TRACK RECORD ]

Copyright (C) 2026 Baus · extracted from ACOS (acos.capital) · License: AGPL-3.0

A track record your users do not have to trust, because they can check it. vtr-core gives any decision-making actor (a trading agent, a bot, a service, a human) an append-only, hash-chained journal with commit-reveal sealing and dual on-chain anchoring. Every decision is sealed before its outcome is known, so a history cannot be cherry-picked or quietly rewritten afterwards.

Agents that cannot lie about their past.

Why

Every agent claims a track record. Screenshots and self-reported logs prove nothing: they can be edited, trimmed and re-generated after the fact. This library makes the history itself tamper-evident:

• Commit before outcome: only the salted hash of a decision enters the chain at decision time. Hindsight cannot rewrite what was sealed.
• Hash chain: every entry carries the previous entry's hash. Deleting or editing any past record breaks the chain for everyone.
• On-chain anchors: the journal head is periodically published to two independent ledgers (any EVM chain as raw calldata, and Bitcoin via OpenTimestamps). Even the operator cannot backdate history afterwards.

Battle-tested, not a concept

This exact code has been sealing and anchoring a live trading agent's decisions since June 2026: 135+ confirmed anchors on Arc and Bitcoin, verifiable right now at https://acos.capital (your browser recomputes the chain and the anchors itself).

Install

pip install git+https://github.com/BausBank/vtr-core
# with the on-chain anchoring extra:
pip install "vtr-core[anchor] @ git+https://github.com/BausBank/vtr-core"

The journal core is pure stdlib. Only the anchoring rails need web3, eth-account and opentimestamps.

Quickstart

from vtr_core.journal import Journal, Manifest, load_journal, verify_journal
from datetime import datetime, timezone

now = lambda: datetime.now(timezone.utc)

j = Journal(jsonl_path="journal.jsonl")
j.set_manifest(Manifest(actor="my-agent", actor_kind="agent", model="v1",
                        strategy="my-strategy", strategy_version="1",
                        config_fingerprint="cafe0000", run_id="run-1",
                        mode="live"), ts=now())

j.commit(ref="trade-1", payload={"side": "long", "size": 1.0}, ts=now())
# ... the position closes ...
j.reveal(ref="trade-1", outcome={"pnl": -3.21}, ts=now())
j.close()

print(verify_journal(load_journal("journal.jsonl")).summary())

Or run the full tour: python examples/seal_and_anchor.py

Verify any journal from the command line:

python -m vtr_core.journal.verify journal.jsonl

Anchoring

One 32-byte fingerprint commits the entire journal prefix. Publish it on a schedule (the reference deployment anchors hourly, skipping quiet hours):

# dry-run by default; add --live to broadcast for real
python -m vtr_core.anchor.anchorer journal.jsonl --rails arc,btc

Two independent rails:

• Any EVM chain: the anchor goes out as tagged calldata in a plain transaction, no contract needed. Configure with ARC_RPC_URL, ARC_CHAIN_ID, ANCHOR_PRIVATE_KEY, ANCHOR_ADDRESS (the variables are named after the first deployment target, Arc testnet, chain id 5042002; point them at any EVM endpoint).
• Bitcoin: via OpenTimestamps calendars, free and batched. Includes a pure-Python upgrade/verify path that cross-checks the Bitcoin block header against multiple independent explorers, no external CLI needed.

Verify anchors against a journal:

python -m vtr_core.anchor.verify journal.jsonl --anchors journal.anchors.jsonl

Scope

This kit is the evidence layer only, entity-agnostic by design. It never sees how decisions are made and contains zero strategy logic. Recomputing P&L from public venue fills, paid verification (x402) and ERC-8004 attestations live in the parent project: https://github.com/BausBank/ACOS

License

AGPL-3.0 (see LICENSE). Forks stay open, copyright lines stay in place.