Runtime Off-Chain Logic (ROFL)

https://docs.oasis.io/build/rofl/
Admin
ROFL enables applications to run on Oasis nodes within a Trusted Execution Environment (TEE),...
Tokens:13,492
Snippets:156
Trust Score:7.8
Update:9 months ago
Show doc for...
Tokens:
Raw
### Build ROFL Bundle

Source: https://docs.oasis.io/build/rofl/quickstart

This command compiles your application into a ROFL bundle, which is a necessary step before submitting secrets and deployment information. The output is a `.orc` file located in your project directory.

```bash
oasis rofl build  
```

--------------------------------

### Deploy ROFL Application

Source: https://docs.oasis.io/build/rofl/quickstart

This command deploys your application to a ROFL provider. By default, it provisions a new machine that meets the specified resource requirements. After deployment, you can manage and monitor your application.

```bash
oasis rofl deploy  
```

--------------------------------

### Initialize ROFL Manifest

Source: https://docs.oasis.io/build/rofl/quickstart

This command generates the initial `rofl.yaml` manifest file within your application directory. This file configures essential aspects of your ROFL application, such as resources, artifacts, and container runtime.

```bash
oasis rofl init  
```

--------------------------------

### Compose Volume Example for UNIX Socket

Source: https://docs.oasis.io/build/rofl/features/appd

Example demonstrating how to expose the `/run/rofl-appd.sock` UNIX socket to a container using Docker Compose volumes. This allows the container to communicate with the `rofl-appd` daemon.

```yaml
services:
  mycontainer:
    # ... other details omitted ...
    volumes:
      - /run/rofl-appd.sock:/run/rofl-appd.sock

```

--------------------------------

### Install ROFL Build Utils on Debian

Source: https://docs.oasis.io/build/rofl/workflow/prerequisites

This command installs necessary utilities for ROFL development on Debian-based Linux systems, including tools for creating squashfs filesystems, disk encryption, and emulation.

```bash
sudo apt install squashfs-tools cryptsetup-bin qemu-utils  

```

--------------------------------

### Create Oasis Wallet Account

Source: https://docs.oasis.io/build/rofl/quickstart

This command initiates the creation of a new wallet account using the specified algorithm. It's a prerequisite for interacting with the Oasis network, including token operations and app registration.

```bash
oasis wallet create my_account --file.algorithm secp256k1-bip44  
```

--------------------------------

### Fetch ROFL Application Logs

Source: https://docs.oasis.io/build/rofl/quickstart

This command retrieves the logs from your deployed ROFL application. This is essential for debugging and monitoring the application's behavior in the ROFL environment.

```bash
oasis rofl machine logs  
```

--------------------------------

### Run Docker Compose Project Locally

Source: https://docs.oasis.io/build/rofl/workflow/containerize-app

This command starts the container(s) defined in your `docker-compose.yaml` file locally. It's useful for testing your application's containerized setup before pushing it to a registry.

```bash
docker compose up
```

--------------------------------

### Create ROFL App on Blockchain

Source: https://docs.oasis.io/build/rofl/quickstart

This command registers a new application on the Oasis blockchain. You can specify the network to use, defaulting to Sapphire Mainnet. Successful execution allows tracking your app on the Oasis Explorer.

```bash
oasis rofl create --network testnet  
```

--------------------------------

### Create Python App Docker Image

Source: https://docs.oasis.io/build/rofl/workflow/containerize-app

This Dockerfile defines how to build a container image for a Python application. It starts from a Python base image, copies the application code and dependencies, installs them, and sets the entrypoint to run the bot script. It assumes `bot.py` and `requirements.txt` are in the same directory.

```dockerfile
FROM python:alpine3.17

WORKDIR /bot
COPY ./bot.py ./requirements.txt /bot
RUN pip install -r requirements.txt

ENTRYPOINT ["python", "bot.py"]
```

--------------------------------

### Build ROFL App with Oasis CLI

Source: https://docs.oasis.io/build/rofl/workflow/prerequisites

This command builds the ROFL app using the Oasis CLI. It's a straightforward command to test the CLI installation and basic build functionality.

```bash
oasis rofl build  

```

--------------------------------

### Show ROFL Machine Status

Source: https://docs.oasis.io/build/rofl/quickstart

This command displays the current status of the ROFL machine provisioned for your deployed application. It's useful for verifying that the machine is running and ready to serve your application.

```bash
oasis rofl machine show  
```

--------------------------------

### Import Oasis Wallet Account

Source: https://docs.oasis.io/build/rofl/quickstart

This command allows importing an existing wallet account into the Oasis CLI using a private key or mnemonic. It's useful for managing existing funds or integrating with other wallet solutions.

```bash
oasis wallet import my_account  
```

--------------------------------

### Set ROFL Secret

Source: https://docs.oasis.io/build/rofl/quickstart

This command securely stores environment variables as secrets on-chain. The example shows how to set a `TOKEN` secret, which can then be referenced in your `compose.yaml` file, ensuring sensitive data is not exposed in plain text.

```bash
echo -n "my-secret-token" | oasis rofl secret set TOKEN -  
```

--------------------------------

### Build ROFL App Bundle

Source: https://docs.oasis.io/build/rofl/workflow/build

This command packs compose.yaml, OS components, and a trusted block hash to create a ROFL bundle for deployment. It also computes the enclave identity for authentication during remote attestation. Ensure you have the 'oasis' CLI installed.

```bash
oasis rofl build
```

--------------------------------

### Workaround for Environment Variables in Podman-Compose

Source: https://docs.oasis.io/build/rofl/troubleshooting

This example demonstrates a workaround for a podman-compose bug where environment variables defined in the compose file are not correctly used in entrypoint commands. It shows how to directly inject the variable's value.

```yaml
services:
  oracle:
    platform: linux/amd64
    environment:
      CONTRACT_ADDRESS: 0x5FbDB2315678afecb367f032d93F642f64180aa3
    entrypoint: /bin/sh -c 'python main.py $${CONTRACT_ADDRESS}'

```

```yaml
services:
  oracle:
    platform: linux/amd64
    entrypoint: /bin/sh -c 'python main.py 0x5FbDB2315678afecb367f032d93F642f64180aa3'

```

--------------------------------

### GET /rofl/v1/metadata

Source: https://docs.oasis.io/build/rofl/features/appd

Retrieves all user-set key-value pairs that are published as replica metadata on the ROFL chain. This metadata is namespaced with `net.oasis.app.`.

```APIDOC
## GET /rofl/v1/metadata

### Description
Retrieves all user-set key-value pairs that are published as replica metadata on the ROFL chain. This metadata is namespaced with `net.oasis.app.`.

### Method
GET

### Endpoint
/rofl/v1/metadata

### Parameters

### Request Example
(No request body for this endpoint)

### Response
#### Success Response (200)
- **key_fingerprint** (string) - The fingerprint of the key associated with the metadata.
- **version** (string) - The version of the metadata schema.

#### Response Example
```json
{
  "key_fingerprint": "a54027bff15a8726",
  "version": "1.0.0"
}
```
```

--------------------------------

### Update ROFL Secrets and Bundle Information

Source: https://docs.oasis.io/build/rofl/quickstart

This command submits the previously set secrets and the ROFL bundle information to the blockchain. This is a crucial step before deployment, ensuring all necessary data is recorded on-chain.

```bash
oasis rofl update  
```

--------------------------------

### GET /rofl/v1/app/id

Source: https://docs.oasis.io/build/rofl/features/appd

Retrieves the unique application identifier for the running app.

```APIDOC
## GET /rofl/v1/app/id

### Description
Retrieves the unique application identifier for the running app.

### Method
GET

### Endpoint
/rofl/v1/app/id

### Parameters

### Request Example
(No request body for this endpoint)

### Response
#### Success Response (200)
- **app_id** (string) - The unique identifier of the app.

#### Response Example
```
rofl1qqn9xndja7e2pnxhttktmecvwzz0yqwxsquqyxdf
```
```

--------------------------------

### Get Replica Metadata via REST API

Source: https://docs.oasis.io/build/rofl/features/appd

Endpoint to retrieve user-set metadata key-value pairs that are published on-chain as part of ROFL replica registration. This data is namespaced with `net.oasis.app.`.

```http
GET /rofl/v1/metadata HTTP/1.1
Host: localhost

```

--------------------------------

### Update ROFL App On-chain Configuration

Source: https://docs.oasis.io/build/rofl/workflow/build

This command updates the on-chain application configuration after changes to the app's policy in the manifest. It requires the designated admin account to issue an update transaction via the CLI. Ensure you have the 'oasis' CLI installed.

```bash
oasis rofl update
```

--------------------------------

### Retrieve App ID via REST API

Source: https://docs.oasis.io/build/rofl/features/appd

Endpoint to retrieve the unique identifier for an app running in ROFL. This is a simple GET request to the `/rofl/v1/app/id` endpoint.

```http
GET /rofl/v1/app/id HTTP/1.1
Host: localhost

```

--------------------------------

### Handling `depends_on` Ignored in Podman-Compose

Source: https://docs.oasis.io/build/rofl/troubleshooting

This snippet illustrates a scenario where the `depends_on` directive is ignored in podman-compose, causing services to start in parallel. It shows the intended configuration and explains that a workaround requires implementing retry logic within the dependent service.

```yaml
services:
  contracts:
    image: "ghcr.io/foundry-rs/foundry:latest"
    platform: linux/amd64
    volumes:
      - ./contracts:/contracts
    entrypoint: /bin/sh -c 'cd contracts && forge create'
  
  oracle:
    platform: linux/amd64
    entrypoint: /bin/sh -c 'python main.py'
    restart: on-failure
    depends_on:
      contracts:
        condition: service_completed_successfully

```

--------------------------------

### ROFL App Initialization Summary Output

Source: https://docs.oasis.io/build/rofl/workflow/init

This output summarizes the creation of a new ROFL application. It includes the app's name, version, the chosen Trusted Execution Environment (TEE), and the kind of ROFL flavor (e.g., container). It also confirms that a Git repository has been initialized and the manifest file has been created.

```bash
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.  
```

--------------------------------

### Initialize ROFL App using Oasis CLI

Source: https://docs.oasis.io/build/rofl/workflow/init

Initializes a new ROFL application with a basic directory structure and a ROFL manifest file. By default, it sets up a TDX container-based flavor. The `--kind` parameter can be used to select alternative flavors. The command outputs a summary of the created app and its configuration.

```bash
oasis rofl init my-app
```

--------------------------------

### List ROFL Deployment Offers using Oasis CLI

Source: https://docs.oasis.io/build/rofl/workflow/deploy

This command lists available offers from the default Oasis-managed ROFL provider. It helps users discover available ROFL nodes based on TEE type, memory, vCPUs, storage, and price, enabling them to choose the most suitable option for their deployment. No specific inputs are required, and the output shows a list of available offers.

```bash
oasis rofl deploy --show-offers
```

--------------------------------

### Deploy ROFL App using Oasis CLI

Source: https://docs.oasis.io/build/rofl/workflow/deploy

This command deploys a ROFL application to a rented ROFL node via the ROFL marketplace. It automatically handles the process of finding a machine, paying for an offer, and storing the machine details. The output confirms the deployment process and provides details about the OCI repository and the selected offer.

```bash
oasis rofl deploy
```

--------------------------------

### ROFL App Directory Structure

Source: https://docs.oasis.io/build/rofl/workflow/init

This illustrates the basic directory structure created for a ROFL application after initialization using the Oasis CLI. It includes essential files like `compose.yaml` for container orchestration and `rofl.yaml` for the ROFL application manifest.

```bash
myapp  
├── compose.yaml        # Container compose file.  
└── rofl.yaml           # ROFL app manifest.  
```

--------------------------------

### Run Oasis CLI from Docker Image (Windows)

Source: https://docs.oasis.io/build/rofl/workflow/prerequisites

This command invokes the Oasis CLI from the `rofl-dev` Docker image on Windows. It mounts the current directory as the source and the Oasis config directory (typically in AppData) for persistent wallet access. Ensure the config path is correct for your system.

```bash
docker run --platform linux/amd64 --rm -v .:/src -v %USERPROFILE%/AppData/Local/oasis/:/root/.config/oasis -it ghcr.io/oasisprotocol/rofl-dev:main oasis  

```

--------------------------------

### Run SGX ROFL with Sapphire-Localnet Docker Image

Source: https://docs.oasis.io/build/rofl/workflow/test

This snippet shows how to run applications in SGX ROFL using the `sapphire-localnet` Docker image. It binds the current directory to the container, automatically registering and executing ORC bundles on startup. Ensure the necessary ports are mapped.

```docker
docker run -it -p8544-8548:8544-8548 -v .:/rofls ghcr.io/oasisprotocol/sapphire-localnet
```

--------------------------------

### Create Oasis ROFL Application CLI Command

Source: https://docs.oasis.io/build/rofl/workflow/create

This command initiates the creation of a ROFL application on the specified network using the designated account. It requires network and account flags. Upon successful execution, it assigns a unique app ID and updates the manifest file.

```bash
oasis rofl create --network testnet --account myaccount  
```

--------------------------------

### Run Oasis CLI from Docker Image (Linux)

Source: https://docs.oasis.io/build/rofl/workflow/prerequisites

This command invokes the Oasis CLI from the `rofl-dev` Docker image on Linux. It mounts the current directory as the source and the Oasis config directory for persistent wallet access. Ensure the config path is correct for your system.

```bash
docker run --platform linux/amd64 --rm -v .:/src -v ~/.config/oasis:/root/.config/oasis -it ghcr.io/oasisprotocol/rofl-dev:main oasis  

```

--------------------------------

### Run Oasis CLI from Docker Image (MacOS)

Source: https://docs.oasis.io/build/rofl/workflow/prerequisites

This command invokes the Oasis CLI from the `rofl-dev` Docker image on MacOS. It mounts the current directory as the source and the Oasis config directory (typically in Application Support) for persistent wallet access. Ensure the config path is correct for your system.

```bash
docker run --platform linux/amd64 --rm -v .:/src -v "~/Library/Application Support/oasis/":/root/.config/oasis -it ghcr.io/oasisprotocol/rofl-dev:main oasis  

```

--------------------------------

### Run TDX ROFL Containers with Podman Compose

Source: https://docs.oasis.io/build/rofl/workflow/test

This snippet demonstrates how to test TDX ROFL containers locally. It involves exporting a secret and then using `podman-compose` to build and run the containers. This mimics the behavior of running containers inside ROFL.

```bash
export SECRET=some_secret
podman-compose up --build
```

--------------------------------

### Build Docker Compose Project

Source: https://docs.oasis.io/build/rofl/workflow/containerize-app

This command builds the container image(s) defined in your `docker-compose.yaml` file. It reads the Dockerfile and executes the build steps to create the image.

```bash
docker compose build
```

--------------------------------

### Oasis ROFL Application Creation Output

Source: https://docs.oasis.io/build/rofl/workflow/create

This output confirms the successful creation of a ROFL application via the CLI. It displays the newly generated application identifier (App ID), which is crucial for on-chain interactions and access to decentralized key management.

```text
Created ROFL application: rofl1qqn9xndja7e2pnxhttktmecvwzz0yqwxsquqyxdf  
```

--------------------------------

### Push Docker Compose Images to Registry

Source: https://docs.oasis.io/build/rofl/workflow/containerize-app

This command builds and then pushes all the container images defined in your `docker-compose.yaml` file to their respective OCI registries. Ensure you are logged in (`docker login`) before running this command.

```bash
docker compose push
```

--------------------------------

### Show ROFL Machine Status using Oasis CLI

Source: https://docs.oasis.io/build/rofl/workflow/deploy

This command displays the status and details of an active ROFL machine. It provides comprehensive information including provider details, machine ID, offer details, status, expiration, proxy URLs, resource allocation, and deployment specifics. This is crucial for monitoring the health and operational status of a deployed application.

```bash
oasis rofl machine show
```

--------------------------------

### Orchestrate Python Bot with Docker Compose

Source: https://docs.oasis.io/build/rofl/workflow/containerize-app

This `compose.yaml` file defines a service for your Python bot using Docker Compose. It specifies how to build the image from the current directory, sets the image name for an OCI registry, defines the platform, and configures environment variables. Remember to replace `YOUR_USERNAME` and `YOUR_PROJECT` with your actual details.

```yaml
services:
  python-bot:
    build: .
    image: "docker.io/YOUR_USERNAME/YOUR_PROJECT"
    platform: linux/amd64
    environment:
      - TOKEN=${TOKEN}
```

--------------------------------

### ROFL Deployment Policy Configuration

Source: https://docs.oasis.io/build/rofl/features/manifest

Defines the policy under which a ROFL app instance will be allowed to run, covering TEE-specific requirements, allowed enclave IDs, endorsement conditions, and fee payment.

```yaml
deployments:
  <deployment name>:
    policy:
      quotes:
        tcb_validity_period: "<period>"
        minimum_tcb_r_number: <number>
      enclaves:
        - "<enclave_id_1>"
        - "<enclave_id_2>"
      endorsements:
        - any: {}
        # or
        # - node: "<node_id>"
        # or
        # - provider: "<provider_address>"
        # or
        # - provider_instance_admin: "<admin_address>"
        # with nested conditions like:
        # - and:
        #   - provider: "oasis1qp2ens0hsp7gh23wajxa4hpetkdek3swyyulyrmz"
        #   - or:
        #     - provider_instance_admin: "oasis1qrk58a6j2qn065m6p06jgjyt032f7qucy5wqeqpt"
        #     - provider_instance_admin: "oasis1qqcd0qyda6gtwdrfcqawv3s8cr2kupzw9v967au6"
      fees: "endorsing_node" # or "instance"
```

--------------------------------

### POST /rofl/v1/keys/generate

Source: https://docs.oasis.io/build/rofl/features/appd

Generates a new decentralized on-chain key within an attested app instance. The generated key is persistent across deployments.

```APIDOC
## POST /rofl/v1/keys/generate

### Description
Generates a new decentralized on-chain key within an attested app instance. The generated key is persistent across deployments.

### Method
POST

### Endpoint
/rofl/v1/keys/generate

### Parameters
#### Request Body
- **key_id** (string) - Required - Used for domain separation of different keys.
- **kind** (string) - Required - Defines the type of key to generate. Supported values: `raw-256`, `raw-386`, `ed25519`, `secp256k1`.

### Request Example
```json
{
  "key_id": "demo key",
  "kind": "secp256k1"
}
```

### Response
#### Success Response (200)
- **key** (string) - The generated private key as a hexadecimal string.

#### Response Example
```json
{
  "key": "a54027bff15a8726b6d9f65383bff20db51c6f3ac5497143a8412a7f16dfdda9"
}
```
```

--------------------------------

### Alias Oasis CLI for Linux

Source: https://docs.oasis.io/build/rofl/workflow/prerequisites

This command creates a shell alias for Linux that runs the Oasis CLI using the `rofl-dev` Docker image. This simplifies invocation by allowing you to use `oasis` directly, with persistent wallet access configured.

```bash
alias oasis='docker run --platform linux/amd64 --rm -v .:/src -v ~/.config/oasis:/root/.config/oasis -it ghcr.io/oasisprotocol/rofl-dev:main oasis'

```

--------------------------------

### Authenticate Docker with Registry

Source: https://docs.oasis.io/build/rofl/workflow/containerize-app

This command prompts you to log in to a Docker registry (e.g., Docker Hub, GitHub Container Registry). This authentication is required before you can push images to the registry.

```bash
docker login
```

--------------------------------

### List Docker Images with Digests

Source: https://docs.oasis.io/build/rofl/workflow/containerize-app

This command lists all local Docker images and displays their corresponding image digests. The digest is a unique identifier for a specific image version and is crucial for pinning image hashes.

```bash
docker images --digests
```

--------------------------------

### Show ROFL App Status

Source: https://docs.oasis.io/build/rofl/workflow/deploy

Command to display all active app replicas for a ROFL application, regardless of deployment method. It shows app ID, admin, staked amount, policy details, and instance information including RAK and expiration.

```bash
oasis rofl show
```

--------------------------------

### ROFL App Resources Configuration

Source: https://docs.oasis.io/build/rofl/features/manifest

Specifies the computational resources required for a containerized app, including memory, vCPUs, and storage. Changes to these resources affect the enclave identity.

```yaml
resources:
  memory: 512 # in megabytes, defaults to 512
  cpus: 1     # number of vCPUs, defaults to 1
  storage:
    kind: "disk-persistent" # options: disk-persistent, disk-ephemeral, ram, none
    size: 512 # in megabytes
```

--------------------------------

### Alias Oasis CLI for MacOS

Source: https://docs.oasis.io/build/rofl/workflow/prerequisites

This command creates a shell alias for MacOS that runs the Oasis CLI using the `rofl-dev` Docker image. This simplifies invocation by allowing you to use `oasis` directly, with persistent wallet access configured.

```bash
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'

```

--------------------------------

### POST /rofl/v1/metadata

Source: https://docs.oasis.io/build/rofl/features/appd

Sets metadata key-value pairs for the application. This action replaces all existing app-provided metadata and initiates a registration refresh if the metadata is altered. Metadata is subject to validation against configured limits for pairs, key size, and value size.

```APIDOC
## POST /rofl/v1/metadata

### Description
Sets metadata key-value pairs. This replaces all existing app-provided metadata and will trigger a registration refresh if the metadata has changed.

### Method
POST

### Endpoint
/rofl/v1/metadata

### Parameters
#### Request Body
- **key_fingerprint** (string) - Required - A unique identifier for the metadata key.
- **version** (string) - Required - The version of the metadata.

### Request Example
```json
{
  "key_fingerprint": "a54027bff15a8726",
  "version": "1.0.0"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating successful metadata update.

#### Response Example
```json
{
  "message": "Metadata updated successfully."
}
```

### Note
Metadata is validated against runtime-configured limits for the number of pairs, key size, and value size.
```

--------------------------------

### Fetch ROFL Machine Logs using Oasis CLI

Source: https://docs.oasis.io/build/rofl/workflow/deploy

This command retrieves the logs of a deployed ROFL application. It's important to note that these logs are not encrypted and are stored unencrypted on the ROFL node. App administrators must sign the request with their admin account. Users should avoid printing confidential data to standard or error outputs in production environments.

```bash
oasis rofl machine logs
```

--------------------------------

### ROFL Manifest Metadata Fields

Source: https://docs.oasis.io/build/rofl/features/manifest

Defines the essential metadata for a ROFL application, including its name, version, repository, author, license, TEE type, and kind.

```yaml
name: "my-app"
version: "0.1.1"
repository: "https://github.com/user/my-app"
author: "John Doe <john@doe.com>"
license: "Apache-2.0"
tee: "tdx" # or "sgx"
kind: "containers" # or "raw" for TDX, only "raw" for SGX
```

--------------------------------

### Stop Docker Compose Project

Source: https://docs.oasis.io/build/rofl/workflow/containerize-app

This command stops and removes the containers, networks, and volumes created by `docker compose up`.

```bash
docker compose down
```

--------------------------------

### Set Metadata Key-Value Pairs (JSON Request)

Source: https://docs.oasis.io/build/rofl/features/appd

This snippet demonstrates how to send a POST request to the /rofl/v1/metadata endpoint to set application metadata. The request body should contain key-value pairs representing the metadata. Note that this action replaces all previously set metadata.

```json
{
  "key_fingerprint": "a54027bff15a8726",
  "version": "1.0.0"
}
```

--------------------------------

### Enable Target Features for Compilation (+aes,+ssse3)

Source: https://docs.oasis.io/build/rofl/troubleshooting

This snippet shows how to configure Rust compiler flags to enable specific target features (+aes,+ssse3) required for SGX and TDX-raw ROFL compilation. It addresses a common compilation error where these features are missing.

```toml
[build]
rustflags = ["-C", "target-feature=+aes,+ssse3"]
rustdocflags = ["-C", "target-feature=+aes,+ssse3"]

[test]
rustflags = ["-C", "target-feature=+aes,+ssse3"]
rustdocflags = ["-C", "target-feature=+aes,+ssse3"]

```

--------------------------------

### Publish Container Port with ROFL Port Proxy (YAML)

Source: https://docs.oasis.io/build/rofl/features/proxy

Expose a container port to the host and public network using ROFL Port Proxy. The proxy handles TLS certificates and routing. Requires publishing the port in the `compose.yaml` file.

```yaml
services:
  frontend:
    image: docker.io/hashicorp/http-echo:latest
    ports:
      - "5678:5678"
```

--------------------------------

### Configure ROFL Port Proxy Mode (YAML)

Source: https://docs.oasis.io/build/rofl/features/proxy

Configure the behavior of the ROFL Port Proxy for a specific published port using annotations in `compose.yaml`. Supported modes include `terminate-tls` (default), `passthrough`, and `ignore`.

```yaml
services:
  myservice:
    image: docker.io/my/service:latest
    ports:
      - "8080:8080"
    annotations:
      net.oasis.proxy.ports.8080.mode: passthrough
```

--------------------------------

### ROFL Persistent Storage Configuration with Docker Compose

Source: https://docs.oasis.io/build/rofl/features/storage

This snippet demonstrates how to configure persistent storage for a Docker container using ROFL's `compose.yaml`. It defines a service named 'ollama' that uses a persistent volume named 'my-volume' to store Docker images and Ollama models. This ensures that models are not re-downloaded after restarts or upgrades.

```yaml
services:
  ollama:
    image: "docker.io/ollama/ollama"
    ports:
      - "11434:11434"
    volumes:
      - my-volume:/root/.ollama
    entrypoint: ["/usr/bin/bash", "-c", "/bin/ollama serve & sleep 5; ollama pull deepseek-r1:1.5b; wait"]

volumes:
  my-volume:

```

--------------------------------

### POST /rofl/v1/tx/sign-submit

Source: https://docs.oasis.io/build/rofl/features/appd

Submits an authenticated transaction to the chain, signed by an ephemeral key endorsed by the app. This allows for automatic transaction origin authentication in smart contracts.

```APIDOC
## POST /rofl/v1/tx/sign-submit

### Description
Submits an authenticated transaction to the chain, signed by an ephemeral key endorsed by the app. This allows for automatic transaction origin authentication in smart contracts.

### Method
POST

### Endpoint
/rofl/v1/tx/sign-submit

### Parameters
#### Request Body
- **tx** (object) - Required - Describes the transaction content.
  - **kind** (string) - Required - The type of transaction. Supported: `eth` (Ethereum-compatible) or `std` (Oasis SDK).
  - **data** (object) - Required for `eth` kind - Transaction details.
    - **gas_limit** (integer) - Optional - Gas limit for the transaction.
    - **to** (string) - Required for `eth` kind - The recipient address.
    - **value** (string) - Optional, defaults to '0' - The value to send with the transaction (decimal or hex string).
    - **data** (string) - Optional - Transaction payload or call data.
- **encrypt** (boolean) - Optional, defaults to `true` - Whether to encrypt the transaction.

### Request Example
```json
{
  "encrypt": true,
  "tx": {
    "kind": "eth",
    "data": {
      "gas_limit": 200000,
      "to": "1234845aaB7b6CD88c7fAd9E9E1cf07638805b20",
      "value": "0",
      "data": "dae1ee1f00000000000000000000000000000000000000000000000000002695a9e649b2"
    }
  }
}
```

### Response
#### Success Response (200)
- **data** (string) - A CBOR-serialized hex-encoded call result.

#### Response Example
*Successful call result (deserialized as `{"ok": ""}`):*
```json
{
  "data": "a1626f6b40"
}
```
*Unsuccessful call result (deserialized as `{"fail": {"code": 8, "module": "evm", "message": "reverted: aJAoLw=="}}`):*
```json
{
  "data": "a1646661696ca364636f646508666d6f64756c656365766d676d6573736167657272657665727465643a20614a416f4c773d3d"
}
```
```

--------------------------------

### Update and Redeploy ROFL Application

Source: https://docs.oasis.io/build/rofl/troubleshooting

This command sequence outlines the steps to fix ROFL proxy URL issues by updating the Oasis CLI, upgrading ROFL artifacts, and then rebuilding and redeploying the application.

```bash
oasis rofl build
 Oasis rofl update
 oasis rofl deploy

```

--------------------------------

### Generate Key via REST API

Source: https://docs.oasis.io/build/rofl/features/appd

Endpoint for generating cryptographic keys within ROFL. Supports different key types like `secp256k1` and raw entropy. Requires a `key_id` for domain separation and a `kind` specifying the key type.

```json
{
  "key_id": "demo key",
  "kind": "secp256k1"
}
```

--------------------------------

### Create Secret using Oasis CLI

Source: https://docs.oasis.io/build/rofl/features/secrets

This command creates a new secret named 'mysecret' with the value 'my very secret value' using the Oasis CLI. The secret is then stored in the local app manifest. It requires the 'echo' command and the 'oasis rofl secret set' command.

```bash
echo -n "my very secret value" | oasis rofl secret set mysecret -  

```

--------------------------------

### Expose Secret as Environment Variable in Compose

Source: https://docs.oasis.io/build/rofl/features/secrets

This YAML snippet demonstrates how to configure a service in a Compose file to use a secret as an environment variable. The secret 'MYSECRET' is made available to the 'test' service. The secret name is capitalized and spaces are replaced with underscores.

```yaml
services:
  test:
    image: docker.io/library/alpine:3.21.2@sha256:f3240395711384fc3c07daa46cbc8d73aa5ba25ad1deb97424992760f8cb2b94
    command: echo "Hello $MYSECRET!"
    environment:
      - MYSECRET=${MYSECRET}  

```

--------------------------------

### Pin Container Image Digest in Compose

Source: https://docs.oasis.io/build/rofl/workflow/containerize-app

This snippet shows how to pin a specific container image using its digest in `compose.yaml`. Appending `@sha256:<digest>` to the image name ensures that a specific version of the image is used, preventing unexpected behavior due to image updates. Replace `<digest>` with the actual SHA256 digest obtained from `docker images --digests`.

```yaml
    image: "docker.io/MY_USERNAME/my-bot@sha256:9633593eb9e8395023cb0d926982602978466ec003efa189d94a34e7bea6ec0d"
```

--------------------------------

### Submit Authenticated Transaction via REST API

Source: https://docs.oasis.io/build/rofl/features/appd

Endpoint for submitting authenticated transactions to the ROFL chain. Transactions are signed by an ephemeral key, ensuring their origin is automatically authenticated. Supports Ethereum-compatible and Oasis SDK transactions.

```json
{
  "encrypt": true,
  "tx": {
    "kind": "eth",
    "data": {
      "gas_limit": 200000,
      "to": "1234845aaB7b6CD88c7fAd9E9E1cf07638805b20",
      "value": "0",
      "data": "dae1ee1f00000000000000000000000000000000000000000000000000002695a9e649b2"
    }
  }
}
```

--------------------------------

### Expose Secret as Container Secret in Compose

Source: https://docs.oasis.io/build/rofl/features/secrets

This YAML snippet shows how to pass a secret to a container using the 'secrets' directive in a Compose file. The 'mysecret' secret is made available within the container at '/run/secrets/mysecret'. It must be defined as an 'external' secret.

```yaml
services:
  test:
    image: docker.io/library/alpine:3.21.2@sha256:f3240395711384fc3c07daa46cbc8d73aa5ba25ad1deb97424992760f8cb2b94
    command: echo "Hello $(cat /run/secrets/mysecret)!"
    secrets:
      - mysecret

secrets:
  mysecret:
    external: true  

```

--------------------------------

### Update ROFL App Configuration via CLI

Source: https://docs.oasis.io/build/rofl/features/secrets

This command updates the on-chain configuration for the ROFL application after secrets have been managed locally. It is a simple command that triggers the update process.

```bash
oasis rofl update  

```
Tokens:
Raw