Skip to main content

Token Interface

Token contracts, including the built-in token and example token implementations expose the following common interface.

Tokens deployed on Soroban can implement any interface they choose, however, they should satisfy the following interface to be interoperable with contracts built to support Soroban's built-in tokens.

pub trait Contract {
/// Sets the administrator to "admin" and metadata.
fn init(env: soroban_sdk::Env, admin: soroban_auth::Identifier, metadata: TokenMetadata);

// --------------------------------------------------------------------------------
// Admin interface – privileged functions.
// --------------------------------------------------------------------------------

/// If "admin" is the administrator, burn "amount" from "from".
fn burn(
env: soroban_sdk::Env,
admin: soroban_auth::Signature,
nonce: soroban_sdk::BigInt,
from: soroban_auth::Identifier,
amount: soroban_sdk::BigInt,
);

/// If "admin" is the administrator, mint "amount" to "to".
fn mint(
env: soroban_sdk::Env,
admin: soroban_auth::Signature,
nonce: soroban_sdk::BigInt,
to: soroban_auth::Identifier,
amount: soroban_sdk::BigInt,
);

/// If "admin" is the administrator, set the administrator to "id".
fn set_admin(
env: soroban_sdk::Env,
admin: soroban_auth::Signature,
nonce: soroban_sdk::BigInt,
new_admin: soroban_auth::Identifier,
);

/// If "admin" is the administrator, freeze "id".
fn freeze(
env: soroban_sdk::Env,
admin: soroban_auth::Signature,
nonce: soroban_sdk::BigInt,
id: soroban_auth::Identifier,
);

/// If "admin" is the administrator, unfreeze "id".
fn unfreeze(
env: soroban_sdk::Env,
admin: soroban_auth::Signature,
nonce: soroban_sdk::BigInt,
id: soroban_auth::Identifier,
);

// --------------------------------------------------------------------------------
// Token interface
// --------------------------------------------------------------------------------

/// Get the allowance for "spender" to transfer from "from".
fn allowance(
env: soroban_sdk::Env,
from: soroban_auth::Identifier,
spender: soroban_auth::Identifier,
) -> soroban_sdk::BigInt;

/// Set the allowance to "amount" for "spender" to transfer from "from".
fn approve(
env: soroban_sdk::Env,
from: soroban_auth::Signature,
nonce: soroban_sdk::BigInt,
spender: soroban_auth::Identifier,
amount: soroban_sdk::BigInt,
);

/// Get the balance of "id".
fn balance(env: soroban_sdk::Env, id: soroban_auth::Identifier) -> soroban_sdk::BigInt;

/// Transfer "amount" from "from" to "to.
fn xfer(
env: soroban_sdk::Env,
from: soroban_auth::Signature,
nonce: soroban_sdk::BigInt,
to: soroban_auth::Identifier,
amount: soroban_sdk::BigInt,
);

/// Transfer "amount" from "from" to "to", consuming the allowance of "spender".
fn xfer_from(
env: soroban_sdk::Env,
spender: soroban_auth::Signature,
nonce: soroban_sdk::BigInt,
from: soroban_auth::Identifier,
to: soroban_auth::Identifier,
amount: soroban_sdk::BigInt,
);

// Returns true if "id" is frozen.
fn is_frozen(env: soroban_sdk::Env, id: soroban_auth::Identifier) -> bool;

// Returns the current nonce for "id".
fn nonce(env: soroban_sdk::Env, id: soroban_auth::Identifier) -> soroban_sdk::BigInt;

// --------------------------------------------------------------------------------
// Descriptive Interface
// --------------------------------------------------------------------------------

// Get the number of decimals used to represent amounts of this token.
fn decimals(env: soroban_sdk::Env) -> u32;

// Get the name for this token.
fn name(env: soroban_sdk::Env) -> soroban_sdk::Bytes;

// Get the symbol for this token.
fn symbol(env: soroban_sdk::Env) -> soroban_sdk::Bytes;
}

Most types that a token implementation utilizes are provided by the soroban-sdk and soroban-auth crates. The following type is also used during initialization.

#[soroban_sdk::contracttype]
pub struct TokenMetadata {
pub name: soroban_sdk::Bytes,
pub symbol: soroban_sdk::Bytes,
pub decimals: u32,
}