Stellar Access Control

Access Control, Ownable, and Role Transfer utilities for Stellar contracts.

Overview

This package provides three main modules for managing access control in Soroban smart contracts:

• Access Control: Role-based access control with hierarchical permissions
• Ownable: Simple single-owner access control pattern
• Role Transfer: Utility module for secure role and ownership transfers

Modules

Access Control

The access_control module provides comprehensive role-based access control functionality:

• Admin Management: Single overarching admin with full privileges
• Role Hierarchy: Roles can have admin roles that can grant/revoke permissions
• Secure Transfers: Two-step admin transfer process for security

Usage Examples

use soroban_sdk::{contract, contractimpl, symbol_short, Address, Env};
use stellar_access::access_control::{self as access_control, AccessControl};

#[contract]
pub struct MyContract;

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

    pub fn admin_restricted_function(e: &Env) {
        access_control::enforce_admin_auth(e);
        // ...
    }

    pub fn mint(e: &Env, to: Address, token_id: u32, caller: Address) {
        access_control::ensure_role(e, &symbol_short!("minter"), &caller );
        caller.require_auth();
        // minting
    }
}

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

With Macros (requires stellar-macros dependency):

use stellar_macros::{only_admin, only_role};

#[only_admin]
pub fn admin_restricted_function(e: &Env) {
    // ...
}

#[only_role(caller, "minter")]
fn mint(e: &Env, to: Address, token_id: u32, caller: Address) {
    // ...
}

Ownable

The ownable module implements a simple ownership pattern:

• Single Owner: Contract has one owner with exclusive access
• Ownership Transfer: Secure two-step ownership transfer
• Ownership Renouncement: Owner can renounce ownership

Usage Examples

use soroban_sdk::{contract, contractimpl, Address, Env};
use stellar_access::ownable::{self as ownable, Ownable};

#[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);
    }

    pub fn owner_restricted_function(e: &Env) {
        ownable::enforce_owner_auth(e);
        // ...
    }
}

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

With Macros (requires stellar-macros dependency):

use stellar_macros::only_owner;

#[only_owner]
pub fn owner_restricted_function(e: &Env) {
    // ...
}

Role Transfer

The role_transfer module is a utility module that provides the underlying infrastructure for secure two-step role and ownership transfers used by both Access Control and Ownable modules.

Security Model

Both Access Control and Ownable modules implement a two-step transfer process for critical role changes:

1. Initiate Transfer: Current admin/owner specifies the new recipient and expiration
2. Accept Transfer: Designated recipient must explicitly accept the transfer

This mechanism prevents accidental transfers to wrong addresses or loss of control due to typos or errors.

Note: Unlike OpenZeppelin's Solidity library where role transfers can be immediate, all role transfers in this Stellar library are always two-step processes for enhanced security. This applies to both ownership transfers and admin role transfers.

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-access = "=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/ownable/ - Simple ownership pattern
• examples/nft-access-control/ - Role-based access control

License

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