導入・運用ガイド https://docs.hazbase.com/guides/production/ IMPLEMENTATION GUIDE 導入・運用ガイド 担当者の役割、導入の手順、1件の処理、日々の照合、障害からの復旧まで。設備に関する権利を割り当てる例を通じて、API・SDKを業務として運用する方法を紹介します。 このガイドで扱う運用例 配送ロボットROBOT-A-001に関する契約上の権利を、上限1,000単位・小数桁0のFlexibleTokenで管理する例です。初回の割当では10単位を新規発行し、取引先のウォレットに付与します。開始時点の発行済み総数と取引先の残高はいずれも0とします。 担当者が確認する完了状態 承認された宛先に10単位が発行され、発行済み総数も10になり、資産台帳から契約・割当先・数量・取引ハッシュをたどれる状態です。以後の移転がある場合は、その取引を含む時点ごとの残高で照合します。 操作IDは業務側の受付番号、取引ハッシュはチェーン上の取引の識別番号、receiptは実行結果の記録です。この三つを結び付けることで、担当者は依頼から実行結果までを追跡できます。 これはAPI・SDKを自社システムに組み込む構成例です。設備・在庫・利用権などでも、対象IDと権利の定義を置き換えて同じ運用の考え方を使えます。RWA OpsやFund Opsを利用する場合は、採用する業務フローに合わせて役割と記録を対応づけます。 この構成のデータモデルとSDKコード 1. 担当と判断者を決める 少人数のチームでも、操作する人、承認する人、障害時に再開を判断する人を明確にすると運用を引き継ぎやすくなります。以下は役割分担の例です。兼務する場合も、どの立場で判断したかを記録します。 役割 担当すること 残すもの 業務責任者 何の権利を、誰へ、何単位割り当てるかを決めます。契約・台帳上の条件変更も判断します。 権利の定義、対象契約、割当条件、業務上の完了基準。 実装担当 接続・認証・送信・結果取得・台帳反映を実装し、異常時の再開方法を検証します。 環境台帳、使用バージョン、テスト結果、反映処理の手順。 運用担当 依頼の受付、処理状況の監視、日次照合、問い合わせの一次対応を行います。 操作記録、照合結果、未解決の処理一覧。 承認・権限管理担当 発行や設定変更の内容を承認し、実行者の権限、停止・再開の判断者を管理します。 承認記録、権限一覧、変更履歴、緊急時の連絡先。 hazBaseのAPI・SDKとコントラクトは実行・照会の機能を提供します。以下の承認フロー、操作ID、監視、業務台帳は、連携するアプリケーション側で組み込む運用設計です。 2. 接続情報と設定を一枚にまとめる 検証用と本番用を別の台帳として管理します。URLだけを入れ替えると、別チェーンのアドレスや権限を引き継いでしまうため、次の情報を一組で確認します。例の値は説明用で、本番の接続先や利用条件を示すものではありません。 記録する項目 値・確認方法の例 確認担当 環境名・提供機能 validation / production。利用できるチェーン、書込機能、レート制限、問い合わせ先を利用環境ごとに確認。 実装・運用 apiEndpoint / chainId / RPC APIとRPCを分けて記録。SepoliaのchainIdは11155111。接続したRPCが返すchainIdとも照合。 実装 コントラクト・ABI・版 FlexibleTokenのアドレス、初期化内容、参照したソース版、デプロイ結果をセットで保存。 実装 SDK・アプリの版 例：@hazbase/kit 0.9.0。依存関係の固定ファイルと、実行するアプリのリリース番号も記録。 実装 資産・契約・数量 ROBOT-A-001、契約AGR-2027-001、cap=1000、decimals=0。移転可否とWhitelistの要否を定義。 業務責任者 署名者・操作権限 発行担当のアドレスとMINTER_ROLE、管理者、停止・再開権限を確認。台帳には鍵の管理先を記録し、秘密鍵そのものは置かない。 権限管理 認証・端末 Wallet APIを使う場合は許可Origin、端末登録、セッション期限、操作承認と失効手順を確認。 実装・権限管理 確定・復旧の基準 何をもってチェーン確定とするか、同期済みブロック、バックアップ先、復旧の判断者を記録。 実装・運用 環境と接続情報 認証とウォレット コントラクトの権限・運用設計 3. 検証から本番へ進める 下記は導入の進め方の例です。実施日数を固定するより、各段階で確認できたことと未解決の事項を残すと、業務責任者が開始を判断しやすくなります。 1 対象業務を一つに絞る 初回はROBOT-A-001の10単位割当だけを対象にします。誰が依頼し、誰が承認し、どの画面で完了を確認するかを定めます。 次へ進む目安 入力項目、承認条件、成功時の台帳表示が一つの手順として説明できる。 2 読み取りと接続を確認する 環境台帳を使い、対象チェーン、トークンのアドレス、decimals、cap、総発行数、受取先残高を確認します。APIの登録対象とコントラクト自体の状態も区別します。 次へ進む目安 対象が正しく、初回検証の残高0・総発行数0・上限1000を確認した記録がある。 3 少量の操作を最後まで通す 分離した検証環境で10単位を発行し、承認、実行結果、イベント、業務台帳の表示を同じ操作IDで追跡します。実装例のコードはこの段階で組み込みます。 次へ進む目安 対象宛先への発行、発行総数10、取引記録、業務画面の完了表示が一致する。 4 失敗と復旧を試す 二重クリック、送信後の応答欠落、権限不足、停止状態、台帳反映前の処理中断を試します。画面を再読込しても未解決の操作を追えることを確認します。 次へ進む目安 二重発行がなく、結果不明は再送されず、停止位置から照合を再開できる。 5 対象を限定して本番を開始する 本番用の設定・権限を改めて確認し、合意した宛先と数量だけで開始します。初回は担当者が受付から照合まで追い、問題がなければ対象件数を広げます。 次へ進む目安 業務責任者と運用担当が、照合結果・監視・緊急連絡先・再開手順を確認している。 4. 1件の割当をどう処理するか 担当者の画面とシステムの処理を次のように対応づけます。この例の割当は、新たに10単位を発行するmintです。発行済みトークンの移転であれば、発行者側の残高が減る別の処理になるため、依頼の種類も記録します。 担当者の操作 システムで行うこと 確認する結果 依頼を受け付ける 資産、契約、宛先、数量を保存し、業務側のoperationIdを発行。同じ依頼の再受付は既存の記録を返す。 ALLOC-2027-001 / MINT / 10 内容を承認する chainId、対象トークン、宛先、10単位を表示。承認後に値が変わる場合は、再承認を求める。 承認者、日時、承認した入力内容。 発行を実行する 権限、発行上限、停止状態を確認し、数量を最小単位に変換。処理を送信中として保存してからFlexibleTokenHelper.mintを呼ぶ。 decimals=0なので10単位は10。実行時の競合による失敗も記録。 実行結果を確認する 取得できた取引ハッシュとreceiptを保存。成功したreceipt、対象コントラクト、宛先、発行イベントの数量を照合する。 送信受付とチェーン上の実行成功を分ける。応答がない場合は「要確認」へ。 台帳へ反映する 対象チェーンの確定基準を満たした結果を業務台帳へ反映。取引ハッシュとイベント位置で処理済みかを確認する。 割当10、総発行数10。元の操作IDと取引から記録を追跡できる。 完了を案内する 台帳反映の成功後に画面と通知を更新。通知だけ失敗した場合は通知を再実行し、発行は繰り返さない。 取引先と担当者の画面が同じ処理状況を示す。 SDKの戻り値と送信途中の扱い @hazbase/kit 0.9.0のFlexibleTokenHelper.mintはTransactionReceiptを返します。戻り値を受け取ってから記録するだけでは、送信後に通信が切れた処理を見失うため、操作記録は呼び出し前に保存します。ハッシュを取得できないまま失敗した場合も、失敗確定とは扱わず照合へ進めます。 発行・残高のSDK仕様 発行・移転・運用の基本 5. 操作記録と処理状態を残す 以下は連携アプリケーション側の記録例です。hazBase APIのリクエスト形式ではありません。アドレスとハッシュは省略しています。契約原本と個人情報はアクセス制御した保管先で管理し、この記録からIDで関連づけます。 allocation-record.json 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 { "operationId" : "ALLOC-2027-001" , "operationType" : "MINT" , "assetId" : "ROBOT-A-001" , "agreementId" : "AGR-2027-001" , "chainId" : 11155111 , "tokenAddress" : "" , "recipient" : "" , "amountAtomic" : "10" , "decimals" : 0 , "approvalRecordId" : "APPROVAL-001" , "status" : "RECONCILED" , "sourceEvent" : { "transactionHash" : "" , "blockNumber" : 1234567 , "blockHash" : "" , "logIndex" : 0 } , "reconciliation" : { "allocatedAtomic" : "10" , "totalSupplyAtomic" : "10" , "asOfBlock" : 1234567 } } 数量は最小単位の文字列として保存すると、桁数が大きい場合も丸めを避けられます。承認時の入力、各段階の日時、実行者、再試行履歴も関連づけます。同じoperationIdへの入力変更や同時実行は、業務DBの一意制約・排他制御などで扱います。IDを記録するだけでは二重実行を防げません。 業務側の状態例 この状態になるとき 次に行うこと AWAITING_APPROVAL 入力を受け付け、宛先・数量の承認を待っている。 承認した値を固定してから実行へ。取消なら履歴を残して終了。 SUBMITTING 承認済みの処理を送信している。応答はまだ得られていない。 二重送信を抑止。通信断や処理中断ならNEEDS_REVIEWへ。 CONFIRMING 追跡できるハッシュがある、または実行結果を得たが、確定基準や照合は未完了。 状態とイベントを確認。反映基準を満たすまで完了通知は保留。 RECONCILED 実行内容を確認し、確定基準を満たして台帳へ反映済み。 完了を案内。通知の再送と発行の再実行を分ける。 NEEDS_REVIEW 送信結果不明、同期の不整合、宛先・数量の不一致などがある。 自動再送を止め、元の取引と記録を照合する。 FAILED 未実行または失敗を、チェーンや実行経路の情報で確認できた。 原因を修正し、再実行の判断と承認を記録。元の履歴を残す。 Wallet APIを使う場合の追跡情報 移転ではsubmitTransferの応答にあるsubmittedUserOpHash、transactionHash、relayModeなどを保存し、getTransferStatusへ元の宛先・数量・userOpHashなどを渡して状態を確認します。必要な認証も引き継ぎます。localUserOpHashだけで送信済みとは判断せず、status、confirmed、errorCodeと対象の取引内容を合わせて確認します。 移転の送信と戻り値 移転の状態確認 所有者操作の状態確認 6. 毎日の運用で見るもの 監視画面には「APIが動いているか」だけでなく、「受け付けた業務が完了しているか」を表示します。以下は確認の頻度と基準の例です。通知までの時間や再試行間隔は、チェーンの確定特性、処理量、提供環境の制限に合わせて設定します。 タイミング 確認する内容 問題がある場合 処理の実行中 送信中・確定待ちの件数と最古の受付時刻、API/RPCのエラー率、状態照会の結果。retryAfterMsがある場合は照会間隔に反映。 自社で定めた滞留時間を超えたものを運用担当へ通知。書き込みを自動で繰り返さない。 要確認が発生したとき NEEDS_REVIEWの操作ID、最後に成功した段階、取得済みのハッシュ、対象資産と数量。 担当者を割り当て、照合結果と次の判断を同じ記録に残す。 日次の締め 受付・完了・失敗・未解決の件数を突合し、割当台帳とチェーン上の残高・イベントを同じ基準時点で照合。 差分を資産ID・操作IDで一覧化。後続の移転やバーンも含めて調べる。 定期点検・担当変更時 操作権限、端末、署名手段、利用費用、通知先、未使用アカウントを確認。 不要な権限を失効し、権限台帳と連絡先を更新。 定期の復旧訓練 バックアップから業務台帳を復元し、同期済みブロックからイベントを読み直せるかを確認。 復元時間、失われた記録の範囲、再開までの手順を見直す。 イベントの重複とチェーンの巻き戻り 取り込んだイベントはchainId・transactionHash・logIndexで識別し、再取得しても二重反映しないようにします。同期位置にはブロック番号とブロックハッシュを保存します。ブロックハッシュが変わった場合は、その範囲から作った台帳の参照データを巻き戻して読み直し、解消するまで該当操作を要確認として扱います。 APIの残高と業務DBの残高を比較する際は、取得時刻や集計範囲の差も確認します。ブロックを固定した照会が必要な場合は対応するRPC・ABIの読み取りを使い、最新値同士の単純比較だけで不整合を確定しないようにします。 取引履歴と取得範囲 残高の照会 7. 異常が起きたときの対応 まず対象の操作を特定し、新しい送信を控えながら、どこまで進んだかを確認します。単なる通信障害と不正な操作の疑いでは停止する範囲が異なります。業務受付の保留と、コントラクト全体のpauseは分けて判断します。 送信した直後にタイムアウトした 最初の確認 操作IDと取得済みのハッシュを確認します。Wallet APIなら対応する状態取得API、直接実行ならRPCのreceipt・送信者・nonce・イベントを調べます。receiptが見つからないだけでは未実行とは断定できません。 対応 実行済みなら台帳反映から再開します。ハッシュがなく処理を一意に特定できない場合は要確認を維持し、時刻・送信者・対象を添えて実装担当へ引き継ぎます。 再開の条件 成功した元の処理を特定するか、未送信・失敗・置換の状況を確認できた後に、再実行の要否を判断できる。 チェーンでは成功したが、台帳が更新されない 最初の確認 receiptの成功と発行イベントの宛先・数量を確認し、DB更新処理と同期位置を調べます。 対応 発行は再実行せず、確定したイベントの取り込みと台帳更新だけを再開します。すでに取り込んだイベントは除外します。 再開の条件 同じ操作IDに元の取引が紐づき、台帳の数量と基準時点の残高が一致している。 権限不足・期限切れ・停止状態で失敗した 最初の確認 実行主体、必要なロール、認証の期限、対象コントラクトの停止状態を確認します。失敗が確定しているかも調べます。 対応 必要な範囲で権限・認証を修正し、元の依頼の有効性を再確認します。停止の解除は、停止理由が解消されたことを判断者が確認してから行います。 再開の条件 設定と実行条件が確認され、失敗した試行を残したまま、承認済みの内容で次の試行へ進める。 残高・数量・宛先が想定と一致しない 最初の確認 chainId、tokenAddress、decimals、承認時の入力、照合ブロックを順に確認します。その後に移転やバーンが行われていないかも調べます。 対応 不一致の原因が分かるまで対象業務を保留します。確定した発行・移転は、アプリを元に戻しても取り消されません。修正操作が必要なら別の承認と記録を用意します。 再開の条件 差分の理由と必要な修正が説明でき、業務責任者と運用担当が照合結果を確認している。 認証情報や操作権限の不正利用が疑われる 最初の確認 影響する端末・署名者・コントラクトと操作履歴を確認し、権限管理担当へ連絡します。 対応 状況に応じて端末や権限を失効し、必要な対象を停止します。EmergencyPauseManagerを使う場合も、個別の失敗イベントと各対象の停止状態を確認します。 再開の条件 影響範囲の照合、認証・権限の更新、少量の確認操作を終え、指定した判断者が再開を承認している。 エラー別の切り分け 停止・再開の仕様 8. 更新・変更を安全に引き継ぐ SDK、アプリ、コントラクト、権限はそれぞれ別の変更です。変更依頼には対象、現在値と変更後の値、影響する業務、確認方法、実施者と承認者を記載します。 変更するもの 実施前後に確かめること SDK・アプリ 変更履歴と型の差分を確認し、読み取り・10単位割当・結果不明からの復旧を検証。旧版へ戻す場合も、新しいDB記録との互換性を確認する。 コントラクト・初期設定 実装方式、ABI、管理権限と状態の互換性を確認。Factoryへの新しい版の登録だけで既存の配置が変わるわけではないため、対象アドレスごとに扱う。 権限・担当者 変更後の担当者で必要な操作を確認し、旧担当者の不要な権限と端末を失効。緊急連絡先と承認記録も更新する。 変更後は少量の操作を照合してから対象を広げます。受付の一時保留が必要な場合は、処理中の依頼と新規依頼の扱いを分け、再開時に未解決一覧から確認できるようにします。 変更履歴 SDKの対象バージョン コントラクト生成とバージョン 9. 運用開始前の引き継ぎ確認 引き継ぎは、説明を聞くだけでなく、運用担当者が操作IDから状況を調べ、次の対応を選べるかで確認できます。以下がそろうと、開始可否を判断しやすくなります。 環境台帳：本番の接続先、アドレス、SDK・ABIの版、権限と管理先がそろっている。 成功の記録：10単位割当について、承認、取引、確定の判断、台帳表示を追跡できる。 復旧の記録：二重クリック、応答欠落、台帳反映失敗を試し、発行を重複させずに処理を再開できる。 監視と日次照合：通知先、滞留の基準、照合時点、未解決の担当者が決まっている。 継続体制：代行担当、権限失効、バックアップ復元、変更時の再検証、停止・再開の判断者を確認している。 技術窓口へ渡す情報 連絡時は、発生日時とタイムゾーン、環境名、chainId、コントラクト、SDK・アプリの版、操作ID、取得できた取引ハッシュ、HTTPステータス・errorCode、想定と実際の結果をまとめます。再送したかどうかと、最後に成功した段階もあると調査を進めやすくなります。 秘密鍵、OTP、セッションやhighTrustToken、顧客の個人情報はそのまま添付せず、必要な範囲を伏せて共有します。リクエストIDは問い合わせの追跡用として使い、二重実行防止用のoperationIdとは分けて扱います。 割当の実装例に進む 技術・導入のご相談