導入・運用ガイド

このガイドで扱う運用例

配送ロボットROBOT-A-001に関する契約上の権利を、上限1,000単位・小数桁0のFlexibleTokenで管理する例です。初回の割当では10単位を新規発行し、取引先のウォレットに付与します。開始時点の発行済み総数と取引先の残高はいずれも0とします。

操作IDは業務側の受付番号、取引ハッシュはチェーン上の取引の識別番号、receiptは実行結果の記録です。この三つを結び付けることで、担当者は依頼から実行結果までを追跡できます。

これはAPI・SDKを自社システムに組み込む構成例です。設備・在庫・利用権などでも、対象IDと権利の定義を置き換えて同じ運用の考え方を使えます。RWA OpsやFund Opsを利用する場合は、採用する業務フローに合わせて役割と記録を対応づけます。

1. 担当と判断者を決める

少人数のチームでも、操作する人、承認する人、障害時に再開を判断する人を明確にすると運用を引き継ぎやすくなります。以下は役割分担の例です。兼務する場合も、どの立場で判断したかを記録します。

hazBaseのAPI・SDKとコントラクトは実行・照会の機能を提供します。以下の承認フロー、操作ID、監視、業務台帳は、連携するアプリケーション側で組み込む運用設計です。

2. 接続情報と設定を一枚にまとめる

検証用と本番用を別の台帳として管理します。URLだけを入れ替えると、別チェーンのアドレスや権限を引き継いでしまうため、次の情報を一組で確認します。例の値は説明用で、本番の接続先や利用条件を示すものではありません。

3. 検証から本番へ進める

下記は導入の進め方の例です。実施日数を固定するより、各段階で確認できたことと未解決の事項を残すと、業務責任者が開始を判断しやすくなります。

1. 1

   対象業務を一つに絞る

   初回はROBOT-A-001の10単位割当だけを対象にします。誰が依頼し、誰が承認し、どの画面で完了を確認するかを定めます。

   次へ進む目安

   入力項目、承認条件、成功時の台帳表示が一つの手順として説明できる。

2. 2

   読み取りと接続を確認する

   環境台帳を使い、対象チェーン、トークンのアドレス、decimals、cap、総発行数、受取先残高を確認します。APIの登録対象とコントラクト自体の状態も区別します。

   次へ進む目安

   対象が正しく、初回検証の残高0・総発行数0・上限1000を確認した記録がある。

3. 3

   少量の操作を最後まで通す

   分離した検証環境で10単位を発行し、承認、実行結果、イベント、業務台帳の表示を同じ操作IDで追跡します。実装例のコードはこの段階で組み込みます。

   次へ進む目安

   対象宛先への発行、発行総数10、取引記録、業務画面の完了表示が一致する。

4. 4

   失敗と復旧を試す

   二重クリック、送信後の応答欠落、権限不足、停止状態、台帳反映前の処理中断を試します。画面を再読込しても未解決の操作を追えることを確認します。

   次へ進む目安

   二重発行がなく、結果不明は再送されず、停止位置から照合を再開できる。

5. 5

   対象を限定して本番を開始する

   本番用の設定・権限を改めて確認し、合意した宛先と数量だけで開始します。初回は担当者が受付から照合まで追い、問題がなければ対象件数を広げます。

   次へ進む目安

   業務責任者と運用担当が、照合結果・監視・緊急連絡先・再開手順を確認している。

4. 1件の割当をどう処理するか

担当者の画面とシステムの処理を次のように対応づけます。この例の割当は、新たに10単位を発行するmintです。発行済みトークンの移転であれば、発行者側の残高が減る別の処理になるため、依頼の種類も記録します。

5. 操作記録と処理状態を残す

以下は連携アプリケーション側の記録例です。hazBase APIのリクエスト形式ではありません。アドレスとハッシュは省略しています。契約原本と個人情報はアクセス制御した保管先で管理し、この記録からIDで関連づけます。

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": "<token address>",
  "recipient": "<approved recipient>",
  "amountAtomic": "10",
  "decimals": 0,
  "approvalRecordId": "APPROVAL-001",
  "status": "RECONCILED",
  "sourceEvent": {
    "transactionHash": "<transaction hash>",
    "blockNumber": 1234567,
    "blockHash": "<block hash>",
    "logIndex": 0
  },
  "reconciliation": {
    "allocatedAtomic": "10",
    "totalSupplyAtomic": "10",
    "asOfBlock": 1234567
  }
}

数量は最小単位の文字列として保存すると、桁数が大きい場合も丸めを避けられます。承認時の入力、各段階の日時、実行者、再試行履歴も関連づけます。同じoperationIdへの入力変更や同時実行は、業務DBの一意制約・排他制御などで扱います。IDを記録するだけでは二重実行を防げません。

6. 毎日の運用で見るもの

監視画面には「APIが動いているか」だけでなく、「受け付けた業務が完了しているか」を表示します。以下は確認の頻度と基準の例です。通知までの時間や再試行間隔は、チェーンの確定特性、処理量、提供環境の制限に合わせて設定します。

イベントの重複とチェーンの巻き戻り

取り込んだイベントはchainId・transactionHash・logIndexで識別し、再取得しても二重反映しないようにします。同期位置にはブロック番号とブロックハッシュを保存します。ブロックハッシュが変わった場合は、その範囲から作った台帳の参照データを巻き戻して読み直し、解消するまで該当操作を要確認として扱います。

APIの残高と業務DBの残高を比較する際は、取得時刻や集計範囲の差も確認します。ブロックを固定した照会が必要な場合は対応するRPC・ABIの読み取りを使い、最新値同士の単純比較だけで不整合を確定しないようにします。

7. 異常が起きたときの対応

まず対象の操作を特定し、新しい送信を控えながら、どこまで進んだかを確認します。単なる通信障害と不正な操作の疑いでは停止する範囲が異なります。業務受付の保留と、コントラクト全体のpauseは分けて判断します。

8. 更新・変更を安全に引き継ぐ

SDK、アプリ、コントラクト、権限はそれぞれ別の変更です。変更依頼には対象、現在値と変更後の値、影響する業務、確認方法、実施者と承認者を記載します。

変更後は少量の操作を照合してから対象を広げます。受付の一時保留が必要な場合は、処理中の依頼と新規依頼の扱いを分け、再開時に未解決一覧から確認できるようにします。

9. 運用開始前の引き継ぎ確認

引き継ぎは、説明を聞くだけでなく、運用担当者が操作IDから状況を調べ、次の対応を選べるかで確認できます。以下がそろうと、開始可否を判断しやすくなります。

• 環境台帳：本番の接続先、アドレス、SDK・ABIの版、権限と管理先がそろっている。
• 成功の記録：10単位割当について、承認、取引、確定の判断、台帳表示を追跡できる。
• 復旧の記録：二重クリック、応答欠落、台帳反映失敗を試し、発行を重複させずに処理を再開できる。
• 監視と日次照合：通知先、滞留の基準、照合時点、未解決の担当者が決まっている。
• 継続体制：代行担当、権限失効、バックアップ復元、変更時の再検証、停止・再開の判断者を確認している。

技術窓口へ渡す情報

連絡時は、発生日時とタイムゾーン、環境名、chainId、コントラクト、SDK・アプリの版、操作ID、取得できた取引ハッシュ、HTTPステータス・errorCode、想定と実際の結果をまとめます。再送したかどうかと、最後に成功した段階もあると調査を進めやすくなります。

秘密鍵、OTP、セッションやhighTrustToken、顧客の個人情報はそのまま添付せず、必要な範囲を伏せて共有します。リクエストIDは問い合わせの追跡用として使い、二重実行防止用のoperationIdとは分けて扱います。