eosio / eosio.token

Reference contract for an EOSIO based token

eosio.token

Version : 2.0.0-rc1

The design of the EOSIO blockchain calls for a number of smart contracts that are run at a privileged permission level in order to support functions such as block producer registration and voting, token staking for CPU and network bandwidth, RAM purchasing, multi-sig, etc. These smart contracts are referred to as the bios, boot, system, msig, wrap (formerly known as sudo) and token contracts.

This repository contains a reference token example contracts that are useful when deploying a token using an EOSIO blockchain. It is provided for reference purposes:

The following unprivileged contract(s) are in this repository.

• eosio.token

Dependencies:

• eosio.cdt v1.8.x
• eosio v2.1.x (optional dependency only needed to build unit tests)

Build

To build the contracts follow the instructions in Build and deploy section.

Contributing

Contributing Guide

Code of Conduct

License

MIT

The included icons are provided under the same terms as the software and accompanying documentation, the MIT License. We welcome contributions from the artistically-inclined members of the community, and if you do send us alternative icons, then you are providing them under those same terms.

Important

See LICENSE for copyright and license terms.

All repositories and other materials are provided subject to the terms of this IMPORTANT notice and you must familiarize yourself with its terms. The notice contains important information, limitations and restrictions relating to our software, publications, trademarks, third-party resources, and forward-looking statements. By accessing any of our repositories and other materials, you accept and agree to the terms of the notice.

eosio.token's Issues

[feature/standartization] Transfer with fee

Sometimes business model for token smart contract want have fee from token transfer. We need standard interface how to do transfer with fee, count fees, inform receiver/sender from transaction payload, which will be used in blockchain history solution such as Hyperion, Chronicle, dfuse etc.

One of possible signature and realization for fee = 1% * quantity:

      * Allows `from` account to transfer to `to` account the `quantity - fee` tokens.
      * One account is debited, smart contract account is credited with fee tokens and the `to` account is credited with quantity - fee tokens.
      *
      * @param from - the account to transfer from,
      * @param to - the account to be transferred to,
      * @param quantity - the quantity of tokens to be transferred,
      * @param fee - the quantity of tokens to be paid as commission,
      * @param memo - the memo string to accompany the transaction.

      [[eosio::action]] void transfer(const name& from, const name& to, const asset& quantity, const asset& fee, const string&  memo);

void token::transfer( const name& from,
                      const name& to,
                      const asset& quantity,
                      const asset& fee,
                      const string&  memo )
{
    check( from != to, "cannot transfer to self" );
    require_auth( from );
    check( is_account( to ), "to account does not exist");
    auto sym = quantity.symbol.code();
    stats statstable( get_self(), sym.raw() );
    const auto& st = statstable.get( sym.raw() );

    require_recipient( from );
    require_recipient( to );

    check( quantity.is_valid(), "invalid quantity" );
    check( fee.is_valid(), "invalid fee" );
    check( quantity.amount > 0, "must transfer positive quantity" );
    check( quantity.amount > 1, "can not transfer minimum amount");
    check( quantity.symbol == st.supply.symbol, "symbol precision mismatch" );
    check( fee.symbol == quantity.symbol, "fee symbol precision mismatch" );
    check( is_valid_fee(fee), "invalid fee quantity" );
    check( memo.size() <= 256, "memo has more than 256 bytes" );

    auto payer = has_auth( to ) ? to : from;

    sub_balance( from, quantity );
    add_balance( get_self(), fee, payer );
    add_balance( to, quantity - fee, payer );
}

bool token::is_valid_fee( const asset& quantity, const asset& fee )
{
      return fee == count_fee(quantity) ? true : false;
}

asset token::count_fee( const asset& quantity )
{
      return (quantity.amount > 100 ? asset(quantity.amount / 100, quantity.symbol) : asset(1, quantity.symbol));
}

So from transaction history we can calculate how much tokens received(quantity - fee).
Total fees received by summing all transfer transactions fee field.

make eosio.token inheritable

It should be possible to inherit from eosio.token class, so that new tokens would not have to just copy the token source code.

So, all flesh should be moved to a token.hpp inside eosiolib, and eosio.token.cpp should only have EOSIO_ABI call.

eosio::buyrambytes doesn't provide the exact amount requested

Original Issue:

https://github.com/EOSIO/eosio.contracts/issues/554

[feature/standartization] Transfer with fee

Original issue:

Sometimes business model for token smart contract want have fee from token transfer. We need standard interface how to do transfer with fee, count fees, inform receiver/sender from transaction payload, which will be used in blockchain history solution such as Hyperion, Chronicle, dfuse etc.

One of possible signature and realization for fee = 1% * quantity:

      * Allows `from` account to transfer to `to` account the `quantity - fee` tokens.
      * One account is debited, smart contract account is credited with fee tokens and the `to` account is credited with quantity - fee tokens.
      *
      * @param from - the account to transfer from,
      * @param to - the account to be transferred to,
      * @param quantity - the quantity of tokens to be transferred,
      * @param fee - the quantity of tokens to be paid as commission,
      * @param memo - the memo string to accompany the transaction.

      [[eosio::action]] void transfer(const name& from, const name& to, const asset& quantity, const asset& fee, const string&  memo);

void token::transfer( const name& from,
                      const name& to,
                      const asset& quantity,
                      const asset& fee,
                      const string&  memo )
{
    check( from != to, "cannot transfer to self" );
    require_auth( from );
    check( is_account( to ), "to account does not exist");
    auto sym = quantity.symbol.code();
    stats statstable( get_self(), sym.raw() );
    const auto& st = statstable.get( sym.raw() );

    require_recipient( from );
    require_recipient( to );

    check( quantity.is_valid(), "invalid quantity" );
    check( fee.is_valid(), "invalid fee" );
    check( quantity.amount > 0, "must transfer positive quantity" );
    check( quantity.amount > 1, "can not transfer minimum amount");
    check( quantity.symbol == st.supply.symbol, "symbol precision mismatch" );
    check( fee.symbol == quantity.symbol, "fee symbol precision mismatch" );
    check( is_valid_fee(fee), "invalid fee quantity" );
    check( memo.size() <= 256, "memo has more than 256 bytes" );

    auto payer = has_auth( to ) ? to : from;

    sub_balance( from, quantity );
    add_balance( get_self(), fee, payer );
    add_balance( to, quantity - fee, payer );
}

bool token::is_valid_fee( const asset& quantity, const asset& fee )
{
      return fee == count_fee(quantity) ? true : false;
}

asset token::count_fee( const asset& quantity )
{
      return (quantity.amount > 100 ? asset(quantity.amount / 100, quantity.symbol) : asset(1, quantity.symbol));
}

So from transaction history we can calculate how much tokens received(quantity - fee).
Total fees received by summing all transfer transactions fee field.

Modify eosio.token::transfer to require necessary table rows to already exist

token::add_balance would assert that the table row it finds (to) exists. That way a eosio.token::transfer would never charge RAM to any user (other than the loophole with notified contracts which is dealt with separately with the subjective fix in eos v1.2.3 and eventually with an objective fix that comes with a protocol upgrade).

This change in behavior would mean that it would no longer be possible to use a single eosio.token::transfer action to transfer some token to a recipient that does not have a table row associated with that token. Since the table rows already are not automatically removed when the balance reaches zero but instead requires an explicit close action, it should typically not be a problem except for the first time the token is being received.

To solve that bootstrapping problem, a new action eosio.token::open (see EOSIO/eosio.contracts#61) can be used to create the appropriate zero-balance table row at the expense of the payer that authorizes that open action.

It may be typical for the recipient themselves to pay for the initial RAM of opening that zero balance table row so that they can receive those tokens from others. However, some users or contracts may wish to pay for that cost themselves. For example, an unsolicited airdrop may prepend the transfer operation with the open action to ensure the airdrop goes through. An "airgrab" which wants to reduce RAM costs of the token issuer may instead require the user requesting the airgrab to first open the zero balance table row.

Add claim (or similarly named) function to token contract to pay for RAM

You should be able to transfer the account row's RAM ownership to yourself. Alternatively, we can change the open function to set payer to yourself if it was already opened.

@arhag if you accept to add this function to the token contract, let me know what you want to call it and I can do the PR myself.