Батарейка

Назначение смарт-контракта golos.charge

Смарт-контракт golos.charge выполняет прикладную функцию — позволяет ограничивать активность пользователей в создании постов, комментариев, а также в голосовании за посты. Непосредственного взаимодействия пользователя со смарт-контактом golos.charge не происходит, обращение к операциям-действиям происходит через смарт контракт публикации.

Принцип работы смарт-контракта golos.charge

Механизм, регулирующий активность пользователя в системе, реализован на основе батареек. Создание батареек позволяет вести учет как отдельных операций пользователя, так и его общую активность. Количество, выделенных пользователю батареек, может быть более одной, каждая из которых может быть настроена на учет одной из операций, выполняемых этим пользователем за определенный интервал времени (например, учет комментариев осуществляется одной батарейкой, отправка голосов в виде «upvote» — другой). При совершении операции расходуется часть ресурса (заряда) ассоциированной батарейки с учетом стоимости этой операции. Затем происходит полное или частичное восстановление этого ресурса. Количество восстановленного ресурса определяется формулой, заданной в настройках батарейки. Если обновленное значение потраченного ресурса превышает граничное значение — выполнение операции блокируется.

Обращение к батарейкам происходит через вызовы операций-действий. В смарт-контракте golos.charge реализованы операции-действия use, setrestorer, usenotifygt, usenotifylt. Доступ к текущему значению потраченного ресурса батарейки осуществляется при помощи встраиваемых (англ. inline) функций get_current_value и get_current_value.

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

Каждая батарейка идентифицируется кодом токена token_code и непосредственно идентификатором батарейки charge_id. У каждого токена может быть более одной батарейки. Конкретная батарейка конкретного токена задается параметром charge_id. Батарейка представляет собой значение, которое при использовании увеличивается и по истечении времени уменьшается, то есть восстанавливается.

use

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

[[eosio::action]] void use(
    name user,
    symbol_code token_code,
    uint8_t charge_id,
    int64_t price,
    int64_t cutoff,
    int64_t vesting_price
);

Параметры:

  • user — имя аккаунта, использующего ресурс батарейки;

  • token_code — код токена, имеющего привязку к батарейке;

  • charge_id — идентификатор батарейки. Данное значение в совокупности с кодом токена token_code обеспечивают идентификацию батарейки;

  • price — количество заряда, потребленного пользователем user, в результате выполнения текущей операции-действия;

  • cutoff — пороговое значение ресурса батарейки, при достижении которого прекращается выполнение действия;

  • vesting_price — сумма средств (в вестинге), которую необходимо потратить пользователю user за выполняемое им действие в случае нехватки ресурса батарейки, то есть в случае, если значение батарейки превысит пороговое значение cutoff (Внимание: в настоящем релизе параметр не используется и должен быть равен 0)

Любой из смарт-контрактов может обратиться к батарейке, но не напрямую, а через вызов операции-действия. В случае, если ресурс батарейки не удовлетворяет значению cutoff, смарт-контракт батарейки выдает соответствующее сообщение с блокировкой выполнения транзакции, в том числе действия, вызвавшего обращение к батарейке.

Для того, чтобы пользователь смог оплатить выполнение действия в случае нехватки ресурса батарейки, необходимо предоставить доступ смарт-контракту батарейки к средствам вестинга этого пользователя, а также право на «сжигание» соответствующей суммы. На балансе пользователя должна быть необходимая сумма вестинга в разблокированном состоянии (Внимание: в настоящем релизе эта функциональность отключена).

setrestorer

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

[[eosio::action]] void setrestorer(
    symbol_code token_code,
    uint8_t charge_id,
    std::string func_str, 
    int64_t max_prev,
    int64_t max_vesting,
    int64_t max_elapsed
);

Параметры:

  • token_code — код токена, имеющего привязку к батарейке;

  • charge_id — идентификатор батарейки. Данное значение в совокупности с кодом токена token_code обеспечивают идентификацию батарейки;

  • func_str — математическое выражение, задающее функцию восстановления ресурса батарейки;

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

  • max_vesting — максимальное значение вестинга, учитываемого функцией в качестве аргумента при восстановлении заряда;

  • max_elapsed — максимальный период времени, учитываемый с момента предыдущего обращения к батарейке.

Значение параметра func_str вычисляется задаваемой функцией с тремя переменными, а именно:

  • p — задает предыдущее значение ресурса батарейки;

  • v — задает значение вестинга пользователя. (Внимание: в настоящем релизе переменная не используется и не должна присутствовать в функуции);

  • t — задает период времени с момента последнего вызова setrestorer.

Например, если в качестве параметра func_str передается строка вида sqrt(v / 500000) × (t / 150) , то батарейка, идентифицируемая параметрами token_code и charge_id, будет восстанавливаться в соответствии с этой функцией. При наличии у пользователя суммы средств равной 500 000 (в вестинге) в течение периода 150 (с) значение func_str составит func_str = sqrt(500000 / 500000) × (150 / 150) = 1 То есть, за время 150 с значение батарейки увеличится на единицу.

usenotifygt и usenotifylt

Данные операции являются внутренними и пользователю недоступны.

Смысловые значения названий операций: usenotifygt — использовать ресурсы батарейки и нотифицировать, если заряд батарейки больше (англ. greater than) порогового значения. usenotifylt — использовать ресурсы батарейки и нотифицировать, если заряд батарейки меньше (англ. less than) порогового значения.

Обе операции используются для мониторинга активности пользователей и извещают передаваемый в качестве параметра смарт-контракт (например, golos.publication) о превышении допустимого уровня активности этих пользователей. Операция-действие usenotifygt отличается от usenotifylt условием, при котором отправляется нотификация.

Операция-действие usenotifygt имеет вид:

void usenotifygt(
    name user,
    symbol_code token_code,
    uint8_t charge_id,
    int64_t price_arg,
    int64_t id,
    name code,
    name action_name,
    int64_t cutoff
)

Параметры:

  • user — имя аккаунта владельца батарейки;

  • token_code — код токена, имеющего привязку к батарейке;

  • charge_id — идентификатор батарейки. Данное значение в совокупности с кодом токена token_code обеспечивают идентификацию батарейки;

  • price_arg — количество заряда, потребленного пользователем user, в результате выполнения текущей операции-действия;

  • id — внутренний идентификатор контракта code. Отправляется в нотификации наряду с именем пользователя и новым значением батарейки;

  • code — код контракта, которому высылается нотификация;

  • action_name — действие, которое обрабатывает нотификацию в контракте с кодом code;

  • cutoff — пороговое значение ресурса батарейки, при достижении которого необходимо отправить нотификацию.

Операция-действие usenotifylt имеет аналогичную структуру и параметры.

usenotifygt используется смарт-контрактом golos.publication для уменьшения вознаграждения за посты пользователей, превышающих установленный лимит на частоту публикаций. Перед публикацией поста смарт-контракт golos.publication отправляет операцию-действие usenotifygt контракту батарейки, указывая в качестве id идентификатор поста. В случае превышения порогового значения смарт-контракт батарейки информирует смарт-контракт golos.publication о текущем заряде пользователя. Получив соответствующую нотификацию, логика смарт-контракта публикации корректирует сумму вознаграждения за пост.

get_stored

Встраиваемая функция get_stored позволяет определить ресурс батарейки конкретного пользователя в конкретный момент времени. Встраиваемая функция get_stored имеет вид:

int64_t get_stored(
    name code,
    name user,
    symbol_code token_code,
    uint8_t charge_id,
    uint64_t stamp_id) {

}

Параметры:

  • code — идентификатор аккаунта;

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

  • token_code — код токена, имеющего привязку к батарейке;

  • charge_id — идентификатор батарейки. Данное значение в совокупности с кодом токена token_code обеспечивают идентификацию батарейки;

  • stamp_id — идентификатор сохраняемого значения ресурса батарейки charge_id, используемого аккаунтом user, которое требуется получить из таблицы батарейки.

Значение ресурса батарейки сохраняется в таблице батарейки при выполнении useandstore. Впоследствие для получения значения из данной таблицы необходимо вызвать get_stored. Вызов get_stored не требует дополнительной авторизации.

Данные о сохраненных значений ресурсов батареек доступны для получения из любого смарт-контракта. Функция get_stored не обрабатывает данные, а только получает сохраненные значения из таблиц смарт-контракта golos.charge.

Взаимодействие смарт-контракта батарейки с любым из смарт-контрактов позволяет контролировать действия (активность) пользователя в этих смарт-контрактах. Одна батарейка может взаимодействовать одновременно с действиями нескольких смарт-контрактов.

get_current_value

Встраиваемая функция get_current_value позволяет определить ресурс батарейки конкретного пользователя. Встраиваемая функция get_current_value имеет вид:

int64_t get_current_value( 
    name code, 
    name user, 
    symbol_code token_code, 
    uint8_t charge_id = 0);

Параметры:

  • code — имя аккаунта, на котором размещен контракт батарейки;

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

  • token_code — код токена, имеющего привязку к батарейке;

  • charge_id — идентификатор батарейки. Данное значение в совокупности с кодом токена token_code обеспечивают идентификацию батарейки;

Last updated