AO Compute Unit (CU)

Overview

An AO Compute Unit (CU) is a critical component in the AO ecosystem responsible for executing AO processes and maintaining their state. CUs serve as the computational backbone of the AO network by:

  • Processing Messages: CUs receive and process messages sent to AO processes
  • Executing WASM Modules: CUs run the WebAssembly (WASM) code that defines process behavior
  • Maintaining State: CUs track and update the state of AO processes
  • Creating Checkpoints: CUs periodically save process state to the Arweave network as checkpoints

Running a CU alongside your gateway allows you to:

  1. Process AO requests locally rather than relying on external services
  2. Improve response times for AO-related queries
  3. Contribute computational resources to the AO network
  4. Ensure your gateway has reliable access to AO functionality

For more detailed information about Compute Units, please refer to the AO Cookbook: Units.

System Requirements

Before deploying a CU, ensure your system meets the following requirements:

  • Recommended: At least 16GB RAM for optimal CU operation
  • Minimum: 4GB RAM is possible with adjusted memory limits (see resource allocation settings)
  • At least 100GB disk space dedicated to CU operation
  • These requirements are separate from your gateway requirements

Running a CU is resource-intensive. Make sure your system has sufficient resources to handle both the gateway and the CU. While you can run a CU with less than the recommended RAM, you'll need to adjust the memory limits accordingly.

Deploying an AO CU

Step 1: Navigate to Gateway Directory

First, navigate to the root directory of your gateway:

cd /path/to/your/gateway

Step 2: Configure Environment Variables

Copy the example environment file:

cp .env.ao.example .env.ao

Default .env.ao.example Contents

The default .env.ao.example file contains the following settings:

CU_WALLET='[wallet json here]'
PROCESS_CHECKPOINT_TRUSTED_OWNERS=fcoN_xJeisVsPXA-trzVAuIiqO3ydLQxM-L4XbrQKzY
GATEWAY_URL=http://envoy:3000
UPLOADER_URL=http://envoy:3000/bundler

These default settings are configured to work with a gateway running on the same machine, but you'll need to modify them as described below.

Open the .env.ao file in your preferred text editor:

nano .env.ao

Configure the following settings:

  1. CU_WALLET: Replace '[wallet json here]' with the JSON from an Arweave wallet.

    The entire JSON must be placed on a single line for proper registration.

  2. PROCESS_CHECKPOINT_TRUSTED_OWNERS: This is a comma-separated list of trusted wallet addresses:

    PROCESS_CHECKPOINT_TRUSTED_OWNERS=fcoN_xJeisVsPXA-trzVAuIiqO3ydLQxM-L4XbrQKzY
    Adding Your Own Wallet

    If you are uploading your own checkpoints, you should add your own CU wallet address after the default value, separated by a comma:

    PROCESS_CHECKPOINT_TRUSTED_OWNERS=fcoN_xJeisVsPXA-trzVAuIiqO3ydLQxM-L4XbrQKzY,YOUR_WALLET_ADDRESS_HERE

    This allows your CU to trust checkpoints from both the official source and your own wallet.

  3. GATEWAY_URL: By default, this is set to use your own gateway:

    GATEWAY_URL=http://envoy:3000

    A gateway must be set to index all ANS-104 data items from AO or the CU will not operate properly. Most users will want to set this to:

    GATEWAY_URL=https://arweave.net

  4. UPLOADER_URL: By default, this is set to use a bundler sidecar run by your gateway:

    UPLOADER_URL=http://envoy:3000/bundler
    Important: Checkpoint Uploads Require Payment

    Checkpoints are uploaded to Arweave, so the upload must be paid for. You must ensure your wallet has sufficient funds:

    • If using https://up.arweave.net (recommended), your CU_WALLET must contain Turbo Credits
    • If using your own bundler or another service, you'll need the appropriate token (AR or other)
    • Without proper funding, checkpoints will fail to upload and your CU may not function correctly

    The simplest option for most users is to use:

    UPLOADER_URL=https://up.arweave.net

    This requires your CU_WALLET to contain Turbo Credits.

  5. Optional: Disable Checkpoint Creation: If you want to disable checkpoint uploads, add:

    DISABLE_PROCESS_CHECKPOINT_CREATION=true

Example of a Completed .env.ao File

Here's an example of what your completed .env.ao file might look like with common settings:

CU_WALLET='{"kty":"RSA","e":"AQAB","n":"mYM07..."}'
PROCESS_CHECKPOINT_TRUSTED_OWNERS=fcoN_xJeisVsPXA-trzVAuIiqO3ydLQxM-L4XbrQKzY
GATEWAY_URL=https://arweave.net
UPLOADER_URL=https://up.arweave.net

After making your changes, save and exit the nano editor:

  1. Press Ctrl+X to exit
  2. Press Y to confirm saving changes
  3. Press Enter to confirm the filename

Optional Resource Allocation Settings

You can fine-tune the CU's resource usage by adding these optional environment variables:

  1. PROCESS_WASM_MEMORY_MAX_LIMIT: Sets the maximum memory limit (in bytes) for WASM processes.

    PROCESS_WASM_MEMORY_MAX_LIMIT=17179869184  # 16GB (16 * 1024^3)
    Important Memory Requirement

    To work with the AR.IO process, PROCESS_WASM_MEMORY_MAX_LIMIT must be at least 17179869184 (16GB).

    Note: This doesn't mean your server needs 16GB of RAM. This is the maximum memory limit the CU will support for processes. Most processes don't use their maximum allocated memory.

    You can set this value to 16GB even if your server only has 4GB of RAM. However, if a process requires more memory than your server has available, the CU will fail when evaluating messages that need more memory.

  2. WASM_EVALUATION_MAX_WORKERS: Sets the maximum number of worker threads for WASM evaluation.

    WASM_EVALUATION_MAX_WORKERS=4  # Example: Use 4 worker threads
    Worker Thread Configuration

    This will default to (available CPUs - 1) if not specified. If you're running a gateway and unbundling on the same server, consider setting this to 2 or less to avoid overloading your CPU.

  3. PROCESS_WASM_COMPUTE_MAX_LIMIT: The maximum Compute-Limit, in bytes, supported for ao processes (defaults to 9 billion)

    PROCESS_WASM_COMPUTE_MAX_LIMIT=9000000000

  4. NODE_OPTIONS: Sets Node.js memory allocation for the Docker container.

    NODE_OPTIONS=--max-old-space-size=8192  # Example: 8GB for Node.js heap
Resource Tuning

Start with conservative values and monitor performance. You can adjust these settings based on your system's capabilities and the CU's performance.

Step 3: Start the CU Container

Once your environment file is configured, start the CU container:

docker compose --env-file .env.ao -f docker-compose.ao.yaml up -d

This command uses the following flags:

  • --env-file .env.ao: Specifies the environment file to use
  • -f docker-compose.ao.yaml: Specifies the Docker Compose file to use
  • up: Creates and starts the containers
  • -d: Runs containers in detached mode (background)

Step 4: Check the Logs

To check the logs of your CU container:

docker compose -f docker-compose.ao.yaml logs -f --tail=20

This command uses the following flags:

  • -f: Follows the log output (continuous display)
  • --tail=20: Shows only the last 20 lines of logs

Exit the logs by pressing Ctrl+C.

Connecting Your Gateway to the CU

To make your gateway use your local CU:

  1. Add the following line to your gateway's .env file:

    AO_CU_URL=http://ao-cu:6363

    This assumes the CU is running on the same machine as the gateway.

  2. Restart your gateway:

    docker compose down
docker compose up -d

A CU won't do anything until requests are being made of it. By connecting your gateway to the CU, you'll start generating these requests.

Accessing Your CU

Once properly set up and connected to your gateway, you can access your CU via:

https://<your-gateway-domain>/ao/cu

This endpoint allows you to interact with your CU directly through your gateway's domain.

Important Notes

  • Initial Processing Time: A CU will need to process AO history before it can give valid responses. This process can take several hours.

  • Gateway Fallback: A gateway on release 27 or above will fallback to arweave.net if its default CU is not responding quickly enough, so gateway operations will not be significantly impacted during the initial processing.

  • Monitoring Progress: Check the CU logs after pointing a gateway at it to watch the process of working through AO history:

    docker compose -f docker-compose.ao.yaml logs -f --tail=20

  • Resource Usage: Running a CU is resource-intensive. Monitor your system's performance to ensure it can handle both the gateway and CU workloads.