Merge pull request #15 from DSRCorporation/docs/process-comments

Improve documentation structure and process review comments
hyperledger · Nov 28, 2023 · 0c76531 · 0c76531
2 parents 4f4b472 + 7f89124
commit 0c76531
Show file tree

Hide file tree

Showing 6 changed files with 162 additions and 84 deletions.
diff --git a/indy-besu/docs/README.md b/indy-besu/docs/README.md
@@ -1,11 +1,18 @@
 ## Design documents
 
-- [Auth model](design/auth.md)
-- [DID Method](design/did-doc.md)
-- [CL Registry](design/cl-registry.md)
-- [VDR](design/vdr.md)
-- [Validators node management](design/network.md)
-- [Upgrading contracts](design/upgradability.md)
+### Modules
+
+- Network Permission modules:
+  - [Auth](design/auth.md) - control user permissions
+    - role control - manage roles assigned to accounts  
+    - access control - first level validation: whether to accept write transactions (execute target contract method) from a given account
+  - [Upgrading contracts](design/upgradability.md) - control versions of deployed contracts (proposing and approving new versions).
+  - [Validators node management](design/network.md) - control the list of network validator nodes
+- [DID Methods](design/did-registry.md) - Supported DID methods 
+- Registries:
+  - [DID Document Registry](design/did-registry.md)
+  - [CL Registry](design/cl-registry.md)
+- [VDR](design/vdr.md) - design of VDR library
 
 ## Migration documents
 

diff --git a/indy-besu/docs/design/auth.md b/indy-besu/docs/design/auth.md
@@ -1,69 +1,19 @@
 # Auth model
 
-## Roles
+## Role control
 
-| Label    | Value     |
-|----------|-----------|
-| Trustee  | 1         |
-| Endorser | 2         |
-| Steward  | 3         |
+Contract to manage roles assigned to accounts.
 
-## Account role management
+### Roles
 
-| Contract    | Method     | Value      | Required Role | Action Description                       |
-|-------------|------------|------------|---------------|------------------------------------------|
-| RoleControl | hasRole    | -          | any           | Check if an account has a requested role |
-| RoleControl | getRole    | -          | any           | Get account role                         |
-| RoleControl | assignRole | Trustee    | Trustee       | Assign Trustee role to an account        |
-| RoleControl | assignRole | Endorser   | Trustee       | Assign Endorser role to an account       |
-| RoleControl | assignRole | Steward    | Trustee       | Assign Steward role to an account        |
-| RoleControl | revokeRole | Trustee    | Trustee       | Revoke Trustee role from an account      |
-| RoleControl | revokeRole | Endorser   | Trustee       | Assign Endorser role to an account       |
-| RoleControl | revokeRole | Steward    | Trustee       | Assign Steward role to an account        |
-
-## Validator nodes management
-
-| Contract         | Method          | Required Role | Action Description                      |
-|------------------|-----------------|---------------|-----------------------------------------|
-| ValidatorControl | getValidators   | any           | Get the list of current validator nodes |
-| ValidatorControl | addValidator    | Steward       | Add new validator node                  |
-| ValidatorControl | removeValidator | Steward       | Remove validator node                   |
-
-## DID Document management
-
-| Contract      | Method                         | Required Role               | Action Description              |
-|---------------|--------------------------------|-----------------------------|---------------------------------|
-| DidRegistry   | createDid                      | Trustee, Endorser, Steward  | Create a new DID Document       |
-| DidRegistry   | updateDid                      | DID owner                   | Update DID an existing Document |
-| DidRegistry   | deactivateDid                  | DID owner                   | Deactivate an existing DID      |
-| DidRegistry   | resolveDid                     | any                         | Resolve DID Document for a DID  |
+| Label              | Value                                  |
+|--------------------|----------------------------------------|
+| Trustee            | 1                                      |
+| Endorser           | 2                                      |
+| Steward            | 3                                      |
+| User without role  | 0 / "null" (not present on the ledger) |
 
-## CL Registry management
-
-| Contract                     | Method                      | Required Role               | Action Description                       |
-|------------------------------|-----------------------------|-----------------------------|------------------------------------------|
-| SchemaRegistry               | createSchema                | Trustee, Endorser, Steward  | Create a new Schema                      |
-| SchemaRegistry               | resolveSchema               | any                         | Resolve Schema by id                     |
-| CredentialDefinitionRegistry | createCredentialDefinition  | Trustee, Endorser, Steward  | Create a new Credential Definition       |
-| CredentialDefinitionRegistry | resolveCredentialDefinition | any                         | Resolve Credential Definition by id      |
-
-## Contract upgrade management
-
-| Contract          | Method                    | Required Role     | Action Description                                                       |
-|-------------------|---------------------------|-------------------|--------------------------------------------------------------------------|
-| UpgradeControl    | propose                   | Trustee           | Propose the upgrade of a specefic contract implementation                |
-| UpgradeControl    | approve                   | Trustee           | Approve the upgrade of a specefic contract implementation                |
-| UpgradeControl    | ensureSufficientApprovals | any               | Ensures that an implementation upgrade has received sufficient approvals |
-
-## Transactions managment
-
-| Transaction              | Required Role               | Action Description                               |
-|--------------------------|-----------------------------|--------------------------------------------------|
-| Deploy contract          | Trustee                     | Deploy a new contract                            |
-| Modify contract state    | Trustee, Endorser, Steward  | Execute contract method to modify its state      |
-| Read contract state      | any                         | Execute contract method to read its state        |
-
-## Storage format
+### Storage format
 
 * Roles collection:
   * Description: Mapping holding the list of accounts with roles assigned to them. Accounts which does not have any role assigned are not present in the list. 
@@ -97,11 +47,11 @@
     }
     ```
 
-## Transactions (Smart Contract's methods)
+### Transactions (Smart Contract's methods)
 
 Contract name: **RoleControl**
 
-### Check if account has role assigned
+#### Check if account has role assigned
 
 * Method: `hasRole`
   * Description: Transaction to check if an account has requested role assigned.
@@ -122,7 +72,7 @@ Contract name: **RoleControl**
       ```
   * Raised Event: None
 
-### Get account role
+#### Get account role
 
 * Method: `getRole`
   * Description: Transaction to get the role assigned to an account 
@@ -141,7 +91,7 @@ Contract name: **RoleControl**
       ```
   * Raised Event: None
 
-### Assign role to an account 
+#### Assign role to an account 
 
 * Method: `assignRole`
   * Description: Transaction to assign role to an account
@@ -163,7 +113,7 @@ Contract name: **RoleControl**
   * Raised Event: 
     * RoleAssigned(ROLE, account, sender)
 
-### Revoke role from an account 
+#### Revoke role from an account 
 
 * Method: `revokeRole`
   * Description: Transaction to revive role from an account
@@ -185,3 +135,87 @@ Contract name: **RoleControl**
   * Raised Event: 
     * RoleRevoked(ROLE, account, sender)
 
+
+
+## Access control
+
+The first level validation whether to accept write transactions (execute target contract method) from a given account or not.
+
+### Transactions (Smart Contract's methods)
+
+Contract name: **transactionAllowed**
+
+#### Check if sender can perform an action
+
+* Method: `transactionAllowed`
+  * Description: Transaction to check whether to accept a transaction received from a given account.
+  * Restrictions: None
+  * Format
+      ```
+      AccountControl.transactionAllowed(
+        address sender,
+        address target,
+        uint256 value,
+        uint256 gasPrice,
+        uint256 gasLimit,
+        bytes calldata payload
+      ) returns (bool)
+      ```
+  * Raised Event: None
+
+## Ledger Permissions
+
+### Account role management
+
+| Contract    | Method     | Value      | Required Role | Action Description                       |
+|-------------|------------|------------|---------------|------------------------------------------|
+| RoleControl | hasRole    | -          | any           | Check if an account has a requested role |
+| RoleControl | getRole    | -          | any           | Get account role                         |
+| RoleControl | assignRole | Trustee    | Trustee       | Assign Trustee role to an account        |
+| RoleControl | assignRole | Endorser   | Trustee       | Assign Endorser role to an account       |
+| RoleControl | assignRole | Steward    | Trustee       | Assign Steward role to an account        |
+| RoleControl | revokeRole | Trustee    | Trustee       | Revoke Trustee role from an account      |
+| RoleControl | revokeRole | Endorser   | Trustee       | Assign Endorser role to an account       |
+| RoleControl | revokeRole | Steward    | Trustee       | Assign Steward role to an account        |
+
+### Validator nodes management
+
+| Contract         | Method          | Required Role | Action Description                      |
+|------------------|-----------------|---------------|-----------------------------------------|
+| ValidatorControl | getValidators   | any           | Get the list of current validator nodes |
+| ValidatorControl | addValidator    | Steward       | Add new validator node                  |
+| ValidatorControl | removeValidator | Steward       | Remove validator node                   |
+
+### DID Document management
+
+| Contract      | Method                         | Required Role               | Action Description              |
+|---------------|--------------------------------|-----------------------------|---------------------------------|
+| DidRegistry   | createDid                      | Trustee, Endorser, Steward  | Create a new DID Document       |
+| DidRegistry   | updateDid                      | DID owner                   | Update DID an existing Document |
+| DidRegistry   | deactivateDid                  | DID owner                   | Deactivate an existing DID      |
+| DidRegistry   | resolveDid                     | any                         | Resolve DID Document for a DID  |
+
+### CL Registry management
+
+| Contract                     | Method                      | Required Role               | Action Description                       |
+|------------------------------|-----------------------------|-----------------------------|------------------------------------------|
+| SchemaRegistry               | createSchema                | Trustee, Endorser, Steward  | Create a new Schema                      |
+| SchemaRegistry               | resolveSchema               | any                         | Resolve Schema by id                     |
+| CredentialDefinitionRegistry | createCredentialDefinition  | Trustee, Endorser, Steward  | Create a new Credential Definition       |
+| CredentialDefinitionRegistry | resolveCredentialDefinition | any                         | Resolve Credential Definition by id      |
+
+### Contract upgrade management
+
+| Contract          | Method                    | Required Role     | Action Description                                                       |
+|-------------------|---------------------------|-------------------|--------------------------------------------------------------------------|
+| UpgradeControl    | propose                   | Trustee           | Propose the upgrade of a specefic contract implementation                |
+| UpgradeControl    | approve                   | Trustee           | Approve the upgrade of a specefic contract implementation                |
+| UpgradeControl    | ensureSufficientApprovals | any               | Ensures that an implementation upgrade has received sufficient approvals |
+
+### General transactions management
+
+| Transaction              | Required Role                          | Action Description                               |
+|--------------------------|----------------------------------------|--------------------------------------------------|
+| Deploy contract          | Trustee                                | Deploy a new contract                            |
+| Modify contract state    | Per contract method as described above | Execute contract method to modify its state      |
+| Read contract state      | any                                    | Execute contract method to read its state        |
diff --git a/indy-besu/docs/design/did-methods.md b/indy-besu/docs/design/did-methods.md
@@ -0,0 +1,46 @@
+# DID Methods
+
+Out of box Ledger provides an ability to use one of two supported DID methods: `did:ethr` or `did:indy`.
+
+Contracts implementing both methods are deployed on the network and integrated with `CL Registry`.
+
+Ledger `permission` related modules are implemented in a way to use **account address** but not a DID.
+
+It is up to a User which DID method to use.
+
+> Moreover, users having an appropriate permissions can even deploy contracts adding support for another DID methods 
+> (need to integrate into `CLRegistry`).
+
+## Ethereum DID method: did:ethr
+
+Ethereum DID Method `did:ethr` described in
+the [specification](https://github.com/decentralized-identity/ethr-did-resolver/blob/master/doc/did-method-spec.md).
+
+Example DID: `did:ethr:0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266`
+
+## Indy2 DID method: did:indy2 - Indy/Sov DID methods adoption
+
+New `indy2` DID method represented in a form compatible with `indy` and `sov` DID methods used in legacy Indy based
+networks.
+
+Users having `indy/sov` DID's (like `did:sov:2wJPyULfLLnYTEFYzByfUR`) can keep using their `id`
+part (`2wJPyULfLLnYTEFYzByfUR`) for preserving the trust.
+
+Example:
+
+* Legacy DID: `did:sov:2wJPyULfLLnYTEFYzByfUR`
+* New DID will be stored on the Ledger: `did:indy2:2wJPyULfLLnYTEFYzByfUR`
+
+### DID Syntax
+
+| parameter          | value                                                   |
+|--------------------|---------------------------------------------------------|
+| did                | “did:” method-name “:” namespace “:” method-specific-id |
+| method-name        | "indy2"                                                 |
+| namespace          | “testnet”/"mainnet"                                     |
+| method-specific-id | indy-id                                                 |
+| indy-id            | Base58(Truncate_msb(16(SHA256(publicKey))))             |
+
+The `indy-id` is received by deriving from the initial ED25519 verkey the same was as it is described in
+the [Sovrin DID Method Specification](https://sovrin-foundation.github.io/sovrin/spec/did-method-spec-template.html#namespace-specific-identifier-nsi).
+
diff --git a/indy-besu/docs/design/did-doc.md → indy-besu/docs/design/did-registry.md b/indy-besu/docs/design/did-doc.md → indy-besu/docs/design/did-registry.md
@@ -1,13 +1,4 @@
-# DID Method
-
-## DID Syntax
-| parameter          | value                                                   |
-|--------------------|---------------------------------------------------------|
-| did                | “did:” method-name “:” namespace “:” method-specific-id |
-| method-name        | "indy2"                                                 |
-| namespace          | “testnet”/"mainnet"                                     |
-| method-specific-id | indy-id / UUID                                          |
-| indy-id            | Base58(Truncate_msb(16(SHA256(publicKey))))             |
+# DID Registry
 
 ## Storage format
 

diff --git a/indy-besu/docs/design/network.md b/indy-besu/docs/design/network.md
@@ -1,6 +1,6 @@
-## Validators node management
+# Validators node management
 
-### Storage format
+## Storage format
 
 * Validators list:
     * Description: List of current validator node addresses

diff --git a/indy-besu/smart_contracts/contracts/network/ValidatorSmartContractInterface.sol b/indy-besu/smart_contracts/contracts/network/ValidatorSmartContractInterface.sol
@@ -3,7 +3,7 @@ pragma solidity ^0.8.20;
 
 /**
  * @title ValidatorSmartContractInterface
- * @dev The contract interface that is used to getting an allowlist of validators.
+ * @dev The interface that defines function for controlling the list of the network validator nodes
  */
 interface ValidatorSmartContractInterface {
     /**