自分のゲートウェイを動かす

Label 309 のレコードを検証するのに、だれかの助けは要りません。アカウントも、サーバーも、鍵も不要です。発行はその残り半分です。発行は Cardano にトランザクションを書き込む操作であり、そこには手数料がかかります。その手数料を支払うのがゲートウェイです。ゲートウェイは、レコードを刻むための資金を入れた Cardano ウォレット（および封じたファイル用の Arweave ウォレット）を保持し、トランザクションを構築して送信し、確定するまで追跡し、だれでも単独で検証できるようレコードを返します。

ふだんは、SDK や CLI をほかの人のゲートウェイに向けて使います。ですが、そのバックエンドはまるごとオープンソースです。label-309-gateway は Rust バイナリ1つと Postgres だけで動くので、自分専用のゲートウェイを立てられます。自分のアプリのために自分専用で動かすのも、有料サービスとしてほかの人に提供するのも自由です。設計からしてマルチテナントで、1つのインスタンスの下に多数のアカウントと API キーを収容できます。このガイドでは、リファレンスの Docker Compose を使って、何もない状態から、価格のついた最初の見積もりを得るところまでを進めます。

はじめる前に

必要なのは Docker と Docker Compose、そして数ギガバイトの空きディスクを備えたホストです。以下の手順はすべて Cardano preprod を対象にしています。デプロイを立ち上げるうえで、これが安全な構えだからです。mainnet への移行は、デプロイに資金を入れて動作を確認したうえで、あとから意図して行う切り替えです。

コードを取得し、設定を書く

リポジトリをクローンし、リファレンスの docker-compose.yml が置かれている deploy/ で作業します。設定例をコピーし、自分のデプロイに合わせて編集してください。ネットワーク、手数料の範囲、ストレージ、価格設定を指定します。

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

設定例には注釈が付いており、はじめから preprod を対象にしているので、最初の起動はそのままで動きます。

キーリングを作成する

ゲートウェイが使う署名鍵は、すべて1つの age 暗号化キーリングファイルに収められます。まずこれを作成し、続けて Cardano 鍵（preprod）、Arweave 鍵、webhook ラップ鍵を追加します。これらの 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- の手順は、いま作成したアドレスを表示します。表示された2つのアドレスに資金を入れてください。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 がホストのポートを一切公開しないのは、意図したものです。データプレーンとコントロールプレーンは1つのソケットを共有しているため、これを外に出すとコントロールプレーンまで露出してしまうからです。コントロールプレーンは、コンテナの内側から操作します。シェルを開いてください。

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さえあれば、アプリに必要なものはそろいます。

最初の見積もりを取る

セットアップ中にホストからデータプレーンにアクセスするには、docker-compose.yml のループバックの ports マッピング（127.0.0.1:8080:8080）のコメントを外し、もう一度 docker compose up -d を実行します。ループバックだけにとどめ、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}'

レスポンスには、15分間有効な quote_id と、費用の内訳が含まれます。発行の呼び出しは、この quote_id を残高の引き落としとアトミックに消費します。SDK のガイドで使うのと同じ、価格をロックし、それから送信するという2ステップの形です。これで、あなたのゲートウェイは動き出しました。

次に進むには

起動したバイナリは、対話的な API リファレンスを自ら配信します。データプレーンは /api/v1/docs、コントロールプレーンは /control/v1/docs で、いずれも完全にオフラインで表示されます。リポジトリには、さらに踏み込んだ2つのドキュメントがあります。運営者向けランブックは、資金の入れ方、認証情報、お金にまつわる仕組み、そして運用開始後の作業を扱います。インテグレーターガイドは、その上に製品を築く方法を扱います。

あなたのゲートウェイのデータプレーンは、SDK と CLI のガイドでいう「ベースURL」そのものです。https://your-gateway.example を、いまあなたが管理するアドレスに置き換え、API キーを配り、完全に自分のものであるバックエンドを通じて最初の存在証明を発行することができます。