メインコンテンツまでスキップ
バージョン: 3.11
Features and pricing

ScalarDL Ledger をはじめよう

注記

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

この入門チュートリアルでは、お好みのデータベースで ScalarDL を設定する方法を説明し、データの履歴状態を追跡するシンプルなアプリケーションを作成するプロセスを示します。

前提条件​

警告

ScalarDL は JDK 8 でビルドされているため、コントラクトは JDK 8 互換バイナリである必要があります。JDK 8 以外のバージョンを使用する場合は、ビルドツールを設定して JDK 8 互換バイナリをビルドする必要があります。バイナリ互換性を指定するには、javac の --release 8 オプションを使用するか、Gradle または Maven 設定を設定して JDK 8 ツールチェーンを使用するなど、いくつかの方法があります。次に、Gradle の設定を示します。

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(8))
    }
}

Gradle および Maven の設定の詳細については、Gradle の JVM プロジェクトのツールチェーンおよび Maven のツールチェーンの使用ガイドを参照してください。

ScalarDL サンプルリポジトリのクローンを作成する​

ターミナル を開き、次のコマンドを実行して ScalarDL サンプルリポジトリのクローンを作成します。

git clone https://github.com/scalar-labs/scalardl-samples

次に、以下のコマンドを実行して、サンプル設定が含まれているディレクトリに移動します。

cd scalardl-samples

データベースを選択して ScalarDL を起動します​

データベースを選択し、指示に従って ScalarDL Ledger をデプロイします。ScalarDL がサポートするデータベースの一覧については、データベースを参照してください。

ライセンスを設定する (Enterprise Edition のみ)

ScalarDL Enterprise Edition を使用している場合は、次のようにライセンスを設定します。Community Edition を使用している場合は、次のセクションに進んで ScalarDL を起動してください。

ライセンスの設定についてはこちらをご覧ください

  1. 次のように、mysql/docker-compose-ledger.yml ファイルで Enterprise Edition の Docker イメージを有効にします。

    • イメージを変更する前 (デフォルト設定):

      services:
        scalardl-ledger:
          image: ghcr.io/scalar-labs/scalardl-ledger:${SCALARDL_VERSION}
          # image: ghcr.io/scalar-labs/scalardl-ledger-byol:${SCALARDL_VERSION}

    • イメージを変更した後:

      services:
        scalardl-ledger:
          # image: ghcr.io/scalar-labs/scalardl-ledger:${SCALARDL_VERSION}
          image: ghcr.io/scalar-labs/scalardl-ledger-byol:${SCALARDL_VERSION}

  2. ScalarDL Ledger のライセンスキーを設定します。mysql/ledger.properties ファイルで、<SET_YOUR_LICENSE_KEY> をライセンスキーに置き換えます。例:

    ##### PLEASE REPLACE THIS VALUE WITH YOUR LICENSE KEY (ENTERPRISE EDITION ONLY) #####
    scalar.dl.licensing.license_key={"organization_name":"XXXXXXXX","expiration_date_time":"YYYY-MM-DDTHH:mm:SS+TIMEZONE","product_name":"ScalarDL Ledger","product_version":N,"license_type":"trial","signature":"XXXXXXXX"}
    ##### PLEASE REPLACE THIS VALUE WITH YOUR LICENSE KEY (ENTERPRISE EDITION ONLY) #####

  3. ライセンスを確認するには、mysql/docker-compose-ledger.yml ファイルを次のように更新します。試用版ライセンスを使用している場合は、この手順をスキップしてください。

    • 証明書ファイルのパスを変更する前に (デフォルト設定):

      services:
        scalardl-ledger:
          volumes:
            - ./ledger.properties:/scalar/ledger/ledger.properties.tmpl
            - ../fixture/ledger-key.pem:/scalar/ledger-key.pem
            - ../fixture/trial-license-cert.pem:/scalar/license-cert.pem
            # If you have a commercial license key, you must use `commercial-license-cert.pem` instead of `trial-license-cert.pem`.
            # - ../fixture/commercial-license-cert.pem:/scalar/license-cert.pem

    • 証明書ファイルのパスを変更した後:

      services:
        scalardl-ledger:
          volumes:
            - ./ledger.properties:/scalar/ledger/ledger.properties.tmpl
            - ../fixture/ledger-key.pem:/scalar/ledger-key.pem
            # - ../fixture/trial-license-cert.pem:/scalar/license-cert.pem
            # If you have a commercial license key, you must use `commercial-license-cert.pem` instead of `trial-license-cert.pem`.
            - ../fixture/commercial-license-cert.pem:/scalar/license-cert.pem

ScalarDL を起動する

以下の手順に従って、ScalarDL Ledger の使用を開始できます。

  1. 次のコマンドを実行して、MySQL をローカルで実行します。

    docker compose -f mysql/docker-compose-ledger.yml up -d mysql

  2. 次のコマンドを実行して、ScalarDL Ledger のデータベーススキーマをロードします。

    docker compose -f mysql/docker-compose-ledger.yml up -d scalardl-ledger-schema-loader

  3. 次のコマンドを実行して ScalarDL Ledger および依存するコンポーネントを起動します。

    docker compose -f mysql/docker-compose-ledger.yml up -d

Client SDK をダウンロードする​

次に、scalardl-java-client-sdk リポジトリ内の ScalarDL クライアントツールとサンプルを使用して ScalarDL と対話します。

次のコマンドを実行して、デプロイされた ScalarDL バージョンと同じバージョンを指定し、ツールのダウンロードに使用します。

VERSION=$(grep SCALARDL_VERSION .env | awk -F= '{print $2}')

次に、以下のコマンドを実行してリポジトリをクローンし、ツールをダウンロードします。

git clone https://github.com/scalar-labs/scalardl-java-client-sdk.git
cd scalardl-java-client-sdk
git checkout v$VERSION
curl -OL https://github.com/scalar-labs/scalardl-java-client-sdk/releases/download/v$VERSION/scalardl-java-client-sdk-$VERSION.zip
unzip scalardl-java-client-sdk-$VERSION.zip
mv scalardl-java-client-sdk-$VERSION client

クライアントプロパティを設定する​

ScalarDL Ledger を実行する前に、ScalarDL クライアントを設定する必要があります。クライアントが ScalarDL Ledger と対話するために必要な最小限のプロパティを含む設定ファイルを作成するには、次のコマンドを実行します。

cat << 'EOF' > client.properties
# A host name for ScalarDL Ledger.
scalar.dl.client.server.host=localhost

# An ID for the certificate holder. This must be configured for each private key and must be unique in the system.
scalar.dl.client.cert_holder_id=foo

# A path to the certificate file.
scalar.dl.client.cert_path=../fixture/client.pem

# A path to the private key file.
scalar.dl.client.private_key_path=../fixture/client-key.pem
EOF

このチュートリアルでは、ScalarDL Ledger ホスト名として localhost を使用できます。秘密鍵と証明書については、scalardl-samples の fixture ディレクトリで提供されているもの (それぞれ client-key.pem と client.pem) を使用できます。証明書所有者には、任意の一意の ID を指定できます。

警告

サンプルの秘密鍵と証明書を実稼働環境で使用しないでください。独自の証明書を取得する方法の詳細については、証明書の取得方法を参照してください。

証明書を登録する​

次に、以下のコマンドを実行して、証明書を ScalarDL Ledger に登録できます。

client/bin/scalardl register-cert --properties client.properties

登録された証明書を使用すると、コントラクトを登録および実行できるようになり、データベースのビザンチン故障の検出にも使用されます。セキュリティ上の理由から、新しい証明書の追加のみが可能で、既存の証明書を更新することはできません。新しい証明書を追加する場合は、登録ツールを実行する前に scalar.dl.client.cert_version に指定する値を増加させてください。

コントラクトを作成する​

ScalarDL は、単一のビジネスロジックを実装する Java プログラムであるコントラクトを通じて操作できます。このチュートリアルでは、アセットを作成し、それにいくつかの状態を関連付ける基本的なコントラクトの例を使用して、コントラクトがどのように作成、ビルドされ、機能するかを確認できます。

以下に、サンプルコントラクト StateUpdater.java を示します。コントラクトは、定義済みの基本コントラクトクラス (JacksonBasedContract クラスなど) を拡張し、invoke メソッドをオーバーライドする Java クラスです。ビジネスロジックは invoke メソッドに実装されています。

具体的には、invoke メソッドは引数からクライアント定義のアセット ID (asset_id) と状態 (state) を抽出し、指定された状態がアセットの現在の状態と異なる場合は、アセット ID を台帳内の状態に関連付けます。

package com.org1.contract;

import com.fasterxml.jackson.databind.JsonNode;
import com.scalar.dl.ledger.contract.JacksonBasedContract;
import com.scalar.dl.ledger.exception.ContractContextException;
import com.scalar.dl.ledger.statemachine.Asset;
import com.scalar.dl.ledger.statemachine.Ledger;
import java.util.Optional;
import javax.annotation.Nullable;

public class StateUpdater extends JacksonBasedContract {

  @Nullable
  @Override
  public JsonNode invoke(Ledger<JsonNode> ledger, JsonNode argument, @Nullable JsonNode properties) {
    if (!argument.has("asset_id") || !argument.has("state")) {
      // ContractContextException is the only throwable exception in a contract and
      // it should be thrown when a contract faces some non-recoverable error
      throw new ContractContextException("please set asset_id and state in the argument");
    }

    String assetId = argument.get("asset_id").asText();
    int state = argument.get("state").asInt();

    Optional<Asset<JsonNode>> asset = ledger.get(assetId);

    if (!asset.isPresent() || asset.get().data().get("state").asInt() != state) {
      ledger.put(assetId, getObjectMapper().createObjectNode().put("state", state));
    }

    return null;
  }
}

次のコマンドを実行してコントラクトをコンパイルできます。

./gradlew assemble

これにより、build/classes/java/main/com/org1/contract/StateUpdater.class が生成されます。

コントラクトを登録する​

次に、以下のコマンドを実行してコントラクトを登録します。

client/bin/scalardl register-contract --properties client.properties --contract-id StateUpdater --contract-binary-name com.org1.contract.StateUpdater --contract-class-file build/classes/java/main/com/org1/contract/StateUpdater.class

コントラクト ID にはグローバルに一意の ID を設定してください (例: 上記のコマンドの StateUpdater)。

ヒント

改ざん検知可能な方法で「誰が何をしたか」を明確にするため、異なる証明書を使用することで、同じコントラクトに異なるコントラクト ID を設定できます。

たとえば、投票アプリケーションについて考えてみましょう。 アプリケーションでは、誰でも同じ投票ロジックで投票できるため、同じコントラクトを使用できますが、A の投票と B の投票は適切かつ安全に区別する必要があります。A が B に投票することはできませんし、その逆も同様です。 同じコントラクトに異なるコントラクト ID を使用することで、A の投票と B の投票が互いに異なる方法で識別されることを保証できます。

コントラクトを実行する​

これで、次のコマンドでコントラクトを実行する準備が整いました。

client/bin/scalardl execute-contract --properties client.properties --contract-id StateUpdater --contract-argument '{"asset_id":"some_asset", "state":3}'

コントラクト引数では、キー asset_id で指定された値は、各アセットに対してグローバルに一意である必要があります。

Ledger の状態を検証する​

次のコマンドを実行すると、Ledger の状態を検証できます。

client/bin/scalardl validate-ledger --properties client.properties --asset-id="some_asset"

検証が何を行うかは、ScalarDL の設定方法によって異なります。簡単に言うと、ScalarDL Ledger のみを使用する場合、検証はアセットを走査して、アセットが再計算可能で、有効なハッシュチェーン構造を持っているかどうかを確認します。ScalarDL Ledger と Auditor を使用する場合、検証は Ledger と Auditor の状態間の矛盾 (つまり、ビザンチン故障) を中央集権的な調整なしでチェックします。Auditor による検証の詳細については、ScalarDL Auditor の使用を開始するをお読みください。

独自のコントラクトを作成するか、汎用コントラクトを使用する​

コントラクトを準備するには、独自のコントラクトを作成するか、定義済みのコントラクトを使用するかの2つのオプションがあります。

上で説明したように、コントラクトを作成するには、定義済みの基本コントラクトクラスを拡張し、必要に応じて invoke メソッドをオーバーライドする必要があります。詳細については、適切なコントラクトを作成する方法に関するガイドを参照してください。

定義済みのコントラクトは汎用コントラクトと呼ばれ、一般的なユースケースの基本機能を提供します。詳細については、汎用コントラクトおよびファンクションの使用を参照してください。

参考文献​

独自のコントラクトを作成するには、以下を参照してください。

汎用コントラクトを使用するには、以下を参照してください。

Java アプリケーションで ScalarDL コンポーネントを操作するには、以下を参照してください。

ScalarDL の基礎をより深く理解するには、以下を参照してください。