Rust API

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

Use the APIs in this order:

1. parse source;
2. verify language and safety rules;
3. compile artifact and reports;
4. execute locally when needed;
5. submit publish, instantiate, and call transactions through AtlasDB.

Common Imports

use atlas_trea::{
    compile_contract, compile_contract_artifact,
    compile_contract_with_modules, compile_contract_with_stdlib,
    parse_contract, verify_contract,
    flatten_module, resolve_module_sources,
    ContractArtifact, IrContractInstance, ExecutionContext, RuntimeValue,
};

Parse Source

let module = parse_contract(source)?;

The parser checks syntax only.

Verify Contract

verify_contract(&module)?;

The verifier checks publishable executable surface.

Compile Artifact And Reports

let compiled = compile_contract(source, 1)?;

Use compile_contract(...) when you need artifact metadata plus reports.

Compile Artifact Only

let artifact = compile_contract_artifact(source, 1)?;

Use compile_contract_artifact(...) when you only need canonical ABI and hash material.

Compile With Explicit Modules

For contracts that use impl composition, pass the base module sources:

use std::collections::BTreeMap;

let mut modules = BTreeMap::new();
modules.insert("BasicToken".to_string(), basic_token_source);
modules.insert("Ownable".to_string(), ownable_source);

let compiled = compile_contract_with_modules(child_source, &modules, 1)?;

compile_contract_with_modules parses each base, flattens the child against them, verifies the result, and compiles. The returned artifact has is_flattened: true and uses_modules listing the base names.

Compile With Stdlib

For contracts that impl stdlib modules, use compile_contract_with_stdlib, which automatically injects all four stdlib sources:

let compiled = compile_contract_with_stdlib(child_source, &BTreeMap::new(), 1)?;

Pass an empty map when no custom modules beyond the stdlib are needed. Custom modules in the second argument are merged with the stdlib sources.

Flatten A Module

To obtain a flattened ContractModule without full compilation:

use std::collections::BTreeMap;

let child = parse_contract(child_source)?;
let base  = parse_contract(base_source)?;

let mut bases = BTreeMap::new();
bases.insert("BasicToken".to_string(), &base);

let flat = flatten_module(&child, &bases)?;

flatten_module merges storage and functions in declaration order and resolves super.method() calls. The returned module can be passed directly to verify_contract and compile_module.

Resolve Module Sources From A Registry

Given a parsed module and a lookup function, resolve all uses declarations to their source text:

let sources = resolve_module_sources(&module, |path| {
    registry.get(path).cloned()   // your lookup: path → Option<String>
})?;

// sources: BTreeMap<module_name, source_text>
let refs: BTreeMap<String, &str> = sources.iter()
    .map(|(k, v)| (k.clone(), v.as_str()))
    .collect();
let compiled = compile_contract_with_modules(main_source, &refs, 1)?;

resolve_module_sources maps each uses ModuleName to its canonical import path, calls the registry closure, and errors if any dependency is missing.

Execute Locally With The IR Runtime

IrContractInstance executes compiled contracts in the IR-based runtime, which is faster and more deterministic than the AST runtime:

use atlas_trea::{IrContractInstance, ExecutionContext, RuntimeValue};

let module = parse_contract(source)?;
// For composed contracts, flatten first:
// let module = flatten_module(&child, &bases)?;

let mut instance = IrContractInstance::new(&module)?;

let ctx = ExecutionContext {
    caller: "wallet:alice".to_string(),
    block_timestamp: 1_700_000_000,
    ..Default::default()
};

let output = instance.execute(
    "initialize",
    vec![RuntimeValue::Address("wallet:owner".to_string())],
    ctx,
)?;

If the source marks initialize with @construct, this call is one-shot and the runtime blocks all other entrypoints until it succeeds.

Read storage after execution:

let balance = instance.storage("total");
// → Some(&RuntimeValue::Integer(1000))

IrContractInstance manages its own in-memory storage and is suitable for unit tests and local simulations. The ledger uses the same IR runtime during ContractCall execution.

Generate Authoring Report

let report = atlas_trea::analyze_contract_authoring(source)?;

Diff Storage Layout

let diff = atlas_trea::diff_contract_storage_layouts(old_source, new_source)?;