Мультиподпись

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

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

В состав смарт-контракта cyber.msig входят операции-действия propose, approve, unapprove, cancel, exec, invalidate.

Используемая терминология

Транзакция мультиподписная (англ. multi-signature transaction) — транзакция, для выполнения которой необходимо получить разрешение (подпись) от одного и более аккаунтов (акторов), имена которых указываются в отдельном списке при ее формировании. В состав транзакции может входить одна и более операций. Транзакция отправляется в блокчейн только после получения необходимого для ее выполнения количества разрешений (подписей).

Актор мультиподписной транзакции — имя аккаунта, от которого необходимо получить разрешение на выполнении мультиподписной транзакции. В роли актора может выступать как отдельный пользователь, так и аккаунт компании. Давать разрешение от лица компании могут только доверенные ей пользователи, указанные при ее регистрации в системе, с определенным уровнем разрешения.

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

Уровень разрешения — значимость подписи (авторизация), которой наделяется аккаунт при регистрации. Авторизация имеет вид структуры, содержащей поля, однозначно идентифицирующие принадлежность подписи конкретному аккаунту с учетом его веса и ключа, которым проставляется подпись.

struct authority {
    uint32_t threshold = 0;
    std::vector<key_weight> keys;
    std::vector<permission_level_weight> accounts;
    std::vector<wait_weight> waits;
}

В зависимости от установленного в транзакции уровня разрешения количество подписей, необходимое для выполнения транзакции, может быть различным. Например, разрешение от лица компании с требуемым пороговым значением threshold=3 , будет считаться полученным, если подпись будет проставлена либо одним аккаунтом с таким же значением threshold, либо двумя аккаунтами со значениями «2» и «1», или тремя по «1».

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

propose

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

void multisig::propose(
    name proposer,
    name proposal_name,
    std::vector<permission_level> requested,
    transaction trx
 )

Параметры:

• proposer — имя аккаунта, автора мультиподписной транзакции.

• proposal_name — уникальное имя, присвоенное мультиподписной транзакции при ее создании. Данный параметр, в совокупности с параметром proposer, однозначно идентифицируют мультиподписную транзакцию.

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

• trx — предложенная на подписание транзакция.

Для вызова операции-действия propose требуется авторизация пользователя proposer.

Пример:

Аккаунты alice, bob и carol создали общий мультиподписной аккаунт multisig, для выполнения транзакций от имени которого достаточно 2 подписи из 3. Для работы с этим аккаунтом bob и alice решили использовать отдельные ключи, добавив их в разрешение msig. Теперь, чтоб отправить транзакцию в сеть, alice может предложить её на подписание, указав всех трёх участников (с требуемыми разрешениями) в списке requested:

cyber.msig::propose(
    alice,
    sendtofund,
    [alice@msig, bob@msig, carol@active],
    {actions:[{account:token, name:transfer, authorization:[multisig@active], …}], …}
)

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

approve

Операция-действие approve используется для отправки разрешения от аккаунта, входящего в список requested, на выполнение мультиподписной транзакции.

void multisig::approve(
    name proposer,
    name proposal_name,
    permission_level level,
    const eosio::binary_extension<eosio::checksum256>& proposal_hash
)

Параметры:

• proposer — имя аккаунта автора мультиподписной транзакции.

• proposal_name — уникальное имя, присвоенное мультиподписной транзакции при ее создании. Данный параметр, в совокупности с параметром proposer, однозначно идентифицируют мультиподписную транзакцию.

• level — разрешение, с помощью которого аккаунт дает свое согласие на выполнение предложенной на подписание транзакции.

• proposal_hash — необязательный параметр, «хэш-сумма» мультиподписной транзакции. Параметр используется для контроля появления изменений в мультиподписной транзакции с момента вызова propose. В случае несоответствия «хэш-сумм», указанной proposal_hash и полученной для входящей транзакции, разрешение level не выдается.

Для вызова операции-действия approve требуется авторизация аккаунта, указанного в параметре level.

Пример:

Для одобрения транзакции, предложенной alice, аккаунты-участники должны выполнить approve с указанным в propose разрешением и подписать транзакцию подписью, удовлетворяющей это разрешение. Для бо́льшей безопасности может быть использован параметр proposal_hash:

cyber.msig::approve(alice, sendtofund, alice@msig, hash)
cyber.msig::approve(alice, sendtofund, bob@msig)
cyber.msig::approve(alice, sendtofund, carol@active)

unapprove

Операция-действие unapprove используется аккаунтом, входящим в список requested, для отзыва ранее данного этим аккаунтом разрешения на выполнение мультиподписной транзакции в случае изменения решения.

void multisig::unapprove(
    name proposer,
    name proposal_name,
    permission_level level
)

Параметры:

• proposer — имя аккаунта, автора мультиподписной транзакции.

• proposal_name — уникальное имя, присвоенное мультиподписной транзакции при ее создании. Данный параметр, в совокупности с параметром proposer, однозначно идентифицируют мультиподписную транзакцию.

• level — разрешение, которое отзывается.

Для вызова операции-действия unapprove требуется авторизация аккаунта, указанного в параметре level.

Пример:

Для отзыва одобрения alice должна выполнить unapprove с указанным в propose разрешением и подписать транзакцию подписью, удовлетворяющей этому разрешению:

cyber.msig::unapprove(alice, sendtofund, alice@msig)

cancel

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

void multisig::cancel(
    name proposer,
    name proposal_name,
    name canceler
)

Параметры:

• proposer — имя аккаунта, автора мультиподписной транзакции.

• proposal_name — уникальное имя, присвоенное мультиподписной транзакции при ее создании. Данный параметр, в совокупности с параметром proposer, однозначно идентифицируют мультиподписную транзакцию.

• canceler — имя аккаунта, отменяющего ее выполнение.

На выполнение мультиподписной транзакции отводится определенное время. Если по истечении этого времени транзакция не завершается, она может быть отменена любым пользователем. Отменить мультиподписную транзакцию до истечения отведенного на ее выполнения время может только ее автор, например, после внесения в нее корректив. В этом случае параметр canceler будет совпадать с параметром proposer.

Для вызова операции-действия cancel требуется авторизация аккаунта, указанного в параметре canceler.

Пример:

В данный момент у транзакции есть 2 необходимые подписи, но alice передумала отправлять её в сеть (см. примеры выше). Как создатель предложенной транзакции, она может отменить транзакцию:

cyber.msig::cancel(alice, sendtofund, alice)

Истёкшую транзакцию может отменить любой пользователь, восстановив тем самым себе STORAGE:

cyber.msig::cancel(alice, sendtofund, anybody)

exec

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

void multisig::exec(
    name proposer,
    name proposal_name,
    name executer
)

Параметры:

• proposer — имя аккаунта, автора мультиподписной транзакции.

• proposal_name — уникальное имя, присвоенное мультиподписной транзакции при ее создании. Данный параметр, в совокупности с параметром proposer, однозначно идентифицируют мультиподписную транзакцию.

• executer — имя аккаунта, выполняющего мультиподписную транзакцию. В качестве аккаунта executer может выступать как актор, так и любой другой пользователь, который обеспечивает оплату используемых ресурсов. Транзакция выполняется, если она содержит необходимое количество разрешений.

Для вызова операции-действия exec требуется авторизация аккаунта, указанного в параметре executer.

Пример:

Если в предыдущем примере транзакция не была отменена, то она имеет необходимые 2 разрешения из 3, и её можно выполнить вызвав exec:

cyber.msig::exec(alice, sendtofund, bob)

invalidate

Операция-действие invalidate используется для аннулирования всех ранее выданных аккаунтом разрешений на выполнение мультиподписных транзакций. Действие распространяется на все предложенные транзакции, находящиеся на этапе голосования.

void multisig::invalidate(name account)

Параметры:

• account — имя аккаунта, чьи ранее выданные разрешения на выполнение мультиподписных транзакций должны быть признаны недействительными.

Вызов invalidate аннулирует все разрешения, выданные аккаунтом с именем account, на выполняемые в настоящий момент мультиподписные транзакции. Действие invalidate не распространяется на разрешения уже завершенных транзакций, а также на разрешения, которые будут выданы данным аккаунтом после вызова invalidate.

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

Для вызова операции-действия invalidate требуется авторизация аккаунта с именем account.

Пример:

carol стало известно, что её ключ похищен. Самое время отменить все предложенные транзакции (и сменить ключ):

cyber.msig::invalidate(carol)