【ITニュース解説】Test your agent's payment loop on a testnet before it goes live

システム開発、特に金銭が関わる決済システムを構築する際には、開発したプログラムが意図せずユーザーに不利益を与えたり、システムが不正利用されたりしないよう、徹底したテストが不可欠だ。例えば、ネットワークの遅延後に同じ請求に二度支払いをしてしまったり、古い設定情報を参照して間違った相手に送金してしまったり、あるいは過去の処理を不正に繰り返す攻撃を受け入れてしまったりといった問題は、実際の金銭が動く「本番環境」（メインネット）で初めて発覚することが少なくない。一度本番環境でこのような問題が起きてしまうと、金銭的な損害が発生し、その取り返しは非常に困難になる。

これらのリスクを未然に防ぐため、「テストネットワーク」（テストネット）を活用した開発が強く推奨される。テストネットは、本番環境のブロックチェーンネットワークとほぼ同じ機能を持つが、そこで扱われる仮想通貨は価値を持たない、いわば「練習用」の環境だ。このテストネットでの開発最大の利点は、どんなに大きなミスをしても、実際の金銭的な損害が一切発生しないことにある。つまり、潜在的なバグを最も安全で安価な方法で発見し、修正できる場所がテストネットなのだ。決済処理を行うプログラム（エージェント）が利用するAPIは、テストネットと本番環境でほとんど同じように設計されているため、本番環境と同じ感覚でテストを進めることができる。APIへのアクセス先（エンドポイント）、認証に必要なヘッダー、サーバーからの応答の形式も同じだ。

プログラムの個々の部品が正しく動くかを確認する「単位テスト」だけでは、このような問題を見つけ出すことは難しい。単位テストはプログラムの内部ロジックの正しさを検証するものであり、外部システム（ブロックチェーン上のウォレットや決済プラットフォームなど）との連携や、実際のネットワーク環境に起因する問題まではカバーできないからだ。例えば、プログラムがウォレットの情報を正しく読み取れるか、送金に必要な手数料が事前に十分に確保されているか、送金要求が正しく暗号学的に署名され、その署名が検証されるか、あるいは自分のサーバーがネットワークの再試行期間内に迅速に応答できるかといった、外部との複雑な連携に関する問題は、単位テストでは見過ごされがちだ。だからこそ、実際の外部連携を伴うテストネットでの検証が不可欠となる。

テストネットでシステムを動かすことで、特に次の三つの重要な点を確認できる。一つ目は、開発したエージェントが与えられたウォレットを正しく読み込み、そこで表示される残高が期待通りであること。これは、ウォレットとの基本的な連携が正しく機能しているかを確認する。二つ目は、送金処理が最低送金額チェックや手数料を含めて問題なく実行できること。ブロックチェーン上の取引には手数料が発生するため、送金額が不足していると取引が成立しないケースがある。テストネットでこれを事前に確認することで、本番環境での不必要なエラーを防ぐことができる。三つ目は、自分のサーバーが送金完了イベントの署名を正しく検証し、プラットフォームが再試行を行う前に十分速く（成功を示す）2xxステータスコードで応答できることだ。これにより、外部からの通知（Webhook）が正しく処理され、セキュリティと応答速度の両面で問題がないことを確認できる。

それでは、具体的なテストの手順を見ていこう。

ステップ1: 損害の心配がないテスト用ウォレットを作成する まず、イーサリアムのSepoliaやSolanaのDevnetといったテストネットワーク上でウォレットを作成する。例では、OpenClawCashというプラットフォームのAPIを利用してウォレットを作成している。APIキーを環境変数に設定し、curlコマンドを使ってAPIにリクエストを送る。重要なのは、"network": "sepolia"のようにテストネットワークを明示的に指定することだ。ウォレットのパスフレーズは安全な方法で別途保存し、その保存を確認する設定も行う。このウォレット作成に使用するAPIキーは、初期設定として「live-transactions」という本番取引を許可するフラグをオフにしておくことが極めて重要だ。これにより、万が一プログラムにバグがあったとしても、テストネット上の価値のない通貨しか扱えないため、実際の金銭的な損失を心配する必要がない。APIからの応答には、ウォレットのID、ラベル、アドレス、ネットワーク、チェーンなどの情報が含まれる。

ステップ2: ウォレットの残高を調べて読み取る ウォレットを作成したら、その残高を確認する。これもAPIを通じて行う。まず、APIを叩いてエージェントが管理するウォレットの一覧を取得できる。これはウォレットの存在を確認するためで、費用はかからない。次に、特定のウォレットIDを指定して詳細な残高情報を取得する。この情報には、「nativeBalanceDisplay」（基盤となる通貨の残高）や「tokenBalances」（トークンの残高）が含まれる。これらの残高情報を用いて、「この請求を支払うのに十分な資金があるか」というプログラムのロジックをテストできる。テストネットのウォレットは通常、作成時には残高がないため、テストネットの「ファセット」（テスト用の仮想通貨を無料で提供するサービス）から少額のテスト通貨を送金し、再度残高を読み込むことで、残高確認機能全体を検証する。

ステップ3: 送金を実行し、その記録を読み取る 残高確認ができたらいよいよテスト送金を実行する。curlコマンドを使って、ウォレットID、送金先のアドレス、送金額を指定して送金APIを呼び出す。ここで注意すべき点が二つある。一つは、送金額を指定する際に「amountDisplay」（人間が認識しやすい単位、例えば「0.01」）か「valueBaseUnits」（最小単位）のどちらか一方のみを指定すること。両方を指定するとエラーになる。二つ目は、基盤通貨の送金は、事前に最低送金額チェックを通過する必要がある点だ。ウォレットに非常に少額の通貨（俗に「ダスト」と呼ばれる）しかない場合、システムは「amount_below_min_transfer」というエラーを返し、取引が成立しないことを通知し、必要な最低金額を教えてくれる。これにより、本番環境で資金不足による送金失敗を防ぐことができる。送金が完了したら、curlコマンドでウォレットの取引履歴を取得し、送金が正しく記録されているかを確認する。network=sepoliaのようにネットワークを指定することで、特定のネットワークの履歴を絞り込んで確認できる。

ステップ4: 自分のサーバーで支払い完了通知を受け取る システム開発では、外部で発生したイベント（例えば支払い完了）を自分のサーバーで受け取り、それに伴う処理を実行することが多い。ここでは、「Webhook」という仕組みを使って支払い完了イベント通知を受け取る方法をテストする。curlコマンドでWebhookのエンドポイントを登録し、"eventTypes": ["wallet.transaction.confirmed"]のように「ウォレットの取引が確認された」イベントを受け取るように設定する。登録が成功すると、Webhookの公開IDと秘密鍵が一度だけ表示される。この秘密鍵はサーバー側で厳重に保管し、エージェントのプログラムからはアクセスできないようにする必要がある。

Webhookで通知を受け取った際、自分のサーバーではいくつかの重要なセキュリティチェックを行う必要がある。一つは、JSONパースを行う前に、リクエストの生データを確認し、改ざんがないかを検証すること。二つ目は、Webhookのタイムスタンプが5分以上古い場合はその通知を拒否すること。これは、過去の通知を不正に再利用するリプレイ攻撃を防ぐための対策だ。三つ目は、通知のデータと秘密鍵を元に計算した署名を、Webhookヘッダーに含まれる署名と比較し、通知が正規のものであることを検証すること。この署名比較は、常に同じ時間で行う「定数時間比較」を使うべきだ。さらに、webhook-idを使って通知の重複を排除することも重要だ。Webhookはネットワークの状況によって複数回同じ通知を送ってくることがあるため、重複して処理しないようにする。最後に、サーバーはWebhook通知を受け取ってから10秒以内に成功を示す2xxステータスコードで応答する必要がある。この時間内に応答できないと、プラットフォームは通知の再試行を続ける。もしサーバーが410ステータスコード（リソースが完全に削除されたことを示す）で応答した場合、そのエンドポイントへの通知は停止される。テストネットでの送金は、本番環境と同じイベントを発生させるため、これらの重複通知、古いタイムスタンプ、410応答パスの失敗といった潜在的な問題を、本番環境で顧客の請求書に影響が出る前に発見し、修正できる。

本番環境に移行する際の注意点 テストネットでのテストが滞りなく完了し、決済処理の動作が安定したら、いよいよ本番環境への移行を検討する。この段階では、テストで使用していたAPIキーとは別に、本番用のAPIキーを新しく発行することが推奨される。この本番用キーには、「live transactions」フラグをオンにし、実際の金銭取引を許可する。さらに、セキュリティを強化するために、このキーの権限範囲（スコープ）を特定のブロックチェーンや特定のウォレットに限定し、ウォレットには「ポリシー」を設定して、サーバーが署名する前にポリシー違反の取引を拒否できるようにする。テストネット用のキーは、今後も継続的なテストスイート（自動テストプログラム群）の実行のために残しておくべきだ。

特に重要なのは、これらの権限範囲やポリシーはプラットフォーム側で強制されるものであり、自分のエージェントのプログラムコードだけで完全にセキュリティを担保できるわけではないという点だ。そのため、本番環境で「live transactions」フラグがオンになっているAPIキーに、適切なポリシーが設定されていない場合、それはウォレットの秘密鍵を直接扱っているのと同じくらい危険な状態になる。また、APIキーを削除しても、ウォレット自体は残高を保持したままだ。これは、ウォレットの秘密鍵がAPIキーとは独立しており、紐付けられていないためである。

上記で説明したAPIのエンドポイント、ヘッダー、フィールドなどの具体的な情報は、OpenClawCashの公開されたAPIリファレンスに詳細が記載されている。APIキーの権限設定に関する詳しい情報は、セットアップガイド「Hermes Agent Wallet Setup: Safe by Default」に詳述されているため、これらのドキュメントを参照しながら、安全で信頼性の高いシステム構築を進めることが求められる。テストネットでの慎重な検証は、本物の金銭が関わるシステムを開発する上で、避けられない、そして極めて重要なステップと言える。