Genie SDK reference

FIRE is a development framework that helps you harness The Grid’s computational model to design scalable, bottleneck-free systems. Genie is the Rust SDK for The Grid. It helps you structure contract logic using FIRE principles — one #[contract] codebase, multiple installable component roles — and handles deployment, installation, access control, and type-safe calls within and across entities.

Genie is an early preview. The API surface will evolve.

Prerequisite. This reference assumes you are familiar with how The Grid structures execution and state. If entities, components, and activations are new, read these first:

Entities and accounts — what an entity is and how it holds components

Components — installable logic and storage, same-entity vs cross-entity interaction

Activations — how work is submitted, queued, and routed to components

Contracts and the entity model

The entity and component model describes how code and state are structured on The Grid.

Entity — an addressable container and the unit of sequential execution. Activations arrive at an entity, enter its queue, and are processed one at a time; each is routed to a component inside the entity. See Entities and accounts.
Component — immutable logic and independent state installed inside an entity. Each component owns its storage; many components can coexist on one entity. See Components.
Logic immutability — Installing a component into an entity does not let the entity owner tamper with it. The instance runs only its verified on-chain code and responds through its published ABI; every activation is handled according to that logic and its access rules, not at the installer’s discretion.
Contract — one verified codebase that defines one or more component types (for example root, issuer, holder). Deploy creates the root instance; install creates other component types on an entity.
Co-location boundary — components on the same entity can call each other synchronously within a single activation on that entity’s queue. Components on different entities do not share storage; they interact only by sending activations between entities.

In Genie, #[deploy] instantiates the root component on an entity; #[install] adds non-root types. The manifest’s component_type_index identifies each type when you push and install from the CLI.

Actor model

In FIRE, the actor model is the foundation for distributing execution and state. On The Grid, the entity is the actor: it owns the activation queue and processes work sequentially. Components are the immutable logic and independent state modules that live inside an entity and run when an activation reaches them.

Core principles

Message passing and sequential handling — Entities communicate asynchronously by sending activations to one another. Each entity maintains its own queue and processes incoming activations one at a time, in order, dispatching each to the targeted component inside it.
Independent execution units — Each entity runs on its own queue. Work on one entity does not block unrelated entities elsewhere in the system.
Immediate state commit — When an activation completes on an entity, the affected components’ state changes commit immediately. Local state stays consistent without waiting for cross-entity consensus.
State isolation — Each component maintains its own storage. During an activation, a component may update its own state and trigger new activations to other entities; it never directly mutates another component’s storage.

Operational considerations

Distributing state and execution trades synchronous, all-or-nothing transactions for parallel throughput. The async consequences are familiar from other actor and message-passing systems. Two show up most often:

No transactional revert — Each activation is its own commit boundary. A failure downstream does not roll back work already committed upstream; coordinate across steps explicitly instead of assuming one global transaction.
Stale reads and interleaving — As in ordinary async code, state can change between sending a request and handling the response. Design multi-step flows with continuations and idempotent handlers where retries are possible.

Key FIRE concepts

FIRE is how you scale safely on The Grid. Scale requires asynchrony — throughput comes from distributed execution across entities, not from serializing the whole network. Mitigate async complexity with developer-defined guarantees and explicit design patterns rather than assuming one global transaction. Unlock parallel scalability by structuring work so independent entities and components run concurrently without a single hot spot. The principles below spell that out and map each one to Genie:

Principle	What it means	In Genie
Distribute state and execution	Segregate state across components and execution across entities to maximize throughput.	Struct fields and `Storage::*` are scoped to one component; each entity runs on its own activation queue.
Manage component relations	Use developer-defined guarantees to ensure distribution safety.	`#[installation_request]`, `#[owner]` / `#[private]`, install ownership, delegated access grants.
Prioritize composability	Build from reusable, interface-defined components while keeping state isolated.	Multi-module `#[contract]`, installers, `GvmContract` handles, generated typed clients.
Co-locate for atomicity	Group cooperating components on the same entity when one activation must see consistent local state.	Same-entity `local` calls; root plus helper components installed together when they must update atomically.

Used together, these principles are how applications built with FIRE are planned for scalability: independent entities and components handle work in parallel — cross-entity remote calls and async continuations where work should be distributed, flow control and error handling shaped by component relations, and entity-level atomicity through co-location when a step must stay local.

Feature snapshot

Area	Capabilities
Contract definition	`#[contract]`, component modules
Lifecycle	`#[deploy]`, `#[install]`, `#[installation_request]`
Access control	`#[owner]`, `#[public]`, `#[private]`, `#[view]`
Storage	Struct member fields, `Storage::save` / `load` / `load_guarded`, keyed storage
Communication	Generated clients and installers, `.local` / `.remote`
Runtime	Remote `.await`, `genie::spawn()`, spawn callbacks (`on_error`, `on_success`, `on_result`)
Error handling	`#[error_type]`, `ensure!`, `try_as()` for cross-call errors
Generated code	Clients, installers, role refs, `Self::root_client()`

Common types

Type	Purpose
`EntityId`	Identifies an account or entity
`AmountInSubunits`	Token amounts; supports `checked_add`, `checked_sub`, `checked_mul`, `checked_div`
`GvmContract`	Handle to a deployed contract instance; pass to `install()` when composing with another contract
`GvmComponentId`	Handle to a specific component instance

Quick start

[dependencies]
genie = { git = "https://github.com/gen-bc/gen-framework-preview", tag = "v0.15.0" }

Define a contract

Contract crates target RISC-V and use #![no_std] instead of the full standard library. If the contract uses heap types (String, Vec, and so on), also add extern crate alloc at the top of src/lib.rs:

#![no_std]
extern crate alloc;

use genie::contract;

#[contract]
pub mod simple_counter_contract {
    /// Root component for counter metadata
    pub mod root {
        use genie::{Result, deploy, installation_request, view};

        /// Component struct with member fields for automatic storage management.
        /// Fields are loaded before method execution and saved after mutable methods.
        pub struct CounterRoot {
            count: u64,
        }

        impl CounterRoot {
            /// Runs once when this contract is instantiated. Initializes the root and returns Self.
            /// Fields are automatically saved to storage after deployment.
            #[deploy]
            pub async fn deploy() -> Result<Self> {
                Ok(Self { count: 0 })
            }

            /// Validates installation requests for counter components.
            #[installation_request]
            pub async fn installation_request(
                &mut self,
                _component_type: SimpleCounterContractComponents,
            ) -> Result<()> {
                Ok(())
            }

            #[view]
            pub fn get_count(&self) -> Result<u64> {
                Ok(self.count)
            }
        }
    }

    /// Controller component for counter operations
    pub mod controller {
        use genie::{Result, install, owner};

        pub struct CounterController {
            count: u64,
        }

        impl CounterController {
            /// Install receives the return value from installation_request.
            /// Initialize all struct fields and return Self.
            #[install]
            pub async fn install(
                _installation_return_value: (),
            ) -> Result<Self> {
                Ok(Self { count: 0 })
            }

            #[owner]
            pub fn increment(&mut self) -> Result<()> {
                self.count += 1;
                Ok(())
            }
        }
    }
}

Use the component

use genie::{Component, Result};

// Use generated client for type-safe calls
let client = SimpleCounterContractClient::new(component_id);

// Local calls (same entity), synchronous
client.controller.local.increment()?;
let count = client.root.local.get_count()?;

// Remote calls (cross-entity), asynchronous
client.controller.remote.increment().await?;
let count = client.root.remote.get_count().await?;

// Install components using generated installer
let installer = SimpleCounterContractClient::installer();
let controller_id = installer.controller.install(contract_id).await?;

Macro reference

Genie uses procedural macros to define component boundaries, roles, and communication patterns. Entry-point attributes (#[view], #[owner], #[public], #[private]) also generate async variants for remote client calls.

Contract definition

Macro	Purpose
`#[contract]`	Defines a contract module containing multiple components
`mod X`	Declares a component module within a contract

Component lifecycle

Macro	Purpose	Example
`#[deploy]`	Instantiates the contract by deploying the root component; one root deployment = one contract instance (must be async)	`#[deploy] pub async fn deploy() -> Result<Self>`
`#[install]`	Internal component method called during component installation (must be async)	`#[install] pub async fn install(data) -> Result<Self>`
`#[installation_request]`	Root gatekeeper called before each install; may return install data passed to `#[install]` (`BorshSerialize` / `BorshDeserialize`)	`#[installation_request] pub async fn installation_request(&mut self, component_type: ContractComponents) -> Result<InstallData>`

Access control

Macro	Purpose	Example
`#[owner]`	Restricts access only to the component owner	`#[owner] fn mint() -> Result<()>`
`#[public]`	Public entry point callable by any caller	`#[public] fn transfer() -> Result<()>`
`#[private]`	Callable only by other components in the same contract	`#[private] fn internal_update() -> Result<()>`

Read-only methods

Macro	Purpose	Example
`#[view]`	Read-only public entry point (no state changes)	`#[view] fn get_balance() -> Result<u64>`

Attribute usage patterns

Read-only versus mutable methods

// View methods: public read-only
#[view]
fn get_balance() -> Result<u64> {
    Storage::load::<u64>()
}

// Public access for any caller
#[public]
fn update_metadata(new_name: String) -> Result<()> {
    Storage::save(new_name)?;
    Ok(())
}

Storage API

StorageKey — a byte key for keyed storage (StorageKey::from(...)). Keyed methods namespace values by type plus key, so you can store multiple values of the same type. StorageGuard<T> — a load–modify–save wrapper returned by load_guarded. Mutate through it like a reference; changes persist when it is dropped. Do not hold it across .await.

Function	Purpose
`Storage::save<T>(value)`	Persist value using type-derived key
`Storage::save_by_key<T>(key, value)`	Persist with explicit `StorageKey`
`Storage::load<T>()`	Load owned copy of stored value
`Storage::load_by_key<T>(key)`	Load with explicit `StorageKey`
`Storage::load_zero_copy<T>()`	Load by shared reference (`Rc`) without cloning payload
`Storage::load_zero_copy_by_key<T>(key)`	Zero-copy load with explicit `StorageKey`
`Storage::load_guarded<T>()`	Returns `StorageGuard<T>` that auto-saves on drop
`Storage::load_guarded_by_key<T>(key)`	Keyed `StorageGuard<T>` variant
`Storage::delete<T>()`	Remove value by type
`Storage::delete_by_key<T>(key)`	Remove by explicit `StorageKey`
`Storage::exists<T>()`	Check existence by type
`Storage::exists_by_key<T>(key)`	Check existence by `StorageKey`
`Storage::save_self<T>(&object)`	Persist entire component struct (used by generated code)
`Storage::load_self<T>()`	Load entire component struct (used by generated code)

Member storage (automatic field persistence)

Components can define struct fields that are automatically persisted to storage. When a component struct has fields:

On load. The entire struct is loaded from storage using Storage::load_self<T>().
On save. After mutable method execution, the entire struct is saved using Storage::save_self<T>(&object).

This whole-struct storage approach is more efficient than field-by-field storage, reducing the number of storage operations and ensuring atomic state updates. It is also convenient: state lives on the component struct and is used naturally through &self, &mut self, and field access, like ordinary Rust.

pub struct FungibleTokenHolder {
    /// Tracks the holder's token balance, automatically persisted.
    token_store: TokenStore,
    /// Stores metadata received during installation, automatically persisted.
    holder_metadata: HolderMetaData,
}

impl FungibleTokenHolder {
    /// Install returns Self with initialized fields.
    /// The framework automatically saves all fields after installation.
    #[install]
    pub async fn install(metadata: Metadata) -> Result<Self> {
        Ok(Self {
            token_store: TokenStore::new(),
            holder_metadata: HolderMetaData::new(metadata),
        })
    }

    /// Read-only access via `&self`; fields are loaded before the method runs.
    #[view]
    pub fn balance(&self) -> Result<AmountInSubunits> {
        Ok(self.token_store.balance())
    }

    /// Mutable access via `&mut self`; fields are saved after this method returns.
    #[private]
    pub fn receive(&mut self, amount: AmountInSubunits) -> Result<()> {
        self.token_store.credit(amount);
        Ok(())
    }
}

Runtime and communication API

Function	Purpose
`genie::spawn(future)`	Queue a remote `ComponentCallFuture`; activation is sent when this execution yields (optional callbacks)
`SpawnHandle::on_result` / `on_error` / `on_success`	Attach callbacks to a spawned call
`Self::context()`	Caller identity (`from`) and executing component (`to`); use `*Self::context().from.entity_id()` for the caller’s entity
`Component::get_owner()`	Owner of the current component, if any
`Component::is_same_entity(&component_id)`	Whether another component is on the same entity
`Component::ensure_same_contract(&component_id)`	Verify another component belongs to the same contract

Remote activation patterns

Remote calls from generated clients return a ComponentCallFuture. Three ways to run them:

Await

Wait for the result in the same method. The execution yields until the remote call completes.

let client = ContractClient::new(target_component);

match client.holder.remote.transfer(amount, recipient).await {
    Ok(()) => { /* success */ }
    Err(err) => { /* handle error */ }
}

The calling method must be async.

Spawn

Queue the call with genie::spawn and continue local work. All queued spawns are sent as activations when execution yields.

genie::spawn(client.holder.remote.transfer(amount, recipient));

self.balance = self.balance.checked_sub(amount).ok_or(/* ... */)?;

// All queued spawns are sent as activations to their destinations only when
// this function returns and execution yields.
Ok(())

Spawn with callbacks

Attach a #[private] handler. The runtime invokes it in a later activation when the call completes or fails.

genie::spawn(client.holder.remote.transfer(amount, recipient))
    .on_error(Self::callbacks().on_transfer_error);

#[private]
pub async fn on_transfer_error(&mut self, err: GvmError) -> Result<()> {
    // handle failure
    Ok(())
}

Use .on_success or .on_result for other callback shapes.

Component communication patterns

Local versus remote calls

Generated clients expose .local and .remote routers on each component role.

let client = ContractClient::new(target_component);

// Local (same entity): synchronous — no async
client.holder.local.balance()?;
client.holder.local.send_same_entity(recipient, amount)?;

// Remote (cross-entity): returns a ComponentCallFuture — await, spawn, or spawn with callbacks (see above)
client.holder.remote.send(recipient, amount).await?;

Typed role references

Method parameters can use generated refs instead of raw GvmComponentId. Import from super::self_refs:

use super::self_refs::Holder;

pub async fn mint(&mut self, dest: Holder, amount: AmountInSubunits) -> Result<()> {
    // The holder owns its balance; the issuer cannot mutate it directly.
    // Mint credits tokens by activating the destination holder's receive method.
    dest.remote.receive(amount).await?;
    Ok(())
}

When you have a GvmComponentId and need a typed ref (or the reverse), use .try_into()?.

Calling root from a non-root component

Non-root components call root methods via Self::root_client():

Self::root_client()
    .remote
    .execute_swap_a_to_b(amount, self.holder_b)
    .await?;

Error handling

Fallible component methods return genie::Result<T> (alias for Result<T, GenieError>). Returning Err reports failure to the caller; it does not revert storage already written in the same activation.

Validation

Use ensure! for early returns — with a message string or a typed error that implements Into<GenieError>.

ensure!(amount > 0, "Amount must be greater than zero");
ensure!(self.is_open, ContractClosed);

Component errors

Define one error enum per component with #[error_type]. Return typed errors via .into().

use genie::{ensure, error_type, AmountInSubunits, Result};

#[error_type]
pub enum TokenError {
    #[error("Insufficient balance: {balance}, required: {required}")]
    InsufficientBalance { balance: AmountInSubunits, required: AmountInSubunits },
    #[error("Amount must be greater than zero")]
    ZeroAmount,
}

#[owner]
pub fn transfer(&mut self, amount: AmountInSubunits) -> Result<()> {
    ensure!(amount > AmountInSubunits::from(0u64), TokenError::ZeroAmount);

    self.balance = self
        .balance
        .checked_sub(amount)
        .ok_or(TokenError::InsufficientBalance {
            balance: self.balance,
            required: amount,
        })?;
    Ok(())
}

Rollback on failed remote calls

Remote calls can fail after local state has already changed. Update local state first, then revert manually if the remote leg fails:

self.balance = self.balance.checked_sub(amount).ok_or(/* ... */)?;
if let Err(e) = to.remote.receive(amount).await {
    self.balance = self.balance.checked_add(amount).ok_or(/* ... */)?;
    return Err(e.into());
}
Ok(())

Cross-contract errors

Use try_as() to match a callee’s typed error after a failed remote call.

match client.holder.remote.transfer(amount, recipient).await {
    Ok(()) => Ok(()),
    Err(err) => {
        if let Some(HolderError::InsufficientBalance { .. }) = err.try_as() {
            Ok(()) // handle known callee error
        } else {
            Err(err.into())
        }
    }
}

Cross-contract composition

A contract can take GvmContract handles to already-deployed contracts, install their components, and call them through generated clients.

Two-token pool example

A pool that trades token A for token B needs one holder per token contract — two holders because there are two different tokens. Root installs pool holders on its own entity at #[deploy] (the liquidity reserves):

#[deploy]
pub async fn deploy(
    token_a_contract: GvmContract,
    token_b_contract: GvmContract,
) -> Result<Self> {
    let pool_holder_a = SimpleTokenClient::installer()
        .holder
        .install(token_a_contract)
        .await?;
    let pool_holder_b = SimpleTokenClient::installer()
        .holder
        .install(token_b_contract)
        .await?;
    Ok(Self {
        install_data: InstallData {
            pool_holder_a,
            pool_holder_b,
            token_a_contract,
            token_b_contract,
        },
        /* ... */
    })
}

Client installs user holders on the installing entity at #[install]. Root passes the token contracts and its pool holder IDs through InstallData:

#[install]
pub async fn install(data: super::root::InstallData) -> Result<Self> {
    let holder_a = SimpleTokenClient::installer()
        .holder
        .install(data.token_a_contract)
        .await?;
    let holder_b = SimpleTokenClient::installer()
        .holder
        .install(data.token_b_contract)
        .await?;
    Ok(Self {
        holder_a,
        holder_b,
        pool_holder_a: data.pool_holder_a,
        pool_holder_b: data.pool_holder_b,
    })
}

Calling the other contract — on root, wrap a stored pool holder ID in a generated client:

use demo_simple_token::simple_token::SimpleTokenClient;

fn pool_b(&self) -> SimpleTokenClient {
    SimpleTokenClient::new(self.install_data.pool_holder_b)
}

// Same entity: read the pool's token-B reserve (synchronous)
let balance = self.pool_b().holder.local.balance()?;

// Cross-entity: send output tokens to a user's holder
self.pool_b()
    .holder
    .remote
    .send(dest.try_into()?, output)
    .await?;

Generated infrastructure

The #[contract] macro automatically generates:

Contract client — {Contract}Client with a router per component role (.local, .remote, .callbacks):

let client = SimpleCounterContractClient::new(component_id);

client.controller.local.increment()?;
client.controller.remote.increment().await?;

Installers — {Contract}Installer for installing non-root components:

let installer = SimpleCounterContractClient::installer();
let controller_id = installer.controller.install(contract_id).await?;

Components enum — one variant per non-root role (for example SimpleCounterContractComponents::Controller). Passed to the root’s #[installation_request] handler so it knows which component is being installed:

#[installation_request]
pub async fn installation_request(
    &mut self,
    component_type: SimpleCounterContractComponents,
) -> Result<()> {
    match component_type {
        SimpleCounterContractComponents::Controller => Ok(()),
    }
}

Callback router — typed refs for #[private] methods, wired via Self::callbacks() in spawn handlers:

genie::spawn(client.root.remote.increment())
    .on_error(Self::callbacks().on_increment_error);

Role refs — super::self_refs::{Holder, Issuer, ...} for type-safe same-contract method parameters.
Self::root_client() — on non-root components, call root methods without constructing a client manually:
Self::root_client().remote.some_root_method(args).await?;

​Contracts and the entity model

​Actor model

​Core principles

​Operational considerations

​Key FIRE concepts

​Feature snapshot

​Common types

​Quick start

​Define a contract

​Use the component

​Macro reference

​Contract definition

​Component lifecycle

​Access control

​Read-only methods

​Attribute usage patterns

​Read-only versus mutable methods

​Storage API

​Member storage (automatic field persistence)

​Runtime and communication API

​Remote activation patterns

​Await

​Spawn

​Spawn with callbacks

​Component communication patterns

​Local versus remote calls

​Typed role references

​Calling root from a non-root component

​Error handling

​Validation

​Component errors

​Rollback on failed remote calls

​Cross-contract errors

​Cross-contract composition

​Two-token pool example

​Generated infrastructure