オペレーター

Private Channelsオペレーターとは？

オペレーターとは、Solanaメインネットとプライベートチャネルネットワークをつなぐオンチェーン許可済みの信頼エンティティです。オペレーターはインスタンス管理者がAddOperatorを通じてプロビジョニングし、オンチェーンにOperator PDAを作成します。これがなければ、どのパーティもReleaseFundsを呼び出すことができません。実際には、オペレーターはデポジットを監視し、チャネル側トークンをミントし、出金を検出してメインネットに資金を決済するサービスを運用する組織またはチームです。インスタンスを運用することで、ユーザーはSolanaメインネット上に記録されないプライベートな大量送金、ネイティブSolana TPSを超えるゼロ手数料の即時スループット、そしてRBACによるアクセス制御を利用できます。

既存のPrivate Channelsインスタンスに対してインテグレーションを行う開発者の方は、デプロイではなくクイックスタートから始めてください。

始める前に

前提条件

Dockerイメージに合わせて、ホスト上でこれらのバージョンを固定してください：

Docker Engine 26以上（macOS Apple Silicon：設定 -> 仮想マシンオプションで「Docker VMM」を有効にする）
Node.js 24.7.0 および pnpm 10.15.1
Solana CLI 3.1.13（Agave）
Rust 1.91.0
Devnet用のYellowstone gRPCエンドポイント（Helius、Triton、QuickNodeから取得可能）

ネットワーク要件とデフォルトポートの割り当てについては、リポジトリ内の docs/TECHNICAL_REQUIREMENTS.md を参照してください。

固定バージョンのSolanaツールチェーンをインストールし、SBFキャッシュをウォームアップします：

make install-toolchain

サービス

Private Channelsインスタンスの運用とは、Docker Composeスタック内の専用コンテナがそれぞれ担当する5つの継続的な責務を担うことを意味します：

メインネットのデポジットをインデックス化 - indexer-solanaはYellowstone gRPC経由でSolanaメインネットのDepositイベントを監視し、operator-solanaは確認済みデポジットを受け取り、チャネルネットワーク上で同等のトークン残高をミントします
チャネルの出金をインデックス化 - indexer-private-channelはチャネルを毎秒ポーリングしてWithdrawFundsバーンイベントを検出し、保留中の出金レコードをデータベースに書き込みます
メインネットで資金を解放 - operator-private-channelは保留中のレコードを取得し、有効なSMT除外証明を使ってエスクロープログラムのReleaseFundsを呼び出します
SMTルートを管理 - operator-private-channelはツリーのepochがローテーションされると自動的にResetSmtRootを呼び出します。オンチェーンのverify_smt_exclusion_proofチェックは、不正な出金に対する最後の防衛ラインです
ゲートウェイと認証サービスを運用 - ゲートウェイはすべてのクライアントトラフィックの単一の公開エンドポイントです。認証サービス（オプション）はJWT_SECRETが設定されている場合にJWT/RBACを適用します

完全なサービス一覧とポートの割り当てについては、設定リファレンスを参照してください。

セキュリティに関する注意： ライトノードとリードノードのポートはループバック（127.0.0.1）のみにバインドされていますが、他のいくつかのサービス（ゲートウェイ、認証、オペレーターメトリクス、Grafana、Prometheus、cAdvisor）はデフォルトですべてのネットワークインターフェースに公開されています。完全なポートテーブルについては設定リファレンスを参照し、公開デプロイ前にファイアウォールを設定してください。RBACはゲートウェイ自身のJSON-RPCメソッドのみをカバーし、これらの他のサービスはカバーしません。

アクセス制御：オープン vs. RBAC

デフォルトでは、ゲートウェイはすべての接続を受け入れます。トークンは不要です。JWTベースのRBACを有効にするには、JWT_SECRETを設定し、--profile authでスタックを起動します。operatorロールのプロビジョニング方法やユーザーウォレットの登録方法を含む完全な設定リファレンスについては、**認証とロール**を参照してください。

認証を有効にする場合は、スタックを起動する前に以下の環境変数を追加してください：

JWT_SECRET=<openssl rand -hex 32>   # must match on gateway and auth service
AUTH_PORT=8903

環境のセットアップ

.env.devnetはDevnet固有のデフォルト値が入力された状態でリポジトリに既にコミットされています。デフォルト値が上書きされてしまう.env.exampleから再生成するのではなく、直接編集してください。

以下のデプロイ手順を進めながら残りの値を入力してください。一部の値はデプロイの途中でのみ取得できます。シークレットはgitignoreされた.envファイルに、非シークレット変数は.env.devnetに記入します。

シークレット - 今すぐ設定してください：

POSTGRES_PASSWORD=<openssl rand -hex 32>
POSTGRES_REPLICATION_PASSWORD=<openssl rand -hex 32>

デプロイ中に取得する変数：

ESCROW_INSTANCE_ID=<instance address - from Step 3>
ADMIN_PRIVATE_KEY=<operator keypair as u8 array or base58 - from Step 4>
DEVNET_RPC_URL=https://api.devnet.solana.com
DEVNET_YELLOWSTONE_ENDPOINT=<your Yellowstone gRPC endpoint>
INDEXER_YELLOWSTONE_TOKEN=<your Yellowstone auth token>

ADMIN_PRIVATE_KEYはオフチェーンサービス自身が必要とする手数料支払い署名者であり、ステップ3のオンチェーンインスタンス管理者とは無関係です。このガイドでは、ステップ4で生成したオペレーターkeypairをADMIN_PRIVATE_KEYに設定し、オプションのOPERATOR_PRIVATE_KEYは未設定のままにします。これにより、オペレーター署名者は同じキーにフォールバックします。ステップ3のプロトコルレベルのインスタンス管理者keypairは、いずれの変数にも設定しないでください。

完全な環境変数リファレンスについては、 **設定**を参照してください。

デプロイ

イメージのビルド

make docker-devnet-build

このコマンドはすべてのRustサービスを共有Dockerイメージにコンパイルします。初回ビルドには30分から1時間かかります。

Admin UIのセットアップ

Admin UIはエスクローインスタンスの作成と設定を行うブラウザベースのツールです。開発・管理用のユーティリティであり、ユーザー向けプロダクトでも必須のランタイムコンポーネントでもありません。Admin UIが実行するすべての操作（CreateInstance、AllowMint、AddOperator）は、リポジトリ内のCLIスクリプトでも実行できます。

cd admin-ui
pnpm install
echo "PRIVATE_CHANNEL_RPC_URL=http://localhost:8899" > .env
pnpm dev   # opens at http://localhost:5173

エスクローインスタンスの作成

ブラウザウォレットをDevnetに設定し、手数料用のDevnet SOLがあることを確認します
Admin UIでCreate New Instanceをクリックしてトランザクションを承認します
Instance Addressをコピーし、.env.devnetのESCROW_INSTANCE_IDに設定します

または、CLIスクリプトを使用します：

cargo run --bin create_instance -- https://api.devnet.solana.com ./keypairs/admin.json

オペレーターkeypairの生成

solana-keygen new -o operator-keypair.json -s --no-bip39-passphrase
solana-keygen pubkey operator-keypair.json

keypairの内容を環境変数のADMIN_PRIVATE_KEYに設定します。公開鍵は環境変数ではありません。後述の「インスタンスの設定」ステップで、オペレーターのpubkeyとして直接渡します。

環境変数の最終設定

.env.devnetにESCROW_INSTANCE_ID、DEVNET_RPC_URL、DEVNET_YELLOWSTONE_ENDPOINT、INDEXER_YELLOWSTONE_TOKENを設定します。シークレット（POSTGRES_PASSWORD、POSTGRES_REPLICATION_PASSWORD、ADMIN_PRIVATE_KEY）はgitignoreされた.envファイルに記入します。

RBACを有効にすることにした場合（アクセス制御：オープン vs. RBAC）、この時点でJWT_SECRETとAUTH_PORTも追加してください。

全サービスの起動

認証なし：

make docker-devnet-up

認証あり：

docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet --env-file .env --profile auth up -d

--env-fileフラグが1つでも指定されると、Composeは自動的な.envの自動読み込みを無効にします。そのため、末尾の--env-file .envが必須です。これがないと、（.envに設定した）POSTGRES_PASSWORD、ADMIN_PRIVATE_KEY、JWT_SECRETが空として解決され、スタックが正常に起動しません。

インスタンスを設定する前にサービスを起動してください。インデクサーはリアルタイムでイベントをストリームするため、先にスタックを起動することで、AllowMintと最初のデポジットがバックフィルなしに順序通りインデックス化されます。

インスタンスの設定

スタックが起動したら、Admin UIでトークンミントをホワイトリストに追加し、オペレーターを登録します：

Allow Mint：Admin Functions -> Mint Management -> ミントアドレスを入力 -> Allow Mint
Add Operator：Admin Functions -> Operator Management -> オペレーターのpubkeyを入力 -> Add Operator

または、CLIを使用します：

cargo run --bin add_operator -- \
  https://api.devnet.solana.com \
  ./keypairs/admin.json \
  <INSTANCE_ID> \
  <OPERATOR_PUBKEY>

このガイドはSolana devnetを対象としています。メインネットの場合：

プログラムIDはdeclare_id!()でコンパイル時に埋め込まれます。リポジトリから正しいメインネットIDを使用していることを確認してください
Yellowstone gRPCエンドポイントにはメインネット対応のプランが必要です。devnetエンドポイントではメインネットのイベントはストリームされません
オペレーターウォレットはReleaseFundsの呼び出しごとにSOL手数料を支払うため、想定される出金量に合わせてSOL残高を確保してください
公開デプロイ前に、すべてのデフォルト認証情報（Grafana、PostgreSQL）を変更してください

運用

便利なコマンド

# View logs (all services)
make docker-devnet-logs

# View logs (specific service)
docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f indexer-solana

# Stop services
make docker-devnet-down

# Stop and wipe all state (volumes)
make docker-devnet-clean

オブザーバビリティ

スタックには、メトリクスとコンテナ監視のためにPrometheus、Grafana、cAdvisorが含まれています。Grafanaはポート37429でアクセスできます。

Grafanaのデフォルトパスワードはadminです。ポート37429をlocalhostを超えるネットワークに公開する前に変更してください。

トラブルシューティング

デポジット後にチャネル残高が更新されない

メインネットのエクスプローラーでメインネットのデポジットトランザクションが完了していることを確認してください
indexer-solanaが稼働していることを確認してください： docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f indexer-solana
operator-solanaが稼働していることを確認してください： docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f operator-solana
Yellowstone gRPCエンドポイントに到達可能で、トークンが有効であることを確認してください（DEVNET_YELLOWSTONE_ENDPOINT、INDEXER_YELLOWSTONE_TOKEN）
インデクサーは入金確定後に確定性の安全遅延を適用するため、オンチェーン確認後最大30秒お待ちください

出金がメインネットに決済されない

indexer-private-channelが稼働していることを確認してください： docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f indexer-private-channel
operator-private-channelが稼働していることを確認してください： docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f operator-private-channel
ADMIN_PRIVATE_KEYのオペレーターkeypairが、AddOperatorでオンチェーンに登録されたキーと一致していることを確認してください
ログに「SMT root mismatch」と表示されている場合、サービスは無効な証明を送信する代わりにシャットダウンします。スタックを停止し、一貫した状態からリストアして再起動してください

JWT認証の失敗（全リクエストに401エラー）

JWT_SECRETがゲートウェイと認証サービスの両コンテナで同一であることを確認してください
スタックが--profile authで起動されていることを確認してください
トークンは24時間後に期限切れになります。新しいトークンを取得するには再認証してください