# VKS API

VKS (Vilna Key Security) координирует согласование транзакций и их совместную подпись. Signer - программный узел, участвующий в формировании подписи. Его оператор управляет узлом и рассматривает запросы согласования. Состав узлов и правила их участия задаются в vault. Порядок действий описан в [руководстве первого подключения](/ru/guides/vks), схемы запросов и ответов - в [справочнике API](/ru/apis/vks/api).

`vks.vilna.io/v1`
VKS-ключ рабочего пространства
`vks:access`

VKS поддерживает подпись в mainnet и тестовых сетях EVM, Tron и Bitcoin. По [таблице сетей](/ru/apis/networks#vks) выберите совместимый формат блокчейн-аккаунта и узлы подписи.

## Лимиты ресурсов 

[Лимиты workspace](/ru/apis/vks/api/limits/get-limits) возвращают количество signer в `used` и действующий максимум `max`. Учитываются зарегистрированные signer и ожидающие приглашения с неистёкшим сроком. При `max`, равном 0, новые приглашения запрещены; после снижения максимума `used` может его превышать. Эти значения носят справочный характер и не резервируют ёмкость.

## Ключи и ресурсы

Выпустите VKS-ключ в [личном кабинете](https://app.vilna.io) и передавайте его в `X-Api-Key`. Все публичные операции VKS требуют `vks:access`. Ключи Platform, RPC и Management его не заменяют. В публичном Management API нет операции выпуска VKS-ключа.

| Ресурс | Назначение |
|  --- | --- |
| Signer | Узел подписи с данными для проверки его подлинности, отпечатками ключей, состоянием подключения и поддерживаемыми методами подписи. |
| Vault | Группа зарегистрированных узлов подписи и правило их участия: все обязательные узлы плюс `threshold_k` дополнительных. |
| Account | Блокчейн-аккаунт, создаваемый узлами активного vault; доступен для подписи только после перехода в `active`. Это отдельный ресурс, не учётная запись пользователя Vilna. |
| Ceremony | Попытка настройки блокчейн-аккаунта; её ход доступен по идентификатору попытки из аккаунта. |
| Transaction | Запрос согласования и подписи с выбранными узлами, решениями операторов, подписанным результатом и историей отправки. |


В vault может быть до 5 узлов подписи; каждый допустимый состав участников включает минимум 2 узла. Для транзакции выбирайте один полный состав из `minimal_quorums`, а не произвольное подмножество. Операторы должны принять конфигурацию vault через интерфейсы своих узлов до его активации. Затем настройка аккаунта начинается автоматически, без нового согласования. В одном vault одновременно настраивается только один аккаунт.

## Действия оператора

Публичный API создаёт приглашения и показывает состояние регистрации; оператор завершает регистрацию через интерфейс управления signer. Сверьте данные идентификации сервиса VKS из VKS API: `GET /v1/info` и отпечатки ключей зарегистрированного узла по доверенному каналу. Одного имени для проверки недостаточно.

Операторы принимают конфигурацию vault и согласуют транзакции через интерфейсы управления signer. В этом API нет публичных HTTP-операций регистрации узла, принятия vault или согласования транзакции. Заранее договоритесь о действиях операторов. Как получить доступ к Beta, демо и интерфейсу управления узлами, описано в [подготовке к подключению](/ru/guides/vks#1-%D0%BE%D1%82%D0%BA%D1%80%D0%BE%D0%B9%D1%82%D0%B5-vks-%D0%B2-vilna).

## Подпись и отправка

[Platform API](/ru/apis/platform) наблюдает за публичной активностью блокчейна и счетами. VKS получает параметры запрашиваемой транзакции и решения операторов, возвращает подписанный результат и при необходимости отправляет готовую транзакцию узлу блокчейна.

Проверяйте `result_form`: `transaction` готов к отправке; `ingredient` - подписанный компонент, который сначала включают в транзакцию с оплатой комиссии спонсором. `raw_tx` закодирован в Base64.

Истечение срока запроса подписи не удаляет готовый результат; результаты доступны без автоматического удаления. Удаление signer отзывает доступ к каталогу, но не стирает ключи на его устройстве и историю в связанных ресурсах. Удаление аккаунта ограничено неуспешными состояниями настройки.

Отправка через VKS возвращает `202`, когда запрос сохранён. Проверяйте попытки в журнале отправки; принятие узлом не означает подтверждения в блокчейне. VKS не отслеживает подтверждения. Поддерживаемые сети и форматы аккаунтов описаны в разделе [сети](/ru/apis/networks#vks), правила повторов запросов на изменение данных - в разделе [идемпотентность](/ru/apis/idempotency).