Trait gear_common::gas_provider::Tree

pub trait Tree {
    type ExternalOrigin;
    type NodeId: Clone;
    type Balance: Clone;
    type Funds: Clone;
    type PositiveImbalance: Imbalance<Balance = Self::Balance>;
    type NegativeImbalance: Imbalance<Balance = Self::Balance>;
    type InternalError: Error;
    type Error: From<Self::InternalError>;

    // Required methods
    fn total_supply() -> Self::Balance;
    fn create(
        origin: Self::ExternalOrigin,
        multiplier: GasMultiplier<Self::Funds, Self::Balance>,
        key: impl Into<Self::NodeId>,
        amount: Self::Balance
    ) -> Result<Self::PositiveImbalance, Self::Error>;
    fn get_origin_node(
        key: impl Into<Self::NodeId>
    ) -> Result<OriginNodeDataOf<Self>, Self::Error>;
    fn get_limit_node(
        key: impl Into<Self::NodeId>
    ) -> Result<(Self::Balance, Self::NodeId), Self::Error>;
    fn get_limit_node_consumed(
        key: impl Into<Self::NodeId>
    ) -> Result<(Self::Balance, Self::NodeId), Self::Error>;
    fn consume(key: impl Into<Self::NodeId>) -> ConsumeResultOf<Self>;
    fn spend(
        key: impl Into<Self::NodeId>,
        amount: Self::Balance
    ) -> Result<Self::NegativeImbalance, Self::Error>;
    fn split_with_value(
        key: impl Into<Self::NodeId>,
        new_key: impl Into<Self::NodeId>,
        amount: Self::Balance
    ) -> Result<(), Self::Error>;
    fn split(
        key: impl Into<Self::NodeId>,
        new_key: impl Into<Self::NodeId>
    ) -> Result<(), Self::Error>;
    fn cut(
        key: impl Into<Self::NodeId>,
        new_key: impl Into<Self::NodeId>,
        amount: Self::Balance
    ) -> Result<(), Self::Error>;
    fn create_deposit(
        key: impl Into<Self::NodeId>,
        new_key: impl Into<Self::NodeId>,
        amount: Self::Balance
    ) -> Result<(), Self::Error>;
    fn exists(key: impl Into<Self::NodeId>) -> bool;
    fn exists_and_deposit(key: impl Into<Self::NodeId>) -> bool;
    fn clear();

    // Provided methods
    fn get_external(
        key: impl Into<Self::NodeId>
    ) -> Result<Self::ExternalOrigin, Self::Error> { ... }
    fn get_funds_multiplier(
        key: impl Into<Self::NodeId>
    ) -> Result<GasMultiplier<Self::Funds, Self::Balance>, Self::Error> { ... }
    fn get_origin_key(
        key: impl Into<Self::NodeId>
    ) -> Result<Self::NodeId, Self::Error> { ... }
    fn get_limit(
        key: impl Into<Self::NodeId>
    ) -> Result<Self::Balance, Self::Error> { ... }
    fn get_limit_consumed(
        key: impl Into<Self::NodeId>
    ) -> Result<Self::Balance, Self::Error> { ... }
}

Abstraction for a chain of value items each piece of which has an attributed owner and can be traced up to some root origin.

The definition is largely inspired by the frame_support::traits::Currency, however, the intended use is very close to the UTxO based ledger model.

Required Associated Types

type ExternalOrigin

Type representing the external owner of a value (gas) item.

type NodeId: Clone

Type that identifies a node of the tree.

type Balance: Clone

Type representing a quantity of value.

type Funds: Clone

Type representing a quantity of token balance.

type PositiveImbalance: Imbalance<Balance = Self::Balance>

Types to denote a result of some unbalancing operation - that is operations that create inequality between the underlying value supply and some hypothetical “collateral” asset. PositiveImbalance indicates that some value has been added to circulation , i.e. total supply has increased.

type NegativeImbalance: Imbalance<Balance = Self::Balance>

NegativeImbalance indicates that some value has been removed from circulation, i.e. total supply has decreased.

type InternalError: Error

type Error: From<Self::InternalError>

Error type

Required Methods

fn total_supply() -> Self::Balance

The total amount of value currently in circulation.

fn create( origin: Self::ExternalOrigin, multiplier: GasMultiplier<Self::Funds, Self::Balance>, key: impl Into<Self::NodeId>, amount: Self::Balance ) -> Result<Self::PositiveImbalance, Self::Error>

Increase the total issuance of the underlying value by creating some amount of it and attributing it to the origin.

The key identifies the created “bag” of value. In case the key already identifies some other piece of value an error is returned.

fn get_origin_node( key: impl Into<Self::NodeId> ) -> Result<OriginNodeDataOf<Self>, Self::Error>

The id of node, external origin and funds multiplier for a key.

Error occurs if the tree is invalidated (has “orphan” nodes), and the node identified by the key belongs to a subtree originating at such “orphan” node, or in case of inexistent key.

fn get_limit_node( key: impl Into<Self::NodeId> ) -> Result<(Self::Balance, Self::NodeId), Self::Error>

Get value associated with given id and the key of an ancestor, that keeps this value.

Error occurs if the tree is invalidated (has “orphan” nodes), and the node identified by the key belongs to a subtree originating at such “orphan” node, or in case of inexistent key.

fn get_limit_node_consumed( key: impl Into<Self::NodeId> ) -> Result<(Self::Balance, Self::NodeId), Self::Error>

Get value associated with given id and the key of an consumed ancestor, that keeps this value.

Error occurs if the tree is invalidated (has “orphan” nodes), and the node identified by the key belongs to a subtree originating at such “orphan” node, or in case of inexistent key.

fn consume(key: impl Into<Self::NodeId>) -> ConsumeResultOf<Self>

Consume underlying value.

If key does not identify any value or the value can’t be fully consumed due to being a part of other value or itself having unconsumed parts, return None, else the corresponding piece of value is destroyed and imbalance is created.

Error occurs if the tree is invalidated (has “orphan” nodes), and the node identified by the key belongs to a subtree originating at such “orphan” node, or in case of inexistent key.

fn spend( key: impl Into<Self::NodeId>, amount: Self::Balance ) -> Result<Self::NegativeImbalance, Self::Error>

Burn underlying value.

This “spends” the specified amount of value thereby decreasing the overall supply of it. In case of a success, this indicates the entire value supply becomes over-collateralized, hence negative imbalance.

fn split_with_value( key: impl Into<Self::NodeId>, new_key: impl Into<Self::NodeId>, amount: Self::Balance ) -> Result<(), Self::Error>

Split underlying value.

If key does not identify any value or the amount exceeds what’s locked under that key, an error is returned.

This can’t create imbalance as no value is burned or created.

fn split( key: impl Into<Self::NodeId>, new_key: impl Into<Self::NodeId> ) -> Result<(), Self::Error>

Split underlying value.

If key does not identify any value an error is returned.

This can’t create imbalance as no value is burned or created.

fn cut( key: impl Into<Self::NodeId>, new_key: impl Into<Self::NodeId>, amount: Self::Balance ) -> Result<(), Self::Error>

Cut underlying value to a reserved node.

If key does not identify any value or the amount exceeds what’s locked under that key, an error is returned.

This can’t create imbalance as no value is burned or created.

fn create_deposit( key: impl Into<Self::NodeId>, new_key: impl Into<Self::NodeId>, amount: Self::Balance ) -> Result<(), Self::Error>

Creates deposit external node to be used as pre-defined gas node.

fn exists(key: impl Into<Self::NodeId>) -> bool

Return bool, defining does node exist.

fn exists_and_deposit(key: impl Into<Self::NodeId>) -> bool

Returns bool, defining does node exist and is external with deposit.

fn clear()

Removes all values.

Provided Methods

fn get_external( key: impl Into<Self::NodeId> ) -> Result<Self::ExternalOrigin, Self::Error>

The external origin for a key.

See get_origin_node for details.

fn get_funds_multiplier( key: impl Into<Self::NodeId> ) -> Result<GasMultiplier<Self::Funds, Self::Balance>, Self::Error>

The funds multiplier for a key.

See get_origin_node for details.

fn get_origin_key( key: impl Into<Self::NodeId> ) -> Result<Self::NodeId, Self::Error>

The id of external node for a key.

See get_origin_node for details.

fn get_limit(key: impl Into<Self::NodeId>) -> Result<Self::Balance, Self::Error>

Get value associated with given id.

See get_limit_node for details.

fn get_limit_consumed( key: impl Into<Self::NodeId> ) -> Result<Self::Balance, Self::Error>

Get value associated with given id within consumed node.

See get_limit_node_consumed for details.

Object Safety

This trait is not object safe.

Implementors

impl<TotalValue, Balance, Funds, InternalError, Error, ExternalId, NodeId, StorageMap> Tree for TreeImpl<TotalValue, InternalError, Error, ExternalId, NodeId, StorageMap>

where Balance: BalanceTrait, Funds: Clone, TotalValue: ValueStorage<Value = Balance>, InternalError: Error, Error: From<InternalError>, ExternalId: Clone, NodeId: Copy, StorageMap: MapStorage<Key = NodeId, Value = GasNode<ExternalId, NodeId, Balance, Funds>>,

type ExternalOrigin = ExternalId

type NodeId = NodeId

type Balance = Balance

type Funds = Funds

type PositiveImbalance = PositiveImbalance<Balance>

type NegativeImbalance = NegativeImbalance<Balance>

type InternalError = InternalError

type Error = Error