docs: Add oasis rofl documentation

docs/README.md

@@ -38,6 +38,7 @@ It boasts a number of handy features:
 - Developer features:
   - built-in testing accounts compatible with the Oasis test runner, the Oasis
     CI and the official Sapphire and Emerald Localnet Docker images
+  - Oasis ROFL app compilation, deployment and management
   - Oasis Wasm smart contract code deployment, instantiation, management and
     calls
   - debugging tools for deployed Wasm contracts

docs/rofl.md

@@ -0,0 +1,202 @@
+---
+title: ROFL
+description: Manage "Runtime OFfchain Logic" apps
+---
+
+# Manage ROFL Apps
+
+The `rofl` command combines a series of actions for managing the [Runtime
+OFfchain Logic (ROFL)][rofl] apps:
+
+- build ROFL locally,
+- verify the ROFL bundle,
+- register, deregister and update ROFL apps on the network,
+- show information about the registered ROFL apps,
+- other convenient tooling for ROFL app developers.
+
+[rofl]: https://github.com/oasisprotocol/docs/blob/main/docs/rofl/README.mdx
+
+## Build ROFL {#build}
+
+The `build` command will execute a series of build commands depending on the
+target Trusted Execution Environment (TEE) and produce the Oasis Runtime
+Container (ORC) bundle.
+
+Building a ROFL bundle requires the [Network and ParaTime][npa] selectors.
+Additionally, the following flags are available:
+
+- `--mode` specifies a `production` (enabled SGX attestations suitable for the
+  Mainnet and Testnet) or `unsafe` build (using mocked SGX for debugging
+  and testing). The default behavior is set to `auto` which, based on the
+  selected [Network and ParaTime][npa], determines the build mode.
+- `--output` the filename of the output ORC bundle. Defaults to the package name
+  inside `Cargo.toml` and the `.orc` extension.
+
+:::info
+
+Building ROFL apps involves **cross compilation**, so you do not need a working
+TEE on your machine. However, you do need to install all corresponding compilers
+and toolchains. Check out the [ROFL Prerequisites] chapter for details.
+
+:::
+
+[ROFL Prerequisites]: https://github.com/oasisprotocol/oasis-sdk/blob/main/docs/rofl/prerequisites.md
+[npa]: ./account.md#npa
+
+### For SGX {#build-sgx}
+
+To build an SGX-based ROFL for the default [Network and ParaTime][npa], run
+`build sgx`.
+
+![code shell](../examples/rofl/build-sgx.in.static)
+
+If you want to build a version for debugging and you're not running a [Sapphire
+Localnet] at build time, you can force the *unsafe* build mode:
+
+![code shell](../examples/rofl/build-sgx-unsafe.in.static)
+
+The following SGX-specific flags are supported:
+
+- `--sgx-heap-size` is the heap size in bytes.
+- `--sgx-stack-size` is the stack size in bytes.
+- `--sgx-threads` is the maximum number of threads that an enclave can spawn.
+  This number must be at least the number of threads required by the [Oasis
+  Core runtime], otherwise the app may crash during the execution under actual
+  SGX. It can be greater, if the app needs to spawn more threads.
+
+[Sapphire Localnet]: https://github.com/oasisprotocol/sapphire-paratime/blob/main/docs/guide.mdx#running-a-private-oasis-network-locally
+[Oasis Core runtime]: https://github.com/oasisprotocol/oasis-core/blob/master/runtime/THREADS.md
+
+<!-- TODO
+### For TDX {#build-tdx}
+
+To build an TDX container for the default [Network and ParaTime][npa], run
+`build tdx`.
+
+-->
+
+## Show ROFL identity {#identity}
+
+Run `rofl identity` to compute the **cryptographic identity** of the ROFL app:
+
+![code shell](../examples/rofl/identity.in.static)
+
+![code](../examples/rofl/identity.out.static)
+
+The output above is Base64-encoded enclave identity which depends on the ROFL
+source code and the build environment. Enclave identities should be reproducible
+on any computer and are used to prove and verify the integrity of ROFL binaries
+on the network. See the [Reproducibility] chapter to learn more.
+
+[Reproducibility]: https://github.com/oasisprotocol/oasis-sdk/blob/main/docs/runtime/reproducibility.md
+
+## Create a new ROFL app on the network {#create}
+
+Use `rofl create` to register a new ROFL app on the network using a
+specific [policy] file:
+
+![code shell](../examples/rofl/create.in.static)
+
+![code](../examples/rofl/create.out.static)
+
+Returned is the unique ROFL app ID starting with `rofl1` and which you
+will refer to for managing your ROFL app in the future.
+
+:::info
+
+In order to prevent spam attacks registering a ROFL app requires a
+certain amount to be deposited from your account until you decide to
+[remove it](#remove). The deposit remains locked for the lifetime of the app.
+Check out the [ROFL chapter][policy] to view the current staking requirements.
+
+:::
+
+You can also define specific [Network, ParaTime and Account][npa] parameters:
+
+![code shell](../examples/rofl/create-npa.in.static)
+
+With the `--scheme` parameter, you can select one of the following ROFL app ID
+derivation schemes:
+
+- `cn` for the ROFL app creator address (the account you're using to sign the
+  transaction) combined with the account's nonce (default). This behavior is
+  similar to the one of the Ethereum [smart contract address derivation] and is
+  deterministic.
+- `cri` uses the ROFL app creator address combined with the block round the
+  transaction will be validated in and its position inside that block.
+
+[policy]: https://github.com/oasisprotocol/oasis-sdk/blob/main/docs/rofl/deployment.md#register-the-app
+[smart contract address derivation]: https://ethereum.org/en/developers/docs/accounts/#contract-accounts
+
+## Update ROFL policy {#update}
+
+Use `rofl update` command to set the new policy and the new administrator of the
+ROFL app:
+
+![code shell](../examples/rofl/update.in.static)
+
+![code shell](../examples/rofl/update.out.static)
+
+For the administrator, you can also specify an account name in your wallet or
+address book.
+
+To keep the existing administrator, pass `self`:
+
+![code shell](../examples/rofl/update-self.in.static)
+
+You can also define specific [Network, ParaTime and Account][npa] parameters:
+
+![code shell](../examples/rofl/update-npa.in.static)
+
+## Remove ROFL app from the network {#remove}
+
+Run `rofl remove` to deregister your ROFL app:
+
+![code shell](../examples/rofl/remove.in.static)
+
+![code](../examples/rofl/remove.out.static)
+
+The deposit required to register the ROFL app will be returned to the current
+administrator account.
+
+You can also define specific [Network, ParaTime and Account][npa] parameters:
+
+![code shell](../examples/rofl/remove-npa.in.static)
+
+## Show ROFL information {#show}
+
+Run `rofl show` to obtain the information from the network on the ROFL admin
+account, staked amount, current ROFL policy and running instances:
+
+![code shell](../examples/rofl/show.in.static)
+
+![code](../examples/rofl/show.out.static)
+
+You can also define specific [Network and ParaTime][npa] parameters:
+
+![code shell](../examples/rofl/show-np.in.static)
+
+## Advanced
+
+### Show the current trust-root {#trust-root}
+
+In order the ROFL app can trust the environment it is executed in, it
+needs to have a hardcoded *trust root*. Typically, it consists of:
+
+- the [ParaTime ID],
+- the [chain domain separation context],
+- the specific consensus block hash and its height.
+
+To obtain the latest trust root in rust programming language, run
+`oasis rofl trust-root`:
+
+![code shell](../examples/rofl/trust-root.in.static)
+
+![code](../examples/rofl/trust-root.out.static)
+
+You can also define specific [Network and ParaTime][npa] parameters:
+
+![code shell](../examples/rofl/trust-root-np.in.static)
+
+[ParaTime ID]: https://github.com/oasisprotocol/oasis-core/blob/master/docs/runtime/identifiers.md
+[chain domain separation context]: https://github.com/oasisprotocol/oasis-core/blob/master/docs/crypto.md#chain-domain-separation

examples/rofl/build-sgx-unsafe.in.static

@@ -0,0 +1 @@
+oasis rofl build sgx --mode unsafe

examples/rofl/build-sgx.in.static

@@ -0,0 +1 @@
+oasis rofl build sgx

examples/rofl/create-npa.in.static

@@ -0,0 +1 @@
+oasis rofl create policy.yml --network testnet --paratime sapphire --account my_rofl_acc

examples/rofl/create.in.static

@@ -0,0 +1 @@
+oasis rofl create policy.yml

examples/rofl/create.out.static

@@ -0,0 +1,44 @@
+You are about to sign the following transaction:
+Format: plain
+Method: rofl.Create
+Body:
+  {
+    "policy": {
+      "quotes": {
+        "pcs": {
+          "tcb_validity_period": 30,
+          "min_tcb_evaluation_data_number": 16
+        }
+      },
+      "enclaves": [
+        "0+tTmlVjUvP0eIHXH7Dld3svPppCUdKDwYxnzplndLea/8+uR7hI7CyvHEm0soNTHhzEJfk1grNoBuUqQ9eNGg=="
+      ],
+      "endorsements": [
+        {
+          "any": {}
+        }
+      ],
+      "fees": 2,
+      "max_expiration": 3
+    },
+    "scheme": 1
+  }
+Authorized signer(s):
+  1. YgkEiVSR4SMQdfXw+ppuFYlqH0seutnCKk8KG8PyAx0= (ed25519)
+     Nonce: 2
+Fee:
+  Amount: 0.0101487
+  Gas limit: 101487
+  (gas price: 0.0000001  per gas unit)
+
+Network:  localnet
+ParaTime: sapphire
+Account:  test:bob
+? Sign this transaction? Yes
+(In case you are using a hardware-based signer you may need to confirm on device.)
+Broadcasting transaction...
+Transaction included in block successfully.
+Round:            18715
+Transaction hash: 91d86ededa202bce7fb6fd8b5db10f0284a90d3e61ce5f73ea8031c1c1cce342
+Execution successful.
+Created ROFL application: rofl1qqn9xndja7e2pnxhttktmecvwzz0yqwxsquqyxdf

examples/rofl/identity.in.static

@@ -0,0 +1 @@
+oasis rofl identity rofl-oracle.orc

examples/rofl/identity.out.static

@@ -0,0 +1 @@
+wzwUd5Ym/e5OO87pGVk2yWL4v0x12U3Zx/48Vdoe1PyTBkRbZbh9kPyqgY1RsvenXEIHQA0c2nR/WlmvS1vbcg==

examples/rofl/remove-npa.in.static

@@ -0,0 +1 @@
+oasis rofl remove rofl1qrtetspnld9efpeasxmryl6nw9mgllr0euls3dwn --network testnet --paratime sapphire --account my_rofl_acc

examples/rofl/remove.in.static

@@ -0,0 +1 @@
+oasis rofl remove rofl1qrtetspnld9efpeasxmryl6nw9mgllr0euls3dwn

examples/rofl/remove.out.static

@@ -0,0 +1,25 @@
+You are about to sign the following transaction:
+Format: plain
+Method: rofl.Remove
+Body:
+  {
+    "id": "rofl1qqn9xndja7e2pnxhttktmecvwzz0yqwxsquqyxdf"
+  }
+Authorized signer(s):
+  1. YgkEiVSR4SMQdfXw+ppuFYlqH0seutnCKk8KG8PyAx0= (ed25519)
+     Nonce: 1
+Fee:
+  Amount: 0.0011285
+  Gas limit: 11285
+  (gas price: 0.0000001  per gas unit)
+
+Network:  localnet
+ParaTime: sapphire
+Account:  test:bob
+? Sign this transaction? Yes
+(In case you are using a hardware-based signer you may need to confirm on device.)
+Broadcasting transaction...
+Transaction included in block successfully.
+Round:            18692
+Transaction hash: d6f738868b9b0e5bfb55e9baa5ed2f23ac8bf8bcb6eb679179a895fd726b0fc2
+Execution successful.

examples/rofl/show-np.in.static

@@ -0,0 +1 @@
+oasis rofl show rofl1qqn9xndja7e2pnxhttktmecvwzz0yqwxsquqyxdf --network testnet --paratime sapphire

examples/rofl/show.in.static

@@ -0,0 +1 @@
+oasis rofl show rofl1qqn9xndja7e2pnxhttktmecvwzz0yqwxsquqyxdf

examples/rofl/show.out.static

@@ -0,0 +1,27 @@
+App ID:        rofl1qqn9xndja7e2pnxhttktmecvwzz0yqwxsquqyxdf
+Admin:         oasis1qrydpazemvuwtnp3efm7vmfvg3tde044qg6cxwzx
+Staked amount: 10000.0
+Policy:
+  {
+    "quotes": {
+      "pcs": {
+        "tcb_validity_period": 30,
+        "min_tcb_evaluation_data_number": 16
+      }
+    },
+    "enclaves": [
+      "0+tTmlVjUvP0eIHXH7Dld3svPppCUdKDwYxnzplndLea/8+uR7hI7CyvHEm0soNTHhzEJfk1grNoBuUqQ9eNGg=="
+    ],
+    "endorsements": [
+      {
+        "any": {}
+      }
+    ],
+    "fees": 2,
+    "max_expiration": 3
+  }
+
+=== Instances ===
+- RAK:        UwuhJrOYX6FDOc27NilQSrcVEtWD9voq+ST+ohsaRTI=
+  Node ID:    DbeoxcRwDO4Wh8bwq5rAR7wzhiB+LeYn+y7lFSGAZ7I=
+  Expiration: 7

examples/rofl/trust-root-np.in.static

@@ -0,0 +1 @@
+oasis rofl trust-root --network testnet --paratime sapphire

examples/rofl/trust-root.in.static

@@ -0,0 +1 @@
+oasis rofl trust-root

examples/rofl/trust-root.out.static

@@ -0,0 +1,6 @@
+TrustRoot {
+    height: 1022,
+    hash: "bb3e63d729dd568ce07b37eea33eddf8082ed4cacbd64097aad32168a4a4fc9a".into(),
+    runtime_id: "8000000000000000000000000000000000000000000000000000000000000000".into(),
+    chain_context: "074f5ba071c4385a7ad24aea0a3a7b137901395e8f3b35479c1cce87d3170f4e".to_string(),
+}

examples/rofl/update-npa.in.static

@@ -0,0 +1 @@
+oasis rofl update rofl1qqn9xndja7e2pnxhttktmecvwzz0yqwxsquqyxdf --policy policy2.yml --admin self --network testnet --paratime sapphire --account my_rofl_acc

examples/rofl/update-self.in.static

@@ -0,0 +1 @@
+oasis rofl update rofl1qqn9xndja7e2pnxhttktmecvwzz0yqwxsquqyxdf --policy policy2.yml --admin self

examples/rofl/update.in.static

@@ -0,0 +1 @@
+oasis rofl update rofl1qqn9xndja7e2pnxhttktmecvwzz0yqwxsquqyxdf --policy policy2.yml --admin oasis1qrec770vrek0a9a5lcrv0zvt22504k68svq7kzve

examples/rofl/update.out.static

@@ -0,0 +1,44 @@
+You are about to sign the following transaction:
+Format: plain
+Method: rofl.Update
+Body:
+  {
+    "id": "rofl1qqn9xndja7e2pnxhttktmecvwzz0yqwxsquqyxdf",
+    "policy": {
+      "quotes": {
+        "pcs": {
+          "tcb_validity_period": 30,
+          "min_tcb_evaluation_data_number": 16
+        }
+      },
+      "enclaves": [
+        "0+tTmlVjUvP0eIHXH7Dld3svPppCUdKDwYxnzplndLea/8+uR7hI7CyvHEm0soNTHhzEJfk1grNoBuUqQ9eNGg=="
+      ],
+      "endorsements": [
+        {
+          "any": {}
+        }
+      ],
+      "fees": 2,
+      "max_expiration": 3
+    },
+    "admin": "oasis1qrydpazemvuwtnp3efm7vmfvg3tde044qg6cxwzx"
+  }
+Authorized signer(s):
+  1. NcPzNW3YU2T+ugNUtUWtoQnRvbOL9dYSaBfbjHLP1pE= (ed25519)
+     Nonce: 7
+Fee:
+  Amount: 0.0101532
+  Gas limit: 101532
+  (gas price: 0.0000001  per gas unit)
+
+Network:  localnet
+ParaTime: sapphire
+Account:  test:alice
+? Sign this transaction? Yes
+(In case you are using a hardware-based signer you may need to confirm on device.)
+Broadcasting transaction...
+Transaction included in block successfully.
+Round:            413
+Transaction hash: 2d8ef6e832256986a19d7b92dcf182976205c5247aff71487832877ff4d72edd
+Execution successful.