Base
Técnica

TREA is the AtlasDB contract language for deterministic financial workflows.

TREA is a deterministic contract language for AtlasDB.

This contract stores a single counter.

Use atlas-trea directly for tests, fixtures, and development tooling.

TREA contracts run through ledger transactions.

A TREA source file contains one contract and may start with static imports.

TREA is statically typed.

Storage is contract-local persistent state.

TREA supports a deliberately small expression set.

Every callable function is a contract entrypoint.

TREA contracts use @construct for one-shot construction. This is the constructor model: initialize required state once, then expose the normal @tx and @view entrypoints.

TREA contracts can inherit storage and behaviour from reusable base modules. Composition is resolved entirely at compile time — there is no virtual dispatch or runtime module loading.

TREA ships built-in modules under the std namespace, grouped by product domain. They are published on-chain as part of the platform bootstrap and are available to every contract without any separate deployment step.

The runtime context is available as ctx.

Intrinsics are built-in functions known to the verifier and runtime.

TREA separates business state from ledger accounting.

TREA supports bounded loops only.

This page documents features outside the current executable profile.

This is the canonical loan example used by the current test fixtures.

These examples show how the Phase 12 stdlib modules compose RWA registration, tokenized ownership, funds, and credit products.

TREA models card-like spending as a contract-controlled authorization, not as a card key controlling the user's main wallet.

Sparse maps and vectors are useful for bounded contract-local business data.

Corrections are first-class accounting events.

TREA contract execution is artifact-based.

TREA Financial Message Profiles are executable contracts that model institutional financial instructions. They are not SWIFT parsers or message adapters — they execute typed financial intent with balance effects, lifecycle governance, and auditable receipts.

TREA ships three ready-to-use insurance contract templates for institutional product flows:

TREA ships two ready-to-use hedge contract templates that settle FX derivative positions whose terms were priced off-chain by QuoteNet:

TREA ships a ConsortiumAgreement template (contracts/products/consortium_agreement.trea) modeling a Brazilian-style *consórcio*: a group of participants who pool periodic contributions into a shared reserve, and take turns receiving the quota's credit value either by lottery (*sorteio*) or by bid (*lance*).

TREA ships a category-card pattern for products where an institution funds a beneficiary, but the beneficiary can only use the value inside declared policy categories such as food, mobility, health, education, cashback, or travel.

TREA includes two pension templates for long-term accumulation products:

contracts/products/capitalization_plan.trea models a capitalization plan (plano de capitalização): periodic or one-off contributions into a per-participant reserve, eligibility for a periodic lottery drawing (sorteio), and maturity/redemption.

contracts/products/surety_agreement.trea models a fiança contratual ou financeira — distinct from a seguro garantia (parametric/insurance-style guarantee). The fiador (surety) assumes the obligation owed to the beneficiary/credor on behalf of the debtor (afiançado). After the fiador pays a claim, a right of regress (direito de regresso) against the debtor is created and tracked on-chain, recoverable partially or in full.

contracts/products/surety_insurance_policy.trea models a seguro garantia (performance bond / garantia contratual) — a specialization sitting between std.profile.GuaranteeLifecycle and the insurance templates in insurance_parametric.trea. The insurer (seguradora) underwrites the policyholder's (tomador) obligation toward the beneficiary/insured (segurado), in exchange for a premium and a reserve/capacity it constitutes for the guaranteed limit. Unlike SuretyAgreement (a pure fiança with collateral-in-escrow), this contract is accounted through the insurance posting lines (post(insurance.*_lines(...))), and after indemnification it creates an explicit right of subrogation against the policyholder, tracked separately from the original guaranteed obligation.

std.asset.EscrowAgreement[Asset] models conditional custody: one party deposits funds into an escrow account, and release or refund happens only through the contract's lifecycle rules.

TREA includes several credit contracts that share the same core idea: the contract stores the product lifecycle, while ledger posting helpers describe the economic event.

The asset primitives are lower-level than the product demos. They are the building blocks used when a contract needs ledger-aware value, ownership, or custody without inheriting a full product lifecycle.

TREA standardizes a small set of administrative modules so product contracts do not invent a different owner, role, or pause shape every time.

A fungible token issued by a financial institution. Combines BasicToken (supply tracking) and Ownable (single-owner access control) via static composition.

Extends the institution token with an emergency pause switch. Mint and transfer are blocked while the contract is paused; the owner can pause and unpause at will.

A treasury that requires M-of-N signer approvals before any transfer executes. Standalone contract — no composition.

A minimal loan lifecycle contract: originate, repay in instalments, declare default. Composes Roles for a separate admin address.

A token where both sender and recipient must be individually whitelisted before any transfer or mint can occur. Composes BasicToken and Ownable. Includes optional per-transfer and daily-mint limits.

The atlas-trea crate exposes parser, verifier, compiler, runtime, authoring, governance, product, economic, and institutional APIs.

Base modules (stdlib and custom) live on-chain as regular contract artifacts. A child contract resolves its impl dependencies against the registry at ContractCall time.

TREA integration uses AtlasDB transaction payloads.

AtlasDB nodes accept signed transactions over REST.

Artifacts bind source, ABI, IR, and storage layout to canonical hashes.

TREA supports an ERC-20-style base token through the BasicToken fixture.

The Ethereum adapter lets any dApp built with ethers.js, viem, wagmi, or web3.js talk to a TREA contract without knowing it's TREA underneath. It speaks the same ABI language that Ethereum established as the industry standard.

TREA contracts emit events via emit EventName(arg1, arg2, ...). After a ContractCall transaction is committed, the emitted events are available through the events endpoint.

The simulation endpoint lets you execute a contract entrypoint without committing any effects to the ledger. Wallets, dashboards, and audit tools use it to preview return values, accounting effects, emitted events, and execution cost before the user signs and submits the real transaction.

Every successful ContractCall transaction produces a ContractExecutionReceipt — a persistent record stored in redb that survives node restarts. Receipts capture what happened inside the execution: which entrypoint ran, what arguments were passed, what the contract returned, the effects summary, and the cost breakdown.

Every posting emitted by a TREA contract carries an operation kind that identifies the economic nature of the entry. Wallets, dashboards, and audit tools use this to classify movements without re-parsing contract source.

TREA uses explicit lifecycle and version acceptance.

TREA contracts can make compliance decisions without receiving documents, personal data, or validator-only evidence. The ledger stores a minimal public KYC state, and detailed disclosure happens through a private validator channel authorized by the wallet.

AI Audit is a predeploy gate for TREA contracts. It combines deterministic compiler facts with an optional LLM explanation, then binds the report to the published artifact.

Operational interoperability lets external systems use TREA contracts without turning contracts into HTTP clients. The chain exposes a plug; external systems present signed envelopes and signed transactions.

The on-demand factory pattern lets an institution publish a governed product template and create one child contract per approved customer request.

trea is the project CLI for TREA contracts — compile, deploy, call, and inspect contracts on any AtlasDB node without writing transaction payloads by hand.

compile_contract(...) returns a rich CompiledContract.

Use authoring diagnostics while writing contracts.

Recommended test layers:

The parser converts source into ContractModule.

TREA has both AST runtime support and direct IR runtime support for the currently lowered executable subset.

Storage encoding is deterministic and sparse.

TREA has static and runtime cost surfaces.

Before publishing a contract:

TREA accounting safety comes from explicit journal intent plus ledger validation.

Bad:

This book uses the following terms consistently.

``python @describe("optional contract description") contract Name: ``

All intrinsics are built into the TREA runtime. You cannot shadow them with function definitions. Collection intrinsics (vec_*, map_*) return new values — assign the result back to the storage field to persist the change.

``json { "kind": "Bool", "value": true } { "kind": "Integer", "value": "123" } { "kind": "Address", "value": "nbex..." } { "kind": "Text", "value": "hello" } ``

Errors surface in two prefix families: MP (mempool / pre-ledger validation) and LE (ledger execution). The prefix tells you which component rejected the transaction — you do not need to reach the ledger to get an MP error.

atlas-common is the shared contract crate for the Rust workspace. It provides the cross-cutting types, errors, address model, signing helpers, proposal and vote data, ledger entry primitives, and abstraction traits that the rest of the system reuses.

atlas-kyc is the workspace crate for portable KYC artifacts and supporting proof material. It defines the signed portable KYC envelope, the cleartext payload it carries, the evidence manifest model, and the Ed25519 signing and verification logic used around those artifacts.

atlas-bank is the domain crate for institution-oriented financial rules that sit on top of the shared ledger primitives. It packages institution registration, institution-level issuance permissions, account opening rules, a simple accounting engine for transfer and issuance entry generation, and a lightweight compliance rule framework.

atlas-ledger is the central persistence and execution crate of the Rust workspace. It owns the durable proposal log, proposal and transaction indexes, in-memory ledger state, state transition execution, shard and AEC persistence, KYC persistence, and the public ledger gRPC service.

atlas-mempool is the transaction staging crate for the Rust workspace. It receives statelessly valid signed transactions before they are proposed, deduplicates them, tracks pending status, and exposes candidate selection for block production.

atlas-p2p is the networking crate for validator-to-validator communication in the Rust workspace. It wraps libp2p, defines the Atlas network protocol payloads, manages peer sets, and exposes an adapter plus publisher interface that the node runtime uses to publish proposals, votes, heartbeats, and state-sync requests.

atlas-consensus is the consensus coordination crate of the Rust workspace. It owns proposal and vote intake, quorum evaluation, equivocation detection, leader schedule helpers, sync recovery state, and a small audit database for proposals, votes, and results.

atlas-node is the main application/runtime package of the Rust workspace. It is the place where atlas-consensus, atlas-ledger, atlas-mempool, and atlas-p2p are assembled into a running node process with networking, block production, state sync, public APIs, telemetry, and operator-facing setup flows.

atlas-ingress is a small public REST ingress/proxy that sits in front of atlas-node's REST API. Its job is to expose a tightly allowlisted public surface for reads, transaction submission, and SSE events without exposing the full node API directly.

atlas-node-admin is a library-only admin/backoffice API crate that atlas-node can embed when the demo-admin-apis feature is enabled. It exposes admin routes for account and institution operations, KYC issuance and registration helpers, and a workflow system for KYC/alias review backed by SQLite plus filesystem-stored evidence blobs.

atlas-wallet is a hybrid package that combines three roles:

atlas-keygen is a very small operational CLI for inspecting libp2p node keypair files. Today it is effectively an extraction tool, not a full key-management suite.

atlas-airdrop is a standalone HTTP faucet service that funds a destination wallet by submitting a small batch of signed transactions to the node API. It owns public request ingress, config validation, rate limiting, upstream node interaction, and Prometheus telemetry.