Токены

Назначение смарт-контракта 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 — значение, содержащее поля:

• максимально возможное количество поставляемых токенов;

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

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

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

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

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

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

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

Параметры: to — имя аккаунта, на баланс которого поступает токен; quantity — значение, содержащее поля:

• количество выпущенных в обращение токенов;

• символ токена:

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

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

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 — значение, содержащее поля:

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

• символ токена:

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

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

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

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

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

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

Параметры: from — имя аккаунта-отправителя, с баланса которого снимаются токены; to — имя аккаунта-получателя, на баланс которого поступают токены; quantity — значение в виде структуры, задающее количество переводимых токенов. Количество токенов должно быть больше нуля; memo — примечание, уточняющее цель перевода токенов.

Операция-действие выполняется с отправкой уведомления на смарт-контракты отправителя и получателя токенов. Операция отправки уведомления имеет вид аналогичный операции-действия 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 — запрашиваемое количество токенов для перевода. Это количество не должно превышать количество токенов, находящихся на балансе 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:

• нулевой баланс токена (определяется символом);

• нулевой платежный баланс.

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

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

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

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

Параметры: supply — значение в виде структуры с полями, показывающее количество токенов в обращении определенного вида; max_supply — значение в виде структуры с полями, показывающее максимально возможное количество в обращении токенов определенного вида; issuer — имя аккаунта, выпустившего токены.

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

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

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

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