In following steps we will register and run the simple-keyvalue runtime on the network.
Initializing a Runtime
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 provide the runtime descriptor.
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).
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.
GENESIS_JSON - Path to the genesis.json file used in the development 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 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.
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.
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.
Submitting the Runtime Register Transaction
To register the runtime, submit the generated transaction.
Since we did not setup any runtime nodes, the runtime will get [suspended] until nodes for the runtime register.
In the next step we will setup and run a runtime node.
Running a Runtime Node
We will now run a node that will act as a compute, storage and client node for the runtime.
In a real word scenario there would be multiple nodes running the runtime, each likely serving as a single type only.
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.
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.
This also enables unsafe debug-only flags which must never be used in a production setting as they may result in node compromise.
When running a runtime node in a production setting, the `worker.p2p.addresses` and `worker.client.addresses` flags need to be configured as well.
Following steps should be run in a new terminal window.
Updating Entity Nodes
Before the newly started runtime node can register itself as a runtime node, we 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).
Update the entity and generate a transaction that will update the registry state.
# NOTE: this ID is not generated deterministically make sure to change the ID
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
oasis-node registry node list -a $ADDR -v | grep "$NODE_ID"
# Ensure runtime is resumed.
oasis-node registry runtime list -a $ADDR -v
You might need to wait few seconds for an epoch transition so that the node is registered and runtime gets resumed.
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.
If you followed build instructions the built client binary is available at target/default/debug/simple-keyvalue-client.