AUTO: Docs repo sync - ScalarDL (#752)

* AUTO: Sync ScalarDL docs in English to docs site repo

* Add tutorial about writing apps with generic contracts

---------

Co-authored-by: josh-wong <joshua.wong@scalar-labs.com>
Co-authored-by: Josh Wong <23216828+josh-wong@users.noreply.github.com>

Author: github-actions[bot]

docs/generic-contracts-reference.mdx

@@ -45,7 +45,7 @@ A null value is returned if it is successful.
 ### Examples
 
 ```console
-scalardl execute-contract --properties client.properties \
+scalardl generic-contracts execute-contract --properties client.properties \
 --contract-id object.Put \
 --contract-argument '{"objct_id": "a.txt", "hash_value": "a3ae11", "metadata": {"note": "something"}}'
 ```
@@ -81,7 +81,7 @@ A null value is returned if it is successful.
 ### Examples
 
 ```console
-scalardl execute-contract --properties client.properties \
+scalardl generic-contracts execute-contract --properties client.properties \
 --contract-id object.Put \
 --contract-argument '{"object_id": "a.txt", "hash_value": "a3ae11"}' \
 --function-id object.PutToMutableDatabase \
@@ -134,7 +134,7 @@ A JSON object that has the following fields is returned.
 ### Examples
 
 ```console
-scalardl execute-contract --properties client.properties \
+scalardl generic-contracts execute-contract --properties client.properties \
 --contract-id object.Get \
 --contract-argument '{"objct_id": "a.txt"}'
 
@@ -184,7 +184,7 @@ Each JSON object for `faulty_versions` and `corresponding_given_versions` has th
 If all specified hash values are the same as the ones in Ledger, the following result is returned.
 
 ```console
-scalardl execute-contract --properties client.properties \
+scalardl generic-contracts execute-contract --properties client.properties \
 --contract-id object.Validate \
 --contract-argument \
 '{"object_id": "a.txt",
@@ -206,7 +206,7 @@ Contract result:
 If a different hash values is found, the following result is returned.
 
 ```console
-scalardl execute-contract --properties client.properties \
+scalardl generic-contracts execute-contract --properties client.properties \
 --contract-id object.Validate \
 --contract-argument \
 '{"object_id": "a.txt",
@@ -228,7 +228,7 @@ Contract result:
 If the `verbose` option is specified and a different hash value and metadata are found, the following result is returned.
 
 ```console
-scalardl execute-contract --properties client.properties \
+scalardl generic-contracts execute-contract --properties client.properties \
 --contract-id object.Validate \
 --contract-argument \
 '{"object_id": "a.txt",
@@ -257,7 +257,7 @@ Contract result:
 If the `all` option is specified and the number of given versions are different from the number of versions stored in ScalarDL, the following result is returned.
 
 ```console
-scalardl execute-contract --properties client.properties \
+scalardl generic-contracts execute-contract --properties client.properties \
 --contract-id object.Validate \
 --contract-argument \
 '{"object_id": "a.txt",
@@ -297,7 +297,7 @@ A null value is returned if it is successful.
 ### Examples
 
 ```console
-scalardl execute-contract --properties client.properties \
+scalardl generic-contracts execute-contract --properties client.properties \
 --contract-id collection.Create \
 --contract-argument '{"collection_id": "audit_set", "object_ids": ["a.txt"]}'
 ```
@@ -323,7 +323,7 @@ A null value is returned if it is successful.
 ### Examples
 
 ```console
-scalardl execute-contract --properties client.properties \
+scalardl generic-contracts execute-contract --properties client.properties \
 --contract-id collection.Add \
 --contract-argument '{"collection_id": "audit_set", "object_ids": ["a.txt"], "options": {"force": true}}'
 ```
@@ -349,7 +349,7 @@ A null value is returned if it is successful.
 ### Examples
 
 ```console
-scalardl execute-contract --properties client.properties \
+scalardl generic-contracts execute-contract --properties client.properties \
 --contract-id collection.Remove \
 --contract-argument '{"collection_id": "audit_set", "object_ids": ["a.txt"], "options": {"force": true}}'
 ```
@@ -377,7 +377,7 @@ A JSON object that has the following field is returned.
 ### Examples
 
 ```console
-scalardl execute-contract --properties client.properties \
+scalardl generic-contracts execute-contract --properties client.properties \
 --contract-id collection.Get \
 --contract-argument '{"collection_id": "audit_set"}'
 
@@ -410,7 +410,7 @@ A JSON object that has the following fields is returned.
 ### Examples
 
 ```console
-scalardl execute-contract --properties client.properties \
+scalardl generic-contracts execute-contract --properties client.properties \
 --contract-id collection.GetHistory \
 --contract-argument '{"collectionId": "audit_set", "options": {"limit": 2}}'
 
@@ -467,7 +467,7 @@ A JSON object that has the following field is returned.
 ### Examples
 
 ```console
-scalardl execute-contract --properties client.properties \
+scalardl generic-contracts execute-contract --properties client.properties \
 --contract-id collection.GetCheckpointInterval \
 --contract-argument '{}'
 

docs/how-to-write-applications-with-generic-contracts.mdx

@@ -0,0 +1,114 @@
+---
+tags:
+  - Community
+  - Enterprise
+displayed_sidebar: docsEnglish
+---
+
+# Write a ScalarDL Application with Generic Contracts
+
+import JavadocLink from "/src/theme/JavadocLink.js";
+
+This document explains how to write ScalarDL applications with generic contracts. You will learn how to interact with ScalarDL in your applications, handle errors, and validate your data when using generic contracts in ScalarDL.
+
+## Use the ScalarDL Client SDK for generic contracts
+
+You have two options to interact with ScalarDL when using generic contracts:
+
+- Using [commands](scalardl-command-reference.mdx), as shown in [Use Generic Contracts and Functions](use-generic-contracts.mdx)
+- Using the [Java Client SDK](scalardl-java-client-sdk/README.mdx)
+
+Using commands is convenient because you don't need to write applications. However, they invoke a process for each execution, which is slow, so they are mainly for quickly testing generic contracts. Instead, using the Client SDK is usually recommended when you write ScalarDL-based applications because it is more efficient.
+
+The Client SDK is available on [Maven Central](https://search.maven.org/search?q=a:scalardl-java-client-sdk). You can install it in your application by using a build tool such as Gradle. For example in Gradle, you can add the following dependency to `build.gradle`, replacing `VERSION` with the version of ScalarDL that you want to use.
+
+```gradle
+dependencies {
+    implementation group: 'com.scalar-labs', name: 'scalardl-java-client-sdk', version: '<VERSION>'
+}
+```
+
+The Client SDK APIs for generic contracts are provided by a service class called <JavadocLink packageName="scalardl-java-client-sdk" path="com/scalar/dl/client/service" className="GenericContractClientService" />. The following is a code snippet that shows how to use `GenericContractClientService` to execute a contract.
+
+```java
+  // ClientServiceFactory should always be reused.
+  ClientServiceFactory factory = new ClientServiceFactory();
+
+  // ClientServiceFactory creates a new GenericContractClientService object in every create method call
+  // but reuses the internal objects and connections as much as possible for better performance and resource usage.
+  GenericContractClientService service = factory.createForGenericContracts(new ClientConfig(new File(properties));
+  try {
+    // create an application-specific argument that matches the generic contract specification
+    JsonNode jsonArgument = ...;
+    ContractExecutionResult result = service.executeContract(contractId, jsonArgument);
+    result.getContractResult().ifPresent(System.out::println);
+  } catch (ClientException e) {
+    System.err.println(e.getStatusCode());
+    System.err.println(e.getMessage());
+  }
+
+  factory.close();
+```
+
+You should always use `ClientServiceFactory` to create `GenericContractClientService` objects. `ClientServiceFactory` caches objects that are required to create `GenericContractClientService` and reuses them on the basis of the given configurations, so `ClientServiceFactory` object should always be reused.
+
+`GenericContractClientService` is a thread-safe client that interacts with ScalarDL components, like Ledger and Auditor, to register certificates, register contracts, execute contracts, and validate data. When you execute a generic contract, you need to specify a `JsonNode` argument. For details about the specification of the input argument, see [Generic Contracts and Functions Reference Guide](generic-contracts-reference.mdx).
+
+:::warning
+
+Do not register and execute your custom contracts through `GenericContractClientService`. Using the generic contracts and your original contracts together is not supported because the proper asset management cannot be guaranteed.
+
+:::
+
+For more information about `ClientServiceFactory` and `GenericContractClientService`, see the [`scalardl-java-client-sdk` Javadoc](https://javadoc.io/doc/com.scalar-labs/scalardl-java-client-sdk/latest/index.html).
+
+## Handle errors
+
+If an error occurs in your application, the Client SDK will return an exception with a status code and an error message with an error code. You should check the status code and the error code to identify the cause of the error. For details about the status code and the error codes, see [Status codes](how-to-write-applications.mdx#status-codes) and [Error codes](how-to-write-applications.mdx#error-codes).
+
+### Implement error handling
+
+The SDK throws <JavadocLink packageName="scalardl-java-client-sdk" path="com/scalar/dl/client/exception" className="ClientException" /> when an error occurs. You can handle errors by catching the exception as follows:
+
+```java
+GenericContractClientService clientService = ...;
+try {
+    // interact with ScalarDL through a ClientService object
+} catch (ClientException) {
+    // e.getStatusCode() returns the status of the error
+}
+```
+
+## Validate your data
+
+In ScalarDL, you occasionally need to validate your data to make sure all the data is in a valid state. Since you can learn the basics of how ScalarDL validates your data in [Write a ScalarDL Application in Java](how-to-write-applications.mdx#validate-your-data), this section mainly describes differences between the `validateLedger` method in the regular `ClientService` and the `validateLedger` method in `GenericContractClientService`.
+
+When validating assets created by generic contracts, you need to specify the type of the asset and a list of keys to identify the asset. Currently, generic contracts create two types of assets: an object (`AssetType.OBJECT`) and a collection (`AssetType.COLLECTION`). For keys, you can specify the object ID or collection ID.
+
+An example code for validating an object is as follows:
+
+```java
+  GenericContractClientService service = ...
+  try {
+    LedgerValidationResult result = service.validateLedger(AssetType.OBJECT, ImmutableList.of("an_object_ID"));
+    // You can also specify age range.
+    // LedgerValidationResult result = service.validateLedger(AssetType.OBJECT, ImmutableList.of("an_object_ID"), startAge, endAge);
+  } catch (ClientException e) {
+  }
+```
+
+:::note
+
+Generic contracts internally assign a dedicated asset ID to an [asset record](data-modeling.mdx#asset-record) that represents an object or a collection. The asset ID consists of a prefix for the asset type and keys; for example, a prefix `o_` and an object ID for `AssetType.OBJECT`. Therefore, you will see such raw asset IDs in `AssetProof` in `LedgerValidationResult`.
+
+:::
+
+## Use other languages
+
+To interact with ScalarDL in languages other than Java, you can use ScalarDL Gateway.
+
+:::note
+
+Documentation for ScalarDL Gateway is currently being created and will be ready in the near future.
+
+:::

docs/scalardl-command-reference.mdx

@@ -24,6 +24,8 @@ This page introduces `scalardl`, which is a client command for interacting with
   - [`list-contracts`](#list-contracts): List registered contracts.
 - **Validate a ledger**
   - [`validate-ledger`](#validate-ledger): Validate a specified asset in a ledger.
+- **Run commands for generic-contracts**
+  - [`generic-contracts`](#generic-contracts): Run commands for a generic-contracts-based setup.
 
 ## `register-cert`
 
@@ -255,6 +257,132 @@ Validate an asset from age 0 to age 10 only.
 scalardl validate-ledger --properties client.properties --asset-id 'some_asset,0,10'
 ```
 
+## `generic-contracts`
+
+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](#subcommands) section.
+
+:::tip
+
+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-cert)                           | Register a specified certificate.       |
+| [`register-secret`](#register-secret)                       | Register a specified secret.            |
+| [`register-contract`](#register-contract)                   | Register a specified contract.          |
+| [`register-contracts`](#register-contracts)                 | Register multiple specified contracts.  |
+| [`register-function`](#register-function)                   | Register a specified function.          |
+| [`register-functions`](#register-functions)                 | Register multiple specified functions.    |
+| [`execute-contract`](#execute-contract)                     | Execute a specified contract.           |
+| [`list-contracts`](#list-contracts)                         | List the registered contracts.          |
+| [`validate-ledger`](#validate-ledger-for-generic-contracts) | Validate a specified asset in a ledger. |
+
+### `validate-ledger` for generic contracts
+
+Validate a specified [asset](data-modeling.mdx#asset) in a ledger.
+
+:::note
+
+Generic contracts internally assign a dedicated asset ID to an [asset record](data-modeling.mdx#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](#common-utility-options) are also available.
+
+### Examples for using subcommands
+
+Register a specified certificate. For available options, see [`register-cert`](#register-cert).
+
+```console
+scalardl generic-contracts register-cert --properties client.properties
+```
+
+Register a specified secret. For available options, see [`register-secret`](#register-secret).
+
+```console
+scalardl generic-contracts register-secret --properties client.properties
+```
+
+Register a specified contract. For available options, see [`register-contract`](#register-contract).
+
+```console
+scalardl generic-contracts 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 specified contracts. For available options, see [`register-contracts`](#register-contracts).
+
+```console
+scalardl generic-contracts register-contracts --properties client.properties --contracts-file /path/to/contracts-file
+```
+
+Register a specified function. For available options, see [`register-function`](#register-function).
+
+```console
+scalardl generic-contracts register-function --properties client.properties --function-id test-function --function-binary-name com.example.function.TestFunction --function-class-file /path/to/TestFunction.class
+```
+
+Register specified functions. For available options, see [`register-functions`](#register-functions).
+
+```console
+scalardl generic-contracts register-functions --properties client.properties --functions-file /path/to/functions-file
+```
+
+Execute a specified contract. For available options, see [`execute-contract`](#execute-contract).
+
+```console
+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`](#list-contracts).
+
+```console
+scalardl generic-contracts execute-contract --properties client.properties
+```
+
+Validate an object for all ages.
+
+```console
+scalardl generic-contracts validate-ledger --properties client.properties --object-id 'a.txt'
+```
+
+Validate an object from age 0 to age 10 only.
+
+```console
+scalardl generic-contracts validate-ledger --properties client.properties --object-id 'a.txt' --start-age 0 --end-age 10
+```
+
+Validate a collection for all ages.
+
+```console
+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`. 
+
+```console
+scalardl-gc validate-ledger --properties client.properties --object-id 'a.txt'
+```
+
+Use the subcommand `scalardl gc` as the alias of `scalardl generic-contracts`.
+
+```console
+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.