Struct frc46_token::token::Token

pub struct Token<'st, S, BS>
where
    S: Syscalls,
    BS: Blockstore,
{ /* private fields */ }

Library functions that implement core FRC-??? standards

Holds injectable services to access/interface with IPLD/FVM layer.

Implementations

impl<'st, S, BS> Token<'st, S, BS>

where S: Syscalls, BS: Blockstore,

pub fn create_state(bs: &BS) -> Result<TokenState, TokenError>

Creates a new clean token state instance

This should be wrapped in a Token handle for convenience. Must be flushed to the blockstore explicitly to persist changes

pub fn create_state_with_bit_width( bs: &BS, hamt_bit_width: u32, ) -> Result<TokenState, TokenError>

Creates a new clean token state instance, specifying the underlying Hamt bit widths

This should be wrapped in a Token handle for convenience. Must be flushed to the blockstore explicitly to persist changes

pub fn wrap( runtime: &'st ActorRuntime<S, BS>, granularity: u64, state: &'st mut TokenState, ) -> Self

Wrap an existing token state

pub fn replace(&mut self, state: TokenState) -> TokenState

Replace the current state with another The previous state is returned and can be safely dropped

pub fn load_state(bs: &BS, state_cid: &Cid) -> Result<TokenState, TokenError>

For an already initialised state tree, loads the state tree from the blockstore at a Cid

pub fn load_replace(&mut self, cid: &Cid) -> Result<TokenState, TokenError>

Loads a fresh copy of the state from a blockstore from a given cid, replacing existing state The old state is returned to enable comparisons and the like but can be safely dropped otherwise

pub fn flush(&mut self) -> Result<Cid, TokenError>

Flush state and return Cid for root

pub fn state(&self) -> &TokenState

Get a reference to the wrapped state tree

pub fn runtime(&self) -> &ActorRuntime<S, BS>

Get a reference to the underlying runtime

impl<'st, S, BS> Token<'st, S, BS>

where S: Syscalls, BS: Blockstore,

pub fn granularity(&self) -> u64

Returns the smallest amount of tokens which is indivisible

Transfers and balances must be in multiples of granularity but allowances need not be. Granularity never changes after it is initially set

pub fn mint( &mut self, operator: &Address, initial_owner: &Address, amount: &TokenAmount, operator_data: RawBytes, token_data: RawBytes, ) -> Result<ReceiverHook<MintIntermediate>, TokenError>

Mints the specified value of tokens into an account

The minter is implicitly defined as the caller of the actor, and must be an ID address. The mint amount must be non-negative or the method returns an error.

Returns a ReceiverHook to call the owner’s token receiver hook, and the owner’s new balance. ReceiverHook must be called or it will panic and abort the transaction.

The hook call will return a MintIntermediate struct which must be passed to mint_return to get the final return data

pub fn mint_return( &self, intermediate: MintIntermediate, ) -> Result<MintReturn, TokenError>

Finalise return data from MintIntermediate data returned by calling receiver hook after minting This is done to allow reloading the state if it changed as a result of the hook call so we can return an accurate balance even if the receiver transferred or burned tokens upon receipt

pub fn total_supply(&self) -> TokenAmount

Gets the total number of tokens in existence

This equals the sum of balance_of called on all addresses. This equals sum of all successful mint calls minus the sum of all successful burn/burn_from calls

pub fn balance_of(&self, owner: &Address) -> Result<TokenAmount, TokenError>

Returns the balance associated with a particular address

Accounts that have never received transfers implicitly have a zero-balance

pub fn allowance( &self, owner: &Address, operator: &Address, ) -> Result<TokenAmount, TokenError>

Gets the allowance between owner and operator

An allowance is the amount that the operator can transfer or burn out of the owner’s account via the transfer and burn methods.

pub fn increase_allowance( &mut self, owner: &Address, operator: &Address, delta: &TokenAmount, ) -> Result<TokenAmount, TokenError>

Increase the allowance that an operator can control of an owner’s balance by the requested delta

Returns an error if requested delta is negative or there are errors in (de)serialization of state.If either owner or operator addresses are not resolvable and cannot be initialised, this method returns MessagingError::AddressNotInitialized.

Else returns the new allowance

pub fn decrease_allowance( &mut self, owner: &Address, operator: &Address, delta: &TokenAmount, ) -> Result<TokenAmount, TokenError>

Decrease the allowance that an operator controls of the owner’s balance by the requested delta

Returns an error if requested delta is negative or there are errors in (de)serialization of of state. If the resulting allowance would be negative, the allowance between owner and operator is set to zero.Returns an error if either the operator or owner addresses are not resolvable and cannot be initialized.

Else returns the new allowance

pub fn revoke_allowance( &mut self, owner: &Address, operator: &Address, ) -> Result<TokenAmount, TokenError>

Sets the allowance between owner and operator to zero, returning the old allowance

pub fn set_allowance( &mut self, owner: &Address, operator: &Address, amount: &TokenAmount, ) -> Result<TokenAmount, TokenError>

Sets the allowance to a specified amount, returning the old allowance

pub fn burn( &mut self, owner: &Address, amount: &TokenAmount, ) -> Result<BurnReturn, TokenError>

Burns an amount of token from the specified address, decreasing total token supply

• The requested value MUST be non-negative
• The requested value MUST NOT exceed the target’s balance
• If the burn operation would result in a negative balance for the owner, the burn is discarded and this method returns an error

Upon successful burn

• The target’s balance decreases by the requested value
• The total_supply decreases by the requested value

pub fn burn_from( &mut self, operator: &Address, owner: &Address, amount: &TokenAmount, ) -> Result<BurnFromReturn, TokenError>

Burns an amount of token from the specified address, decreasing total token supply

If operator and owner are the same address, this method returns an InvalidOperator error.

• The requested value MUST be non-negative
• The requested value MUST NOT exceed the target’s balance
• If the burn operation would result in a negative balance for the owner, the burn is discarded and this method returns an error
• The operator MUST have an allowance not less than the requested value

Upon successful burn

• The target’s balance decreases by the requested value
• The total_supply decreases by the requested value
• The operator’s allowance is decreased by the requested value

pub fn transfer( &mut self, from: &Address, to: &Address, amount: &TokenAmount, operator_data: RawBytes, token_data: RawBytes, ) -> Result<ReceiverHook<TransferIntermediate>, TokenError>

Transfers an amount from the caller to another address

• The requested value MUST be non-negative
• The requested value MUST NOT exceed the sender’s balance
• The receiving actor MUST implement a method called tokens_received, corresponding to the interface specified for FRC-0046 token receiver. If the receiving hook aborts, when called, the transfer is discarded and this method returns an error

Upon successful transfer:

• The from balance decreases by the requested value
• The to balance increases by the requested value

Returns a ReceiverHook to call the recipient’s token receiver hook, and a TransferIntermediate struct ReceiverHook must be called or it will panic and abort the transaction.

Return data from the hook should be passed to transfer_return which will generate the Transfereturn struct

pub fn transfer_return( &self, intermediate: TransferIntermediate, ) -> Result<TransferReturn, TokenError>

Generate TransferReturn from the intermediate data returned by a receiver hook call

pub fn transfer_from( &mut self, operator: &Address, from: &Address, to: &Address, amount: &TokenAmount, operator_data: RawBytes, token_data: RawBytes, ) -> Result<ReceiverHook<TransferFromIntermediate>, TokenError>

Transfers an amount from one address to another

• The requested value MUST be non-negative
• The requested value MUST NOT exceed the sender’s balance
• The receiving actor MUST implement a method called tokens_received, corresponding to the interface specified for FRC-0046 token receiver. If the receiving hook aborts, when called, the transfer is discarded and this method returns an error
• The operator MUST be initialised AND have an allowance not less than the requested value

Upon successful transfer:

• The from balance decreases by the requested value
• The to balance increases by the requested value
• The owner-operator allowance decreases by the requested value

Returns a ReceiverHook to call the recipient’s token receiver hook, and a TransferFromIntermediate struct. ReceiverHook must be called or it will panic and abort the transaction.

Return data from the hook should be passed to transfer_from_return which will generate the TransferFromReturn struct

pub fn transfer_from_return( &self, intermediate: TransferFromIntermediate, ) -> Result<TransferFromReturn, TokenError>

Generate TransferReturn from the intermediate data returned by a receiver hook call

pub fn set_balance( &mut self, owner: &Address, amount: &TokenAmount, ) -> Result<TokenAmount, TokenError>

Sets the balance of an account to a specific amount

Using this library method obeys internal invariants (changing total supply etc.) but does not invoke the receiver hook on recipient accounts. Returns the old balance.

impl<'st, S, BS> Token<'st, S, BS>

where S: Syscalls, BS: Blockstore,

pub fn call_receiver_hook( &mut self, token_receiver: &Address, params: FRC46TokenReceived, ) -> Result<(), TokenError>

Calls the receiver hook, returning the result

pub fn assert_invariants( &self, ) -> Result<StateSummary, Vec<StateInvariantError>>

Checks the state invariants, throwing an error if they are not met

pub fn check_invariants(&self) -> (StateSummary, Vec<StateInvariantError>)

Checks the state invariants, returning a state summary and list of errors