ScalarDL ノード クライアント SDK

注記

このページは英語版のページが機械翻訳されたものです。英語版との間に矛盾または不一致がある場合は、英語版を正としてください。

これは、アプリケーションが ScalarDL ネットワークと対話できるようにする Node.js アプリケーション用のライブラリです。

開発とテストに使用されるノードのバージョン

このパッケージは、Node LTS v14.16.0 を使用して開発およびテストされています。 名前は fermium。 これは、他のノード バージョンを使用する場合、パッケージの通常の動作を保証できないことを意味します。

インストール

このライブラリをインストールするには、任意の NPM パッケージ マネージャーを使用できます。 たとえば、NPM を使用してインストールするには:

npm install @scalar-labs/scalardl-node-client-sdk

方法

ClientService インスタンスを作成する

ClientService クラスはこのパッケージのメインクラスです。 ScalarDLネットワークをリクエストするために以下の機能を提供します。

名前	用途
registerCertificate	ScalarDL ネットワークにクライアントの証明書を登録するには
registerContract	ScalarDL ネットワークに (登録済みクライアントの) 契約を登録するには
listContracts	クライアントの登録済み契約を一覧表示するには
execute と executeContract (将来廃止される)	顧客が登録した契約を履行するため
validateLedger	ScalarDL ネットワーク上の資産を検証して、改ざんされているかどうかを確認するには

上記のメソッドのいずれかの実行時にエラーが発生した場合、ClientError がスローされます。 ClientError.code は追加のエラー コンテキストを提供します。 ステータス コードの仕様については、以下の 実行時エラー セクションを参照してください。

以下のコード スニペットを使用して、ClientService インスタンスを作成します。

const { ClientService } = require('@scalar-labs/scalardl-node-client-sdk');
const clientService = new ClientService(clientProperties);

clientProperties 引数はコンストラクターにとって必須です。 これは、ユーザー foo@example.com が ScalarDL ネットワークのサーバー scalardl-server.example.com:50051 に接続するために使用するプロパティの例です。

{
    'scalar.dl.client.server.host': 'scalardl-server.example.com',
    'scalar.dl.client.server.port': 50051,
    'scalar.dl.client.server.privileged_port': 50052,
    'scalar.dl.client.cert_holder_id': 'foo@example.com',
    'scalar.dl.client.private_key_pem': '-----BEGIN EC PRIVATE KEY-----\nMHc...',
    // scalar.dl.client.private_key_path is applied when scalar.dl.client.private_key_pem is not given
    'scalar.dl.client.private_key_path': 'path-to-key-file',
    'scalar.dl.client.cert_pem': '-----BEGIN CERTIFICATE-----\nMIICjTCCAj...\n',
    // scalar.dl.client.cert_path is applied when scalar.dl.client.cert_pem is not given
    'scalar.dl.client.cert_path': 'path-to-certificate-file',
    'scalar.dl.client.cert_version': 1,
    'scalar.dl.client.tls.enabled': false,
    'scalar.dl.client.tls.ca_root_cert_pem': '-----BEGIN CERTIFICATE-----\n...\n',
    // scalar.dl.client.tls.ca_root_cert_path is applied when scalar.dl.client.tls.ca_root_cert_pem is not given
    'scalar.dl.client.tls.ca_root_cert_path': 'path-to-ca-root-certificate-file',
    'scalar.dl.client.authorization.credential': '...',
    'scalar.dl.client.proxy.server': '...',
}

ScalarDL ネットワークで Auditor 機能が有効になっている場合は、次の例のように追加のプロパティを指定します。 この例では、クライアントは Auditor 機関 scalardl-auditor.example.com と対話し、契約実行時のデータ改ざんなどのビザンチン障害を検出します。

{
    'scalar.dl.client.auditor.enabled': true,
    'scalar.dl.client.auditor.host': 'scalardl-auditor.example.com',
    'scalar.dl.client.auditor.port': 40051,
    'scalar.dl.client.auditor.privileged_port': 40052,
}

以下の説明では、clientService インスタンスがあると仮定します。

証明書を登録する

registerCertificate 関数を使用して、ScalarDL ネットワークに証明書を登録します。

await clientService.registerCertificate();

契約書を登録する

契約を登録するには、registerContract 関数を使用します。

await clientService.registerContract('contractId', 'com.example.contract.contractName', contractUint8Array, propertiesObject);

レジスタ関数

関数を登録するには、registerFunction 関数を使用します。

await clientService.registerFunction('functionId', 'com.example.function.functionName', functionUint8Array);

登録された契約をリストする

listContracts 関数を使用して、登録されているすべての契約を一覧表示します。

const constracts = await clientService.listContracts();

契約を締結する

execute 関数を使用して、登録されたコントラクトと関数を実行します (オプション)。

const response = await clientService.execute('contractId', argumentObject);
const executionResult = response.getResult();
const proofsList = response.getProofs();

const response = await clientService.execute(
    'contractId',
    { 'arg1': 'a' },
    'functionId',
    { 'arg2': 'b' }
);

{ 'arg1': 'a' } は contractArgument 経由で渡されます。 一方、{ 'arg2': 'b' } は functionArgument 経由で渡されます。

アセットを検証する

validateLedger 関数を使用して、ScalarDL ネットワーク内のアセットを検証します。

const response = await clientService.validateLedger('assetId');
const statusCode = response.getCode();
const proof = response.getProof();

Auditor を使用する場合の Ledger 検証

こちらを参照し、上記の Node SDK インターフェイス (registerContract および validateLedger) を同じ方法で使用して、Ledger と Auditor の状態を検証します。 ValidateLedger のコントラクト ID を scalar.dl.client.auditor.linearizable_validation.contract_id プロパティに設定できます。それ以外の場合は、デフォルト ID validate-ledger が使用されます。

{
    'scalar.dl.client.auditor.enabled': true,
    'scalar.dl.client.auditor.linearizable_validation.contract_id': '<choose a contract ID>',
}

ランタイムエラー

クライアントによってスローされたエラーにはステータス コードが表示されます。

try {
    await clientService.registerCertificate();
} catch (clientError) {
    const message = clientError.message;
    const statusCode = clientError.code;
}

StatusCode = {
  OK: 200,
  INVALID_HASH: 300,
  INVALID_PREV_HASH: 301,
  INVALID_CONTRACT: 302,
  INVALID_OUTPUT: 303,
  INVALID_NONCE: 304,
  INCONSISTENT_STATES: 305,
  INVALID_SIGNATURE: 400,
  UNLOADABLE_KEY: 401,
  UNLOADABLE_CONTRACT: 402,
  CERTIFICATE_NOT_FOUND: 403,
  CONTRACT_NOT_FOUND: 404,
  CERTIFICATE_ALREADY_REGISTERED: 405,
  CONTRACT_ALREADY_REGISTERED: 406,
  INVALID_REQUEST: 407,
  CONTRACT_CONTEXTUAL_ERROR: 408,
  ASSET_NOT_FOUND: 409,
  FUNCTION_NOT_FOUND: 410,
  UNLOADABLE_FUNCTION: 411,
  INVALID_FUNCTION: 412,
  DATABASE_ERROR: 500,
  UNKNOWN_TRANSACTION_STATUS: 501,
  RUNTIME_ERROR: 502,
  CLIENT_IO_ERROR: 600,
  CLIENT_DATABASE_ERROR: 601,
  CLIENT_RUNTIME_ERROR: 602,
};

生の gRPC リクエストを作成する

バイト配列 (JavaScript Uint8Array) で生の gRPC リクエストを作成することもできます。 関数の名前は executeContract などの通常の関数とは異なりますが、パラメータはまったく同じであることに注意してください。

証明書を登録する

const binary = await ClientService.createSerializedCertificateRegistrationRequest();

契約書を登録する

const binary = await clientService.createSerializedContractRegistrationRequest('contractId', 'com.example.contract.contractName', contractUint8Array, propertiesObject);

関数を登録する

const binary = await clientService.createSerializedFunctionRegistrationRequest('functionId', 'com.example.function.functionName', functionUint8Array);

登録された契約をリストする

const binary = await clientService.createSerializedContractsListingRequest();

契約を締結する

const binary = await clientService.createSerializedContractExecutionRequest('contractId', argumentObject);

アセットを検証する

const binary = await clientService.createSerializedLedgerValidationRequest('assetId');

生の gRPC リクエストを ScalarDL サーバーに送信します

SDK には、リクエストのバイト配列を ScalarDL ネットワークに送信するための別の ClientServiceWithBinary クラスがあります。

const { ClientServiceWithBinary } = require('@scalar-labs/scalardl-node-client-sdk');
const clientService = new ClientServiceWithBinary(clientProperties);

証明書を登録する

const binary = await ClientService.createSerializedCertificateRegistrationRequest();
await ClientService.registerCertificate(binary);

契約書を登録する

const binary = await clientService.createSerializedContractRegistrationRequest('contractId', 'com.example.contract.contractName', contractUint8Array, propertiesObject);
await ClientService.registerContract(binary);

関数を登録する

const binary = await clientService.createSerializedFunctionRegistrationRequest('functionId', 'com.example.function.functionName', functionUint8Array);
await clientService.registerFunction(binary);

登録された契約をリストする

const binary = await clientService.createSerializedContractsListingRequest();
const contracts = await clientService.listContracts(binary);

契約を締結する

const binary = await clientService.createSerializedContractExecutionRequest('contractId', argumentObject);
const response = await clientService.executeContract(binary);
const executionResult = response.getResult();
const proofsList = response.getProofs();

アセットを検証する

const binary = await clientService.createSerializedLedgerValidationRequest('assetId');
const response = await clientService.validateLedger(binary);
const statusCode = response.getCode();
const proof = response.getProof();

貢献する

このライブラリは主に Scalar Engineering チームによって保守されていますが、もちろん、どんなご支援にも感謝いたします。

• 質問したり、回答を見つけたり、他のユーザーを支援するには、stackoverflow にアクセスし、scalardl タグを使用してください。
• バグの報告、改善の提案、新機能のリクエストについては、問題を開いてご協力ください。

ライセンス

ScalarDL Node クライアント SDK は、AGPL (ルート ディレクトリの LICENSE ファイルにあります) と商用ライセンスの両方に基づいてデュアル ライセンスが付与されています。 必要に応じて、上記のライセンスのいずれかを選択できます。 商用ライセンスについては、お問い合わせ までお問い合わせください。