Tapyrus API (1.5.0)

Download OpenAPI specification:Download

イントロダクション

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

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

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

Tapyrus API の利用法

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

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がご利用いただけます。

Authentication

OpenID

Security Scheme Type OpenID Connect
Connect URL https://accounts.google.com/.well-known/openid-configuration

timestamp

タイムスタンプAPI

Timestampを記録

ブロックチェーンに任意の値をタイムスタンプとして記録します。 現在、記録方法として2種類のtypesimple(デフォルト)、trackable)をサポートしています。

simpleを指定した場合は、値がトランザクション内のOP_RETURNアウトプットに直接埋め込まれます。 単純に値をブロックチェーンに記録する場合はsimpleの利用を推奨します。

trackableを指定した場合は、ハッシュ値を組み合わせたPay to Contractアドレスが生成され、ハッシュ値は間接的に記録されます。 アドレスは、Timestampの戻り値の1つであるpayment_baseと指定されたコンテンツハッシュを使って次のように計算されます。

アドレスの公開鍵 = payment_base + SHA256(payment_base || コンテンツハッシュ)G

※Gは楕円曲線の生成元。公開鍵からアドレス(P2PKH)を導出すると、戻り値の1つであるp2c_addressと合致します。 trackableを使用するとハッシュ値は間接的に記録されますが、ブロックチェーン上で使用可能なアセットとして管理できます。 そのため、ある記録を持つデータを更新する場合に、このアセットを使用して新しいtrackableアセットを作成することで、 記録の更新、最新性を表現することが可能になります。未使用な記録のみlatestがtrueになります。

contentで指定した値は、digestで指定した方法でハッシュ化されます。 digest指定方法の種類は以下の通りです。(未指定の場合sha256を使用)

  • 1: sha256: SHA256ハッシュ化
  • 2: double_sha256: SHA256の二重ハッシュ化
  • 3: none: 値をハッシュ化せずそのまま記録

v1.3.0 まであった content_hash は v1.4.0 からは非推奨です。content を使用してください。content_hashは将来のメジャーバージョンアップで削除されます。

Authorizations:
Request Body schema: application/json

content, digest, prefix, type を受け取り、ブロックチェーンにハッシュ値をタイムスタンプとして記録します。

content
required
string
digest
string
prefix
string
type
string (TimestampType)
Enum: "simple" "trackable"

Responses

Request samples

Content type
application/json
{
  • "content": "Content for Timestamp",
  • "digest": "sha256",
  • "prefix": "TMESTAMPAPP",
  • "type": "trackable"
}

Response samples

Content type
application/json
{
  • "id": 2,
  • "txid": "6fce02d39279f6d645ecc710ebcf1dbb7b8104106553d8da13f5db79c5a628fc",
  • "status": "unconfirmed",
  • "content_hash": "3d1469aa427f97921a1b71c5981c1848041246290394a32ec26fdee2685bdece",
  • "prefix": "TMESTAMPAPP",
  • "wallet_id": "b831e51927edc7b3a21869909d526e51",
  • "latest": "true",
  • "timestamp_type": "trackable",
  • "block_height": 101,
  • "block_time": 1626169080,
  • "p2c_address": "1CY6TSSARn8rAFD9chCghX5B7j4PKR8S1a",
  • "payment_base": "02124fd6b3c968390be4828058efc941b83f8ce9ccb00cfde86423744dbcb82576",
  • "prev_id": 1
}

Timestamp一覧表示

ブロックチェーンに記録したタイムスタンプを取得し、content_hash,prefix,txidを一覧で表示します。

Authorizations:

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Timestamp表示

タイムスタンプ ID に対応する Timestamp を表示します。

Authorizations:
path Parameters
id
required
integer

Timestamp id。Timestamp を記録 API(POST /timestamps) の返り値の JSON の id 要素の値です。

Responses

Response samples

Content type
application/json
{
  • "id": 2,
  • "txid": "6fce02d39279f6d645ecc710ebcf1dbb7b8104106553d8da13f5db79c5a628fc",
  • "status": "unconfirmed",
  • "content_hash": "3d1469aa427f97921a1b71c5981c1848041246290394a32ec26fdee2685bdece",
  • "prefix": "TMESTAMPAPP",
  • "wallet_id": "b831e51927edc7b3a21869909d526e51",
  • "latest": "true",
  • "timestamp_type": "trackable",
  • "block_height": 101,
  • "block_time": 1626169080,
  • "p2c_address": "1CY6TSSARn8rAFD9chCghX5B7j4PKR8S1a",
  • "payment_base": "02124fd6b3c968390be4828058efc941b83f8ce9ccb00cfde86423744dbcb82576",
  • "prev_id": 1
}

Trackable Timestampの更新

trackable タイプのタイムスタンプを更新する新たなタイムスタンプを記録します。更新されたタイムスタンプは latest フィールドに false が返る様になり、最新のものではない事が確認出来るようになります。

また、ブロックチェーン上では IDを指定したタイムスタンプに対応する Pay to Contract UTXO をインプットとして持つ新たなトランザクションがブロードキャストされます。そのトランザクションのアウトプットリストには古いタイムスタンプが登録されたときと同様に Pay to Contract アドレス宛の支払いアウトプットがセットされます。

これにより、古いタイムスタンプの UTXO は消費され、更新された新たなタイムスタンプを記録する UTXO が生まれます。この仕組みにより、この API によって発行されるトランザクションが、更新対象の古いタイムスタンプを更新する唯一のものであることが保証されます。

Authorizations:
path Parameters
id
required
integer

更新する対象となるタイムスタンプのIDです。

Request Body schema: application/json

content, digest, prefix を受け取り、ブロックチェーンにハッシュ値をタイムスタンプとして記録します。

content
required
string
digest
string
prefix
string

Responses

Request samples

Content type
application/json
{
  • "content": "Content for Timestamp",
  • "digest": "sha256",
  • "prefix": "TMESTAMPAPP"
}

Response samples

Content type
application/json
{
  • "id": 2,
  • "txid": "6fce02d39279f6d645ecc710ebcf1dbb7b8104106553d8da13f5db79c5a628fc",
  • "status": "unconfirmed",
  • "content_hash": "3d1469aa427f97921a1b71c5981c1848041246290394a32ec26fdee2685bdece",
  • "prefix": "TMESTAMPAPP",
  • "wallet_id": "b831e51927edc7b3a21869909d526e51",
  • "latest": "true",
  • "timestamp_type": "trackable",
  • "block_height": 101,
  • "block_time": 1626169080,
  • "p2c_address": "1CY6TSSARn8rAFD9chCghX5B7j4PKR8S1a",
  • "payment_base": "02124fd6b3c968390be4828058efc941b83f8ce9ccb00cfde86423744dbcb82576",
  • "prev_id": 1
}

token

トークンAPI

トークンの新規発行

任意の数のトークンを新規発行します。

Authorizations:
Request Body schema: application/json

amountを受け取り指定した数のトークンを新規発行します。 任意でtoken_typeを設定し、トークンの種類を指定できます。 token_typeが未指定な場合、再発行可能なトークンが発行されます。 トークンの種類は以下の通りです。

  • 1: 再発行可能なトークン
  • 2: 再発行不可能なトークン
  • 3: NFT

また、token_typeが未指定または1の場合、任意でトークン識別子idを指定することで、指定したトークン識別子のトークンを再発行します。 splitを指定することで発行するトランザクションにsplit数分のアウトプットを追加し、 各アウトプットに均等になるようにトークンを発行できます。 トークンの量に余りが出る場合、余りの値の調整は最後のアウトプットで行われます。 発行量がsplitよりも小さい場合、指定された発行量の数分のアウトプットが作られます。 例えば、amountに10、splitに3を指定した場合、トランザクションのアウトプットは3つに分割され、 それぞれに含まれるトークンの数量は3, 3, 4 となります。 splitに指定できる値の範囲は1以上、100以下です。

amount
required
integer
token_type
integer
split
integer

Responses

Request samples

Content type
application/json
{
  • "amount": 100,
  • "token_type": 1,
  • "split": 100
}

Response samples

Content type
application/json
{
  • "token_id": "c3ec2fd806701a3f55808cbec3922c38dafaa3070c48c803e9043ee3642c660b46",
  • "txid": "6fce02d39279f6d645ecc710ebcf1dbb7b8104106553d8da13f5db79c5a628fc"
}

トークンの総量取得

所有するトークンの総量を取得し、トークン識別子(token_id)ごとに総量(amount)を一覧で表示します。

Authorizations:
query Parameters
confirmation_only
boolean (ConfirmationOnlyParam)
Example: confirmation_only=true

オプションでconfirmation_onlyを設定でき、trueの場合ブロックチェーン上で承認済みのトークンのみを取得し、falseの場合未承認のトークンも含めて取得します。デフォルトはtrueです。

Responses

Response samples

Content type
application/json
[
  • {
    }
]

トークンの再発行

指定した識別子を持つ再発行可能なトークンを任意の量再発行します。

Authorizations:
path Parameters
token_id
required
string (TokenIdParam)

トークンの識別子。

Request Body schema: application/json
amount
required
integer
split
integer

Responses

Request samples

Content type
application/json
{
  • "amount": 100,
  • "split": 100
}

Response samples

Content type
application/json
{
  • "token_id": "c3ec2fd806701a3f55808cbec3922c38dafaa3070c48c803e9043ee3642c660b46",
  • "txid": "6fce02d39279f6d645ecc710ebcf1dbb7b8104106553d8da13f5db79c5a628fc"
}

トークンの送付

任意の数のトークンを指定したアドレスに対して送付します。

Authorizations:
path Parameters
token_id
required
string (TokenIdParam)

トークンの識別子。

Request Body schema: application/json

addressでトークンを送付する相手のアドレスを指定し、amountで送付するトークンの量を指定します。

address
required
string
amount
integer

Responses

Request samples

Content type
application/json
{
  • "address": "1CY6TSSARn8rAFD9chCghX5B7j4PKR8S1a",
  • "amount": 100
}

Response samples

Content type
application/json
{
  • "token_id": "c3ec2fd806701a3f55808cbec3922c38dafaa3070c48c803e9043ee3642c660b46",
  • "txid": "6fce02d39279f6d645ecc710ebcf1dbb7b8104106553d8da13f5db79c5a628fc"
}

複数アドレスへのトークン送付

任意の数のトークンを指定した複数のアドレスに対して送付します。

Authorizations:
path Parameters
token_id
required
string (TokenIdParam)

トークンの識別子。

Request Body schema: application/json

アドレスと量の配列を指定します。 配列の各要素ではaddressでトークンを送付する相手のアドレスを指定し、amountで送付するトークンの量を指定します。"

required
Array of objects (TransferTokenRequest) [ items ]

Responses

Request samples

Content type
application/json
{
  • "destinations": [
    ]
}

Response samples

Content type
application/json
{
  • "token_id": "c3ec2fd806701a3f55808cbec3922c38dafaa3070c48c803e9043ee3642c660b46",
  • "txid": "6fce02d39279f6d645ecc710ebcf1dbb7b8104106553d8da13f5db79c5a628fc"
}

トークンの焼却

任意の数のトークンを焼却します。

Authorizations:
path Parameters
token_id
required
string (TokenIdParam)

トークンの識別子。

query Parameters
amount
integer (AmountParam)
Example: amount=100

amountを受け取り、指定した量のトークンを焼却します。 amountが未入力の場合全てのトークンを焼却します。

Responses

tracking

サブジェクトの登録

サブジェクト(トラッキングの対象となる物)を登録し、新規でトラッキングを開始します。指定されたサブジェクトがすでにトラッキング中の場合はトラッキングの開始に失敗します。

Authorizations:
Request Body schema: application/json
from_address
required
string

供給元を表すアドレス

required
Array of objects (TrackingDestination) [ items ]

サブジェクトの移動先を表します。

Responses

Request samples

Content type
application/json
{
  • "from_address": "1CY6TSSARn8rAFD9chCghX5B7j4PKR8S1a",
  • "destinations": [
    ]
}

Response samples

Content type
application/json
{
  • "txid": "6fce02d39279f6d645ecc710ebcf1dbb7b8104106553d8da13f5db79c5a628fc"
}

サブジェクトの移動

サブジェクトの移動を記録します。サブジェクトがトラッキング中でない場合は記録に失敗します。

Authorizations:
Request Body schema: application/json
required
Array of objects (TrackingDestination) [ items ]

サブジェクトの移動先を表します。

Responses

Request samples

Content type
application/json
{
  • "destinations": [
    ]
}

Response samples

Content type
application/json
{
  • "txid": "6fce02d39279f6d645ecc710ebcf1dbb7b8104106553d8da13f5db79c5a628fc"
}

サブジェクトを消費

トラッキング中のサブジェクトが消費されたものとみなして、トラッキングを終了します。サブジェクトがトラッキング中でない場合は失敗します。

Authorizations:
Request Body schema: application/json
subjects
required
Array of strings (TrackingSubjectId)

消費したサブジェクトを示します。

Responses

Request samples

Content type
application/json
{
  • "subjects": [
    ]
}

Response samples

Content type
application/json
{
  • "txid": "6fce02d39279f6d645ecc710ebcf1dbb7b8104106553d8da13f5db79c5a628fc"
}

トレース一覧

サブジェクトの移動の履歴を返します。履歴は発生日時の昇順でソートされています。

Authorizations:
path Parameters
subject_id
required
string (TrackingSubjectId)
Example: 6948DF80-14BD-4E04-8842-7668D9C001F5

サブジェクトの識別子。

Responses

Response samples

Content type
application/json
[
  • {
    }
]

トレースの詳細

サブジェクトの移動履歴(trace)に関する情報を返します。

Authorizations:
path Parameters
trace_id
required
number

サブジェクトの移動履歴(trace)に一意に振られたID

Responses

Response samples

Content type
application/json
{
  • "trace_id": 1,
  • "subject_id": "6948DF80-14BD-4E04-8842-7668D9C001F5",
  • "parents": [
    ],
  • "child_subject_ids": [
    ],
  • "tracking_payload": "545001fd8001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002df31817469c8c55647",
  • "tracking_payload_output_index": 1,
  • "inclusion_proof": "7598e2d934e1502a2e4e15f1ca3329bd444815430d6cdfe8465cdead162f824d3ed8d0fec153db11789998e1dae08f1210fe8dede07362b51a432c5dcf597388738b46b3bf72d2120e7c5ae9324940e159754d6548255c1b189507be2fcbae45eff9ee348b767ff382773444200f2e89c1469366306557c178d07deafb1c8197e20482237f0bc1f273021ee3fcbf1ad06f1c77829a91f2834d96d7d3eadd06fe8b81959d52cd979e0881ea7e6efdd1e2f5441bf30f346ada077ae16dcf4dec545e4116202dfe42a3a38d009cc5ae539942a9d73e945495913a22386c833660c51e381338c65bd474346210ac4530d7d5a186b416fab9ea06fbfd8ddcdd0311cb34b1175ea50a0b9364a0a6e4a815f964d2249308bae0853c611f44c9a3445a6138f028852d9eca13fc09bcd9b1f8606710240907d7697b2e851e0bd8ba26f015b962c296edf9e4b00d23083c9c504f10ffdc02ae8328532ebd3bb36a30b7a630ddf4129a1e9e21c4d787c980d12d8c978e598ad31ab0e371397b864b1dd4ac26",
  • "txid": "6fce02d39279f6d645ecc710ebcf1dbb7b8104106553d8da13f5db79c5a628fc",
  • "tx_index": 0,
  • "block_height": 101,
  • "block_time": 1626169080,
  • "from_address": "mnzdZUieW2Hqe9GzZzVbcA7nHkDeFhJFzd",
  • "to_address": "mnzdZUieW2Hqe9GzZzVbcA7nHkDeFhJFzd",
  • "moved": true
}

サブジェクトの一覧

指定したアドレスが所持しているsubjectのリストを取得します。 指定するアドレスは自身が生成したアドレスでなければいけません。 自身が生成したアドレスでない場合はHTTPステータスコードとして404(Not Found)を返します。 subjectが階層化されている場合は、下位階層のsubjectも含めて返します。 指定したアドレスに対応するsubjectが存在しない場合は空のリストを返します。

Authorizations:
path Parameters
address
required
string
Example: mnzdZUieW2Hqe9GzZzVbcA7nHkDeFhJFzd

アドレス

query Parameters
per
integer (PerPageParam)

1ページあたりの件数

page
integer (PageNumberParam)

ページ番号

Responses

Response samples

Content type
application/json
{
  • "count": 1,
  • "subjects": [
    ]
}

address

アドレスの一覧

これまで生成したアドレスを一覧にして返します。 任意でpurposeを設定し、取得するアドレスの種類を指定できます。未指定の場合、汎用的に使うアドレスのみ取得します。

  • purposegeneralと入力すると、生成したアドレスのうち、汎用的に使うアドレスのみ取得します。

  • purposeallと入力すると、生成したアドレスすべて取得します。

  • purposetrackingと入力すると、生成したアドレスのうち、トラッキングに使用されているアドレスを取得します。

Authorizations:
query Parameters
per
integer (PerPageParam)

1ページあたりの件数

page
integer (PageNumberParam)

ページ番号

purpose
string (PurposeAddressParam)

取得したいアドレス

Responses

Response samples

Content type
application/json
{
  • "count": 1,
  • "addresses": [
    ]
}

アドレスの生成

受金用のアドレスを生成して返します。 任意でpurposeを設定し、生成するアドレスの種類を指定できます。未指定の場合、汎用的に使うアドレスを生成します。

  • purposegeneral と入力する、または未指定の場合、汎用的に使うアドレスを生成します。
  • purposetrackingと入力すると、トラッキングに使用するアドレスを生成します。
Authorizations:
Request Body schema: application/json
purpose
string

Responses

Request samples

Content type
application/json
{
  • "purpose": "general"
}

Response samples

Content type
application/json
"mnzdZUieW2Hqe9GzZzVbcA7nHkDeFhJFzd"

user

ユーザ情報

ユーザのid,balance, addressの情報を返します。

Authorizations:
query Parameters
confirmation_only
boolean (ConfirmationOnlyParam)
Example: confirmation_only=true

オプションでconfirmation_onlyを設定でき、trueの場合ブロックチェーン上で承認済みのtpc・トークンのみを取得し、falseの場合未承認のtpc・トークンも含めて取得します。デフォルトはtrueです。

Responses

Response samples

Content type
application/json
{
  • "sub": 1,
  • "balances": {
    },
  • "addresses": [
    ]
}