Токены

Назначение смарт-контракта cyber.token

Системный смарт-контракт cyber.token предоставляет функции по управлению токенами, генерирует новые токены и хранит информацию о созданных токенах, предоставляет возможность проводить взаиморасчеты между аккаунтами.

В состав смарт-контракта cyber.token входят следующие операции-действия: create, issue, retire, transfer, bulktransfer, payment, bulkpayment, claim, open и close.

Операция-действие create

Операция-действие create используется для создания токена для обращения его в системе. Операция-действие create имеет следующий вид:

[[eosio::action]] void create(
    name   issuer,
    asset  maximum_supply
);

Параметры:

• issuer — имя аккаунта, который станет владельцем (издателем) создаваемого токена в системе;

• maximum_supply — максимально возможное количество поставляемых токенов, тип asset, содержит поля:

  • целочисленное количество токена;

  • символ токена (тип данных, однозначно определяющий токен):

    • код символа — имя токена, состоящее из набора прописных букв;

    • поле, задающее точность стоимости токена в виде количества знаков после запятой.

Аккаунт issuer наделяется правами по выпуску и изъятию из обращения токенов. Нельза создать 2 и более токена с одинаковым кодом символа. Права на выполнение операции-действия create имеются только у смарт-контракта cyber.token. Для выполнения данной операции-действия необходима подпись валидаторов.

Операция-действие issue

Операция-действие issue используется для выпуска в обращение заданного количества токенов. Операция-действие issue имеет следующий вид:

[[eosio::action]] void issue(
    name to,  
    asset quantity,  
    string memo
);

Параметры:

• to — имя аккаунта, на баланс которого поступает токен;

• quantity — количество выпускаемых в обращение токенов, тип asset:

• memo — примечание, текст которого дополняет смысловое значение выпуска токена (например, эмиссия токена). Количество символов в строке не должно превышать 384 шт.

При выполнении операции-действия create в таблицу записывается символ токена и имя аккаунта issuer. При выполнении операции-действия issue из полученного значения quantity берется символ токена и по нему, используя табличные данные, определяется аккаунт issuer. Правами на выполнение операции-действия обладает аккаунт issuer. Общее количество выпущенных токенов не должно превышать значение maximum_supply, заданного в операции-действия create. За использование ресурсов bandwidth (RAM) взимается плата c аккаунта issuer.

Операция-действие retire

Операция-действие retire используется для изъятия из обращения определенного количества токенов в системе. Операция-действие retire имеет следующий вид:

[[eosio::action]] void retire(
    asset quantity,
    string memo
);

Параметры:

• quantity — количество изымаемых из обращения токенов, тип asset;

• memo — строка, поясняющая изъятие средств. Длина строки не более 384 символов.

Правами запуска операции-действия обладает аккаунт issuer. Указанное в операции-действия количество изымаемых из обращения токенов также снимается с баланса аккаунта issuer, поэтому он не может изъять из обращения токенов больше, чем имеется на его балансе.

Операция-действие transfer

Операция-действие transfer используется для передачи токена с баланса одного аккаунта на баланс другого. Операция-действие transfer имеет следующий вид:

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

Параметры:

• from — имя аккаунта-отправителя, с баланса которого снимаются токены;

• to — имя аккаунта-получателя, на баланс которого поступают токены;

• quantity — количество переводимых токенов, тип asset. Количество токенов должно быть больше нуля;

  memo — примечание, уточняющее цель перевода токенов. Длина строки не более 384 символов.

Операция-действие выполняется с отправкой уведомления на смарт-контракты отправителя и получателя токенов. Операция отправки уведомления имеет вид аналогичный операции-действия transfer. Отличие состоит в том, что операция отправки уведомления выполняется не на смарт-контракте cyber.token, а на контрактах отправителя и получателя уведомления (например, если смарт-контракт vesting получает уведомление, он автоматически начисляет токены на баланс vesting). Для отправки токенов аккаунт должен быть наделен правами отправителя.

За использование ресурсов bandwidth (RAM) плата взимается либо с аккаунта-отправителя, либо с аккаунта-получателя в зависимости от того, кто подписал транзакцию. В случае, если предварительно была выполнена операция-действие open, никто из них не оплачивает bandwidth, так как используется уже созданная в БД запись.

Примечание

Раньше в EOS при пересылке токенов создавалась запись в БД для хранения баланса пользователя для случая, когда у получателя не было в наличии токена. Если аккаунт-отправитель оплачивал используемые ресурсы (RAM) за аккаунта-получателя, то существовала возможность расхода всей выделенной доли памяти аккаунту-получателю. С целью недопущения подобных случаев при выполнении операции-действия transfer было принято решение ввести дополнительные операции-действия open и close. Функциональное назначение данных операций — предварительное создание записи в БД, чтобы запись создавалась не во время выполнения операции-действия transfer, а также ее удаление.

Операция-действие bulktransfer

Операция-действие bulktransfer используется для трансфера токенов с баланса одного аккаунта на балансы нескольких аккаунтов (например, для выплаты вознаграждений за пост). Операция-действие bulktransfer имеет следующий вид:

[[eosio::action]] void bulktransfer(
    name from,
    vector<recipient> recipients
)

Параметры:

• from — имя аккаунта-отправителя, с баланса которого снимаются токены;

• recipients — массив (перечень) получателей токенов. Каждый элемент массива является структурой, содержащей поля:

  • to — имя аккаунта, на баланс которого переводятся токены;

  • quantity — количество токенов, переводимых на баланс аккаунта to. Количество токенов должно быть больше нуля;

  • memo — примечание, уточняющее цель перевода токенов. Длина строки memo не должна превышать 384 символов.

Ограничения на выполнение операции-действия bulktransfer:

• трансфер токенов различного вида не допускается;

• трансфер токенов самому себе не допускается, то есть перечень получателей токенов recipients не должен содержать имя аккаунта from;

• количество переводимых токенов должно быть больше нуля для каждого аккаунта.

Допускается в перечне recipients указывать одно и то же имя аккаунта to более одного раза. Операция-действие выполняется с отправкой уведомления на смарт-контракты отправителя и получателя токенов аналогично выполнению transfer.

Для выполнения операции-действия bulktransfer требуется подпись аккаунта from.

Операция-действие payment

Операция-действие payment также как и операция-действие transfer используется для перечисления средств от одного аккаунта другому.

Операция-действие payment имеет следующий вид:

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

Параметры:

• from — имя аккаунта-отправителя, с баланса которого снимаются токены;

• to — имя аккаунта-получателя токенов;

• quantity — количество перечисляемых токенов аккаунту to. Количество токенов должно быть больше нуля;

• memo — примечание, уточняющее цель перевода токенов. Длина строки memo не должна превышать 384 символов.

В отличие от transfer при выполнении операции-действия payment отправка уведомлений не происходит и средства поступают не на ликвидный баланс аккаунта-получателя, а на отдельный payment-баланс. Для пересылки средств с баланса-посредника payment на баланс аккаунта-получателя to дополнительно требуется выполнить операцию-действие claim.

Операция-действие payment является более надёжным вариантом трансфера токенов, т.к. не отправляются уведомления, которые могли бы завершиться ошибкой и прервать трансфер. Для ее выполнения требуется подпись аккаунта from.

Операция-действие bulkpayment

Операция-действие bulkpayment также как и операция-действие bulktransfer используется для перечисления средств от одного аккаунта нескольким другим аккаунтам (например, для выплаты вознаграждений кураторам и бенефициарам за пост). Операция-действие имеет вид:

[[eosio::action]] void bulkpayment(
    name from,
    vector<recipient> recipients
)

Параметры:

• from — имя аккаунта-отправителя, с баланса которого снимаются токены;

• recipients — массив (перечень) получателей токенов. Каждый элемент массива является структурой, содержащей поля:

  • to — имя аккаунта-получателя токенов;

  • quantity — количество перечисляемых токенов аккаунту to. Количество токенов должно быть больше нуля;

  • memo — примечание, уточняющее цель перевода токенов. Длина строки memo не должна превышать 384 символов.

Ограничения на выполнение операции-действия bulkpayment:

• трансфер токенов различного вида не допускается;

• трансфер токенов самому себе не допускается, то есть перечень получателей токенов recipients не должен содержать имя аккаунта from.

В отличие от bulktransfer при выполнении операции-действия bulkpayment отправка уведомлений не происходит, и средства поступают на дополнительный payment-баланс аккаунта-получателя. Для пересылки средств с баланса-посредника payment на основной (ликвидный) баланс аккаунта-получателя to дополнительно требуется выполнить операцию-действие claim.

Операция-действие bulkpayment является более надёжным вариантом трансфера токенов. Для ее выполнения требуется подпись аккаунта from.

Операция-действие claim

Операция-действие claim используется для перевода средств с баланса payment на основной баланс аккаунта. Операция-действие имеет вид:

[[eosio::action]] void claim(
    name owner,
    asset quantity
)

Параметры:

• owner — имя аккаунта, на балансах которого совершается перевод;

• quantity — запрашиваемое количество токенов для перевода. Это количество должно быть больше 0 и не должно превышать количество токенов, находящихся на балансе payment, собственником которых является аккаунт owner.

Для выполнения операции-действия claim требуется подпись аккаунта owner.

Операция-действие open

Операция-действие open создаёт запись в БД для хранения баланса аккаунта для заданного токена. Операция-действие open имеет следующий вид:

[[eosio::action]] void open(
    name owner,
    symbol symbol,
    name ram_payer
);

Параметры:

• owner — имя аккаунта, которому выделяется память;

• symbol — символ токена, для которого создается запись;

• ram_payer — имя аккаунта, который оплачивает используемую память.

Выполнение операции-действия open требует подписи аккаунта ram_payer.

Операция-действие close

Операция-действие close является обратным действием по отношению к open и используется для освобождение выделенной памяти в БД. Для выполнения данной операции-действия требуется наличие нулевого баланса токена (определяемого символом) у аккаунта. Операция-действие close имеет следующий вид:

[[eosio::action]] void close(
    name owner,
    symbol symbol
);

Параметры:

• owner — имя аккаунта, баланс которого удаляется;

• symbol — символ, для которого удаляется запись.

Для выполнения close требуется наличие нулевых балансов указанного токена у аккаунта owner:

• нулевой основной баланс;

• нулевой payment баланс.

Получение статистической информации по системным токенам

Для получения статистической информации по токенам в смарт-контракте cyber.token используются две таблицы currency_stats и account.

currency_stats

Запись в таблице currency_stats имеет следующий вид:

struct [[eosio::table]] currency_stats {
    asset supply;
    asset max_supply;
    name issuer;
};

Параметры:

• supply — количество токенов определенного вида в обращении, тип asset;

• max_supply — максимально возможное количество в обращении токенов определенного вида, тип asset;

• issuer — имя аккаунта, выпустившего токены.

Первичным ключом для таблицы currency_stats является символьное значение в asset, по которому определяется токен. По токену определяется значение supply — количество выпущенных в обращение токенов, а также имя аккаунта, выпустившего токены.

account

Записи в таблице account имеет следующий вид:

struct [[eosio::table]] account {
    asset balance;
    asset payments;
};

Параметры:

• balance — количество токенов на основном (ликвидном) балансе пользователя, тип asset;

• payments — количество токенов на payment-балансе (переводятся на основной с помощью claim), тип asset;

Область видимости таблицы определяется именем аккаунта, владеющего соответствующим балансом.