The TREA Book

TREA is the AtlasDB contract language for deterministic financial workflows.

It is a small, Python-like language designed around three commitments:

1. contract execution must be deterministic;
2. accounting effects must be explicit;
3. runtime behavior must remain auditable after the fact.

A TREA contract can:

• store business state;
• expose read-only and mutating entrypoints;
• emit events;
• produce ledger effects.

Contract execution and ledger commit are separate stages.

The runtime executes contract code and produces an execution result. The ledger then validates the resulting effects against chart rules, posting routes, lifecycle rules, version acceptance, and active policy constraints.

A successful local execution does not guarantee ledger commit.

Audience

Read this book if you are:

• writing .trea contracts;
• integrating contract publication and calls into an application or wallet;
• working on AtlasDB ledger/runtime internals;
• reviewing a contract for accounting or safety properties.

What This Book Covers

• the current TREA language subset;
• examples that compile in this repository;
• Rust and transaction APIs for integration;
• artifact, ABI, lifecycle, and version binding behavior;
• parser, verifier, IR, runtime, storage, and cost internals;
• security patterns and common mistakes.

This book uses the following terms consistently:

• contract artifact: published source plus canonical metadata and ABI;
• contract instance: an instantiated contract bound to an artifact family;
• accepted version: an actor-specific artifact selection for execution;
• execution result: storage changes, events, and effects produced by the runtime;
• ledger commit: final ledger-side validation and persistence of those effects.

Version Scope

This book documents the current implemented TREA profile in this repository.

Architectural specs live under trea/, but production contracts should target the implemented language and runtime described here.

Quick Links

• Start with A Simple Contract.
• Learn syntax in Source Layout.
• See a full financial example in Wallet Loan.
• Integrate with AtlasDB using Ledger Transactions.
• Preview effects before submitting with Simulation (Dry-Run).
• Query persisted execution history with Execution Receipts.
• Browse the posting classification table in Operation Kind Catalog.
• Use credit lifecycle templates from the Standard Library.
• Review safety with Authoring Checklist.