contract-utils

Stellar Contract Utils

Utilities for Stellar contracts.

Modules

Pausable

The pausable module provides functionality to pause and unpause contract operations for emergency situations or maintenance.

Usage Examples

use soroban_sdk::{contract, contractimpl, Address, Env};
use stellar_contract_utils::pausable::{self as pausable, Pausable};
use stellar_access::ownable::{self as ownable, Ownable};
use stellar_macros::{only_owner, when_not_paused, when_paused};

#[contract]
pub struct MyContract;

#[contractimpl]
impl MyContract {
    // deploy this contract with the Stellar CLI:
    //
    // stellar contract deploy \
    // --wasm path/to/file.wasm \
    // -- \
    // --owner <owner_address>
    pub fn __constructor(e: &Env, owner: Address) {
        ownable::set_owner(e, &owner);
    }

    #[when_not_paused]
    pub fn normal_operation(e: &Env) {
        // This function can only be called when contract is not paused
    }

    #[when_paused]
    pub fn emergency_reset(e: &Env) {
        // This function can only be called when contract is paused
    }
}

#[contractimpl(contracttrait)]
impl Pausable for MyContract {
    #[only_owner]
    pub fn pause(e: &Env) {
        pausable::pause(e);
    }

    #[only_owner]
    pub fn unpause(e: &Env) {
        pausable::unpause(e);
    }
}

#[contractimpl(contracttrait)]
impl Ownable for MyContract {}

Upgradeable

The upgradeable module provides a trait and helper for contract upgrades. Implementing the Upgradeable trait generates an UpgradeableClient that other contracts (e.g. a governance contract, upgrader helper, or multisig) can use to trigger upgrades.

For storage migration patterns (eager, lazy, and enum wrapper), see the module-level documentation in src/upgradeable/mod.rs and the examples/upgradeable/ directory.

Usage Examples

use soroban_sdk::{contract, contractimpl, Address, BytesN, Env};
use stellar_access::ownable::{self as ownable, Ownable};
use stellar_contract_utils::upgradeable::{self as upgradeable, Upgradeable};
use stellar_macros::only_owner;

#[contract]
pub struct ExampleContract;

#[contractimpl]
impl ExampleContract {
    // deploy this contract with the Stellar CLI:
    //
    // stellar contract deploy \
    // --wasm path/to/file.wasm \
    // -- \
    // --owner <owner_address>
    pub fn __constructor(e: &Env, owner: Address) {
        ownable::set_owner(e, &owner);
    }
}

#[contractimpl]
impl Upgradeable for ExampleContract {
    #[only_owner]
    fn upgrade(e: &Env, new_wasm_hash: BytesN<32>, _operator: Address) {
        upgradeable::upgrade(e, &new_wasm_hash);
    }
}

#[contractimpl(contracttrait)]
impl Ownable for ExampleContract {}

Crypto

The crypto module provides cryptographic utilities including hash functions and Merkle tree verification.

Usage Examples

use soroban_sdk::{Bytes, BytesN, Env};
use stellar_contract_utils::crypto::{hasher::Hasher, keccak::Keccak256};

pub fn hash_data(e: &Env, data: Bytes) -> BytesN<32> {
    let mut hasher = Keccak256::new(e);
    hasher.update(data);
    hasher.finalize()
}

Features

• Hash Functions: SHA-256 and Keccak-256 implementations
• Merkle Verification: Verify Merkle proofs for data integrity
• Utility Functions: Hash pairs and commutative hashing

Merkle Distributor

The merkle_distributor module implements a Merkle-based claim distribution system for snapshot-based voting and token distributions.

Features

• Indexed Claims: Claims are indexed by position in the Merkle tree
• Flexible Leaf Structure: Support for custom claim data structures
• Use Cases: Token airdrops, NFT distributions, allowlists, snapshot voting

Installation

Add this to your Cargo.toml:

[dependencies]
# We recommend pinning to a specific version, because rapid iterations are expected as the library is in an active development phase.
stellar-contract-utils = "=0.6.0"
# Add this if you want to use macros
stellar-macros = "=0.6.0"

Examples

See the following examples in the repository:

• examples/pausable/ - Pausable contract functionality
• examples/upgradeable/ - Contract upgrade patterns
• examples/fungible-merkle-airdrop/ - Merkle-based token distribution

License

This package is part of the Stellar Contracts library and follows the same licensing terms.