Manage ROFL Apps

The rofl command combines a series of actions for managing the Runtime OFfchain Logic (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.

Build ROFL

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 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, 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.

For SGX

To build an SGX-based ROFL for the default Network and ParaTime, run build sgx.

oasis rofl build sgx

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:

oasis rofl build sgx --mode unsafe

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.

Show ROFL identity

Run rofl identity to compute the cryptographic identity of the ROFL app:

oasis rofl identity rofl-oracle.orc

wzwUd5Ym/e5OO87pGVk2yWL4v0x12U3Zx/48Vdoe1PyTBkRbZbh9kPyqgY1RsvenXEIHQA0c2nR/WlmvS1vbcg==

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.

Create a new ROFL app on the network

Use rofl create to register a new ROFL app on the network using a specific policy file:

oasis rofl create policy.yml

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

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. The deposit remains locked for the lifetime of the app. Check out the ROFL chapter to view the current staking requirements.

You can also define specific Network, ParaTime and Account parameters:

oasis rofl create policy.yml --network testnet --paratime sapphire --account my_rofl_acc

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.

Update ROFL policy

Use rofl update command to set the new policy and the new administrator of the ROFL app:

oasis rofl update rofl1qqn9xndja7e2pnxhttktmecvwzz0yqwxsquqyxdf --policy policy2.yml --admin oasis1qrec770vrek0a9a5lcrv0zvt22504k68svq7kzve

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.

For the administrator, you can also specify an account name in your wallet or address book.

To keep the existing administrator, pass self:

oasis rofl update rofl1qqn9xndja7e2pnxhttktmecvwzz0yqwxsquqyxdf --policy policy2.yml --admin self

You can also define specific Network, ParaTime and Account parameters:

oasis rofl update rofl1qqn9xndja7e2pnxhttktmecvwzz0yqwxsquqyxdf --policy policy2.yml --admin self --network testnet --paratime sapphire --account my_rofl_acc

Remove ROFL app from the network

Run rofl remove to deregister your ROFL app:

oasis rofl remove rofl1qrtetspnld9efpeasxmryl6nw9mgllr0euls3dwn

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.

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 parameters:

oasis rofl remove rofl1qrtetspnld9efpeasxmryl6nw9mgllr0euls3dwn --network testnet --paratime sapphire --account my_rofl_acc

Show ROFL information

Run rofl show to obtain the information from the network on the ROFL admin account, staked amount, current ROFL policy and running instances:

oasis rofl show rofl1qqn9xndja7e2pnxhttktmecvwzz0yqwxsquqyxdf

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

You can also define specific Network and ParaTime parameters:

oasis rofl show rofl1qqn9xndja7e2pnxhttktmecvwzz0yqwxsquqyxdf --network testnet --paratime sapphire

Advanced

Show the current 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:

oasis rofl trust-root

TrustRoot {
    height: 1022,
    hash: "bb3e63d729dd568ce07b37eea33eddf8082ed4cacbd64097aad32168a4a4fc9a".into(),
    runtime_id: "8000000000000000000000000000000000000000000000000000000000000000".into(),
    chain_context: "074f5ba071c4385a7ad24aea0a3a7b137901395e8f3b35479c1cce87d3170f4e".to_string(),
}

You can also define specific Network and ParaTime parameters:

oasis rofl trust-root --network testnet --paratime sapphire

Build ROFL​

For SGX​

Show ROFL identity​

Create a new ROFL app on the network​

Update ROFL policy​

Remove ROFL app from the network​

Show ROFL information​

Advanced​

Show the current trust-root​

Build ROFL

For SGX

Show ROFL identity

Create a new ROFL app on the network

Update ROFL policy

Remove ROFL app from the network

Show ROFL information

Advanced

Show the current trust-root