Recently, I shared a quickstart guide titled "How To Enhance Your App With Oasis ROFL". While the tutorial was complete in itself, I skipped some of the finer implementation details to keep it streamlined. Here, in this new 2-part series, I will unpack those sections step by step.
Rather than covering old ground from the post, which already features a short explainer video and visuals of the architectural breakdown and the workflow overview of the ROFL (runtime off-chain logic) framework, let's dive straight into the developers' POV here.
Workflow
As this visual shows, there is a dedicated Trusted Execution Environment (TEE) for every app that runs inside ROFL. An Oasis node provides the TEE from its ORC bundle, consisting of a zip archive containing the program binaries and metadata required for execution.
As a result, the ROFL apps registering on Oasis's network can easily authenticate to on-chain smart contracts and also transparently gain access to the decentralized per-app key management system.
The TEE ensures app security and enables secure communication with the outside world. The function of the light client here is to establish a fresh view of the Oasis consensus layer. This not only provides a source of approximate time references but also acts as an integrity gatekeeper for the verification of all on-chain states.
In addition, the app also generates a set of ephemeral cryptographic keys, used in remote attestation and on-chain registration, and then discarded at the end of the session to provide forward and backward secrecy.
The authentication process for on-chain modules is completed by signing and submitting special transactions. As a result, the app can now perform any arbitrary task and interact with the outside world through network connections, authenticated via HTTPS/TLS, or other methods such as light clients for other chains.
Prerequisites
We need 2 tools for ROFL development and deployment.
Oasis CLI: The Oasis command-line interface (CLI) is an all-in-one tool, handling wallet management, app registration, building, deployment, and replica management. For a detailed overview and installation instructions, check out the oasis command.
Docker: Having a containerized build environment is an essential prerequisite, as it ensures that you do not have to install a handful of Intel-specific libraries and dependencies on your system. Moreover, the Compose function will help test the ROFL locally before you deploy it on-chain.
You can choose any of the 3 following ways to continue.
Preferred
This method uses Oasis CLI and a container for building and testing.
First, you need to download and install the Oasis CLI on your platform.
Next, test the functionality by building the ROFL app.
oasis rofl build
Conservative
In this method, there are containers everywhere.
If there are any issues while installing the Oasis CLI locally, or perhaps you want to skip the Oasis CLI step altogether, the workaround is to run the oasis command from the rofl-dev image.
Note: You must be careful when you bind-mount the Oasis CLI config folder, which contains your wallet. Otherwise, there is a risk of losing access to your (funded) accounts.
- Invoke oasis from the rofl-dev image.
For Linux:
docker run --platform linux/amd64 --rm -v .:/src -v ~/.config/oasis:/root/.config/oasis -it ghcr.io/oasisprotocol/rofl-dev:main oasis
For MacOS:
docker run --platform linux/amd64 --rm -v .:/src -v "~/Library/Application Support/oasis/":/root/.config/oasis -it ghcr.io/oasisprotocol/rofl-dev:main oasis
For Windows:
docker run --platform linux/amd64 --rm -v .:/src -v %USERPROFILE%/AppData/Local/oasis/:/root/.config/oasis -it ghcr.io/oasisprotocol/rofl-dev:main oasis
- This step here is optional. You can choose to add oasisalias to your shell start-up script. This will mimic as if Oasis CLI was installed locally.
For Linux:
~/.bashrc
alias oasis='docker run --platform linux/amd64 --rm -v .:/src -v ~/.config/oasis:/root/.config/oasis -it ghcr.io/oasisprotocol/rofl-dev:main oasis'
For MacOS:
~/.bash_profile
alias oasis='docker run --platform linux/amd64 --rm -v .:/src -v "~/Library/Application Support/oasis/":/root/.config/oasis -it ghcr.io/oasisprotocol/rofl-dev:main oasis'
Advanced
This method uses native Oasis CLI and ROFL build utils.
Note: It is for linux/amd64 only.
The first step is installing the Oasis CLI locally.
Next, you need to install tools for creating and encrypting partitions and Quick Emulator (QEMU). For a Debian-based Linux, this can be done by running this command:
sudo apt install squashfs-tools cryptsetup-bin qemu-utils
Finally, you may be looking to build SGX and TDX-raw ROFL bundles. In that case, it will require the installation of the Rust toolchain and Fortanix libraries. It is a separate detailed process involving Oasis Core prerequisites, which I will elaborate on in a later post. For now, you just follow the steps outlined here.
Note: You do not need a working SGX/TDX TEE when building ROFL natively. Even an Intel-based CPU and the corresponding libraries will suffice.
Containerize
We have often mentioned that an ROFL app needs to be containerized. What does this mean? A container is basically a controlled environment that includes the exact version of the operating system, both system and user libraries, as well as your configured service. The image of the container is uploaded to an OCI file server, such as docker.io or ghcr.io. The server hosting your app can then download it, consisting two files.
my-bot
├── bot.py # A python bot script
└── requirements.txt # Python dependencies
Now, we will use Docker to containerize. However, you can choose to go with Podman instead of Docker, as once the app is deployed to a ROFL node, the containers there will be orchestrated by Podman anyway.
Dockerfile
Here we will create a file called Dockerfile inside the project folder. This will tell Docker to compile a python-based image and add the python bot script on top of it.
Dockerfile
FROM python:alpine3.17
WORKDIR /bot
COPY ./bot.py ./requirements.txt /bot
RUN pip install -r requirements.txt
ENTRYPOINT ["python", "bot.py"]
Compose
The function of Docker Compose is to orchestrate the containers you will be using. This ensures correct sequencing, defining storage points, networking, and other functionalities. You can create compose.yaml with the following command.
compose.yaml
services:
python-bot:
build: .
image: "docker.io/YOUR_USERNAME/YOUR_PROJECT"
platform: linux/amd64
environment:
- TOKEN=${TOKEN}
You may need to adjust the image: field(s) to fit your needs. The image: field must always point to a publicly accessible OCI registry from where your image will be downloaded for execution.
If you are replacing the image: field with a fully qualified domain of the OCI server you use, followed by your username, the field will look like:
- docker.io/your_username/my-bot
- ghcr.io/your_username/my-bot
Note: Always specify the container image URL with a fully qualified domain name, e.g., docker.io/ollama/ollama and not just ollama/ollama.
Build and Push
Now, you can build the container image and tag it using docker compose.
docker compose build
To check the compose setup locally, test it with this command.
docker compose up
To stop once done, use this command.
docker compose down
After you have completed building and tagging the images, the next step is to push the container images to a publicly accessible OCI registry that we referred to earlier (docker.io or ghcr.io).
For first-time use, you need to perform an authentication step by running this command.
docker login
Once done and for all those already logged in before, this command will upload the container images to the registry.
docker compose push
Note: For first-timers, when pushing the image to GitHub containers, please ensure public package visibility is properly configured.
Pin Your Image Hash
This is the final step in the containerizing process. It helps prevent another container image from being pulled inside ROFL. You do it by pinning the image digest inside compose.yaml. To fetch the sha256:... digest, try invoking:
docker images --digests
Then you need to append @ and the digest next to the image tag in your compose.yaml. Example:
image: "docker.io/MY_USERNAME/my-bot@sha256:9633593eb9e8395023cb0d926982602978466ec003efa189d94a34e7bea6ec0d"
Init
In the final section of this tutorial, we will see how to initialize the ROFL app. Before starting, you need to choose from the 3 options below. Notably, whatever you choose, it would likely be a trade-off between the Trusted Computing Base (TCB) size and ease of use.
- TDX containers ROFL (default): A Docker compose-based container service packed in a secure virtual machine.
- Raw TDX ROFL: A Rust app compiled as the init process of the operating system and packed in a secure virtual machine.
- SGX ROFL: A Rust app with fixed memory allocation compiled and packed into a single secure binary.
Init App Directory and Manifest
The first step is to create the basic directory structure for the app using the Oasis CLI.
oasis rofl init my-app
You now have a my-app directory and have also initialized a ROFL manifest file. As noted above, the default is a TDX container-based ROFL. To select one of the other options, you need to use the --kind parameter.
As a result of the init command, you will get the following output summary.
Creating a new ROFL app with default policy...
Name: my-app
Version: 0.1.0
TEE: tdx
Kind: container
Git repository initialized.
Created manifest in 'rofl.yaml'.
Run `oasis rofl create` to register your ROFL app and configure an app ID.
The directory structure (omitting git artifacts) will look like this.
myapp
├── compose.yaml # Container compose file.
└── rofl.yaml # ROFL app manifest.
Note: The manifest that this step initialized is a ROFL feature that contains metadata, secrets, and requested resources. These can be modified either manually or by using the CLI commands and require to be discussed in detail separately. For now, we have finished initialization.
In the concluding part of the series, I will guide you through the next steps in ROFLizing your app, involving create, build, deploy, and test processes.
Until then, if you encounter any issues, you can have a quick chat with the Oasis engineering team for help by dropping your comments in the dev-central channel in the official Discord.
