Documentation Index
Fetch the complete documentation index at: https://mintlify.com/stellar/rs-soroban-sdk/llms.txt
Use this file to discover all available pages before exploring further.
The token module contains types for interacting with token contracts, including the Stellar Asset Contract. It provides a standardized interface defined by SEP-41.
Overview
The token interface provides a standard way to interact with fungible tokens on Soroban, including transfers, allowances, balances, and metadata.
Interfaces
TokenInterface
Standard interface for token contracts defined by SEP-41.
pub trait TokenInterface {
// ... methods ...
}
TokenClient
Client for calling token contract functions.
use soroban_sdk::token::TokenClient;
let token = TokenClient::new(&env, &token_address);
Balance Functions
balance
Returns the balance of an address.
fn balance(env: Env, id: Address) -> i128
id - The address to query. Returns 0 if the address has no balance.
Example:
use soroban_sdk::{Env, Address};
use soroban_sdk::token::TokenClient;
fn get_balance(env: &Env, token: &Address, account: &Address) -> i128 {
let token = TokenClient::new(env, token);
token.balance(account)
}
Transfer Functions
transfer
Transfers tokens from one address to another.
fn transfer(env: Env, from: Address, to: MuxedAddress, amount: i128)
from - The address holding the tokens (requires authorization)to - The recipient address (can be muxed)amount - The amount of tokens to transfer
Events: Emits a transfer event with topics [from, to] and data {to_muxed_id, amount}.
Example:
use soroban_sdk::{contract, contractimpl, Env, Address};
use soroban_sdk::token::TokenClient;
#[contract]
pub struct PaymentContract;
#[contractimpl]
impl PaymentContract {
pub fn pay(
env: Env,
token: Address,
from: Address,
to: Address,
amount: i128
) {
from.require_auth();
let token = TokenClient::new(&env, &token);
token.transfer(&from, &to.into(), &amount);
}
}
transfer_from
Transfers tokens using an allowance.
fn transfer_from(
env: Env,
spender: Address,
from: Address,
to: Address,
amount: i128
)
spender - The address authorizing the transfer (requires authorization)from - The address holding the tokensto - The recipient addressamount - The amount to transfer
Note: Requires that spender has sufficient allowance from from.
Events: Emits a transfer event.
Example:
use soroban_sdk::{contract, contractimpl, Env, Address};
use soroban_sdk::token::TokenClient;
#[contract]
pub struct Escrow;
#[contractimpl]
impl Escrow {
pub fn release(
env: Env,
token: Address,
from: Address,
to: Address,
amount: i128
) {
let contract = env.current_contract_address();
contract.require_auth();
let token = TokenClient::new(&env, &token);
// Use the escrow contract's allowance
token.transfer_from(&contract, &from, &to, &amount);
}
}
Allowance Functions
allowance
Returns the allowance for a spender.
fn allowance(env: Env, from: Address, spender: Address) -> i128
from - The address holding the tokensspender - The address authorized to spend
Returns: The amount the spender can transfer from from’s balance.
approve
Sets an allowance for a spender.
fn approve(
env: Env,
from: Address,
spender: Address,
amount: i128,
expiration_ledger: u32
)
from - The address holding the tokens (requires authorization)spender - The address being authorizedamount - The amount to approveexpiration_ledger - Ledger number when the allowance expires
Events: Emits an approve event with topics [from, spender] and data [amount, expiration_ledger].
Example:
use soroban_sdk::{Env, Address};
use soroban_sdk::token::TokenClient;
fn approve_spender(
env: &Env,
token: &Address,
from: &Address,
spender: &Address,
amount: i128
) {
from.require_auth();
let token = TokenClient::new(env, token);
let expiration = env.ledger().sequence() + 1000;
token.approve(from, spender, &amount, &expiration);
}
Burn Functions
burn
Burns (destroys) tokens from an address.
fn burn(env: Env, from: Address, amount: i128)
from - The address holding the tokens (requires authorization)amount - The amount to burn
Events: Emits a burn event with topics [from] and data amount.
burn_from
Burns tokens using an allowance.
fn burn_from(env: Env, spender: Address, from: Address, amount: i128)
spender - The address authorizing the burn (requires authorization)from - The address holding the tokensamount - The amount to burn
Events: Emits a burn event.
decimals
Returns the number of decimals used to represent token amounts.
fn decimals(env: Env) -> u32
use soroban_sdk::{Env, Address};
use soroban_sdk::token::TokenClient;
fn get_decimals(env: &Env, token: &Address) -> u32 {
let token = TokenClient::new(env, token);
token.decimals()
}
name
Returns the name of the token.
fn name(env: Env) -> String
symbol
Returns the symbol of the token.
fn symbol(env: Env) -> String
StellarAssetInterface
Extended interface for Stellar Asset Contracts with admin capabilities.
pub trait StellarAssetInterface {
// Includes all TokenInterface methods plus:
// ...
}
StellarAssetClient
Client for calling Stellar Asset Contract functions.
use soroban_sdk::token::StellarAssetClient;
let asset = StellarAssetClient::new(&env, &asset_address);
Admin Functions (Stellar Asset Contract)
admin
Returns the admin address of the asset contract.
fn admin(env: Env) -> Address
set_admin
Sets a new administrator for the asset contract.
fn set_admin(env: Env, new_admin: Address)
new_admin - The new administrator address
Events: Emits a set_admin event.
authorized
Checks if an address is authorized to use the token.
fn authorized(env: Env, id: Address) -> bool
set_authorized
Sets whether an address is authorized.
fn set_authorized(env: Env, id: Address, authorize: bool)
id - The address to authorize/deauthorizeauthorize - true to authorize, false to deauthorize
Events: Emits a set_authorized event.
mint
Mints new tokens to an address.
fn mint(env: Env, to: Address, amount: i128)
to - The recipient addressamount - The amount to mint
Events: Emits a mint event with topics [to] and data amount.
clawback
Claws back (burns) tokens from an address.
fn clawback(env: Env, from: Address, amount: i128)
from - The address to claw back fromamount - The amount to claw back
Events: Emits a clawback event.
Examples
Simple Token Transfer
use soroban_sdk::{contract, contractimpl, Env, Address};
use soroban_sdk::token::TokenClient;
#[contract]
pub struct PaymentProcessor;
#[contractimpl]
impl PaymentProcessor {
pub fn process_payment(
env: Env,
token: Address,
from: Address,
to: Address,
amount: i128
) {
from.require_auth();
let token = TokenClient::new(&env, &token);
token.transfer(&from, &to.into(), &amount);
}
}
Token Swap with Allowances
use soroban_sdk::{contract, contractimpl, Env, Address};
use soroban_sdk::token::TokenClient;
#[contract]
pub struct TokenSwap;
#[contractimpl]
impl TokenSwap {
pub fn swap(
env: Env,
user: Address,
token_a: Address,
token_b: Address,
amount_a: i128,
amount_b: i128
) {
user.require_auth();
let contract = env.current_contract_address();
let token_a_client = TokenClient::new(&env, &token_a);
let token_b_client = TokenClient::new(&env, &token_b);
// Transfer token A from user to contract
token_a_client.transfer(&user, &contract.into(), &amount_a);
// Transfer token B from contract to user
token_b_client.transfer(&contract, &user.into(), &amount_b);
}
}
Checking Token Balance
use soroban_sdk::{contract, contractimpl, Env, Address};
use soroban_sdk::token::TokenClient;
#[contract]
pub struct BalanceChecker;
#[contractimpl]
impl BalanceChecker {
pub fn has_sufficient_balance(
env: Env,
token: Address,
account: Address,
required: i128
) -> bool {
let token = TokenClient::new(&env, &token);
let balance = token.balance(&account);
balance >= required
}
}
Best Practices
- Always require authorization: Call
require_auth() before token operations
- Check balances: Verify sufficient balance before transfers
- Handle allowances carefully: Set appropriate expiration times for allowances
- Use events: Monitor token events for tracking transfers and approvals
- Test with Stellar Assets: Test your contract with both custom tokens and Stellar Asset Contracts
See Also