golos.ctrl_contract.md

Смарт-контракт golos.ctrl

Смарт-контракт golos.ctrl содержит логику выбора делегатов, в том числе процедуру регистрации аккаунта как делегата, процедуру голосования за делегата, а также определение списка наиболее рейтинговых делегатов.

Общее

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

Также смарт-контракты имеют возможность получать список наиболее рейтинговых (верхушки) делегатов и соответствующие им значения полномочий. Это позволяет проверять достоверность заверенных делегатами действий.

Параметры, устанавливаемые в смарт-контракте golos.ctrl

ctrl_param, types: [
    symbol_code ctrl_token,
    name multisig_acc,
    uint16_t max_witnesses,
    struct multisig_perms (
        uint16_t super_majority,
        uint16_t majority,
        uint16_t minority
    ), 
    uint16_t max_witness_votes,
    struct update_auth (
        uint32_t period
    )
]

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

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

multisig_acc — имя аккаунта. Авторизация данного аккаунта изменяется при каждом изменении верхушки списка делегатов;
max_witnesses — максимально допустимое количество делегатов, которое может принимать решение (подписывать транзакции) от имени сообщества. Перечень таких делегатов содержит multisig_acc;
multisig_perms — необходимое количество подписей от верхушки делегатов, дающее разрешение (англ. permission) на выполнение действий от имени делегатов сообщества. В зависимости от важности параметра на его изменение требуется соответствующий уровень разрешения. Имеется три уровня разрешения:

• super_majority — высокий уровень разрешения, на получение которого требуется не менее «двух третей плюс один» голосов верхушки списка делегатов (устанавливается по умолчанию);
• majority — средний уровень разрешения, на получение которого требуется не менее «половины плюс один» голосов верхушки списка делегатов (устанавливается по умолчанию);
• minor_majority — низкий уровень разрешения, на получение которого требуется не менее «одной трети плюс один» голосов верхушки списка делегатов (устанавливается по умолчанию);

max_witness_votes — максимально допустимое количество делегатов, за которое может проголосовать пользователь сообщества;
update_auth — параметр, определяющий частоту обновления авторизации для аккаунта multisig_acc:

• period — период обновления (в секундах). Повторная смена авторизации для аккаунта не выполняется, если с момента последнего обновления не прошло указанное количество секунд.

Экшен-операции, применяемые в смарт-контракте golos.ctrl

Экшен-операция setparams

Экшен-операция setparams используется для настройки параметров смарт-контракта golos.ctrl. Экшен-операция имеет следующий вид:

void control::setparams(vector<ctrl_param> params)

Параметр params — значение в виде структуры, содержащей поля с настраиваемыми параметрами.

Экшен-операция validateprms

Экшен-операция validateprms проверяет параметры на валидность, контролирует наличие в них ошибок. Экшен-операция validateprms вызывается смарт-контрактом, имеет следующий вид:

void control::validateprms(vector<ctrl_param> params)

Параметр params — значение в виде структуры, содержащей проверяемые параметры.

Экшен-операция regwitness

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

void control::regwitness(
    name witness,
    string url
)

Параметры:
witness — имя кандидата в делегаты сообщества;
url — адрес веб-сайта, откуда можно получить информацию о кандидате в делегаты, в том числе о мотивах, по которым он изъявил желание стать делегатом. Длина строки адреса не должна превышать 256 символов.

Выполнение экшен-операции regwitness требует подписи самого кандидата в делегаты witness.

Экшен-операция unregwitness

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

void control::unregwitness(name witness)

Параметр witness — имя пользователя, которое необходимо удалить из числа зарегистрированных в кандидаты делегатов.

Выполнение экшен-операции regwitness требует подписи самого кандидата в делегаты witness. Вызвать regwitness может как сам кандидат в делегаты (в случае самоотвода), так и делегат, усмотревший какое-либо несоответствие возможностей кандидата в делегаты желаемым требованиям к делегату, а также несоответствие данных, опубликованных на веб-сайте, его актуальным данным.

Экшен-операция votewitness

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

void control::votewitness(
    name voter,
    name witness
)

Параметры:
voter — имя аккаунта, голосующего за кандидата в делегаты;
witness — имя кандидата в делегаты, за которого отдается голос.

Выполнение экшен-операции votewitness требует подписи аккаунта voter.

Ограничения:

• имя кандидата в делегаты witness предварительно должно быть зарегистрировано через вызов regwitness;
• количество голосов, отданных аккаунтом voter за кандидаты в делегаты, не должно превышать значение параметра max_witness_votes.

Экшен-операция unvotewitn

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

void control::unvotewitn(
    name voter,
    name witness
)

Параметры:
voter — имя аккаунта, который намеревается снять свой ранее отданный голос за кандидата в делегаты;
witness — имя кандидата в делегаты, у которого снимается ранее отданный за него голос.

Выполнение экшен-операции unvotewitn требует подписи аккаунта voter.

Экшен-операция changevest

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

void control::changevest(
    name who,
    asset diff
)

Параметры:
who — имя аккаунта, на балансе которого изменилась сумма вестинга;
diff — количество относительного изменения вестинга.

Вызов экшен-операции changevest происходит автоматически при изменении суммы вестинга на балансе каждого из пользователей. Смарт-контракт вестинг информирует об этом изменении смарт-контракт управления. Поскольку сумма вестинга на балансе пользователя влияет на вес голоса этого пользователя, то рейтинг делегата, за которого проголосовал этот пользователь, также будет зависеть от вестинга этого пользователя. Смарт-контракт управления корректирует рейтинг среди верхушки делегатов с учетом полученной информации об изменении. Данные таблицы смарт-контракта вестинга при этом не модифицируются.
При изменении списка верхушки делегатов также автоматически изменяется их авторизация.