Merge pull request #3903 from oasisprotocol/ptrus/feature/cmd-runtime…

…-simplify

go/cmd/registry: simplify register runtime command

.changelog/3903.breaking.md

@@ -0,0 +1,8 @@
+go/cmd/registry: simplify register runtime command
+
+The `registry runtime gen_register` command now accepts a JSON runtime
+descriptor, which should simplify generating runtime registration
+transactions.
+The `registy runtime init_genesis` command is removed as runtime
+descriptors in genesis are not singed since version 21.0+ making the command
+obsolete.

docs/setup/deploying-a-runtime.md

@@ -2,8 +2,8 @@
 
 Before proceeding, make sure to look at the [prerequisites] required for running
 an Oasis Core environment followed by [build instructions] for the respective
-environment (non-SGX or SGX), using the [`oasis-net-runner`] and see
-[runtime documentation] for a general documentation on runtimes.
+environment (non-SGX or SGX), using the [`oasis-net-runner`] and see [runtime
+documentation] for a general documentation on runtimes.
 
 These instructions will show how to register and deploy a runtime node on a
 local development network.
@@ -19,6 +19,7 @@ Use the [`oasis-net-runner`] to provision a validator node network without any
 registered runtimes.
 
 <!-- markdownlint-disable line-length -->
+
 ```
 mkdir /tmp/runtime-example
 
@@ -31,11 +32,12 @@ oasis-net-runner \
   --fixture.default.fund_entities \
   --fixture.default.num_entities 2
 ```
+
 <!-- markdownlint-enable line-length -->
 
-The following steps should be run in a separate terminal window.
-To simplify the instructions set up an `ADDR` environment variable
-pointing to the UNIX socket exposed by the started node:
+The following steps should be run in a separate terminal window. To simplify the
+instructions set up an `ADDR` environment variable pointing to the UNIX socket
+exposed by the started node:
 
 ```
 export ADDR=unix:/tmp/runtime-example/net-runner/network/validator-0/internal.sock
@@ -50,11 +52,13 @@ oasis-node registry entity list -a $ADDR -v
 Should give output similar to:
 
 <!-- markdownlint-disable line-length -->
+
 ```
 {"v":2,"id":"JTUtHd4XYQjh//e6eYU7Pa/XMFG88WE+jixvceIfWrk=","nodes":["LQu4ZtFg8OJ0MC4M4QMeUR7Is6Xt4A/CW+PK/7TPiH0="]}
 {"v":2,"id":"+MJpnSTzc11dNI5emMa+asCJH5cxBiBCcpbYE4XBdso="}
 {"v":2,"id":"TqUyj5Q+9vZtqu10yw6Zw7HEX3Ywe0JQA9vHyzY47TU="}
 ```
+
 <!-- markdownlint-enable line-length -->
 
 In following steps we will register and run the [simple-keyvalue] runtime on the
@@ -66,51 +70,102 @@ network.
 
 To generate and sign a runtime registration transaction that will initialize and
 register the runtime we will use the `registry runtime gen_register` command.
-When initializing a runtime we need to specify various runtime parameters. To
-list all of the available parameters with short descriptions run:
-`registry runtime gen_register --help` subcommand.
-
-```
-oasis-node registry runtime gen_register --help
-```
+When initializing a runtime we need to provide the runtime descriptor.
 
-For additional information about runtimes and parameters see the
-[runtime documentation] and [code reference].
+For additional information about runtimes and parameters see the [runtime
+documentation] and [code reference].
 
 Before generating the registration transaction, gather the following data and
 set up environment variables to simplify instructions.
 
 - `ENTITY_DIR` - Path to the entity directory created when starting the
-development network. This entity will be the runtime owner. The genesis used in
-the provisioning initial network step funds the all entities in entities. In
-the following instructions we will be using the `entity-2` entity (located in
-`/tmp/runtime-example/net-runner/network/entity-2/` directory).
+  development network. This entity will be the runtime owner. The genesis used
+  in the provisioning initial network step funds the all entities in entities.
+  In the following instructions we will be using the `entity-2` entity (located
+  in `/tmp/runtime-example/net-runner/network/entity-2/` directory).
 - `ENTITY_ID` - ID of the entity that will be the owner of the runtime. You can
-get the entity ID from `$ENTITY_DIR/entity.json` file.
+  get the entity ID from `$ENTITY_DIR/entity.json` file.
 - `GENESIS_JSON` - Path to the genesis.json file used in the development
-network. (defaults to: `/tmp/runtime-example/net-runner/network/genesis.json`).
+  network. (defaults to:
+  `/tmp/runtime-example/net-runner/network/genesis.json`).
 - `RUNTIME_ID` - See [runtime identifiers] on how to choose a runtime
-identifier. In this example we use
- `8000000000000000000000000000000000000000000000000000000001234567`, which is a
-test identifier and will not work outside local tests.
+  identifier. In this example we use
+  `gAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEjRWc=`, which is the `base64` encoded:
+  `8000000000000000000000000000000000000000000000000000000001234567` - a test
+  identifier that will not work outside local tests.
 - `RUNTIME_GENESIS_JSON` - Path to the runtime genesis state file. The runtime
-used in this example does not use a genesis file.
-- `NONCE` - Entity account nonce. If you followed the guide, nonce `0`
-would be the initial nonce to use for the entity. Note: make sure to keep
-updating the nonce when generating new transactions. To query for current
-account nonce value use [stake account info] CLI.
+  used in this example does not use a genesis file.
+- `NONCE` - Entity account nonce. If you followed the guide, nonce `0` would be
+  the initial nonce to use for the entity. Note: make sure to keep updating the
+  nonce when generating new transactions. To query for current account nonce
+  value use [stake account info] CLI.
 
 ```
 export ENTITY_DIR=/tmp/runtime-example/net-runner/network/entity-2/
 export ENTITY_ID=+MJpnSTzc11dNI5emMa+asCJH5cxBiBCcpbYE4XBdso=
 export GENESIS_JSON=/tmp/runtime-example/net-runner/network/genesis.json
-export RUNTIME_ID=8000000000000000000000000000000000000000000000000000000001234567
-export RUNTIME_GENESIS_JSON=""
+export RUNTIME_ID=gAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEjRWc=
+export RUNTIME_DESCRIPTOR=/tmp/runtime-example/runtime_descriptor.json
 export NONCE=0
 ```
 
+Prepare a runtime descriptor:
+
+```
+cat << EOF > "${RUNTIME_DESCRIPTOR}"
+{
+  "v": 2,
+  "id": "${RUNTIME_ID}",
+  "entity_id": "${ENTITY_ID}",
+  "genesis": {
+    "state_root": "xnK40e9W7Sirh8NiLFEUBpvdOte4+XN0mNDAHs7wlno=",
+    "state": null,
+    "storage_receipts": null,
+    "round": 0
+  },
+  "kind": 1,
+  "tee_hardware": 0,
+  "versions": {
+    "version": {}
+  },
+  "executor": {
+    "group_size": 1,
+    "group_backup_size": 0,
+    "allowed_stragglers": 0,
+    "round_timeout": 5,
+    "max_messages": 32
+  },
+  "txn_scheduler": {
+    "algorithm": "simple",
+    "batch_flush_timeout": 1000000000,
+    "max_batch_size": 1000,
+    "max_batch_size_bytes": 16777216,
+    "propose_batch_timeout": 5
+  },
+  "storage": {
+    "group_size": 1,
+    "min_write_replication": 1,
+    "max_apply_write_log_entries": 100000,
+    "max_apply_ops": 2,
+    "checkpoint_interval": 10000,
+    "checkpoint_num_kept": 2,
+    "checkpoint_chunk_size": 8388608
+  },
+  "admission_policy": {
+    "entity_whitelist": {
+      "entities": {
+        "${ENTITY_ID}": {}
+      }
+    }
+  },
+  "staking": {},
+  "governance_model": "entity"
+}
+EOF
+```
+
 [runtime identifiers]: ../runtime/identifiers.md
-[stake account info]:  ../oasis-node/cli.md#info
+[stake account info]: ../oasis-node/cli.md#info
 
 ```
 oasis-node registry runtime gen_register \
@@ -121,13 +176,7 @@ oasis-node registry runtime gen_register \
   --genesis.file $GENESIS_JSON \
   --signer.backend file \
   --signer.dir $ENTITY_DIR \
-  --runtime.id $RUNTIME_ID \
-  --runtime.kind compute \
-  --runtime.genesis.state "$RUNTIME_GENESIS_JSON" \
-  --runtime.executor.group_size 1 \
-  --runtime.storage.group_size 1 \
-  --runtime.admission_policy entity-whitelist \
-  --runtime.admission_policy_entity_whitelist $ENTITY_ID \
+  --runtime.descriptor /tmp/runtime-example/runtime-descriptor.json
   --debug.dont_blame_oasis \
   --debug.allow_test_keys
 ```
@@ -136,17 +185,18 @@ After confirmation, this command outputs a signed transaction in the
 `/tmp/runtime-example/register_runtime.tx` file. In the next step we will submit
 the transaction to complete the runtime registration.
 
-{% hint style="warning" %}
-**WARNING**
+{% hint style="warning" %} **WARNING**
 
-When registering a runtime on a _non-development_ network you will likely
-want to modify default parameters. Additionally, since we are running this on
-a debug network, we had to enable the `debug.dont_blame_oasis` and
-`debug.allow_test_keys` flags.
-{% endhint %}
+When registering a runtime on a _non-development_ network you will likely want
+to modify default parameters. Additionally, since we are running this on a debug
+network, we had to enable the `debug.dont_blame_oasis` and
+`debug.allow_test_keys` flags. {% endhint %}
 
 <!-- markdownlint-disable line-length -->
-[code reference]: https://pkg.go.dev/github.com/oasisprotocol/oasis-core/go/registry/api?tab=doc#Runtime
+
+[code reference]:
+  https://pkg.go.dev/github.com/oasisprotocol/oasis-core/go/registry/api?tab=doc#Runtime
+
 <!-- markdownlint-enable line-length -->
 
 ## Submitting the Runtime Register Transaction
@@ -173,15 +223,15 @@ oasis-node registry runtime list \
 Should give output similar to
 
 <!-- markdownlint-disable line-length -->
+
 ```
 {"v":2,"id":"gAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEjRWc=","entity_id":"+MJpnSTzc11dNI5emMa+asCJH5cxBiBCcpbYE4XBdso=","genesis":{"state_root":"xnK40e9W7Sirh8NiLFEUBpvdOte4+XN0mNDAHs7wlno=","state":null,"storage_receipts":null,"round":0},"kind":1,"tee_hardware":0,"versions":{"version":{}},"executor":{"group_size":1,"group_backup_size":0,"allowed_stragglers":0,"round_timeout":5,"max_messages":32},"txn_scheduler":{"algorithm":"simple","batch_flush_timeout":1000000000,"max_batch_size":1000,"max_batch_size_bytes":16777216,"propose_batch_timeout":5},"storage":{"group_size":1,"min_write_replication":1,"max_apply_write_log_entries":100000,"max_apply_ops":2,"checkpoint_interval":10000,"checkpoint_num_kept":2,"checkpoint_chunk_size":8388608},"admission_policy":{"entity_whitelist":{"entities":{"+MJpnSTzc11dNI5emMa+asCJH5cxBiBCcpbYE4XBdso=":{}}}},"staking":{},"governance_model":"entity"}
 ```
+
 <!-- markdownlint-enable line-length -->
 
-{% hint style="info" %}
-Since we did not setup any runtime nodes, the runtime will get [suspended] until
-nodes for the runtime register.
-{% endhint %}
+{% hint style="info" %} Since we did not setup any runtime nodes, the runtime
+will get [suspended] until nodes for the runtime register. {% endhint %}
 
 In the next step we will setup and run a runtime node.
 
@@ -192,23 +242,22 @@ In the next step we will setup and run a runtime node.
 We will now run a node that will act as a compute, storage and client node for
 the runtime.
 
-{% hint style="info" %}
-In a real word scenario there would be multiple nodes running the runtime,
-each likely serving as a single type only.
-{% endhint %}
+{% hint style="info" %} In a real word scenario there would be multiple nodes
+running the runtime, each likely serving as a single type only. {% endhint %}
 
 Before running the node, gather the following data parameters and set up
 environment variables to simplify instructions.
 
-- `RUNTIME_BINARY` - Path to the runtime binary that will be run on the node.
-We will use the [simple-keyvalue] runtime. If you followed the
-[build instructions] the built binary is available at
-`./target/default/debug/simple-keyvalue`.
+- `RUNTIME_BINARY` - Path to the runtime binary that will be run on the node. We
+  will use the [simple-keyvalue] runtime. If you followed the [build
+  instructions] the built binary is available at
+  `./target/default/debug/simple-keyvalue`.
 - `SEED_NODE_ADDRESS` - Address of the seed node in the development network.
-Seed node address can be seen in the `oasis-net-runner` logs, when the network
-is initially provisioned.
+  Seed node address can be seen in the `oasis-net-runner` logs, when the network
+  is initially provisioned.
 
 <!-- markdownlint-disable line-length -->
+
 ```
 export RUNTIME_BINARY=/workdir/target/default/debug/simple-keyvalue
 export SEED_NODE_ADDRESS=<seed-node-tendermint-addr>@127.0.0.1:20000
@@ -238,19 +287,17 @@ oasis-node \
   --debug.dont_blame_oasis \
   --debug.allow_test_keys
 ```
+
 <!-- markdownlint-enable line-length -->
 
-{% hint style="danger" %}
-**WARNING**
+{% hint style="danger" %} **WARNING**
 
 This also enables unsafe debug-only flags which must never be used in a
-production setting as they may result in node compromise.
-{% endhint %}
+production setting as they may result in node compromise. {% endhint %}
 
-{% hint style="info" %}
-When running a runtime node in a production setting, the `worker.p2p.addresses`
-and `worker.client.addresses` flags need to be configured as well.
-{% endhint %}
+{% hint style="info" %} When running a runtime node in a production setting, the
+`worker.p2p.addresses` and `worker.client.addresses` flags need to be configured
+as well. {% endhint %}
 
 Following steps should be run in a new terminal window.
 
@@ -261,8 +308,8 @@ need to update the entity information in registry, to include the started node.
 
 Before proceeding, gather the runtime node id and store it in a variable. If you
 followed above instructions, the node id can be seen in
-`/tmp/runtime-example/runtime-node/identity_pub.pem` (or using the [node
-control status command]).
+`/tmp/runtime-example/runtime-node/identity_pub.pem` (or using the [node control
+status command]).
 
 Update the entity and generate a transaction that will update the registry
 state.
@@ -300,17 +347,19 @@ Confirm the entity in the registry has been updated by querying the registry
 state:
 
 <!-- markdownlint-disable line-length -->
+
 ```
 oasis-node registry entity list -a $ADDR -v
 
 {"v":1,"id":"JTUtHd4XYQjh//e6eYU7Pa/XMFG88WE+jixvceIfWrk=","nodes":["LQu4ZtFg8OJ0MC4M4QMeUR7Is6Xt4A/CW+PK/7TPiH0="]}
 {"v":1,"id":"+MJpnSTzc11dNI5emMa+asCJH5cxBiBCcpbYE4XBdso=","nodes":["vWUfSmjrHSlN5tSSO3/Qynzx+R/UlwPV9u+lnodQ00c="]}
 {"v":1,"id":"TqUyj5Q+9vZtqu10yw6Zw7HEX3Ywe0JQA9vHyzY47TU=","allow_entity_signed_nodes":true}
 ```
+
 <!-- markdownlint-enable line-length -->
 
-Node is now able to register and the runtime should get resumed, make sure
-this happens by querying the registry for runtimes:
+Node is now able to register and the runtime should get resumed, make sure this
+happens by querying the registry for runtimes:
 
 ```
 # Ensure node is registered
@@ -320,26 +369,26 @@ oasis-node registry node list -a $ADDR -v | grep "$NODE_ID"
 oasis-node registry runtime list -a $ADDR -v
 ```
 
-{% hint style="info" %}
-You might need to wait few seconds for an epoch transition so that the node
-is registered and runtime gets resumed.
+{% hint style="info" %} You might need to wait few seconds for an epoch
+transition so that the node is registered and runtime gets resumed.
 {% endhint %}
 
 [node control status command]: ../oasis-node/cli.md#status
 
 ## Testing the Runtime
 
-Now that the runtime node is running, is registered, and runtime is resumed,
-we can test the runtime by submitting runtime transactions.
-For that we use the [simple-keyvalue-client] binary which tests the
-functionality of the `simple-keyvalue` runtime.
+Now that the runtime node is running, is registered, and runtime is resumed, we
+can test the runtime by submitting runtime transactions. For that we use the
+[simple-keyvalue-client] binary which tests the functionality of the
+`simple-keyvalue` runtime.
 
 If you followed [build instructions] the built client binary is available at
 `target/default/debug/simple-keyvalue-client`.
 
 Run the test client:
 
 <!-- markdownlint-disable line-length -->
+
 ```
 ./target/default/debug/simple-keyvalue-client \
   --node-address unix:/tmp/runtime-example/runtime-node/internal.sock \
@@ -357,6 +406,7 @@ Getting latest block...
 ...
 Simple key/value client finished.
 ```
+
 <!-- markdownlint-enable line-length -->
 
 [simple-keyvalue-client]: ../../tests/clients/simple-keyvalue