TREA Dev Chain Runner

The TREA Dev Chain runner is the local-first test environment for TREA contracts. It runs the deterministic atlas-dev-chain runtime and exposes the HTTP/JSON API used by scripts, SDK experiments, and CI smoke tests.

Use it when you want to test publish, deploy, call, receipts, accounts, balances, and contract storage without starting a production AtlasDB node.

cargo run -p atlas-dev-chain -- dev

When installed or aliased as trea-dev, the same command is:

trea-dev dev

Configuration

By default the runner reads trea.dev.toml and stores local chain state under .atlas-dev-chain.

seed = "atlas-dev-chain"
chain_id = "atlas-dev-chain-1"
start_time = 1800000000
block_time_ms = 1000

[[accounts]]
name = "admin"
index = 0
balance = 100000000

[roles]
operator = ["admin"]

[oracles]
clock = "virtual"

Pass explicit paths when a test needs isolation:

cargo run -p atlas-dev-chain -- \
  --config ./fixtures/trea.dev.toml \
  --data-dir /tmp/trea-dev-test-chain \
  --port 8545 \
  dev

Common global flags:

| Flag | Meaning | |------|---------| | --config <path> | Path to trea.dev.toml | | --data-dir <path> | Local state directory | | --port <port> | HTTP port, default 8545 | | --json | Print command output as stable JSON where supported |

Commands

| Command | Purpose | |---------|---------| | dev | Start the local HTTP/JSON dev chain server | | reset | Delete the local data directory, recreate the chain, then start the server | | status | Show chain id, height, virtual clock, block time, and state root | | accounts | Print deterministic accounts derived from the config seed | | blocks | Print local block receipts in order | | receipts | Print the same ordered receipt stream used by block inspection | | publish | Publish a TREA source file as a contract artifact | | deploy | Instantiate a published artifact as a contract | | call | Call a contract entrypoint | | snapshot <name> | Save the current chain state as a named snapshot | | snapshots | List available snapshots with height and state root | | restore <name> | Restore the chain to a previously saved snapshot | | reset-genesis | Reset the running chain to genesis without stopping the server |

accounts is offline: it derives addresses from the config and does not require the server to be running. status, blocks, receipts, publish, deploy, call, snapshot, snapshots, restore, and reset-genesis talk to the local HTTP server.

Start And Inspect

In one shell:

cargo run -p atlas-dev-chain -- \
  --config crates/application/atlas-dev-chain/trea.dev.toml.example \
  --data-dir .atlas-dev-chain \
  dev

In another shell:

cargo run -p atlas-dev-chain -- accounts
cargo run -p atlas-dev-chain -- status
cargo run -p atlas-dev-chain -- blocks
cargo run -p atlas-dev-chain -- receipts

JSON output is meant for scripts and CI:

cargo run -p atlas-dev-chain -- --json status
cargo run -p atlas-dev-chain -- --json accounts

Publish, Deploy, Call

The runner uses the real TREA execution path through atlas-dev-chain and its HTTP/JSON API. It does not reimplement contract semantics in the CLI.

Create a minimal contract source:

cat > /tmp/dev-counter.trea <<'TREA'
contract DevCounter:
    storage:
        count: u128 = 0

    @tx
    def increment(amount: u128) -> bool:
        self.count = self.count + amount
        return True
TREA

Publish the source file:

cargo run -p atlas-dev-chain -- publish dev-counter:v1 \
  /tmp/dev-counter.trea \
  --signer admin

Deploy a contract instance:

cargo run -p atlas-dev-chain -- deploy dev-counter:v1 dev-counter-1 \
  --signer admin

Call an entrypoint:

cargo run -p atlas-dev-chain -- call dev-counter-1 increment \
  --signer admin \
  --arg int:7

Argument syntax is TYPE:VALUE.

| Type | Example | |------|---------| | bool | bool:true | | int | int:1000 | | addr | addr:wallet:nbex... | | text | text:hello |

Each write command prints a block receipt containing height, transaction hash, proposal id, state root, and contract receipt data when available. The same receipt can be inspected later through receipts or through the HTTP endpoint GET /transactions/{tx_id}/receipt.

Reset Safety

reset removes the directory passed through --data-dir with recursive deletion and then starts a fresh dev chain.

Use a dedicated dev/test directory:

cargo run -p atlas-dev-chain -- \
  --data-dir /tmp/trea-dev-reset-demo \
  reset

Do not point --data-dir at a directory that contains anything you want to keep. The runner is intentionally local-only; it is not a production data management tool.

HTTP Surface

The runner talks to the HTTP/JSON API introduced for the TREA Dev Chain:

| Endpoint | Purpose | |----------|---------| | GET /health | Liveness and chain id | | GET /status | Height, virtual clock, block time, state root | | GET /accounts | Deterministic dev accounts | | GET /accounts/{nameOrAddress} | Account lookup by name or address | | GET /balances/{address} | Balances, nonce, account nature, last tx hash | | POST /mine | MVP no-op/manual mining marker | | POST /contracts/artifacts | Publish artifact | | POST /contracts/deploy | Deploy contract | | POST /contracts/{contract_id}/call | Call contract | | GET /transactions/{tx_id}/receipt | Receipt lookup | | GET /aec/{scope} | Contract storage/AEC view when available | | GET /snapshots | List metadata for all saved snapshots | | POST /snapshots | Save current state as a named snapshot | | POST /snapshots/{name}/restore | Restore from a saved snapshot | | POST /reset | Reset running chain to genesis |

Errors are JSON objects with an error string so SDKs and shell scripts can handle failures predictably.

Snapshots and Fixtures

The dev chain supports saving and restoring named snapshots and running fixture sequences at startup via trea.dev.toml. See Dev Chain Snapshots and Fixtures for the full reference.