Stellar Tokens

Fungible and NonFungible Tokens for the Stellar contracts.

Modules

Fungible

The fungible module provides functionalities for fungible tokens: balance management, transfer operations, allowance delegation, total supply tracking.

Usage Examples

use soroban_sdk::{contract, contractimpl, Address, Env, String};
use stellar_tokens::fungible::{burnable::FungibleBurnable, Base, ContractOverrides, FungibleToken};
use stellar_access::ownable::{self as ownable, Ownable};
use stellar_macros::{only_owner};

#[contract]
pub struct MyContract;

#[contractimpl]
impl MyContract {
    // deploy this contract with the Stellar CLI:
    //
    // stellar contract deploy \
    // --wasm path/to/file.wasm \
    // -- \
    // --name "My Token" \
    // --symbol MTK \
    // --initial_owner <initial_owner_address>
    pub fn __constructor(e: &Env, name: String, symbol: String, initial_owner: Address) {
        // Set token metadata
        Base::set_metadata(
            e,
            8, // 8 decimals
            name,
            symbol,
        );

        // Set the contract owner
        ownable::set_owner(e, &initial_owner);
    }

    #[only_owner]
    pub fn mint_tokens(e: &Env, to: Address, amount: i128) {
        // Mint tokens to the recipient
        Base::mint(e, &to, amount);
    }
}

#[contractimpl(contracttrait)]
impl FungibleToken for MyContract {
    type ContractType = Base;
}

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

Extensions

• Burnable: Allow token holders to destroy their tokens
• Capped: Set maximum supply limits
• Allowlist: Restrict transfers to approved addresses
• Blocklist: Prevent transfers from/to blocked addresses
• Vault: Enable deposit/withdrawal of underlying assets in exchange for vault shares

Non-Fungible

The non_fungible module implements non-fungible token functionality:

• Unique Token IDs: Each token has a unique identifier
• Ownership Tracking: Track which account owns each token
• Approval System: Approve others to transfer specific tokens
• Metadata Support: Store name, symbol, and token URI

Usage Examples

use soroban_sdk::{contract, contractimpl, Address, Env, String};
use stellar_tokens::non_fungible::{
    burnable::NonFungibleBurnable,
    Base, ContractOverrides, NonFungibleToken,
};

#[contract]
pub struct MyNFTContract;

#[contractimpl]
impl MyNFTContract {
    // deploy this contract with the Stellar CLI:
    //
    // stellar contract deploy \
    // --wasm path/to/file.wasm \
    // -- \
    // --uri "www.mygame.com" \
    // --name "My Game Items Collection" \
    // --symbol MGMC
    pub fn __constructor(e: &Env, uri: String, name: String, symbol: String) {
        Base::set_metadata(e, uri, name, symbol);
    }

    pub fn award_item(e: &Env, to: Address) -> u32 {
        // access control might be needed
        Base::sequential_mint(e, &to)
    }
}

#[contractimpl(contracttrait)]
impl NonFungibleToken for MyNFTContract {
    type ContractType = Base;
}

#[contractimpl(contracttrait)]
impl NonFungibleBurnable for MyNFTContract {}

Extensions

• Burnable: Allow token holders to destroy their NFTs
• Enumerable: Enable iteration over all tokens and owner tokens
• Consecutive: Efficiently mint multiple tokens in batches
• Royalties: Support for creator royalties on secondary sales

Design Philosophy

Both modules follow a dual-layered approach:

1. High-Level Functions: Include all necessary checks, verifications, authorizations, and event emissions. Perfect for standard use cases.

2. Low-Level Functions: Provide granular control for custom workflows. Require manual handling of verifications and authorizations.

This design allows developers to choose between convenience and customization based on their project requirements.

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-tokens = "=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/fungible-pausable/ - Pausable fungible token
• examples/nft-sequential-minting/ - Basic non-fungible token
• examples/fungible-merkle-airdrop/ - Airdrop with merkle proofs

License

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