Rosetta

Rosetta は、取引所、ブロックエクスプローラー、ウォレットにおけるブロックチェーンベーストークンの統合を簡素化するために Coinbase が導入したオープンスタンダードです。 CeFi の取引所で取引できることを目指したトークンを IC 上にデプロイしたい場合や、ブロックエクスプローラーやウォレットに取り組んでいる場合、このドキュメントが役に立つはずです。

Rosetta ノードのセットアップ

Rosetta API に対応したノードをセットアップして、Internet Computer と対話し、Internet Computer Protocol (ICP) トークンを交換することができます。 手順をシンプルにするため、Rosetta API との統合を作成するためにDocker イメージを使用します。 また、ソースコードを使ってバイナリをビルドして実行することもできます。 Docker がまだインストールされていない場合は、最新版をダウンロードしてインストールしてください。

Rosetta ノード（testnet に接続する）をセットアップするには：

1. Docker のインストール と Docker daemon を起動します。

   コンピュータを再起動すると、Docker デーモン（dockerd）が自動的に起動するはずです。手動で Docker デーモンを起動する場合は、ローカルのオペレーティングシステムによって手順が異なります。

2. 以下のコマンドを実行し、Docker Hub から最新の dfinity/rosetta-api イメージを取得します：

   docker pull dfinity/rosetta-api

3. 以下のコマンドを実行して、統合ソフトを起動します：

   docker run \
       --interactive \
       --tty \
       --publish 8080:8080 \
       --rm \
      dfinity/rosetta-api

   このコマンドは、ローカルホスト上でソフトウェアを起動し、次のような出力を表示します：

   Listening on 0.0.0.0:8080
   Starting Rosetta API server

   デフォルトでは、このソフトウェアはテストネットに接続します。 Internet Computer ブロックチェーンメインネット上で動作している台帳 Canister には接続しません。

   テストネットワークとそれに対応する台帳 Canister の識別子が割り当てられている場合、追加の canister 引数を指定することで、そのネットワークに対してコマンドを実行することができます。 たとえば、次のコマンドでは canister 引数を 2xh5f-viaaa-aaaab-aae3q-cai に設定して、テストネットワーク上の台帳 Canister に接続する例を示しています。

   docker run \
       --interactive \
       --tty \
       --publish 8080:8080 \
       --rm \
      dfinity/rosetta-api \
      --canister 2xh5f-viaaa-aaaab-aae3q-cai
   note

   最初にこのコマンドを実行したとき、ノードがチェーンの現在のリンクに追いつくまで、いくらか時間がかかるかもしれません。 ノードが追いつくと、以下のような出力が表示されるはずです。

   You are all caught up to block height 109

   このステップの完了後、ノードはブロック作成に参加しない passive ノードとして実行を継続します。

4. 新しいターミナルウィンドウまたはタブを開いて ps コマンドを実行し、サービスの状態を確認します。

   サービスを停止する必要がある場合は、Ctrl-C を押してください。例えば、使用している Canister の識別子を変更するために、この操作を行いたい場合があります。

   ノードのセットアップ後に統合をテストするには、Principal がトランザクションを送信したり、口座残高を検索したりすることをシミュレートするプログラムを作成する必要があります。

Rosetta ノードをプロダクトモードで稼動する

テストが終わったら、 --interactive、 --tty、--rm コマンドラインオプションを指定せずに、プロダクトモードで Docker イメージを実行する必要があります。 これらのコマンドラインオプションは、インタラクティブなターミナルセッションをアタッチし、コンテナを削除するために使用され、主にテスト目的のために用意されています。 プロダクト環境で実行する場合は、--detach オプションを使用して Docker イメージを起動し、コンテナをバックグラウンドで実行し、オプションとしてブロックを保存するための --volume コマンドを指定します。

Rosetta ノードインスタンスをメインネットに接続するためにフラグを追加します。--mainnet と --not-whitelisted を追加します。

Docker のコマンドラインオプションの詳細については、Docker reference documentation を参照してください。

要求事項と制限事項

Docker イメージで提供される統合ソフトウェアには、Rosetta API の標準仕様にはない要件がひとつあります。

ICP トークンを含むトランザクションでは、署名なしトランザクションはネットワークが署名付きトランザクションを受け取る24時間以内に作成されなければなりません。 その理由は、各トランザクションの ‘created_at’ フィールドが、既存のトランザクション（基本的にはトランザクション作成時にローカルで利用可能な last_index）を参照しているからです。 あまりにも古いトランザクションを参照するトランザクション送信は、運用効率を維持するために拒否されます。

この要件以外では、Rosetta API 統合ソフトウェアは、すべての標準的な Rosetta エンドポイントに完全に準拠し、rosetta-cli のテストに合格しています。 ソフトウェアはあらゆる有効な Rosetta リクエストを受け入れることができます。 しかし、この統合ソフトウェアは、ここにリストされているすべての署名スキームではなく、Ed25519 を使用して署名するトランザクションを要求するだけです。そのため仕様でサポートされている潜在的なレスポンスだけが小さなサブセットとして返信されています。 例えば、このソフトウェアは Rosetta の UTXO 機能を実装していないため、ソフトウェアの応答に UTXO メッセージが含まれることはないでしょう。

よくある質問

以下の質問は、Rosetta と Internet Computer の連携に関して、開発者コミュニティからよく報告される質問とエラー等をまとめたものです。

Rosetta ノード

Rosetta ノードのインスタンスを実行するにはどうしたらいいですか？

これを実現する簡単な方法は、dfinity/rosetta-api Docker イメージを使用することです。 ノードが初期化され、全てのブロックが同期されると、ノード上で Rosetta API を呼び出してクエリを実行したり、トランザクションを送信したりすることができます。 ノードは 8080 ポートでリッスンします。

Rosetta ノードをメインネットに接続するにはどうしたらいいですか？

フラグの --mainnet と --not-whitelisted を使用します。

Rosetta ノードをメインネットに接続するにはどうしたらいいですか？

フラグの --mainnet と --not-whitelisted を使用します。

ノードがテストネットに追いついたかどうかは、どうすれば分かりますか？

Rosetta API サーバーの起動ログを検索してください。You are all caught up to block XX というログエントリーがあるはずです。 このメッセージは、すべてのブロックに追いついていることを確認するものです。

同期されたブロックデータを永続化するには？

data ディレクトリを ボリューム としてマウントします。

docker volume create rosetta

docker run \
    --volume rosetta:/data \
    --interactive \
    --tty \
    --publish 8080:8080 \
    --rm \
   dfinity/rosetta-api

Rosetta ノードはバージョン管理されていますか？

はい、定期的に DockerHub で新バージョンを公開しています。 プロダクト環境では dfinity/rosetta-api:v1.7.0 のように、特定のバージョンを使用することをお勧めします。 /network/options エンドポイントを使用すると、実行中の Rosetta ノードのバージョンを照会することができます。

$ curl -s -q -H 'Content-Type: application/json' -d '{"network_identifier": {"blockchain": "Internet Computer", "network": "00000000000000020101"}}' -X POST http://localhost:8080/network/options | jq '.version.node_version'

"1.7.0"

ICP 固有のRosetta API の詳細

アカウントの生成と検証はどのように行われるのですか？

• ED25519 キーペアを生成します。
• 秘密鍵はトランザクションに署名するために使用されます。
• 公開鍵は、自己認証の Principal ID を生成するために使用されます。詳細は、Section Principals in the Interface Specification を参照してください。
• Principal ID はハッシュ化されるとアカウントアドレスが生成されます。

公開鍵を使って、そのアカウントアドレスを生成する方法は？

• 16進数（hex）エンコードされた 32バイトの公開鍵で /construction/derive エンドポイントを呼び出します。
• JavaScript SDK の pub_key_to_address 関数を呼び出します。

アカウントアドレスのチェックサムを確認する方法は？

• 16進数（hex）デコード後、最初の 4バイトはアドレスの残りの部分のビッグエンディアンの CRC32 チェックサムです。
• JavaScript SDK でaddress_from_hex を呼び出してください。チェックサムが一致しない場合はエラーを返します。
• アドレス検証ロジックの Java 実装はこちらです。

ED25519 の signature_type と curve_type とは何ですか？

• signature_type とは "ed25519" のことです。
• curve_type とは "edwards25519" のことです。

ロックに表示される取引にはどのような種類があり、どのような意味があるのでしょうか？

• エンドポイント/block から照会される各ブロックには、正確に1つのトランザクションが含まれます。 burn などのいくつかの操作は、Rosetta API コールではサポートされていないことに注意してください。

• Transfer

  • 操作0: "TRANSACTION" と入力し、送金元のアカウントから送金数を引きます。
  • 操作1: "TRANSACTION" と入力し、同じ送金数を送金先のアカウントに追加します。
  • 操作2: "FEE" と入力し、送金元のアカウントから手数料を引きます。
  note

  前のポイントで提示した操作の順番に依存してはいけません。 システムは /construction/payloads 呼び出しに渡された操作を並べ替えることができます。 代わりに、トランザクションの種類と金額の符号をチェックする必要があります。

• Mint

  • 操作0：タイプ "MINT”、ミント額を送金先アカウントに追加します。

• Burn

  • 操作 0: "BURN" と入力し、ソースアカウントからバーンの金額を引きます。

• "status" はいつも "COMPLETED". 失敗した取引は台帳に表示されません。

どのような料金が必要ですか？料金のカスタマイズは可能ですか？

• /construction/metadata を呼び出すことで、suggested_fee を取得することができます。
• 現時点では、suggested_fee は定数であり、送金時に指定する料金はこれと等しくなければなりません。
• 手数料は Mint や Burn の操作には適用されません。

送信されたトランザクションがチェーンにヒットしたかどうかを知るにはどうすればよいですか？

• Rosetta サーバーは /construction/submit を呼び出した後、しばらく待つ必要があります。トランザクションがチェーンにヒットした場合、サーバーはブロックハッシュを返します。

• 台帳からエラーが出た場合は、/construction/submit の結果でエラー情報を得ることができます。

• /construction/submit の呼び出しが正常に返されたとしても、それがチェーンにヒットするまでにはまだ時間がかかる可能性があります。 最新のブロックをポーリングして、トランザクションハッシュを検索することができます。 Rosetta ノードは /search/transactions インターフェースのサブセットもサポートしており、ハッシュが与えられたトランザクションを検索することができます。

• 最悪の場合、５分でタイムアウトです。

• mempool API を使用しないでください。空のスタブ実装となっています。

Rosetta API の呼び出しで、どのようなエラーが発生する可能性がありますか？

• 呼び出しに成功すると、常に 200 応答ステータスコードが表示されます。
• 失敗した呼び出しには、常に 500 応答ステータスコードがあり、より詳細な情報を含む JSON ペイロードがあります。 すべての Rosetta エラーコードとそのテキスト説明は、/network/options のコール結果に記載されています。

Mint や Burn のトランザクションを送信するにはどうすればよいですか？

• Mint は高いレベルのアクセス権（特権）が必要な操作です。現在、Rosetta API コールによる Burn はサポートしていません。

同じ署名付きトランザクションを複数回送信した場合はどうなりますか？

台帳は重複したトランザクションを拒否します。 最初のトランザクションだけがチェーンに登録されます。/construction/submit の呼び出しは、重複したトランザクションに対して失敗します。

Rosetta API を呼び出さずに署名する方法は？

JavaScript SDK には、オフライン署名ロジックの 実装 が含まれています。 この機能は内部実装の詳細と連動しているため不安定であり、可能であれば /construction/combine を呼び出してトランザクションに署名することを強く推奨します。

イングレスの時間帯を設定するには？

construct/payloads の呼び出しでは、 ingress_start / ingress_end フィールドを一つまたは全て追加して、イングレスの時間帯を指定することができます。 これらは Unix のエポックからのナノ秒であり、次の 24時間以内である必要があります。 ingress_start / ingress_end フィールドを追加すると、トランザクションの生成と署名が可能になりますが、送信は後に延期されます。

署名付きトランザクションをデシリアライズする方法は？

Rosetta ノードの /construction/parse エンドポイントを使用します。 この機能は、オフラインモードでも使用できます。