VDR Tools SDK pool configuration and key management docs (#133)

* Initial Pool/keys API documentation * Add more information about inputs and responses * Renamed the file and moved in menu tree * Making formatting more consistent with current standards * Split key management to its own page * Update vdr-tools-sdk-key-management.md * Separate out pool config doc to its own page * Update vdr-tools-sdk-key-management.md * Formatted pool connection docs * Matched the pool config docs for internal style guidelines * Fixed links and summary page * Fix MDLint fail Co-authored-by: Ankur Banerjee <[email protected]>
cheqd · Feb 24, 2022 · 6820e4c · 6820e4c
1 parent e5160fc
commit 6820e4c
Show file tree

Hide file tree

Showing 3 changed files with 274 additions and 0 deletions.
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -25,6 +25,8 @@
   * [Docker Compose Based Localnet](docs/build-and-networks/local-docker-compose-network.md)
   * [Setting up a new network](docs/build-and-networks/manual-network-setup.md)
 * [Client-app Identity APIs](docs/identity-api/README.md)
+  * [Account and key management in VDR Tools SDK](docs/identity-api/vdr-tools-sdk-accounts-keys.md)
+  * [Ledger connections in VDR Tools SDK](docs/identity-api/vdr-tools-sdk-ledger-connection.md)
   * [Error messages](docs/identity-api/identity-api-error-messages.md)
 
 ## Architecture

diff --git a/docs/identity-api/vdr-tools-sdk-accounts-keys.md b/docs/identity-api/vdr-tools-sdk-accounts-keys.md
@@ -0,0 +1,104 @@
+# Account and key management in VDR Tools SDK
+
+## Overview
+
+This page describes how [Evernym VDR Tools](https://gitlab.com/evernym/verity/vdr-tools) works with cheqd accounts in identity wallets built using the VDR Tools SDK.
+
+## Identity wallet key methods for cheqd accounts
+
+These methods below are used to manage [cheqd accounts/wallets](../cheqd-cli/cheqd-cli-accounts.md) within identity wallets built using VDR Tools SDK. (For example, to pay for or receive payment for transactions that need to be written to ledger.)
+
+For compatibility purposes, VDR Tools SDK method names use the `indy_` prefix. This may be updated in the future as work is done on the upstream project to refactor method names to be ledger-agnostic.
+
+### indy_cheqd_keys_add_random
+
+Create a new identity wallet key with specified `alias`, without specifying any other additional information, such as mnemonics.
+
+#### Input parameters
+
+* `wallet_handle` (integer): Linked to previously created and opened wallet.
+* `alias` (string): Memorable key name/alias that makes it easier to reference for a user.
+
+#### Example output
+
+```jsonc
+{
+    "alias": "some_alias",
+    "account_id": "cheqd1gudhsalrhsurucr5gkvga5973359etv6q0xvwz",
+    "pub_key": "xSMzGopEnnTPCwjQwryDcrG9MGw3sVyb4ecYVaJrfkoA"
+}
+```
+
+### indy_cheqd_keys_add_from_mnemonic
+
+Similar to the technique used in [cheqd CLI to recover a key](../cheqd-cli/cheqd-cli-key-management.md), it allows identity wallets that use VDR Tools SDK to recover a key from mnemonic.
+
+#### Input parameters
+
+* `wallet_handle` (integer): Linked to previously created and opened wallet.
+* `alias` (string): Memorable key name/alias that makes it easier to reference for a user.
+* `mnemonic` (string): 12 or 24 word seed phrase to recover the keys associated with a wallet.
+
+#### Example output
+
+```jsonc
+{
+	"alias": "some_alias_2",
+    "account_id": "cheqd10hcwm576uprz53wj2p8vv2dg0u8zu3n6l0wsxr",
+    "pub_key": "fPn3LGakGrbHJTEk5fs7hAfa65DfpefgWawmwfCwjTHF"
+}
+```
+
+### indy_cheqd_keys_get_info
+
+Display information about an existing key based on its `alias` in an identity wallet.
+
+#### Input parameters
+
+* `wallet_handle` (integer): Linked to previously created and opened wallet.
+* `alias` (string): Memorable key name/alias that makes it easier to reference for a user.
+
+#### Example output
+
+```jsonc
+{
+    "alias": "some_alias",
+    "account_id": "cheqd17t7fmt3vpkkxa04hql0gyx8dufumq05vr9ztp6",
+    "pub_key": "juXSChod4MmAAniezu44pDtTMgTUizUi84RaWqnhf43j"
+}
+```
+
+### indy_cheqd_keys_get_list_keys
+
+Return a list of all keys stored in the local identity wallet.
+
+#### Input parameters
+
+* `wallet_handle` (integer): Linked to previously created and opened wallet.
+
+#### Example output
+
+```js
+ [
+ Object({"account_id": String("cheqd1x33xkjd3gqlfhz5l9h60m53pr2mdd4y3nc86h0"), "alias": String("alice"), "pub_key": String("fTsZShn9KkgYKyDmbP5bLhVucNuPRdo4N6zGjAfzSSgv")}), 
+ Object({"account_id": String("cheqd1c4n6j030trrljqsphmw9tcrcpgdf33hd3jd0jn"), "alias": String("some_alias_2"), "pub_key": String("g2vxGLkuYg84s3UcsKSxSttNgCKoQgRBQXizzSqbHdRJ")}), 
+ Object({"account_id": String("cheqd1kcwadpmfreuvdrvkz7v79ydclfnn4ukdhp57c2"), "alias": String("some_alias_1"), "pub_key": String("27taHHmKLcxZEHQPmiNHuXTXQYF7u2CxGrzKQMxBZALsQ")})
+ ]
+ ```
+
+### indy_cheqd_keys_sign
+
+Sign a transaction using key in identity wallet with specified `alias`. The cheqd account associated with the key must have sufficient balance to fund the transaction.
+
+#### Input parameters
+
+* `wallet_handle` (integer): Linked to previously created and opened wallet.
+* `alias` (string): Memorable key name/alias that makes it easier to reference for a user.
+* `tx_raw`: Raw bytecode representation of of a correctly formattted cheqd/Cosmos transaction.
+* `tx_len`: Length of string for bytes in transaction.
+
+#### Example output
+
+```text
+[10, 146, 1, 10, 134, 1, 10, 37, 47, 99, 104, 101, 113, 100, 105, 100, 46, 99, 104, 101, 113, 100, 110, 111, 100, 101, 46, 99, 104, 101, 113, 100, 46, 77, 115, 103, 67, 114, 101, 97, 116, 101, 78, 121, 109, 18, 93, 10, 45, 99, 111, 115, 109, 111, 115, 49, 120, 51, 51, 120, 107, 106, 100, 51, 103, 113, 108, 102, 104, 122, 53, 108, 57, 104, 54, 48, 109, 53, 51, 112, 114, 50, 109, 100, 100, 52, 121, 51, 110, 99, 56, 54, 104, 48, 18, 10, 116, 101, 115, 116, 45, 97, 108, 105, 97, 115, 26, 11, 116, 101, 115, 116, 45, 118, 101, 114, 107, 101, 121, 34, 8, 116, 101, 115, 116, 45, 100, 105, 100, 42, 9, 116, 101, 115, 116, 45, 114, 111, 108, 101, 18, 4, 109, 101, 109, 111, 24, 192, 2, 18, 97, 10, 78, 10, 70, 10, 31, 47, 99, 111, 115, 109, 111, 115, 46, 99, 114, 121, 112, 116, 111, 46, 115, 101, 99, 112, 50, 53, 54, 107, 49, 46, 80, 117, 98, 75, 101, 121, 18, 35, 10, 33, 2, 59, 126, 95, 52, 102, 213, 99, 251, 102, 62, 148, 101, 72, 226, 188, 243, 222, 31, 35, 148, 19, 127, 79, 75, 79, 37, 160, 132, 193, 33, 148, 7, 18, 4, 10, 2, 8, 1, 18, 15, 10, 9, 10, 4, 99, 104, 101, 113, 18, 1, 48, 16, 224, 167, 18, 26, 64, 130, 229, 164, 76, 214, 244, 157, 39, 135, 11, 118, 223, 29, 196, 41, 92, 247, 126, 129, 194, 18, 154, 136, 165, 153, 76, 202, 85, 187, 195, 40, 69, 10, 206, 165, 238, 223, 245, 35, 140, 92, 123, 246, 110, 23, 39, 32, 215, 239, 230, 196, 146, 168, 5, 147, 9, 67, 113, 242, 163, 0, 223, 233, 73]
+```
diff --git a/docs/identity-api/vdr-tools-sdk-ledger-connection.md b/docs/identity-api/vdr-tools-sdk-ledger-connection.md
@@ -0,0 +1,168 @@
+# Ledger connections in VDR Tools SDK
+
+## Overview
+
+This page describes how [Evernym VDR Tools](https://gitlab.com/evernym/verity/vdr-tools) connects to the cheqd network ledger "pool".
+
+It is worth noting here that the terminology of "pool" connection is specifically a legacy term originally used in [Hyperledger Indy](https://github.com/hyperledger/indy-node), which as a permissioned blockchain assumes there is a finite pools of servers. While this paradigm is no longer true in the public, permissionless world of the cheqd network, the identity APIs in VDR Tools SDK and similar Hyperledger Aries-based frameworks is retained for explanations.
+
+## Ledger pool connection methods
+
+Establishing a ledger "pool" connection in VDR Tools SDK broadly has the following steps:
+
+1. Generate keys or restore them from mnemonic as described in [key management using VDR Tools SDK](vdr-tools-sdk-accounts-keys.md).
+2. Add ledger "pool" configuration as described using the methods below, i.e., `indy_cheqd_pool_add`. This only adds the configuration, without actually establishing the connection. The connection is established once the first transaction is sent.
+
+For compatibility purposes, VDR Tools SDK method names use the `indy_` prefix. This may be updated in the future as work is done on the upstream project to refactor method names to be ledger-agnostic.
+
+### indy_cheqd_pool_add
+
+Add a new cheqd network ledger `PoolConfig` configuration.
+
+#### Input parameters
+
+* `alias` (string): Friendly-name for pool connection
+* `rpc_address` (string): Tendermint RPC endpoint (e.g., `http://localhost:26657`) for a cheqd network node(s) to send/receive transactions to.
+* `chain_id` (string): cheqd network identifier, e.g., `cheqd-mainnet-1`
+
+#### Example output
+
+```jsonc
+{
+    "alias": "cheqd_pool",
+    "rpc_address": "https://rpc.testnet.cheqd.network:443",
+    "chain_id": "cheqd-testnet-4"
+}
+```
+
+### indy_cheqd_pool_get_config
+
+Fetch pool configuration for a specific connection `alias`.
+
+#### Input parameters
+
+* `alias` (string): Friendly-name for pool connection
+
+#### Example output
+
+```jsonc
+{
+    "alias": "cheqd_pool",
+    "rpc_address": "https://rpc.testnet.cheqd.network:443",
+    "chain_id": "cheqd-testnet-4"
+}
+```
+
+### indy_cheqd_pool_get_all_config
+
+Display pool configuration for all pools.
+
+#### Example output
+
+```js
+[Object({
+	"alias": String("cheqd_pool_1"),
+	"chain_id": String("cheqd-testnet-4"),
+	"rpc_address": String("https://rpc.testnet.cheqd.network:443")
+}), 
+Object({
+	"alias": String("cheqd_pool_2"),
+	"chain_id": String("cheqd-mainnet-1"),
+	"rpc_address": String("https://rpc.cheqd.net:443")
+})]
+```
+
+### indy_cheqd_pool_broadcast_tx_commit
+
+Broadcast a signed cheqd/Cosmos transaction to node(s) in a defined pool. This wraps up any identity-related payloads generated by VDR Tools SDK in a cheqd ledger transaction wrapper [using standard Cosmos broadcast methods](https://docs.cosmos.network/master/run-node/txs.html#broadcasting-a-transaction).
+
+#### Input parameters
+
+* `alias` (string): Friendly-name for pool connection
+* `signed_tx_raw` (string): String of bytes containing a correctly formattted cheqd/Cosmos transaction.
+* `signed_tx_len` (integer): Length of signed transaction string in bytes.
+
+#### Example output
+
+```jsonc
+{
+	"check_tx": {
+		"code": 0,
+		"data": "",
+		"log": "[]",
+		"info": "",
+		"gas_wanted": "300000",
+		"gas_used": "38591",
+		"events": [],
+		"codespace": ""
+	},
+	"deliver_tx": {
+		"code": 0,
+		"data": "Cg8KCUNyZWF0ZU55bRICCAU=",
+		"log": [{
+			"events ": [{
+				"type ": "message",
+				"attributes": [{
+					"key": "action",
+					"value": "CreateDid"
+				}]
+			}]
+		}],
+		"info": "",
+		"gas_wanted": "300000",
+		"gas_used": "46474",
+		"events": [{
+			"type": "message",
+			"attributes": [{
+				"key": "YWN0aW9u",
+				"value": "Q3JlYXRlTnlt"
+			}]
+		}],
+		"codespace": ""
+	},
+	"hash": "364441EDC5266A0B6AF5A67D4F05AC5D1FE95BFEDFBEBBE195723BEDBA877CAE",
+	"height": "121"
+}
+```
+
+### indy_cheqd_pool_abci_query
+
+Send a [Tendermint ABCI query](https://docs.cosmos.network/v0.44/intro/sdk-app-architecture.html#abci) to specified pool `alias`. ABCI queries allow custom queries to be constructed and resultant answers fetched from the cheqd network ledger, for any data that may not be covered under the usual RPC/REST API endpoints.
+
+#### Input parameters
+
+* `alias` (string): Friendly-name for pool connection
+* `req_json` (string): ABCI query in JSON format
+
+#### Example output
+
+```jsonc
+{
+   "did":
+   {
+      "creator": "cheqd1x33xkjd3gqlfhz5l9h60m53pr2mdd4y3nc86h0",
+      "id": 4,
+      "alias": "test-alias",
+      "verkey": "did:cheqd:<namespace>:<unique-id>#key1",
+      "did": "did:cheqd:<namespace>:<unique-id>"
+   }
+}
+```
+
+### indy_cheqd_pool_abci_info
+
+Display pool information for a specified pool `alias`. Similar to the response that can be fetched directly from Tendermint RPC endpoint at the `/abci_info` path, e.g., `http://localhost:26657/abci_info`
+
+#### Example output
+
+```jsonc
+{
+	"response": {
+    	"data": "cheqd-node",
+    	"version": "0.4.0",
+    	"app_version": "1",
+    	"last_block_height": "541557",
+    	"last_block_app_hash": "fMbrqSo1KFPeKBASylG4lEVy7iItUwGVqSUw1CE9Ydw="
+    }
+}
+```