Co-Signer

Операції з гаманцями

Co-Signer

BroSettlement Co-Signer — це сервіс із відкритим кодом, який працює у вашій інфраструктурі, зберігає вашу MPC-частку ключа та бере участь у підписанні без відновлення повного приватного ключа.

Що робить Co-Signer

Co-Signer:

  • опитує BroSettlement щодо нових DKG- і signing intents;
  • автентифікує запити вашим Ed25519 API-ключем;
  • отримує роботу через підписані HTTPS-запити;
  • обмінюється MPC-повідомленнями через BroSettlement;
  • зберігає MPC-частку ключа в зашифрованому локальному файлі;
  • бере участь у підписанні транзакцій без відновлення повного приватного ключа;
  • повідомляє BroSettlement фінальний результат.

Репозиторій: BroLabel/brosettlement-mpc-co-signer

Межа довіри

BroSettlement і ваш Co-Signer контролюють окремі MPC-матеріали для підписання. BroSettlement не може завершити MPC-підпис без участі Co-Signer під контролем клієнта.

Co-Signer використовує pull model і сам ініціює вихідні HTTPS-з’єднання з BroSettlement. Відкривати локальний health port у публічний інтернет не потрібно.

Конфігурація

ЗміннаОбов’язковаОпис
CO_SIGNER_MONOLITH_URLТакBase URL BroSettlement API. Для staging: https://brosettlement-staging-api.brolabel.io/.
CO_SIGNER_API_KEY_IDТакUUID API-ключа, створеного для Co-Signer.
CO_SIGNER_API_PRIVATE_KEYТакПриватний Ed25519-ключ клієнта у форматі PKCS#8 PEM, hex або Base64.
CO_SIGNER_SHARE_ENCRYPTION_KEYТакСтворений клієнтом secret для AES-256-шифрування файлів MPC-часток.
CO_SIGNER_SHARES_DIRНіПостійний каталог зашифрованих часток. Типово: ./data/shares.
CO_SIGNER_HTTP_ADDRНіАдреса локального health server. Типово: 0.0.0.0:8081.
CO_SIGNER_PARTY_IDНіІдентифікатор учасника MPC. Типово: co-signer.
CO_SIGNER_MAX_CONCURRENTНіМаксимальна кількість паралельних workers. Типово: 4.
CO_SIGNER_POLL_MIN_INTERVALНіМінімальний інтервал опитування intents. Типово: 2s.
CO_SIGNER_POLL_MAX_INTERVALНіМаксимальний інтервал опитування intents. Типово: 10s.
CO_SIGNER_POLL_BACKOFF_FACTORНіМножник backoff для опитування. Типово: 1.5.
CO_SIGNER_FRAME_POLL_INTERVALНіІнтервал опитування MPC-повідомлень. Типово: 500ms.
CO_SIGNER_HTTP_TIMEOUTНіTimeout запитів до BroSettlement API. Типово: 30s.

Робота з secrets

  • Ніколи не додавайте private.pem, ключ шифрування частки або каталог часток до Git.
  • Не передавайте secrets через аргументи командного рядка, query string, тікети або чати.
  • Передавайте secrets під час запуску через secrets manager або захищені файли.
  • Обмежте API-ключ необхідними дозволами й access settings зі сторінки API key.
  • Прив’яжіть health endpoint до 127.0.0.1, якщо приватна мережа моніторингу не вимагає іншого.
  • Надайте доступ до каталогу часток лише користувачу операційної системи, який запускає Co-Signer.
  • Вимкніть core dumps і не допускайте потрапляння secrets або вмісту часток у logs.

Постійне сховище та резервні копії

Co-Signer записує один зашифрований JSON-файл для кожного MPC-ключа в CO_SIGNER_SHARES_DIR. Файли зашифровані AES-256-GCM і створюються з обмеженими правами доступу.

Захищайте та резервуйте:

  1. повний постійний каталог часток;
  2. відповідний ключ шифрування частки;
  3. приватний Ed25519 API-ключ або задокументовану процедуру ротації API-ключа.

Зберігайте резервні копії зашифрованих часток і ключ шифрування в різних захищених місцях. Перевірте процедуру відновлення до того, як покладатися на неї. Файл частки неможливо використати без відповідного ключа шифрування.

Після ініціалізації MPC не видаляйте, не замінюйте та не редагуйте файли часток вручну. Не копіюйте їх між організаціями.

Запуск і моніторинг

Сервіс записує структуровані JSON logs у standard output. Надсилайте stdout і stderr у централізовану систему logs із належним редагуванням secrets і контролем доступу.

Контролюйте:

  • доступність процесу;
  • HTTP-статус /health;
  • значення ready;
  • версію сервісу;
  • перевірку каталогу часток;
  • статус і останній heartbeat Co-Signer у BroSettlement Console;
  • помилки автентифікації, опитування, DKG і підписання.

Оновлення

Перед оновленням:

  1. створіть резервну копію зашифрованого каталогу часток;
  2. переконайтеся, що відповідний ключ шифрування доступний;
  3. прочитайте release notes;
  4. зберіть і протестуйте цільову версію;
  5. коректно зупиніть старий процес;
  6. запустіть нову версію з тим самим каталогом часток і secrets;
  7. перевірте локальний health і heartbeat у BroSettlement;
  8. виконайте testnet-перевірку підписання перед поверненням сервісу до робочого режиму.

Не запускайте два процеси Co-Signer для однієї організації та одного каталогу часток, якщо release documentation прямо не підтримує таку модель.

Усунення проблем

Co-Signer не запускається

Переконайтеся, що всі обов’язкові змінні задані, а також:

  • приватний ключ є дійсним Ed25519-ключем;
  • CO_SIGNER_SHARES_DIR існує або може бути створений;
  • користувач сервісу може читати й записувати цей каталог;
  • локальний health port вільний.

Локальний health повертає ready: false

Перевірте результат checks.shares_dir. Переконайтеся, що каталог існує і користувач сервісу має до нього доступ.

Console показує Co-Signer як offline

Перевірте:

  • CO_SIGNER_MONOLITH_URL відповідає середовищу; для staging використовується https://brosettlement-staging-api.brolabel.io/;
  • API Key ID;
  • відповідність приватного ключа завантаженому публічному ключу;
  • наявність усіх трьох MPC-дозволів;
  • завершені network і allowlist settings на сторінці API key;
  • вихідний HTTPS-доступ;
  • активність API-ключа та строк його дії.

MPC залишається not configured

Co-Signer у статусі Online не запускає MPC автоматично. Відкрийте Multi-Party Computation і явно натисніть Initialize MPC.

Ініціалізація MPC завершується помилкою

Не вимикайте Co-Signer і перевірте його JSON logs. Виправте помилки автентифікації, IP allowlist, з’єднання, версії або сховища. Повторюйте спробу лише після того, як попередня ініціалізація перейде у фінальний стан failed або expired.

Створення гаманця недоступне

Переконайтеся, що:

  • MPC-ключ має статус Active або Ready;
  • Co-Signer має статус Online;
  • вибрана мережа має статус Ready;
  • план організації дозволяє створити ще один гаманець.