ScalarDL Client Command Reference
This page introduces scalardl, which is a client command for interacting with ScalarDL components.
Overview of commands​
- Bootstrap a client
bootstrap: Bootstrap a client by registering the identity information and system contracts.
- Register identity information
register-cert: Register a specified certificate.register-secret: Register a specified secret.
- Register business logic
register-contract: Register a specified contract.register-contracts: Register specified contracts.register-function: Register a specified function.register-functions: Register specified functions.
- Execute and list the registered business logic
execute-contract: Execute a specified contract.list-contracts: List registered contracts.
- Manage namespaces
create-namespace: Create a namespace.list-namespaces: List namespaces.drop-namespace: Drop a namespace.
- Validate a ledger
validate-ledger: Validate a specified asset in a ledger.
- Run commands for generic-contracts
generic-contracts: Run commands for a generic-contracts-based setup.
bootstrap​
Bootstrap a client by registering the identity information and system contracts. This command performs the following:
- Registers a certificate or secret based on the authentication method configured in the properties file.
- Registers the
ValidateLedgercontract if Auditor is enabled.
If the identity information or the contract is already registered, the command skips the registration and continues without error.
Options​
| Option | Description |
|---|---|
--config, --properties | A configuration file in properties format. |
Common utility options are also available.
Examples​
scalardl bootstrap --properties client.properties
register-cert​
Register a specified certificate.
Options​
| Option | Description |
|---|---|
--config, --properties | A configuration file in properties format. |
--namespace | A namespace where the certificate is registered. |
--entity-id | An entity ID for the certificate. |
--cert-path | A path to a PEM-formatted certificate file. |
--cert-version | The version of the certificate (default: 1). |
When --namespace is specified, --entity-id and --cert-path are also required. When --namespace is not specified, the identity information from the properties file is used.
Common utility options are also available.
Examples​
Register a certificate by using identity information from the properties file.
scalardl register-cert --properties client.properties
Register a certificate to a specific namespace.
scalardl register-cert --properties client.properties --namespace my_namespace --entity-id my_entity --cert-path /path/to/cert.pem
register-secret​
Register a specified secret.
Options​
| Option | Description |
|---|---|
--config, --properties | A configuration file in properties format. |
--namespace | A namespace where the secret is registered. |
--entity-id | An entity ID for the secret. |
--secret-key | A secret key for HMAC authentication. |
--secret-key-version | The version of the secret key (default: 1). |
When --namespace is specified, --entity-id and --secret-key are also required. When --namespace is not specified, the identity information from the properties file is used.
Common utility options are also available.
Examples​
Register a secret by using identity information from the properties file.
scalardl register-secret --properties client.properties
Register a secret to a specific namespace.
scalardl register-secret --properties client.properties --namespace my_namespace --entity-id my_entity --secret-key my-secret-key
register-contract​
Register a specified contract.
Options​
| Option | Description |
|---|---|
--config, --properties | A configuration file in properties format. |
--contract-binary-name | A binary name of a contract to register. |
--contract-class-file | A contract class file to register. |
--contract-id | An ID of a contract to register. |
--contract-properties | Contract properties in a serialized format. |
--deserialization-format | A deserialization format for contract properties. Valid values: JSON or STRING (default: JSON) |
Common utility options are also available.
Examples​
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
register-contracts​
Register specified contracts.
Options​
| Option | Description |
|---|---|
--config, --properties | A configuration file in properties format. |
--contracts-file | A file that includes contracts to register in TOML format. |
Common utility options are also available.
Examples​
scalardl register-contracts --properties client.properties --contracts-file /path/to/contracts-file
An example of the contracts file is as follows.
[[contracts]]
contract-id = "StateUpdater"
contract-binary-name = "com.org1.contract.StateUpdater"
contract-class-file = "build/classes/java/main/com/org1/contract/StateUpdater.class"
[[contracts]]
contract-id = "StateReader"
contract-binary-name = "com.org1.contract.StateReader"
contract-class-file = "build/classes/java/main/com/org1/contract/StateReader.class"
register-function​
Register a specified function.
Options​
| Option | Description |
|---|---|
--config, --properties | A configuration file in properties format. |
--function-binary-name | A binary name of a function to register. |
--function-class-file | A function class file to register. |
--function-id | An ID of a function to register. |
Common utility options are also available.
Examples​
scalardl register-function --properties client.properties --function-id test-function --function-binary-name com.example.function.TestFunction --function-class-file /path/to/TestFunction.class
register-functions​
Register specified functions.
Options​
| Option | Description |
|---|---|
--config, --properties | A configuration file in properties format. |
--functions-file | A file that includes functions to register in TOML format. |
Common utility options are also available.
Examples​
scalardl register-functions --properties client.properties --functions-file /path/to/functions-file
An example of the functions file is as follows.
[[functions]]
function-id = "TestFunction1"
function-binary-name = "com.org1.function.TestFunction1"
function-class-file = "build/classes/java/main/com/org1/function/TestFunction1.class"
[[functions]]
function-id = "TestFunction2"
function-binary-name = "com.org1.function.TestFunction2"
function-class-file = "build/classes/java/main/com/org1/function/TestFunction2.class"
execute-contract​
Execute a specified contract.
Options​
| Option | Description |
|---|---|
--config, --properties | A configuration file in properties format. |
--contract-argument | An argument for a contract to execute in a serialized format. |
--contract-id | An ID of a contract to execute. |
--deserialization-format | A deserialization format for contract and function arguments. Valid values: JSON or STRING (default: JSON) |
--function-id | An ID of a function to execute. |
Common utility options are also available.
Examples​
Execute a contract without a function.
scalardl execute-contract --properties client.properties --contract-id StateUpdater --contract-argument '{"asset_id":"some_asset", "state":3}'
Execute a contract with a function.
scalardl execute-contract --properties client.properties --contract-id TestContract --contract-argument '{...}' --function-id TestFunction --function-argument '{...}'
list-contracts​
List registered contracts.
Options​
| Option | Description |
|---|---|
--config, --properties | A configuration file in properties format. |
--contract-id | The ID of a contract to show. |
Common utility options are also available.
Examples​
List all contracts registered by the specified entity.
scalardl list-contracts --properties client.properties
Show a specified contract only.
scalardl list-contracts --properties client.properties --contract-id StateUpdater
create-namespace​
The namespace feature is currently in Public Preview. The feature and related documentation are subject to change.
Create a namespace. A namespace name must start with an alphabetic character and can only contain alphanumeric characters and underscores (pattern: [a-zA-Z][a-zA-Z0-9_]*). The default namespace default is reserved and cannot be created or dropped.
Options​
| Option | Description |
|---|---|
--config, --properties | A configuration file in properties format. |
--namespace | A name for the namespace that will be created. |
Common utility options are also available.
Examples​
scalardl create-namespace --properties client.properties --namespace my_namespace
list-namespaces​
The namespace feature is currently in Public Preview. The feature and related documentation are subject to change.
List namespaces.
Options​
| Option | Description |
|---|---|
--config, --properties | A configuration file in properties format. |
--pattern | A pattern to filter namespaces (partial match). |
Common utility options are also available.
Examples​
List all namespaces.
scalardl list-namespaces --properties client.properties
List namespaces that match a specified pattern.
scalardl list-namespaces --properties client.properties --pattern my_
drop-namespace​
The namespace feature is currently in Public Preview. The feature and related documentation are subject to change.
Drop a namespace. This command requires confirmation by typing the namespace name.
Options​
| Option | Description |
|---|---|
--config, --properties | A configuration file in properties format. |
--namespace | The name of the namespace to drop. |
Common utility options are also available.
Examples​
scalardl drop-namespace --properties client.properties --namespace my_namespace
validate-ledger​
Validate a specified asset in a ledger.
Options​
| Option | Description |
|---|---|
--config, --properties | A configuration file in properties format. |
--namespace | The namespace of the asset. If not specified, the scalar.dl.client.context.namespace value in the properties file will be used. If that is also not configured, the default namespace will be used. |
--asset-id | The ID of an asset or the ID and the ages of an asset. Format: 'ASSET_ID', the ID of an asset to validate, or 'ASSET_ID,START_AGE,END_AGE', the ID and the ages of an asset to validate. |
Common utility options are also available.
Examples​
Validate an asset for all ages.
scalardl validate-ledger --properties client.properties --asset-id 'some_asset'
Validate an asset from age 0 to age 10 only.
scalardl validate-ledger --properties client.properties --asset-id 'some_asset,0,10'
generic-contracts​
Although generic contracts were introduced in ScalarDL 3.10, HashStore, released in ScalarDL 3.12, provides a higher-level abstraction that wraps generic contracts. For most use cases, using HashStore is simpler and more efficient than using generic contracts directly. For details, see Get Started with ScalarDL HashStore in the latest version of ScalarDL.
Run commands for a generic-contracts-based setup, which are almost the same subcommands for the scalardl command. The only difference is in the validate-ledger subcommand, where you can specify assets by object IDs of the generic-contracts context instead of the raw asset IDs. For the other subcommands, see each corresponding command in the following Subcommands section.
You can also use the scalardl-gc top-level command and the gc subcommand as aliases of the generic-contracts subcommand.
Subcommands​
| Subcommand | Description |
|---|---|
register-cert | Register a specified certificate. |
register-secret | Register a specified secret. |
register-contract | Register a specified contract. |
register-contracts | Register multiple specified contracts. |
register-function | Register a specified function. |
register-functions | Register multiple specified functions. |
execute-contract | Execute a specified contract. |
list-contracts | List the registered contracts. |
validate-ledger | Validate a specified asset in a ledger. |
validate-ledger for generic contracts​
Validate a specified asset in a ledger.
Generic contracts internally assign a dedicated asset ID to an asset record that represents an object or collection. The asset ID consists of a prefix for the asset type and keys; for example, a prefix o_ and an object ID for an object. Therefore, you will see such raw asset IDs after running the validate-ledger command.
Options​
| Option | Description |
|---|---|
--config, --properties | A configuration file in the .properties format. |
--object-id | The ID of an object created by the object.Put contract. |
--collection-id | The ID of a collection created by the collection.Create contract. |
--start-age | The validation start age of the asset (optional). |
--end-age | The validation end age of the asset (optional). |
Common utility options are also available.
Examples for using subcommands​
Register a specified certificate. For available options, see register-cert.
scalardl generic-contracts register-cert --properties client.properties
Register a specified secret. For available options, see register-secret.
scalardl generic-contracts register-secret --properties client.properties
Register a specified contract. For available options, see register-contract.
scalardl generic-contracts register-contract --properties client.properties --contract-id object.Put --contract-binary-name com.scalar.dl.genericcontracts.object.Put --contract-class-file /path/to/Put.class
Register specified contracts. For available options, see register-contracts.
scalardl generic-contracts register-contracts --properties client.properties --contracts-file /path/to/contracts-file
Register a specified function. For available options, see register-function.
scalardl generic-contracts register-function --properties client.properties --function-id object.PutToMutableDatabase --function-binary-name com.scalar.dl.genericcontracts.object.PutToMutableDatabase --function-class-file /path/to/PutToMutableDatabase.class
Register specified functions. For available options, see register-functions.
scalardl generic-contracts register-functions --properties client.properties --functions-file /path/to/functions-file
Execute a specified contract. For available options, see execute-contract.
scalardl generic-contracts execute-contract --properties client.properties --contract-id object.Put --contract-argument '{"object_id": "a.txt", "hash_value": "b97a42c87a46ffebe1439f8c1cd2f86e2f9b84dad89c8e9ebb257a19b6fdfe1c", "metadata": {"note": "updated"}}'
List registered contracts. For available options, see list-contracts.
scalardl generic-contracts list-contracts --properties client.properties
Validate an object for all ages.
scalardl generic-contracts validate-ledger --properties client.properties --object-id 'a.txt'
Validate an object from age 0 to age 10 only.
scalardl generic-contracts validate-ledger --properties client.properties --object-id 'a.txt' --start-age 0 --end-age 10
Validate a collection for all ages.
scalardl generic-contracts validate-ledger --properties client.properties --collection-id 'audit_set'
Use the top-level command scalardl-gc as the alias of scalardl generic-contracts.
scalardl-gc validate-ledger --properties client.properties --object-id 'a.txt'
Use the subcommand scalardl gc as the alias of scalardl generic-contracts.
scalardl gc validate-ledger --properties client.properties --object-id 'a.txt'
Common utility options​
You can use the following options in all the commands above.
| Option | Description |
|---|---|
-g, --use-gateway | A flag to use the gateway. |
-h, --help | Display the help message of a command. |
--stacktrace | Output Java Stack Trace to stderr stream. |