Trait TokenInterface

pub trait TokenInterface {
    // Required methods
    fn allowance(env: Env, from: Address, spender: Address) -> i128;
    fn approve(
        env: Env,
        from: Address,
        spender: Address,
        amount: i128,
        expiration_ledger: u32,
    );
    fn balance(env: Env, id: Address) -> i128;
    fn transfer(env: Env, from: Address, to: Address, amount: i128);
    fn transfer_from(
        env: Env,
        spender: Address,
        from: Address,
        to: Address,
        amount: i128,
    );
    fn burn(env: Env, from: Address, amount: i128);
    fn burn_from(env: Env, spender: Address, from: Address, amount: i128);
    fn decimals(env: Env) -> u32;
    fn name(env: Env) -> String;
    fn symbol(env: Env) -> String;
}

Interface for Token contracts, such as the Stellar Asset Contract.

Defined by SEP-41.

The token interface provides the following functionality.

If a contract implementing the interface does not support some of the functionality, it should return an error.

The interface does not define any set of standard errors. Errors can be defined by the implementing contract.

Meta

Tokens implementing the interface expose meta functions about the token:

• decimals
• name
• symbol

Balances

Tokens track a balance for each address that holds the token. Tokens implementing the interface expose a single function for getting the balance that an address holds:

• balance

Transfers

Tokens allow holders of the token to transfer tokens to other addresses. Tokens implementing the interface expose a single function for doing so:

• transfer

Burning

Tokens allow holders of the token to burn, i.e. dispose of, tokens without transferring them to another holder. Tokens implementing the interface expose a single function for doing so:

• burn

Allowances

Tokens can allow holders to permit others to transfer amounts from their balance using the following functions.

• allowance
• approve
• transfer_from
• burn_from

Minting

There are no functions in the token interface for minting tokens. Minting is an administrative function that can differ significantly from one token to the next.

Required Methods

fn allowance(env: Env, from: Address, spender: Address) -> i128

Returns the allowance for spender to transfer from from.

The amount returned is the amount that spender is allowed to transfer out of from’s balance. When the spender transfers amounts, the allowance will be reduced by the amount transferred.

Arguments

• from - The address holding the balance of tokens to be drawn from.
• spender - The address spending the tokens held by from.

fn approve( env: Env, from: Address, spender: Address, amount: i128, expiration_ledger: u32, )

Set the allowance by amount for spender to transfer/burn from from.

The amount set is the amount that spender is approved to transfer out of from’s balance. The spender will be allowed to transfer amounts, and when an amount is transferred the allowance will be reduced by the amount transferred.

Arguments

• from - The address holding the balance of tokens to be drawn from.
• spender - The address being authorized to spend the tokens held by from.
• amount - The tokens to be made available to spender.
• expiration_ledger - The ledger number where this allowance expires. Cannot be less than the current ledger number unless the amount is being set to 0. An expired entry (where expiration_ledger < the current ledger number) should be treated as a 0 amount allowance.

Events

Emits an event with topics ["approve", from: Address, spender: Address], data = [amount: i128, expiration_ledger: u32]

fn balance(env: Env, id: Address) -> i128

Returns the balance of id.

Arguments

• id - The address for which a balance is being queried. If the address has no existing balance, returns 0.

fn transfer(env: Env, from: Address, to: Address, amount: i128)

Transfer amount from from to to.

Arguments

• from - The address holding the balance of tokens which will be withdrawn from.
• to - The address which will receive the transferred tokens.
• amount - The amount of tokens to be transferred.

Events

Emits an event with topics ["transfer", from: Address, to: Address], data = amount: i128

fn transfer_from( env: Env, spender: Address, from: Address, to: Address, amount: i128, )

Transfer amount from from to to, consuming the allowance that spender has on from’s balance. Authorized by spender (spender.require_auth()).

The spender will be allowed to transfer the amount from from’s balance if the amount is less than or equal to the allowance that the spender has on the from’s balance. The spender’s allowance on from’s balance will be reduced by the amount.

Arguments

• spender - The address authorizing the transfer, and having its allowance consumed during the transfer.
• from - The address holding the balance of tokens which will be withdrawn from.
• to - The address which will receive the transferred tokens.
• amount - The amount of tokens to be transferred.

Events

Emits an event with topics ["transfer", from: Address, to: Address], data = amount: i128

fn burn(env: Env, from: Address, amount: i128)

Burn amount from from.

Reduces from’s balance by the amount, without transferring the balance to another holder’s balance.

Arguments

• from - The address holding the balance of tokens which will be burned from.
• amount - The amount of tokens to be burned.

Events

Emits an event with topics ["burn", from: Address], data = amount: i128

fn burn_from(env: Env, spender: Address, from: Address, amount: i128)

Burn amount from from, consuming the allowance of spender.

Reduces from’s balance by the amount, without transferring the balance to another holder’s balance.

The spender will be allowed to burn the amount from from’s balance, if the amount is less than or equal to the allowance that the spender has on the from’s balance. The spender’s allowance on from’s balance will be reduced by the amount.

Arguments

• spender - The address authorizing the burn, and having its allowance consumed during the burn.
• from - The address holding the balance of tokens which will be burned from.
• amount - The amount of tokens to be burned.

Events

Emits an event with topics ["burn", from: Address], data = amount: i128

fn decimals(env: Env) -> u32

Returns the number of decimals used to represent amounts of this token.

Panics

If the contract has not yet been initialized.

fn name(env: Env) -> String

Returns the name for this token.

Panics

If the contract has not yet been initialized.

fn symbol(env: Env) -> String

Returns the symbol for this token.

Panics

If the contract has not yet been initialized.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors