Struct frc46_token::token::state::TokenState

pub struct TokenState {
    pub supply: TokenAmount,
    pub balances: Cid,
    pub allowances: Cid,
    /* private fields */
}

Token state IPLD structure

Fields

supply: TokenAmount

Total supply of token

balances: Cid

Map<ActorId, TokenAmount> of balances as a Hamt

allowances: Cid

Map<ActorId, Map<ActorId, TokenAmount>> as a Hamt. Allowances are stored balances[owner][operator]

Implementations

impl TokenState

An abstraction over the IPLD layer to get and modify token state without dealing with HAMTs etc.

This is a simple wrapper of state and in general does not account for token protocol level checks such as ensuring necessary approvals are enforced during transfers. This is left for the caller to handle. However, some invariants such as non-negative balances, allowances and total supply are enforced.

pub fn new<BS: Blockstore>(store: &BS) -> Result<Self, StateError>

Create a new token state-tree, without committing it (the root cid) to a blockstore

pub fn new_with_bit_width<BS: Blockstore>( store: &BS, hamt_bit_width: u32, ) -> Result<Self, StateError>

Create a new token state-tree, without committing it (the root cid) to a blockstore

Explicitly sets the bit width of underlying Hamt structures. Caller must ensure 1 <= hamt_bit_width <= 8.

pub fn load<BS: Blockstore>(bs: &BS, cid: &Cid) -> Result<Self, StateError>

Loads a fresh copy of the state from a blockstore from a given cid

pub fn save<BS: Blockstore>(&self, bs: &BS) -> Result<Cid, StateError>

Saves the current state to the blockstore, returning the cid

pub fn get_balance<BS: Blockstore>( &self, bs: &BS, owner: ActorID, ) -> Result<TokenAmount, StateError>

Get the balance of an ActorID from the currently stored state

pub fn change_balance_by<BS: Blockstore>( &mut self, bs: &BS, owner: ActorID, delta: &TokenAmount, ) -> Result<TokenAmount, StateError>

Changes the balance of the specified account by the delta

Caller must ensure that the sign of of the delta is consistent with token rules (i.e. negative transfers, burns etc. are not allowed). Returns the new balance of the account.

pub fn set_balance<BS: Blockstore>( &mut self, bs: &BS, owner: ActorID, new_balance: &TokenAmount, ) -> Result<TokenAmount, StateError>

Set the balance of the account returning the old balance

Consistent with change_balance_by, this method does not change the total supply. Business logic to reconcile the total supply with changes in balancesis the responsibility of the caller.

pub fn get_balance_map<'bs, BS: Blockstore>( &self, bs: &'bs BS, ) -> Result<Hamt<&'bs BS, TokenAmount, BytesKey>, StateError>

Retrieve the balance map as a HAMT

pub fn make_transfer<BS: Blockstore>( &mut self, bs: &BS, from: ActorID, to: ActorID, amount: &TokenAmount, ) -> Result<(), StateError>

Record a transfer of an amount between two accounts

It is the caller’s responsibility to ensure that allowance invariants are upheld. The caller should check that the amount is non-negative and complies with the token granularity.

pub fn count_balances<BS: Blockstore>( &self, bs: &BS, ) -> Result<usize, StateError>

Retrieve the number of token holders

This involves iterating through the entire HAMT

pub fn change_supply_by( &mut self, delta: &TokenAmount, ) -> Result<&TokenAmount, StateError>

Increase/decrease the total supply by the specified value

Returns the new total supply

pub fn get_allowance_between<BS: Blockstore>( &self, bs: &BS, owner: ActorID, operator: ActorID, ) -> Result<TokenAmount, StateError>

Get the allowance that an owner has approved for a operator

If an existing allowance cannot be found, it is implicitly assumed to be zero

pub fn change_allowance_by<BS: Blockstore>( &mut self, bs: &BS, owner: ActorID, operator: ActorID, delta: &TokenAmount, ) -> Result<TokenAmount, StateError>

Change the allowance between owner and operator by the specified delta

pub fn revoke_allowance<BS: Blockstore>( &mut self, bs: &BS, owner: ActorID, operator: ActorID, ) -> Result<TokenAmount, StateError>

Revokes an approved allowance by removing the entry from the owner-operator map

If that map becomes empty, it is removed from the root map. Returns the old allowance

pub fn set_allowance<BS: Blockstore>( &mut self, bs: &BS, owner: ActorID, operator: ActorID, amount: &TokenAmount, ) -> Result<TokenAmount, StateError>

Set the allowance between owner and operator to a specific amount, returning the old allowance

pub fn attempt_use_allowance<BS: Blockstore>( &mut self, bs: &BS, operator: u64, owner: u64, amount: &TokenAmount, ) -> Result<TokenAmount, StateError>

Atomically checks if value is less than the allowance and deducts it if so

Returns new allowance if successful, else returns an error and the allowance is unchanged

pub fn get_owner_allowance_map<'bs, BS: Blockstore>( &self, bs: &'bs BS, owner: ActorID, ) -> Result<Option<Hamt<&'bs BS, TokenAmount, BytesKey>>, StateError>

Get the allowances map of a specific actor, resolving the CID link to a Hamt

Ok(Some) if the owner has allocated allowances to other actors Ok(None) if the owner has no current non-zero allowances to other actors Err if operations on the underlying Hamt failed

pub fn get_allowances_map<'bs, BS: Blockstore>( &self, bs: &'bs BS, ) -> Result<Hamt<&'bs BS, Cid, BytesKey>, StateError>

Get the global allowances map

Gets a HAMT with CIDs linking to other HAMTs

impl TokenState

pub fn check_invariants<BS: Blockstore>( &self, bs: &BS, granularity: u64, ) -> (StateSummary, Vec<StateInvariantError>)

Checks that the current state obeys all system invariants

Checks that there are no zero balances, zero allowances or empty allowance maps explicitly stored in the blockstore. Checks that balances, total supply, allowances are never negative. Checks that sum of all balances matches total_supply. Checks that no allowances are stored where operator == owner. Checks that all balances are a multiple of the granularity.

Returns a state summary that can be used to check application specific invariants and a list of errors that were found.

Trait Implementations

impl Clone for TokenState

fn clone(&self) -> TokenState

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TokenState

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for TokenState

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for TokenState

fn eq(&self, other: &TokenState) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for TokenState

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for TokenState

impl StructuralPartialEq for TokenState