docs: Update for TDX container-based ROFL apps

Author: kostko

docs/rofl.md

@@ -16,72 +16,44 @@ OFfchain Logic (ROFL)][rofl] apps:
 
 [rofl]: https://github.com/oasisprotocol/docs/blob/main/docs/build/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 a ROFL app manifest (`rofl.yaml`) to be present
-in the current working directory. All information about what kind of ROFL app
-to build is specified in the manifest.
-
-Additionally, the following flags are available:
-
-- `--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
+## Initialize a new ROFL app manifest {#init}
 
-## Show ROFL identity {#identity}
+The `rofl init` command will prepare a new ROFL app manifest in the given
+directory (defaults to the current directory). The manifest is a YAML file named
+`rofl.yaml` which defines the versions of all components, upgrade policies, etc.
+needed to manage, build and deploy the ROFL app.
 
-Run `rofl identity` to compute the **cryptographic identity** of the ROFL app:
-
-![code shell](../examples/rofl/identity.in.static)
+You can also define specific [Network, ParaTime and Account][npa] parameters
+as those get recorded into the manfiest so you don't need to specify them on
+each invocation:
 
-![code](../examples/rofl/identity.out.static)
+![code shell](../examples/rofl/init.in.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
+![code](../examples/rofl/init.out.static)
 
 ## 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:
+Use `rofl create` to register a new ROFL app on the network using an existing
+manifest.
 
 ![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.
+will refer to for managing your ROFL app in the future. If you specify the
+`--update-manifest` parameter the manifest will be automatically updated with
+the newly assigned app identifier.
 
 :::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.
+Check out the [ROFL chapter][app] 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:
 
@@ -92,28 +64,46 @@ derivation schemes:
 - `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
+[app]: https://github.com/oasisprotocol/oasis-sdk/blob/main/docs/rofl/app.mdx
 [smart contract address derivation]: https://ethereum.org/en/developers/docs/accounts/#contract-accounts
 
-## Update ROFL policy {#update}
+## Build ROFL {#build}
 
-Use `rofl update` command to set the new policy and the new administrator of the
-ROFL app:
+The `rofl 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.
 
-![code shell](../examples/rofl/update.in.static)
+Additionally, the following flags are available:
 
-![code shell](../examples/rofl/update.out.static)
+- `--update-manifest` updates the enclave identity in the app manifest with the
+  identity of the locally built app.
+
+- `--output` the filename of the output ORC bundle. Defaults to the pattern
+  `<name>.<deployment>.orc` where `<name>` is the app name from the manifest and
+  `<deployment>` is the deployment name from the manifest.
+
+- `--verify` also verifies the locally built enclave identity against the
+  identity that is currently defined in the manifest and also against the
+  identity that is currently set in the on-chain policy.
 
-For the administrator, you can also specify an account name in your wallet or
-address book.
+:::info
 
-To keep the existing administrator, pass `self`:
+Building ROFL apps does not require a working TEE on your machine. However, you
+do need to install all corresponding tools. Check out the [ROFL Prerequisites]
+chapter for details.
 
-![code shell](../examples/rofl/update-self.in.static)
+:::
 
-You can also define specific [Network, ParaTime and Account][npa] parameters:
+[ROFL Prerequisites]: https://github.com/oasisprotocol/oasis-sdk/blob/main/docs/rofl/prerequisites.md
+[npa]: ./account.md#npa
 
-![code shell](../examples/rofl/update-npa.in.static)
+## Update ROFL app config {#update}
+
+Use `rofl update` command to update the ROFL app's configuration on chain:
+
+![code shell](../examples/rofl/update.in.static)
+
+![code shell](../examples/rofl/update.out.static)
 
 ## Remove ROFL app from the network {#remove}
 
@@ -126,10 +116,6 @@ Run `rofl remove` to deregister your ROFL app:
 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
@@ -139,11 +125,22 @@ account, staked amount, current ROFL policy and running instances:
 
 ![code](../examples/rofl/show.out.static)
 
-You can also define specific [Network and ParaTime][npa] parameters:
+## Advanced
 
-![code shell](../examples/rofl/show-np.in.static)
+### Show ROFL identity {#identity}
 
-## Advanced
+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
 
 ### Show the current trust-root {#trust-root}
 

examples/rofl/create-npa.in.static

@@ -1 +1 @@
-oasis rofl create policy.yml
+oasis rofl create --update-manifest

examples/rofl/create.in.static

@@ -7,12 +7,11 @@ Body:
       "quotes": {
         "pcs": {
           "tcb_validity_period": 30,
-          "min_tcb_evaluation_data_number": 16
+          "min_tcb_evaluation_data_number": 17,
+          "tdx": {}
         }
       },
-      "enclaves": [
-        "0+tTmlVjUvP0eIHXH7Dld3svPppCUdKDwYxnzplndLea/8+uR7hI7CyvHEm0soNTHhzEJfk1grNoBuUqQ9eNGg=="
-      ],
+      "enclaves": [],
       "endorsements": [
         {
           "any": {}
@@ -24,21 +23,22 @@ Body:
     "scheme": 1
   }
 Authorized signer(s):
-  1. YgkEiVSR4SMQdfXw+ppuFYlqH0seutnCKk8KG8PyAx0= (ed25519)
-     Nonce: 2
+  1. sk5kvBHaZ/si0xXRdjllIOxOgr7o2d1K+ckVaU3ndG4= (ed25519)
+     Nonce: 319
 Fee:
-  Amount: 0.0101487
-  Gas limit: 101487
-  (gas price: 0.0000001  per gas unit)
+  Amount: 0.0101405 TEST
+  Gas limit: 101405
+  (gas price: 0.0000001 TEST per gas unit)
 
-Network:  localnet
-ParaTime: sapphire
-Account:  test:bob
+Network:  testnet
+ParaTime: sapphire (Sapphire Testnet)
+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:            18715
-Transaction hash: 91d86ededa202bce7fb6fd8b5db10f0284a90d3e61ce5f73ea8031c1c1cce342
+Round:            412
+Transaction hash: 2d8ef6e832256986a19d7b92dcf182976205c5247aff71487832877ff4d72edd
 Execution successful.
-Created ROFL application: rofl1qqn9xndja7e2pnxhttktmecvwzz0yqwxsquqyxdf
+Created ROFL app: rofl1qzd82n99vtwesvcqjfyur4tcm45varz2due7s635
+Run `oasis rofl build --update-manifest` to build your ROFL app.

examples/rofl/create.out.static

@@ -0,0 +1 @@
+oasis rofl init --network testnet --account my_rofl_acc

examples/rofl/init.in.static

@@ -0,0 +1,12 @@
+Creating a new ROFL app with default policy...
+Name:     myapp
+Version:  0.1.0
+TEE:      tdx
+Kind:     container
+Deployment 'default':
+  Network:  testnet
+  ParaTime: sapphire
+  Debug:    false
+  Admin:    test_a
+Created manifest in 'rofl.yaml'.
+Run `oasis rofl create --update-manifest` to register your ROFL app and configure an app ID.

examples/rofl/init.out.static

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

examples/rofl/remove-npa.in.static

@@ -3,23 +3,23 @@ Format: plain
 Method: rofl.Remove
 Body:
   {
-    "id": "rofl1qqn9xndja7e2pnxhttktmecvwzz0yqwxsquqyxdf"
+    "id": "rofl1qzd82n99vtwesvcqjfyur4tcm45varz2due7s635"
   }
 Authorized signer(s):
-  1. YgkEiVSR4SMQdfXw+ppuFYlqH0seutnCKk8KG8PyAx0= (ed25519)
-     Nonce: 1
+  1. sk5kvBHaZ/si0xXRdjllIOxOgr7o2d1K+ckVaU3ndG4= (ed25519)
+     Nonce: 321
 Fee:
-  Amount: 0.0011285
-  Gas limit: 11285
-  (gas price: 0.0000001  per gas unit)
+  Amount: 0.0011288 TEST
+  Gas limit: 11288
+  (gas price: 0.0000001 TEST per gas unit)
 
-Network:  localnet
-ParaTime: sapphire
-Account:  test:bob
+Network:  testnet
+ParaTime: sapphire (Sapphire Testnet)
+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:            18692
-Transaction hash: d6f738868b9b0e5bfb55e9baa5ed2f23ac8bf8bcb6eb679179a895fd726b0fc2
+Round:            510
+Transaction hash: b3a6f36c7a846dcf3f28c2dd3d2383cc2c3f7c1e05cea4be92fff2338849d825
 Execution successful.