Voltar para Documentação

Docs Técnicas

TREA CLI (`trea`)

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

O conteúdo abaixo vem das fontes técnicas do repositório e é prerenderizado no site para leitura direta por pessoas, crawlers e agentes.

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

text
trea [--signer SPEC] [--node URL] [--json] <command>

Read-only commands (status, events, view, simulate) require no signer. Write commands (deploy, deploy-child, call) require one.

Configuration — `trea.toml`

Place trea.toml at the project root (searched upward like Cargo.toml). It only contains environment profiles — contract specs live in deploy/*.toml:

toml
[profile.default]
node = "http://localhost:3001"
# signer = "env:TREA_SIGNER_KEY"   # or just: export TREA_SIGNER_KEY=<hex>  (auto-detected)

[profile.staging]
node   = "https://staging.atlas.bank"
signer = "env:STAGING_SIGNER_KEY"

Select a profile with --profile staging or TREA_PROFILE=staging.

Signer

The simplest approach — no config file needed:

bash
export TREA_SIGNER_KEY="<64-hex-chars>"   # auto-detected by every write command

TREA_SIGNER_KEY holds the raw ed25519 private key as hex. When set, trea picks it up automatically without any trea.toml signer entry.

For more control, pass via --signer, TREA_SIGNER env var, or the profile signer field, using one of these forms:

| Form | Description | |-------------------|----------------------------------------------------------| | env:<VAR> | hex key from named environment variable | | key:<hex> | inline hex key — avoid in scripts | | file:<path> | file containing 32 raw bytes or hex | | mnemonic:<words>| BIP-39 phrase (space-separated) | | demo:<identity> | dev only — requires TREA_UNSAFE_DEMO=1 |

demo: identities: seedbank-admin, alice-savings, metabank-admin, kyc-verifier.

`trea deploy` — Publish, Instantiate, Construct

The central command. Publish and instantiate are idempotent. Construction is one-shot at runtime when the target entrypoint is decorated with @construct.

bash
export TREA_SIGNER_KEY="<64-hex-chars>"
trea deploy vault-brl

Steps performed:

  1. Publish — checks GET /api/contracts/artifacts/{artifact_id} first; skips if already published.
  2. Instantiate — checks GET /api/contracts/{contract_id}; skips if contract exists.
  3. Construct — calls the configured constructor entrypoint, usually named

initialize; the source should decorate it with @construct.

Output on first run:

text
[published]    std-spending-vault-brl  nonce=5
[instantiated] alice-card-brl          nonce=6
[initialized]  alice-card-brl          nonce=7

Second run (same state):

text
[skipped] std-spending-vault-brl  artifact already published
[skipped] alice-card-brl          contract already instantiated
[skipped] initialize              already initialized

Some CLI output still uses the legacy word initialize. In TREA source, the entrypoint should be decorated with @construct; the function name and manifest section remain compatible with existing deploy scripts.

Deploy Manifest — `deploy/<script>.toml`

Each deploy script is a self-contained TOML file with three sections:

toml
# deploy/vault-brl.toml

[artifact]
id          = "std-spending-vault-brl"
path        = "crates/domain/atlas-trea/src/stdlib/spending_vault.trea"
type_params = { Asset = "BRL" }

[contract]
id = "alice-card-brl"

[initialize]
check_field = "owner"
asset       = "00000000-0000-0000-0000-000000000001/BRL"
args = [
    ["owner",         "addr:nbex1raclw5skj6xxn7adresk6wurex4rd4a5f3l7ramr8ds8hklww8hqa4c00r"],
    ["card_pubkey",   "text:033e2b34dab3a3c4b4c6b8e2a2e5f1e5a63a4a8d7c1b0e9f2d4c3b2a1908070605"],
    ["card_curve",    "text:secp256k1"],
    ["token_id",      "text:00000000-0000-0000-0000-000000000001/BRL"],
    ["max_per_tx",    "int:100"],
    ["daily_limit",   "int:500"],
    ["expires_at",    "int:1811375410"],
]

Each arg is a ["name", "kind:value"] tuple — the name is documentation, the value is what gets passed positionally. CLI flags override manifest values. Arg kinds: int, addr, text, bool.

The manifest section is still named [initialize] for CLI compatibility. It describes the constructor call. The runtime source of truth is the @construct decorator in the contract.

New vault-aware contracts should derive custody with ctx.vault() instead of requiring a vault_account argument. Legacy deploy scripts may still include an explicit vault address until their contract source is migrated.

Generic Contracts

Contracts with type parameters declare them in [artifact].type_params:

toml
[artifact]
type_params = { Asset = "BRL" }

Or override on the command line:

bash
trea deploy vault-brl --type-param Asset=USD

Flags

| Flag | Default | Description | |-----------------------|------------------|------------------------------------------| | --init-check-field | owner | Legacy storage hint used before submitting the constructor call | | --no-wait | — | Submit and exit without waiting | | --no-retry | — | Disable MP-022 automatic retry | | --asset | from trea.toml | Asset for the constructor call | | --audit basic\|pro\|institutional | — | Run the AI Audit predeploy gate |

`trea deploy-child` — Bind An On-Demand Child

deploy-child packages the factory flow. It reads the derived child id from an approved ProductTemplate request, deploys a child script at that exact id, fetches artifact hashes, and calls register_child_instance.

bash
trea deploy-child tmpl req-1 child-req-1 --audit basic

Arguments:

| Argument | Meaning | |----------|---------| | template | ProductTemplate contract id or alias | | request_id | Approved request id | | script | Child deploy script name or path |

The child deploy manifest is the normal trea deploy manifest. Its [contract].id is overwritten by the derived id returned from the template.

toml
[artifact]
id   = "std-credit-card-brl"
path = "crates/domain/atlas-trea/src/stdlib/credit_card_vault.trea"
type_params = { Asset = "BRL" }

[contract]
id = "ignored-by-deploy-child"

Operationally, avoid --no-wait when the next step must bind immediately: deploy-child needs the child artifact hashes to be visible before it can call register_child_instance.

See On-Demand Contract Factory.

`trea call` — Submit a `@tx` Entrypoint

bash
trea call vault-brl deposit --arg int:300

Wait for confirmation by default. Use --no-wait to submit and exit immediately:

bash
trea call vault-brl deposit --arg int:300 --no-wait

Output:

text
contract  : alice-card-brl
entrypoint: deposit
caller    : nbex1raclw5skj6xxn7adresk6wurex4rd4a5f3l7ramr8ds8hklww8hqa4c00r
nonce     : 8
status    : confirmed

`trea view` — Query a `@view` Entrypoint

No transaction, no signer required.

bash
trea view vault-brl available
text
contract  : alice-card-brl
entrypoint: available
status    : ok
returns[0] : "350"

`trea simulate` — Dry-Run a `@tx` Entrypoint

Shows what effects a call would produce without submitting it. No signer required.

bash
trea simulate vault-brl pay --arg addr:nbex1... --arg int:50 --arg int:1

`trea status` — Inspect Contract Storage

No signer required.

bash
trea status vault-brl
text
contract_id : alice-card-brl
lifecycle   : drafted
storage     :
  {
    "balance": "350",
    "owner": "nbex1raclw5...",
    "paused": false,
    ...
  }

`trea events` — List Execution Receipts

No signer required.

bash
trea events vault-brl
trea events vault-brl --entrypoint deposit --limit 5

`trea build` — Compile Without Deploying

bash
trea build
trea build src/spending_vault.trea
text
OK  src/spending_vault.trea  (12 entrypoints, 14 storage fields)

`trea wallet` — Key Utilities

bash
trea wallet new                            # generate keypair + BIP-39 mnemonic
trea wallet address env:TREA_SIGNER_KEY    # show address for any signer spec
trea wallet from-mnemonic word1 word2 …    # restore from mnemonic

`trea init` — Scaffold a New Project

bash
mkdir my-contract && cd my-contract
trea init

Creates trea.toml, src/MyContract.trea, deploy/my-contract.toml, tests/.gitkeep.

JSON Output

Every command supports --json:

bash
trea --json status vault-brl
trea --json deploy vault-brl

Full Deploy Walkthrough

bash
# 1. Set signer key in environment — no file on disk, no trea.toml signer entry
export TREA_SIGNER_KEY="<64-hex-chars>"

# 2. Verify the address before spending funds
trea wallet address env:TREA_SIGNER_KEY

# 3. trea.toml — only the node URL is required
cat > trea.toml <<'EOF'
[profile.default]
node = "http://localhost:3001"
EOF

# 4. Write deploy/vault-brl.toml (see "Deploy Manifest" above)

# 5. Deploy — idempotent, safe to run again
trea deploy vault-brl

# 6. Verify
trea status alice-card-brl
trea view alice-card-brl available

# 7. Interact
trea call alice-card-brl deposit --arg int:300
trea events alice-card-brl --entrypoint deposit