これは chaintope 社が開発するブロックチェーン Tapyrus を使ったブロックチェーンに関係する機能を簡単に利用するための REST API です。 現在以下のユースケースをサポートしています。これは今後も拡張されていきます。

• Timestamp: 任意のデータをタイムスタンプとしてブロックチェーンに記録
• Token: 新しいトークンの発行、送金、焼却。NFTも利用可能
• Tracking: トレーサビリティを目的としてたサブジェクトの移動履歴を記録

また、以下の機能をベータ版として提供しています。

• MaterialTracking: 製品に含まれる原材料の量を秘匿したまま、サプライチェーンにおけるアイテムの移動履歴を記録

Tapyrus ブロックチェーンについては以下の情報を参照してください。

• Chaintope のブロックチェーンプロトコル
• chaintope/tapyrus-core - github

Tapyrus API は REST API として提供されています。利用を開始するためには、Tapyrus API の エンドポイント に対して、 認証 済みの トークンを使いアクセスする必要があります。また、認証されたユーザーはそれぞれが自身のウォレットを Tapyrus API 内部に持つことになります。 ウォレットではそのユーザーのトークンなどのアセットを管理するための鍵が管理され、アセットの移動などで利用されます。

Tapyrus API のエンドポイント

エンドポイントは以下のフォーマットで作成されます。

https://xxx.api.tapyrus.chaintope.com/api/v1

xxxの部分は各ユーザー固有の識別子になります。正式なURLは、ダッシュボードで確認できます。

API接続の準備

ダッシュボードに登録すると、chaintopeが登録情報を確認後、お客様のAPIエンドポイントを設定します。 エンドポイントが設定されるまでは、APIの機能はご利用いただけません。

クライアント証明書

Tapyrus APIに接続する際には、クライアント証明書が必要になります。ダッシュボードの「クライアント証明書」のメニューより、 クライアント証明書を発行してください。 発行すると秘密鍵と公開鍵の証明書を含むPKCS#12形式のファイルがダウンロードできます。

ユーザーの登録

ダッシュボードからAPIに接続するユーザーを作成します。Tapyrus APIではユーザー単位にウォレットが作成されます。 ウォレットではアセットの受け取りや、送付に必要な公開鍵と秘密鍵のペアが管理されています。 そのため、認証を行ったユーザーごとに独立したアセットの管理が可能になります。

ダッシュボードの、「ユーザー一覧」からアクセスするユーザーを作成することができます。 ユーザーを作成すると、そのユーザー用のアクセストークンが発行されます。このアクセストークンとクライアント証明書の両方が漏洩すると、 不正アクセスが可能になるため、データの取り扱いには十分注意してください。

接続確認

クライアント証明書とユーザーが作成されると、APIにアクセスできるようになります。簡単な接続確認は、curlで以下のように行なえます。

1. ダウンロードしたPKCS#12ファイルからcert.pemを生成。 $ openssl pkcs12 -in <ダウンロードした.p12ファイルのパス> -out cert.pem -nodes -clcerts
2. cert.pemとアクセストークンを使ってAPIへアクセス。 $ curl -X GET -H 'Authorization: Bearer <ユーザーのアクセストークン>' "https://xxx.api.tapyrus.chaintope.com/api/v1/timestamps" -E cert.pem

成功するとAPIへのアクセスが可能になっています。これらの認証情報を使って、以下に記載する各APIがご利用いただけます。

タイムスタンプ V2 API

タイムスタンプ V1 API

トークン V2 API

トークン V1 API

トラッキングAPI

この機能は現在ベータ版としてのみ提供しています。 以下の制限にご注意ください

• ベータ版の期間中にAPIのパラメータやパスに変更が加えられる可能性があります。ご利用中のアプリケーションやシステムのコードを定期的に確認してください。
• ベータ版では、データベースのデータ構成に関して変更が加えられる可能性があります。ベータ版を使用して登録されたデータについてはその後のバージョンで参照される際に制約を受けるなどの影響が出る可能性があります。ただし、Tapyrus ブロックチェーンに記録されたトランザクションについては変更されることはありません。

マテリアルトラッキング API(ベータ版) は、製品に含まれる原材料の量を秘匿したまま、 サプライチェーンにおける原材料のトレースを可能にするため のプロトコルを REST API から実行可能にするものです。 これは例えば、原材料、メーカー、サプライヤー、リサイクル事業者を通じて移動する製品の 原材料の量を第三者から秘匿したまま追跡することを可能にします。

トラッキング対象の アイテム は複数の材料 (マテリアル) とその量で構成されます。Tapyrus ブロックチェーン上にはこれら から計算されたコミットメント(*1) が記録され、各種材料の量が直接記録されることはありません。これによって、製品の原材料の量を秘匿したままトレースを可能にします。

またこの API は、材料について秘匿された状態のまま、各取引で不正な材料の混入がないことを検証可能にするという特徴があります。 これによりサプライチェーンの監査コストを削減できる可能性があります。

※注意

アイテムの詳細は Tapyrus ブロックチェーンには記録されず秘匿されますが、同一の Tapyrus API エンドポイントを利用しているユーザは取得できます。 アイテムの詳細の公開範囲を厳密に管理する必要がある場合は、ご利用の API エンドポイントへのアクセス権の管理にご注意ください。

(*1): コミットメントとは、暗号学の手法で、ある情報を秘密にして固定（コミット）し、後からその情報を公開（オープン）することができるものを指します。この手法では、情報は変更できず、予め公開された証拠でその正当性が確認できます。

マテリアルトラッキングを利用するためには、まずマテリアルトラッキング専用のアドレスを作成する必要があります。 このアドレスは、特定の場所、工場、工程、またはサプライチェーンの参加者を識別する識別子として機能し、トラッキング対象のアイテムを操作できる権限が誰にあるのかを示します。 アイテムは常にアドレスに所属し、そのアドレスに対応する秘密鍵を使用してのみ操作することができます。

アイテムは追跡対象物を表します。アイテムは複数種類の材料から構成され、材料は「材料名（name）」「量（quantity）」「単位（unit）」で表現されます。 例えば、「アルミニウム100キログラム」「銅200グラム」などがアイテムの構成要素となり得ます。 アイテムは、Tapyrusブロックチェーン上に対応するトランザクション出力と対応します。

• 鋳造(Mint) は新しいアイテムをTapyrusブロックチェーン上に登録する操作です。
• 輸送(Transfer) は既に登録されたアイテムを別のトラッキングアドレスに転送する操作です。1つのアイテムを分割して複数の送り先に送ることや、複数のアイテムを1つの送り先に送ることも可能です。
• 焼却(Burn) はアイテム、またはアイテムの一部をこれ以上転送できない状態にする操作です。アイテムが全て消費された場合や、アイテムの一部が消費された場合に行われます。また、加工や選別等によりアイテムに含まれる材料の量が減少した場合にもこの操作が行われます。

1 回の処理でこれらのオペレーションを組み合わせることができます。 その 1 回の処理は、１つの Tapyrus トランザクションとしてブロックチェーンに記録されます。

マテリアルトラッキング API は以下の特徴を持ちます。

• 製品に含まれる材料の量や割合を秘匿したまま Tapyrus ブロックチェーンに記録できる
• 各取引で不正な材料の混入がないことを検証可能にする

マテリアルトラッキング API に送られる材料の内訳は、Tapyrus API のデータベースに保存されますが、公開される Tapyrus ブロックチェーンにはそのまま記録されることはなく、 第三者から完全に秘匿されます。 具体的には、材料の情報とブラインドファクターから計算されたコミットメントだけが、 Tapyrus ブロックチェーンに記録されます。

マテリアルトラッキング API の重要な特徴として、１回の処理（１つのトランザクション）の前後で材料の種類や量が変化しないことを誰でも検証できることが挙げられます。 この検証には材料の内訳といった秘匿された情報は必要ありません。 ブロックチェーンに記録されたコミットメントをもとに暗号学的に検証することができます。

3つのオペレーションのうち鋳造だけがこの検証に含まれません。 サプライチェーンにおける鋳造のプロセスの安全性だけを担保することができれば、 そのサプライチェーンで流通するアイテムや材料は、サプライチェーンの末端に至るまで不正に水増しされていないことを誰でも検証できるようになると言えます。

この特徴を利用することでサプライチェーンの過程でおこる不正な材料の混入を低コストで検知することができます。

検証の流れ

検証の方法について簡単に説明します。

1. Tapyrus Core ノードを Tapyrus API が使用するブロックチェーンに参加する設定で起動し、同期を完了させます
2. 検証を実施したい Tapryus トランザクションの入力のコミットメントと出力のコミットメントを取得します
3. 入力のコミットメントの合算値と出力のコミットメントの合算値の差を計算し、これが楕円曲線上の無限遠点になっていることを確認します

この検証に成功すると、対象の Tapyrus トランザクションは入力と出力の間で材料の種類や量が変化していないことが保証されます。

マテリアルトラッキング API の利用を開始するにあたって、トラッキングする材料（マテリアル）の定義を導入対象のサプライチェーン内で合意する必要があります。 材料は「材料名（name）」「量（quantity）」「単位（unit）」から定義されます。

例えば、アルミニウム合金を扱うサプライチェーンを例にするとトラッキングする材料は以下のように定義されるかもしれません。

このように定義された材料名と単位はサプライチェーン内で一貫して使用される必要があります。 このうち、材料名と単位を API では扱うことになります。表記の揺らぎがでないように厳密にどの文字を利用するのかまで定義し、サプライチェーン内で合意する必要があります。

単位はそのサプライチェーンで扱う必要がある精度を十分に表現できる最小の単位を定義することをお勧めします。 これはサプライチェーンの途中でより小さい単位に変換を行おうとすると、焼却(Burn)と鋳造(Mint) を行う必要が生まれ、 後述するアイテムの詳細を公開しなくても取引の前後で材料の量が不変であることを検証可能にする機能が活用できなくなるためです。

単位のルール

単位は以下の基本的な単位と、SI接頭辞を組み合わせて使用することができます。

基本的な単位

• メートル: m
• グラム: g
• モル: mol
• 平方メートル: m2
• 立方メートル: m3

SI接頭辞

• 10 ^ 30: Q (quetta)
• 10 ^ 27: R (ronna)
• 10 ^ 24: Y (yotta)
• 10 ^ 21: Z (zetta)
• 10 ^ 18: E (exa)
• 10 ^ 15: P (peta)
• 10 ^ 12: T (tera)
• 10 ^ 9: G (giga)
• 10 ^ 6: M (mega)
• 10 ^ 3: k (kilo)
• 10 ^ 2: h (hecto)
• 10 ^ 1: da (deca)
• 10 ^ -1: d (deci)
• 10 ^ -2: c (centi)
• 10 ^ -3: m (milli)
• 10 ^ -6: µ (micro)
• 10 ^ -9: n (nano)
• 10 ^ -12: p (pico)
• 10 ^ -15: f (femto)
• 10 ^ -18: a (atto)
• 10 ^ -21: z (zepto)
• 10 ^ -24: y (yocto)
• 10 ^ -27: r (ronto)
• 10 ^ -30: q (quecto)

例

• キログラム: kg
• キロメートル: km
• マイクロメートル: µm

ここに含まれない単位（例えばリットルやフィートなど）で量の数値を持っている場合は、ここで許可された単位に変換してから登録してください。 これらの単位で表現できない単位を使用する必要がある場合は chaintope 社までお問い合わせください。

各ステークホルダー内またはステークホルダー間で輸送されるアイテムは実際には何であるかについて決めておく必要があります。 マテリアルトラッキング API がサポートするのは、アイテム単位でのトラッキングです。 このアイテムが具体的に何を指すかは、適用対象のサプライチェーンやそれに参加するステークホルダーによって異なります。

そのため、アイテムがトレースを行う際の起点とする単位となります。 最初に取り決めたアイテムより小さい単位で、後からトレースをしたいとなってもできないことに注意してください。

例えばある部品メーカーが製造する際にアイテムを同じ時間単位で製造された 10 ロット単位で扱うことにしたとします。 その後ある１つのロットの部品に重大な不良品が含まれる可能性が発覚しました。 その１つのロットの流通先をトレースしたくても、実際には10ロット単位で管理していたため、 問題のロットが流通した可能性がある範囲を特定するには一緒に管理されている 10 ロットすべてについて調査をする必要があります。

できるだけ細かい単位でアイテムを定義すればよいかというとそうはなりません。 アイテムの輸送では、アイテムごとの材料の割合を変えずに、ただアイテムを所有しているアドレスだけを移動させたい場合、 アイテムごとに１つのトランザクションを作成する必要があります。 複数のアイテムを１つのトランザクションで輸送すると、アイテムが混ざってしまい、輸送トランザクションの各アウトプットそれぞれが、 インプットのどれと対応するかわからなくなります。 そして、トランザクションの発行には費用がかかるため、アイテムをどの粒度で管理したいのかと言うことと、コストのバランスを取る必要があります。

利用を開始するためにサプライチェーンのすべてのステークホルダーはトラッキングアドレスを生成する必要があります。 直接取引があるステークホルダーは取引相手にアドレスを伝えることで、相手からアイテムを受け取ることができます。

アドレスの生成 API を使い生成します。 purpose には material_tracking を指定します。

アドレスの生成 APIリクエストボディ

{
  "purpose": "material_tracking"
}

レスポンス

"14CZAF6gva9Ayd8oLZg7EWGpjF5MCNJYhM"

次のセクションでは、APIを使ってサプライチェーン内でアイテムの鋳造（Mint）、輸送（Transfer）の方法を説明します。 さらに、アイテムを使って新たなアイテムを製造する例も示します。 アイテムの流れは図で示されています。矢印はAPIによるアイテムの操作を表しています。 「鋳造(Mint)」や「輸送(Transfer)」の矢印は一つずつですが、製造のための矢印は二つあります。 扱うアイテムや送り先が増えると、「鋳造(Mint)」や「輸送(Transfer)」に関連する矢印も増えます。

サプライチェーンに参加する材料は鋳造(Mint)オペレーションによって Tapyrus ブロックチェーン上に登録することでトラッキングを開始します。 アイテムの登録 API を利用して、材料を鋳造することができます。

アルミニウム合金の素材となるアルミニウムを鋳造する場合、以下のような JSON をリクエストボディにセットして API を実行します。

アイテムの登録 APIリクエストボディ

{
  "from_address": "14CZAF6gva9Ayd8oLZg7EWGpjF5MCNJYhM",
  "mint": [
    {
      "to_address": "14CZAF6gva9Ayd8oLZg7EWGpjF5MCNJYhM",
      "materials": [
        { "name": "Al", "quantity": 500000, "unit": "g" }
      ]
    }
  ]
}

実行に成功すると以下のような応答が返ります。

レスポンス

{
  "txid": "d4676c9fed254a5951968f7b72156c99fa8ace4708406ee96bf3cc5bb26a2cc4",
  "tracking_payloads": [
    {
      "item_id": "d4676c9fed254a5951968f7b72156c99fa8ace4708406ee96bf3cc5bb26a2cc400000000",
      "txid": "d4676c9fed254a5951968f7b72156c99fa8ace4708406ee96bf3cc5bb26a2cc4",
      "index": 0,
      "materials": [
        {
          "name": "Al",
          "quantity": 500000,
          "unit": "g"
        }
      ],
      "r": "80b7018888e5469e9097b844d3d24cca06e98c929db50c69dccf1d2e0008e449",
      "commitment": "0223859323520cb294dc3e3a2bb62e5c293e586cc5deb3fc9df01406831f4a8bb9",
      "to_address": "14CZAF6gva9Ayd8oLZg7EWGpjF5MCNJYhM"
    }
  ]
}

応答に含まれる item_id の値は、この鋳造されたアイテムを使用するために必要になります。 また、鋳造されたアイテムは Tapyrus ブロックチェーン上に記録されており、 どこに記録されているかは txid 及び、index(txid のトランザクションのアウトプットのインデックス) で見つけることができます。

仮に応答に含まれる情報を忘れても ユーザのアイテム一覧取得 API を利用して取得することができます。

アイテムの輸送 API ではアイテムを別のトラッキングアドレスへ移動することができます。 アイテムの鋳造(Mint) で登録したアイテムを出荷して、取引先に送る場合などに利用します。

例えば、前のセクションで登録したアイテムを送る場合、次のような JSON をリクエストボディにセットして API を実行します。

アイテムの輸送 APIリクエストボディ

{
  "item_ids": [
    "d4676c9fed254a5951968f7b72156c99fa8ace4708406ee96bf3cc5bb26a2cc400000000"
  ],
  "transfer": [
    {
      "materials": [
        { "name": "Al", "quantity": 500000, "unit": "g" }
      ],
      "to_address": "12nePnPumNoUDLiJLihprsSwV7T78R1J1X"
    }
  ]
}

実行に成功すると以下のような応答が返ります。

レスポンス

{
  "txid": "a3f943bf63dde234ca6bf3e5eddb12ede1cd417cd9e317eb19d39fc005974403",
  "tracking_payloads": [
    {
      "item_id": "a3f943bf63dde234ca6bf3e5eddb12ede1cd417cd9e317eb19d39fc00597440300000000",
      "txid": "a3f943bf63dde234ca6bf3e5eddb12ede1cd417cd9e317eb19d39fc005974403",
      "index": 0,
      "materials": [
        {
          "name": "Al",
          "quantity": 500000,
          "unit": "g"
        }
      ],
      "r": "80b7018888e5469e9097b844d3d24cca06e98c929db50c69dccf1d2e0008e449",
      "commitment": "0223859323520cb294dc3e3a2bb62e5c293e586cc5deb3fc9df01406831f4a8bb9",
      "to_address": "12nePnPumNoUDLiJLihprsSwV7T78R1J1X"
    }
  ]
}

また、輸送だけではなく、複数のアイテムに含まれる材料を組み合わせて新しいアイテムを生成することもできます。 いま輸送したアイテムと、別のアイテムを組み合わせて新しいアイテムを生成する例を紹介します。

アルミニウムを主成分とする合金を生成します。使用する材料の 0.2% が製造の過程で失われると仮定します。 失われる材料は、焼却(Burn)オペレーションによってブロックチェーンにそれ以上流通できない形で記録されます。

アイテムの輸送 APIリクエストボディ

{
  "item_ids": [
    "a3f943bf63dde234ca6bf3e5eddb12ede1cd417cd9e317eb19d39fc00597440300000000",
    ...
  ],
  "transfer": [
    {
      "materials": [
        { "name": "Al", "quantity": 499000, "unit": "g" },
        { "name": "Cu", "quantity": 2047, "unit": "g" },
        { "name": "Mg", "quantity": 2047, "unit": "g" },
        { "name": "Mn", "quantity": 4094, "unit": "g" },
        { "name": "Si", "quantity": 4606, "unit": "g" }
      ],
      "to_address": "12nePnPumNoUDLiJLihprsSwV7T78R1J1X"
    }
  ],
  "burn": [
        { "name": "Al", "quantity": 1000, "unit": "g" },
        { "name": "Cu", "quantity": 4, "unit": "g" },
        { "name": "Mg", "quantity": 4, "unit": "g" },
        { "name": "Mn", "quantity": 8, "unit": "g" },
        { "name": "Si", "quantity": 9, "unit": "g" }
  ]
}

実行に成功すると以下のような応答が返ります。応答に含まれる１つめの item_id が新しく生成されたアイテムの ID です。 Tapyrus ブロックチェーン上には commitment の値だけが記録され、materials 等の詳細は秘匿されます。 2つめの item_id は焼却されたものを示しており、送り先アドレスを示す to_address は null になります。

レスポンス

{
  "txid": "0700dae442f960503ebde27d626318f2f6a41eb6fc0981c52c6f598568631d5c",
  "tracking_payloads": [
    {
      "item_id": "0700dae442f960503ebde27d626318f2f6a41eb6fc0981c52c6f598568631d5c00000000",
      "txid": "0700dae442f960503ebde27d626318f2f6a41eb6fc0981c52c6f598568631d5c",
      "index": 0,
      "materials": [
        { "name": "Al", "quantity": 499000, "unit": "g" },
        { "name": "Cu", "quantity": 2047, "unit": "g" },
        { "name": "Mg", "quantity": 2047, "unit": "g" },
        { "name": "Mn", "quantity": 4094, "unit": "g" },
        { "name": "Si", "quantity": 4606, "unit": "g" }
      ],
      "r": "c60b763ee27da675edaaaa69a3183112ad6335334f88c51b6e432d8a1a55831a",
      "commitment": "03408c1ac8a6588575947e4b0b09d6dc786cb6fb8c9ac38bcb7d10c814e96045fa",
      "to_address": "12nePnPumNoUDLiJLihprsSwV7T78R1J1X"
    },
    {
      "item_id": "0700dae442f960503ebde27d626318f2f6a41eb6fc0981c52c6f598568631d5c00000002",
      "txid": "0700dae442f960503ebde27d626318f2f6a41eb6fc0981c52c6f598568631d5c",
      "index": 2,
      "materials": [
        { "name": "Al", "quantity": 1000, "unit": "g" },
        { "name": "Cu", "quantity": 4, "unit": "g" },
        { "name": "Mg", "quantity": 4, "unit": "g" },
        { "name": "Mn", "quantity": 8, "unit": "g" },
        { "name": "Si", "quantity": 9, "unit": "g" }
      ],
      "r": "68f51100ea75344fb384e4590f75fda0e732f6090907988c26b56ba6cbb26f2d",
      "commitment": "033093b78c787655a9782ff153d43c8f9f637149bd11609575857c5065ff10f364",
      "to_address": null
    }
  ]
}

同じTapyrus API エンドポイントを共有していない取引相手へアイテムを送る場合、以下のデータ（共有値）を取引先と共有する必要があります。

• コミットメントに含まれる材料と量と単位
• ブランドファクター r の値
• コミットメントが記録されたトランザクションのアウトプットを示すアウトポイント( txid と index )

ここまでトラッキングしてきたアイテムを取引先へ納品するとします。 このとき取引先がこれまで利用したものとは違う Tapyrus API エンドポイント（https://xxxxxxxx.api.tapyrus.chaintope.com の xxxxxxxx が異なるエンドポイント）を利用してる場合に、 取引先が受け取ったアイテムを操作するためにはこの 共有値 を共有しておく必要があります。

共有値 を受け取った取引先は アイテム詳細の登録 API を使い、共有値を Tapyrus API へ登録します。 これによって、受け取ったアイテムを操作することができるようになります。

アイテムの詳細取得 API の応答に含まれる opened_value (開示値） は、あるアイテムに含まれる材料の内訳を公開し、その内容が Tapyrus ブロックチェーン上に記録されたコミットメントと一致することを検証するために必要なすべての情報を含んだ JWT 形式のデータです。 不特定多数へアイテムの品質を提示する際に利用できます。