From 9843e730f4d1fe6c66fe7a1a957b7c0fa562e5d4 Mon Sep 17 00:00:00 2001
From: josh-wong <joshua.wong@scalar-labs.com>
Date: Wed, 30 Oct 2024 07:18:55 +0000
Subject: [PATCH] AUTO: Sync ScalarDL docs in English to docs site repo

---
 docs/how-to-write-contract.mdx | 36 ++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/docs/how-to-write-contract.mdx b/docs/how-to-write-contract.mdx
index 479ee5ae..38aa7823 100644
--- a/docs/how-to-write-contract.mdx
+++ b/docs/how-to-write-contract.mdx
@@ -117,6 +117,10 @@ setContext(context);
 
 ## Write a complex contract
 
+This section describes how to write a complex contract.
+
+### Call contracts in a nested way
+
 If your contract is more than 100 lines of code, it is a good sign that you are probably doing more than one thing with your contract.
 It is a good practice to write modularized contracts, where each contract is doing only one thing, and to combine contracts to express more complex business logic.
 
@@ -153,6 +157,38 @@ The `StateUpdaterReader` updates the Ledger just like `StateUpdater` and additio
 
 It's to be noted that all the contracts in the nested invocation are executed transactionally (in an ACID manner) in ScalarDL so that they are executed entirely successfully or they are entirely failed.
 
+### Manage who can access assets
+
+You can get identity information, which indicates who is executing the contract, by calling `getClientIdentityKey()` in a contract. This functionality helps to control who can access a certain asset. The following example shows `StateUpdater`, which has been modified so that it can only update a restricted asset with the name `state-xxx`, where `xxx` is an entity ID of the certificate or secret holder.
+
+For details, see the base contract page and the `ClientIdentityKey` page in the [Javadoc](https://javadoc.io/doc/com.scalar-labs/scalardl-java-client-sdk/latest/index.html) of the version of ScalarDL that you are using.
+
+```java
+public class StateUpdater extends JacksonBasedContract {
+
+  @Nullable
+  @Override
+  public JsonNode invoke(Ledger<JsonNode> ledger, JsonNode argument, @Nullable JsonNode properties) {
+    if (!argument.has("state")) {
+      throw new ContractContextException("please set state in the argument");
+    }
+
+    ClientIdentityKey clientIdentityKey = getClientIdentityKey();
+    String entityId = clientIdentityKey.getEntityId();
+    String assetId = "state-" + entityId;
+    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;
+  }
+}
+```
+
 ## Summary
 
 Here are the best practices for writing good contracts for ScalarDL.