← Все записи

7 мин чтения

Используйте CLI CardanoWall в CI/CD и скриптах

Запускайте Proof of Existence из скрипта: CLI cardanowall выводит JSON в stdout, диагностику в stderr, даёт стабильные коды возврата для проверки, безопасно принимает секреты и публикует через любой шлюз Label 309.

Берите CLI cardanowall, когда Proof of Existence должен работать внутри скрипта, а не в браузере. Он создан для автоматизации: передайте --json, чтобы получить машиночитаемые данные в stdout, рассматривайте stderr как диагностику и ветвите логику по небольшому набору стабильных кодов возврата. Этого достаточно, чтобы встроить его в CI/CD, релизные конвейеры, задачи комплаенса и внутренние инструменты аудита.

CLI умеет проверять записи без учётной записи CardanoWall, публиковать подтверждения через любой шлюз Label 309, подписывать записи локально, выводить идентичность из сида, строить и проверять доказательства Merkle, а также читать запечатанные входящие. Это тот же инструмент с открытым исходным кодом, который может запустить кто угодно: он опубликован на crates.io как бинарник cardanowall — без алиаса cw — а исходники лежат на github.com/cardanowall.

Зачем использовать CLI вместо сайта?

Сайт сделан для людей. Автоматизации нужно другое:

  • детерминированные команды, которые можно запускать без участия человека;
  • машиночитаемый вывод;
  • стабильные коды возврата, по которым можно ветвить логику;
  • отсутствие браузерной сессии, которой надо управлять;
  • явная настройка шлюза вместо входа в учётную запись;
  • секреты, читаемые из stdin, файла или переменной окружения, — а не вводимые в интерактивном запросе;
  • логи, которые можно архивировать вместе с задачей.

Именно это и даёт CLI, и он держит подтверждение рядом с системой, которая на самом деле производит свидетельства.

Как проверить подтверждение в скрипте?

Проверку проще всего автоматизировать, и её полезнее всего запускать где угодно:

cardanowall verify <tx-hash> --json

Для проверки не нужны ни учётная запись CardanoWall, ни оператор шлюза. Команда читает метаданные транзакции из публичного обозревателя блокчейна Cardano (совместимого с Koios или Blockfrost), при необходимости получает содержимое из публичных шлюзов Arweave или IPFS, проверяет запись и сверяет все подписи. В этом и весь смысл стандарта: подтверждение, которое вы проверили однажды, остаётся независимо проверяемым кем угодно — без доверия к издателю, его домену или его серверу.

Для более строгого контроля укажите собственный источник данных и задайте глубину подтверждения:

cardanowall verify <tx-hash> \
  --cardano-gateway https://api.koios.rest/api/v1 \
  --threshold 20 \
  --json

Данные идут в stdout, а диагностика — в stderr, поэтому композиция команд остаётся чистой:

if cardanowall verify "$TX_HASH" --json > verify-report.json; then
  echo "proof verified"
else
  code=$?
  echo "verification did not pass, exit code: $code" >&2
fi

Подробнее о том, что именно проверяет верификатор, читайте в статье как проверить запись Label 309.

Что означают коды возврата?

Ветвите логику по коду возврата, а не разбирайте текст, написанный для человека: код уже сообщает класс результата.

КодЗначение
0valid / успех
1сбой класса целостности (не пройдена криптографическая или структурная проверка)
2сбой сетевого класса или результат невозможно проверить (ошибка загрузки или транспорта)
3pending — обычно недостаточно подтверждений
4ошибка ввода в CLI (неверные аргументы или отсутствует обязательный ввод)

Для verify коды 0–3 напрямую соответствуют вердикту верификатора — valid, failed, unverifiable и pending соответственно, — так что один и тот же контракт работает, читаете ли вы код возврата или отчёт --json.

Это даёт автоматизации понятную политику:

  • 0: продолжать.
  • 1: завершить задачу с ошибкой — проверка подтверждения или содержимого не пройдена.
  • 2: повторить попытку или пометить запуск как неопределённый.
  • 3: подождать и повторить после новых подтверждений.
  • 4: исправить скрипт или его входные данные.

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

Как опубликовать подтверждение из автоматизации?

Для публикации нужен шлюз, потому что она отправляет реальную транзакцию Cardano и списывает средства с баланса вашего шлюза, чтобы оплатить комиссию за транзакцию и хранение на Arweave. (О том, почему публикация вообще стоит денег, читайте в статье почему публикация имеет цену.)

Вычислить хеш файла и закрепить его в блокчейне:

cardanowall submit \
  --file ./release-manifest.json \
  --base-url https://your-gateway.example \
  --api-key "$CARDANOWALL_API_KEY" \
  --json

Закрепить заранее вычисленный дайджест:

cardanowall submit --hash <64-hex-digest> --json

Закрепить пакет Merkle, построенный из списка листьев:

cardanowall submit --merkle ./leaves.txt --json

Эти три режима аккуратно ложатся на распространённые сценарии автоматизации. Небольшая задача может закрепить один файл. Релизная система может закрепить заранее вычисленный дайджест манифеста. Высоконагруженная система может свернуть множество хешей элементов в один корень Merkle и опубликовать одну запись. Первый проход разобран в статье опубликуйте своё первое подтверждение.

Запустите cardanowall <command> --help, чтобы получить авторитетный список флагов, соответствующий версии, — это всегда последнее слово по опциям для вашей установленной сборки.

Как настроить шлюзы один раз, а не в каждой задаче?

Зашивать URL шлюза и ключ API в каждую задачу — ненадёжно. Вместо этого CLI хранит именованные профили шлюзов:

cardanowall gateway add prod --base-url https://your-gateway.example
cardanowall gateway use prod
cardanowall gateway list

В CI подавайте ключ из stdin, а не отвечайте на интерактивный запрос:

cardanowall gateway add prod \
  --base-url https://your-gateway.example \
  --api-key-stdin < ./gateway-api-key.txt

Сервисный шлюз разрешается в фиксированном порядке: явный флаг побеждает, затем переменная окружения, затем активный профиль. Такое разделение подходит обеим средам: разработчик может опереться на сохранённый профиль, а CI подставляет CARDANOWALL_BASE_URL и CARDANOWALL_API_KEY и полностью обходится без файла конфигурации.

Как не пускать секреты в командную строку?

Эту ошибку легко совершить, поэтому сделайте так, чтобы её было трудно совершить. Никогда не помещайте сырой Identity Seed или ключ получателя прямо в аргументы команды: argv утекает в историю shell, логи CI и списки процессов (ps).

Используйте безопасный источник ввода:

  • --seed-stdin или --seed-file;
  • --secret-key-stdin или --secret-key-file;
  • переменную окружения — только если обработка секретов в вашем CI безупречна.

Например, передайте сид в stdin:

printf '%s' "$CARDANOWALL_SEED" | \
  cardanowall submit --file ./manifest.json --seed-stdin --json

Секрет должен приходить ровно из одного источника; передача его сразу из двух (скажем, устаревший --seed-file плюс CARDANOWALL_SEED) — это жёсткая ошибка ввода, поэтому старое значение никогда не сможет незаметно подменить то, которое вы имели в виду. Сырые флаги argv --seed и --secret-key всё ещё существуют для одноразовых тестовых значений, но при использовании печатают однострочное предупреждение в stderr. Относитесь к этому предупреждению как к реальному средству контроля, а не к шуму. И поскольку ключам не нужно отправляться на сервер, чтобы выполнить эту работу, сид остаётся на машине, где выполняется команда, — это принцип, лежащий в основе статьи почему ключи никогда не покидают устройство.

Как подписать запись в конвейере?

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

Для простого локального подписания безопасно прикрепите сид прямо при публикации:

cardanowall submit --file ./release.json --seed-stdin --json

Для более строгих сред полностью держите ключ вне сборочного хоста и подписывайте в два шага:

cardanowall sign prepare --signer-pubkey <hex> --hash <hex>
cardanowall sign assemble --signer-pubkey <hex> --signature <hex> --in record.cbor

Такое разделение позволяет KMS, HSM, офлайн-рабочей станции или защищённому сервису подписи произвести подпись Ed25519, тогда как конвейер автоматизации занимается сборкой записи и публикацией, ни разу не касаясь приватного ключа.

Как упаковать тысячи артефактов в одну запись?

Корни Merkle — это то, как масштабируется рабочий процесс на CLI. Вместо одной транзакции на артефакт постройте список листьев и закрепите корень:

cardanowall merkle build --in leaves.txt --json > merkle.json
cardanowall submit --merkle ./leaves.txt --json

Позже докажите отдельный лист с его доказательством включения:

cardanowall merkle verify \
  --root <hex32> \
  --leaf <hex32> \
  --proof proof.json

Это отлично подходит для свидетельств релизов в CI/CD, пакетов содержимого, сгенерированного ИИ, манифестов наборов данных, снимков комплаенса, архивов логов и пакетов происхождения медиа. Храните список листьев и доказательства включения вместе с остальными свидетельствами релиза: корень в блокчейне — лишь половина истории будущей проверки. Этот подход подробно разобран в статье одна запись для тысяч файлов, а применение в CI — в статье подтверждения в вашем конвейере CI/CD.

Когда автоматизации стоит работать с запечатанными записями?

CLI умеет работать и с запечатанным PoE — зашифрованными записями, адресованными одному или нескольким получателям:

cardanowall inbox sync --seed-stdin
cardanowall inbox list --seed-stdin --json
cardanowall inbox decrypt <tx-hash> --secret-key-stdin

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

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

Что должна архивировать задача CI?

Архивируйте отчёт о подтверждении, а не только хеш транзакции. Хороший запуск сохраняет:

  • версию CLI;
  • аргументы команды с отредактированными секретами;
  • входной манифест или дайджест файла;
  • хеш транзакции;
  • вывод публикации в --json;
  • отчёт о проверке в --json;
  • список листьев Merkle и доказательства включения, если они использовались;
  • идентичность подписанта для любой подписанной записи;
  • логи повторных попыток для результатов pending или unverifiable.

Это даёт будущим аудиторам достаточно контекста, чтобы воспроизвести проверку, и никому не придётся реконструировать, как релизная задача была собрана несколько месяцев назад.

Практический шаблон релиза

Релизная задача может принять такую форму:

  1. Соберите артефакты.
  2. Сгенерируйте контрольные суммы, SBOM, аттестации и релизный манифест.
  3. Вычислите хеш манифеста или постройте список листьев Merkle.
  4. Опубликуйте через cardanowall submit.
  5. Зафиксируйте хеш транзакции и дождитесь подтверждений.
  6. Запустите cardanowall verify.
  7. Сохраните отчёты JSON вместе с релизными артефактами.
  8. Завершайте релиз с ошибкой при failed; повторяйте попытку или удерживайте при pending и unverifiable.

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

Дополнительное чтение

cliautomationci-cd