Overview
This page is the map before the territory. It covers:
- What Tari Ootle is, and where it sits in the wider Tari system.
- The division of labour between the base layer (Minotari) and Ootle.
- What “anchoring” does — and, just as importantly, does not — mean.
- The roles of the nodes that make up the network.
- What “finality” means here, and why two layers are involved.
- The life of a transaction, stage by stage.
- How value enters the system.
For the mechanics behind each item, follow the links into the rest of the Concepts section.
What is Tari Ootle?
Tari Ootle is a layer-2 execution layer. It runs WebAssembly smart contracts — called templates — over a sharded, account-and-object state model, and it anchors its security and its supply of the native token to the Minotari base layer.
If you are coming from other ecosystems, the closest mental model is “a smart-contract chain that does not produce its own consensus-independent security; it borrows a base layer for identity and for the final say on value.” Ootle is not a rollup: it does not post state roots to the base layer, and the base layer does not re-execute or verify Ootle transactions. Ootle runs its own Byzantine-fault-tolerant consensus among its own validator set.
Two layers, then, but not two copies of the same thing:
| Layer | Records | Model | Consensus |
|---|---|---|---|
| Minotari (base layer) | Assets — which coins exist and move | UTXO | Proof of work |
| Ootle (this layer) | State — what a program’s data is right now | Objects and components | Chained BFT |
The base layer keeps a ledger of value. Ootle keeps a ledger of state: a key-value map from a
SubstateId to a versioned Substate (see
State and Execution). A transaction does
not move coins from column A to column B so much as it calls a component method and changes the
state of the objects it touches.
The division of labour
The two layers are split deliberately, by trust surface.
The base layer does the few hard things. It is kept simple on purpose — a UTXO chain with a weak script — so that there is little on the security anchor to attack. It provides:
- Identity and registration. Validator nodes register on the base layer, and that registration is what the Ootle epoch oracle reads to decide who is in a committee this epoch.
- The minting source. The only way to create the Ootle native token is to burn its base-layer counterpart. There is no reverse bridge (see Tokenomics).
- The epoch clock. Epochs are a fixed number of base-layer blocks, so membership rotation and Ootle’s notion of time advance against the base layer’s block height.
Ootle does the programmable, high-throughput thing. It owns execution, the sharded state, and its own finality, and it isolates the complex, higher-risk logic — arbitrary contracts — away from the anchor.
Note
The base-layer identifiers Ootle consumes — validator registrations, contract (template)
registrations — are read through an epoch oracle. In this repository you will see that
boundary as crates/epoch_oracles/src/base_layer/oracle.rs, which pulls the base-layer epoch
length and validator set. The base-layer chain itself lives in the upstream Minotari project.
The seam, in one picture
Two ledgers, three connections. Notice that only one of them carries value, and it runs one way.
Three things cross the seam, and it is worth naming what each one is not:
- Membership flows inward only. The base layer says who is registered; the oracle turns that into committee membership. Ootle never writes membership back.
- Value flows inward only. Burning a base-layer coin is the sole way to create L2 TARI. Nothing flows out.
- State does not cross at all. No state root, no proof, and no transaction is ever posted to the base layer for verification.
The moving parts
Ootle is a network of cooperating node roles. Only one of them votes on state.
| Node | Role |
|---|---|
| Validator node | Runs the consensus protocol (HotStuff) and executes transactions within its shard group. This is the only role that produces finality. |
| Indexer | Tracks the chain, indexes transactions, substates, and events, and serves queries to clients. It does not vote. |
| Wallet daemon | Holds keys, builds and signs transactions, and talks to the indexer. It does not vote. |
| Base-layer node | The upstream Minotari node. Ootle nodes read registrations and epoch data from it. |
A deeper role-by-role breakdown, together with how nodes are grouped into shards, is in Architecture.
Finality, briefly
Ootle reaches finality inside its own consensus, not on the base layer. A block becomes irreversible when the validator committee’s HotStuff chain grows far enough past it — under the three-chain rule, the oldest block in a consecutive three-block chain is committed. Read the mechanism in detail in Consensus.
The base layer’s role in finality is narrower: it decides membership (who is allowed to vote this epoch) and it is the reference clock that epochs advance against. Both safety and liveness of a state transition are statements about the Ootle committee. A stalled committee is un-stuck by its own pacemaker, and the next epoch re-forms its membership from the base layer’s registrations.
What “anchoring” does not mean
Because Ootle borrows identity and value from the base layer, it is easy to assume it also borrows verification. It does not. Four negatives define the boundary:
| Ootle is not… | …which means |
|---|---|
| a rollup | No state root is posted to the base layer, so the base layer has no record of Ootle’s state. |
| a validity proof | Ootle transactions are never re-executed on the base layer; there is no fraud proof or SNARK securing execution. |
| a sidechain needing base-layer finality | Ootle’s finality comes from its own committee’s three-chain rule, not from proof of work. |
| a settlement layer for the base coin | Value crosses inward only; the base layer keeps full control of its own supply. |
What Ootle does take from the base layer is narrower and more valuable than verification: a single canonical answer to “who is allowed to validate, right now”, delivered on a clock both layers agree on. That answer is what stops one committee from being swapped for another by an attacker, and it is the only thing standing between a validator set and an identity free-for-all.
Note
The trade this buys: Ootle cannot be silently corrupted, because producing a conflicting final state requires a quorum of a committee drawn from base-layer registrations. The price is that if a committee loses more than a third of its members, Ootle stalls until the epoch boundary re-forms it — a liveness cost, paid in time, not in safety. See Consensus for the arithmetic.
The life of a transaction
The sections that follow each zoom into one stage. In order, a transaction:
- Is built and sealed. A wallet daemon assembles instructions, attaches a separate stream of fee instructions, and signs. The signers’ public keys become the transaction’s initial authorization scope — the badges its access rules are checked against.
- Is submitted and gossiped. The wallet hands it to an indexer, which checks its shape and
publishes it on the network-wide
transactionsgossip topic. Every validator receives it; only validators in committees holding one of its inputs pass it to consensus. - Is sequenced. The relevant committee orders it into a block. If the inputs live in more than one shard group, the other groups first pledge not to touch them, so the parts commit together or not at all.
- Is executed. The TVM runs the fee instructions first and checkpoints, then runs the main instructions. Metered work becomes the fee.
- Is committed. Votes aggregate into a
ProposalCertificate; the chain advances; the three-chain rule makes an earlier block irreversible. - Is published. The transaction’s
SubstateDiffwrites new substate versions, and the receipt — including events — is served by indexers.
Each stage has a page: Consensus for steps 3 and 5, State and Execution for step 4 and 6, and Transaction Overview for how a client performs steps 1 and 2.
Where the value comes from
The native token on Ootle is TARI (a stealth resource). It enters the system through a one-way path: burn the base-layer coin, claim a matching amount on Ootle. There is no peg-out — you cannot burn TARI to recreate base-layer coins — so base-layer supply control stays entirely on the base layer, and demand for TARI is anchored to the fee market. See Tokenomics.
Where to go next
The rest of this section follows one thread: how the machine is put together.
- Architecture — node roles, sharding, epochs, and the P2P layer.
- Consensus — HotStuff, the three-chain rule, quorums, and cross-shard transactions.
- State and Execution — substates, the state tree, the TVM, and fees.
- Privacy — confidential and stealth assets, and the cryptography behind them.
- Privacy in Applications — what privacy looks like for a deployed application.
- Stablecoins — building an issuance-backed asset from the native primitives.
- Templates and Assets — the resource types and built-in templates you can build on.
- Tokenomics — the native token, the burn bridge, and fee distribution.
- Glossary — an A–Z of the terms used across this section.
Tip
Every concept in this section is grounded in the codebase. Where a statement maps to a specific constant or module, the source path is cited inline, so you can read the implementation alongside the prose. Design documents (RFCs and TIPs) predate the current implementation and are not treated as authoritative here — where they disagree with the code, the code wins.