VIZ Ledger Documentation

Русский

English
中文

Русский

English
中文

Appearance

Агент-доступ (HF15) ​

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

Типичные случаи: торговый бот, который ставит в прогнозных рынках; сервис, который делает выплаты переводами; ключ, который внешний сервис (например vizhub) принимает для входа и своих действий.

set_agent_permission_operation (ID 105) ​

Подпись: active аккаунта account. До HF15 отвергается.

ПолеТипОписание
accountaccount_name_typeПринципал
agent_namestringИмя агента, уникально у принципала; [a-z0-9_-], непустое
agent_keypublic_key_typeКлюч агента; обязателен при выдаче, при отзыве не проверяется
operationsflat_set<string>Wire-имена операций, которые может подписывать ключ (transfer, pm_place_bet, …)
expirationtime_point_sec1970-01-01T00:00:00 = бессрочно; время в прошлом = отзыв
addonsflat_set<string>Метки для внешних сервисов (напр. vizhub); до 10 штук, каждая короче 64 байт, без ,. Нода их хранит, но не толкует: в цепи они ничего не дают
extensionsextensions_typeВсегда []

Выдача (бот может ставить и переводить, vizhub принимает его ключ):

json
["set_agent_permission", {
  "account": "alice",
  "agent_name": "trade-bot",
  "agent_key": "VIZ6MyX5QiXAXRZk7SYCiqpi6Mtm8UbHWDFSV8HPpt7FJyahCnc2T",
  "operations": ["pm_place_bet", "transfer"],
  "expiration": "2027-01-01T00:00:00",
  "addons": ["vizhub"],
  "extensions": []
}]

Агент только с addons (ключ для внешнего сервиса, без операций цепи):

json
["set_agent_permission", {
  "account": "alice",
  "agent_name": "hub-login",
  "agent_key": "VIZ7…",
  "operations": [],
  "expiration": "1970-01-01T00:00:00",
  "addons": ["vizhub"],
  "extensions": []
}]

Отзыв — оба списка пусты (ключ можно передать нулевой VIZ1111111111111111111111111111111114T1Anm):

json
["set_agent_permission", {
  "account": "alice", "agent_name": "trade-bot",
  "agent_key": "VIZ1111111111111111111111111111111114T1Anm",
  "operations": [], "expiration": "1970-01-01T00:00:00", "addons": [], "extensions": []
}]

Повторная выдача по тому же имени заменяет ключ, операции, addons и срок (смена ключа = перевыдача).

Правила ​

  • Не делегируются никогда: set_agent_permission, proposal_update, account_update, recover_account, change_recovery_account, set_account_price, set_subaccount_price, target_account_sale. Виртуальные операции и устаревшие алиасы (писать validator_update, а не witness_update) отвергаются.
  • Один ключ — один агент: ключ, уже привязанный к другому имени того же принципала, отвергается.
  • Не больше 16 агентов на принципала. Выдача сначала удаляет его истёкших агентов.
  • Дополнительные возможности, не исправления: явная выдача разрешает прямые требования active и regular. Область проверяется по операции и принципалу: агент Alice с transfer не обязан иметь custom Bob, подписанный отдельно; собственная невыданная операция Alice запрещена. Сначала проверяются обычные полномочия, включая master; лишние подписи по-прежнему отвергаются. Смешивать regular с active/master нельзя.
  • Без повышения полномочий: агент не заменяет master, произвольные other или вложенные account_auths. Его доказательство не становится одобрением аккаунта для другого требования транзакции.
  • Предложения: явно выданный proposal_create лишь сохраняет предложение, даже с невыданными внутренними операциями: одобрения пусты, ничего не исполняется. proposal_delete разрешает вето только с проверками requester существующего evaluator. proposal_update запрещён: подпись агента не создаёт постоянное одобрение предложения ни аккаунтом, ни ключом.
  • Отзыв при применении: только агентские доказательства перепроверяются непосредственно перед соответствующей операцией. Предшествующий отзыв, ограничение списка, замена ключа или стирание агентов отменяет такое доказательство. Обычные полномочия проверяются на входе; привычная смена ключей с последующим использованием в той же транзакции сохраняется.
  • Удаление: все агенты принципала стираются при смене master, смене active, восстановлении аккаунта, прямой продаже и закрытии аукциона. Смена только regular их не трогает. «Смена» — это наличие поля в account_update: если в операции есть master или active, агенты стираются даже при том же ключе. Клиент, который правит только regular или memo, обязан не передавать master/active (в viz-php-lib build_account_update передайте null для роли, чтобы её не слать).

Чтение агентов ​

database_api.get_agent_permissions(account) — см. database_api.

get_potential_signatures возвращает ключи-кандидаты, включая обычный fallback к active/master и явно выданные ключи агентов; это не разрешение операции. get_required_signatures возвращает доступные подписи-вклады, даже если независимому аккаунту или явной authority ещё не хватает подписей. Уже подписанные ключи исключаются; ключ агента учитывается только при покрытии всех прямых требований своего аккаунта. Частичные обычные multisig-подписи сохраняются. Подбор подписей не означает принятие транзакции: verify_authority и применение по-прежнему требуют все полномочия и проверяют границы гранта.

В кошельках ​

Выдача (принципал). WebVIZWallet → Агенты: имя агента, публичный ключ (кнопка Сгенерировать создаёт новую пару — приватный ключ сохраните, он показывается один раз), галочки разрешённых операций, срок (бессрочно или дата), addons строкой через запятую. На странице — список текущих агентов с кнопкой Отозвать. Выдача подписывается active-ключом принципала. Vizonator даёт ту же операцию сайтам через window.vizonator, всегда через окно подтверждения с ключом, операциями, сроком и addons.

Вход агентом. В WebVIZWallet и Vizonator есть отдельный вход агентом: аккаунт принципала + приватный ключ агента. Клиент сверяет ключ с get_agent_permissions и отказывает, если ключ не выдан или срок истёк. Агентская сессия помечена 🤖, показывает разрешённые операции и оставшийся срок; недоступные действия заблокированы. Агентский ключ не проходит беспарольную авторизацию на сайтах и sign_data — он подписывает только выданные операции.

Когда агенты пропадают. Смена master или active (даже тем же ключом), восстановление и продажа аккаунта стирают всех агентов — после этого выдайте заново.

VIZ Ledger