Genie SDK reference

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

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

            /// Deploy initializes the component and returns Self.
            /// Fields are automatically saved to storage after deployment.
            #[deploy]
            pub async fn deploy() -> Result<Self> {
                Ok(Self { count: 0 })
            }

            #[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 {
            #[owner]
            pub fn increment(&mut self) -> Result<()> {
                // Access root component for state modification
                self.count += 1;
                Ok(())
            }

            /// 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 })
            }
        }
    }
}

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?;

// Router-scoped call configuration.
// Use `.with_delegated_owner(holder_id)` when the routed-to component should
// receive delegated Owner authority scoped to `holder_id` for just this call.
// `holder_id` is the permission source and scope target; the router's
// destination component is the grantee that gets to act on that holder's behalf.
client.controller
    .remote
    .with_delegated_owner(holder_id)
    .increment()
    .await?;

// Install components using generated installer
let installer = SimpleCounterContractClient::installer();
let controller_id = installer.controller.install(
    root_id,
    entity_id,
    owner_component_id
).await?;

// Entry point accessible from external calls
#[entry]
fn public_function() -> Result<()> { ... }

// Owner access (component owner restriction)
#[owner]
fn mint_tokens(amount: u64) -> Result<()> { ... }

// Public access (any caller allowed)
#[public]
fn get_public_info() -> Result<String> { ... }

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

// Read-only calculation (no storage access needed)
#[read_only]
fn calculate_fee(amount: u64) -> Result<u64> {
    Ok(amount * 3 / 1000) // 0.3% fee
}

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

// Private methods for inter-component communication
#[private]
fn receive_tokens(amount: u64, from: GenComponentId) -> Result<()> {
    let mut balance = Storage::load_guarded::<u64>()?;
    *balance += amount;
    Ok(())
}

// Root deployment (root module only)
#[deploy]
async fn deploy(metadata: TokenMetadata) -> Result<()> {
    Storage::save(metadata)?;
    Ok(())
}

// Component installation (non-root modules)
#[install]
async fn setup(config: ComponentConfig) -> Result<()> {
    Storage::save(config)?;
    Storage::save(0u64)?; // Initial balance
    Ok(())
}

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),
        })
    }

    /// Methods can access fields directly via &self or &mut self.
    /// Mutable methods (&mut self) trigger automatic field saving on completion.
    #[view]
    pub fn balance(&self) -> Result<AmountInSubunits> {
        Ok(self.token_store.balance())
    }

    #[private]
    pub fn receive(&mut self, amount: AmountInSubunits) -> Result<()> {
        self.token_store.credit(amount)
        // Fields are automatically saved after this method returns
    }
}

let client = ContractClient::new(target_component);

// Local calls (same entity), synchronous
client.holder.local.transfer_same_entity(amount, recipient)?;

// Remote calls (cross-entity), asynchronous with confirmation
client.holder.remote.transfer_with_confirmation(amount, recipient).await?;

// Fire-and-forget remote calls
let future = client.holder.remote.transfer(amount, recipient);
Async::spawn(future);

// 1. Deploy root component first
let root_client = ContractClient::new(root_component_id);

// 2. Install user components using the generated installer pattern
let installer = ContractClient::installer();

let issuer_component = installer.issuer.install(
    root_id,
    installed_on_entity,
    owner
).await?;

let holder_component = installer.holder.install(
    root_id,
    installed_on_entity,
    owner
).await?;

// Components should use structured error types
#[derive(Error, Debug)]
pub enum TokenError {
    #[error("Insufficient balance: {balance}, required: {required}")]
    InsufficientBalance { balance: u64, required: u64 },
    #[error("Transfer to self not allowed")]
    SelfTransfer,
}

// Use Result<T> returns for fallible operations
fn transfer(amount: u64, to: GenComponentId) -> Result<()> {
    let balance = Storage::load::<u64>()?;
    if balance < amount {
        return Err(TokenError::InsufficientBalance {
            balance,
            required: amount
        }.into());
    }
    // ... transfer logic
    Ok(())
}