Поднимите собственный шлюз

Проверка записи Label 309 ни от кого ничего не требует — ни аккаунта, ни сервера, ни ключа. Публикация — вторая половина: она помещает транзакцию в Cardano, а это стоит комиссии. Шлюз — та часть, что её оплачивает. Он держит пополненный кошелёк Cardano, который закрепляет запись (и кошелёк Arweave для запечатанных файлов), собирает и отправляет транзакцию, отслеживает её до подтверждения и отдаёт записи обратно для автономной проверки.

Чаще всего вы направляете SDK или CLI на чужой шлюз. Но весь бэкенд открыт — label-309-gateway, один бинарник на Rust плюс Postgres, — так что вы можете поднять и свой. Разверните его для себя, для собственных приложений, или сделайте из него платный сервис для других: он изначально многопользовательский, и под одним экземпляром живёт множество аккаунтов и API-ключей. Это руководство проведёт вас от пустого места до первой рассчитанной цены с помощью эталонного Docker Compose.

Прежде чем начать

Вам понадобятся Docker и Docker Compose, а также хост с несколькими гигабайтами свободного места на диске. Всё, что описано ниже, рассчитано на сеть Cardano preprod — это безопасный вариант, чтобы поднять развёртывание. Переход на mainnet — осознанный шаг, который вы делаете позже, когда развёртывание пополнено и проверено.

Получите код и напишите конфигурацию

Склонируйте репозиторий и работайте из каталога deploy/, где лежит эталонный docker-compose.yml. Скопируйте пример конфигурации и отредактируйте его под своё развёртывание — сеть, диапазон комиссий, хранилище и ценообразование:

git clone https://github.com/cardanowall/label-309-gateway
cd label-309-gateway/deploy
cp ../gateway.example.toml gateway.toml

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

Создайте связку ключей

Каждый ключ подписи, которым пользуется шлюз, хранится в одном файле связки ключей, зашифрованном age. Создайте его, затем добавьте ключ Cardano (preprod), ключ Arweave и ключ для обёртывания вебхуков. Эти шаги keyring запускают бинарник gateway напрямую: связку ключей полагается создавать на доверенной машине, а в контейнер копировать только её зашифрованный файл, поэтому ради этого одного шага возьмите релизную сборку из репозитория.

mkdir -p secrets
printf '%s' 'a-strong-passphrase' > secrets/gateway-keyring-passphrase
export GATEWAY_KEYRING_PASSPHRASE="$(cat secrets/gateway-keyring-passphrase)"

gateway keyring init             --path secrets/gateway-keyring.age
gateway keyring add-cardano      --path secrets/gateway-keyring.age --network preprod
gateway keyring add-arweave      --path secrets/gateway-keyring.age
gateway keyring add-webhook-wrap --path secrets/gateway-keyring.age
chmod 600 secrets/*

Каждый шаг add- печатает адрес, который только что создал. Пополните оба напечатанных адреса: адрес Cardano оплачивает комиссии за закрепление, а адрес Arweave оплачивает хранение запечатанных файлов. Затем задайте пароль базы данных, который читает compose:

echo 'POSTGRES_PASSWORD=a-strong-db-password' > .env

Поднимите шлюз

Сначала подготовьте оператора. Эта команда применяет миграции и ровно один раз печатает корневой секрет — сохраните его в надёжном месте, это главный ключ доступа к плоскости управления:

docker compose run --rm gateway operator bootstrap --label acme

Затем запустите Postgres и шлюз:

docker compose up -d

Зарегистрируйте кошелёк, аккаунт и ключ

Compose намеренно не публикует ни одного порта на хосте: плоскости данных и управления делят один сокет, поэтому, открыв его наружу, вы открыли бы и плоскость управления. Работайте с плоскостью управления изнутри контейнера. Откройте оболочку:

docker compose exec gateway sh

Нацельте его на локальную плоскость управления, указав корневой секрет, который напечатал bootstrap, затем зарегистрируйте пополненный кошелёк Cardano (адрес, который напечатал keyring add-cardano), создайте аккаунт, пополните его и выпустите API-ключ плоскости данных с правами на публикацию:

export GATEWAY_CONTROL_URL=http://127.0.0.1:8080/control/v1
export GATEWAY_CONTROL_TOKEN='ctl_…the root secret from bootstrap…'

gateway admin wallet register primary addr_test1… preprod
gateway admin account create
gateway admin account fund <account_id> 10000000 "starter credit"   # $10
gateway admin key create <account_id> poe:create,poe:read,account:read

key create печатает API-ключ, который управляет плоскостью данных. Этот ключ вместе с базовым URL — всё, что нужно приложению.

Зафиксируйте первую цену

Чтобы во время настройки достучаться до плоскости данных с хоста, раскомментируйте проброс порта на loopback (127.0.0.1:8080:8080) в docker-compose.yml и снова выполните docker compose up -d — только loopback, ни в коем случае не 0.0.0.0. Затем зафиксируйте цену тем API-ключом, который только что выпустили:

curl -sS -X POST http://127.0.0.1:8080/api/v1/poe/quote \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"record_bytes":256,"recipient_count":0,"file_bytes_total":0}'

В ответе придёт quote_id, действительный 15 минут, и разбивка стоимости. Вызов публикации расходует этот quote_id атомарно, вместе со списанием с баланса, — та же схема из двух шагов зафиксировать цену, затем отправить, что и в руководствах по SDK. Ваш шлюз работает.

Что дальше

Запущенный бинарник сам отдаёт интерактивный справочник по API — плоскость данных по адресу /api/v1/docs, плоскость управления по /control/v1/docs, и оба отображаются полностью офлайн. Два документа в репозитории копают глубже: руководство оператора охватывает пополнение, учётные данные, денежную семантику и повседневную эксплуатацию, а руководство интегратора — как построить продукт поверх шлюза.

Плоскость данных вашего шлюза — это ровно то, что руководства по SDK и CLI называют базовым URL. Замените https://your-gateway.example на адрес, которым теперь управляете вы, раздайте API-ключи и опубликуйте своё первое подтверждение существования через бэкенд, который целиком ваш.