Custom Compute Instructions

A Compute Instruction is a Docker image that runs inside Vana's secure Compute Engine. It allows you to define custom logic for processing and transforming query results. While Vana provides a default instruction for basic queries, creating your own allows for powerful use cases like data normalization, embedding extraction, or AI model training.

📘

Before You Begin

This is an advanced guide that assumes you have Docker installed and are familiar with building and publishing Docker images to a public registry (like Docker Hub or GitHub Container Registry).

Step 1: Start with the Template

We provide a Python-based job template to handle the basic setup, including receiving the query results from the Query Engine.

• Template Repository: vana-compute-job-template-py

Your primary task is to modify the worker.py file to load the input data, perform your custom processing, and save any outputs as artifacts.

• Input Data: The results of the SQL query will be available inside the container at query_results.db.
• Output Artifacts: Any files you want to retrieve after the job runs must be saved to the /mnt/output/ directory.

Step 2: Build and Publish Your Docker Image

Once your logic is complete, build the Docker image and push it to a public container registry.

The template repository includes a GitHub Actions workflow to automate this process. Alternatively, you can build and push manually. Ensure the final image is publicly accessible so the Vana Compute Engine can pull it.

Step 3: Generate the Image Checksum

You must compute the SHA256 digest of your final Docker image. This checksum is registered on-chain to verify the integrity of the image each time it runs.

You can compute the hash using a command like this:

docker pull your-username/your-image:latest
docker save your-username/your-image:latest | sha256sum

Copy the full SHA256 hash output.

Step 4: Register the Instruction On-Chain

Finally, register your compute instruction with the ComputeInstructionRegistry contract. This will generate a unique computeInstructionId for your new instruction.

• Contract: ComputeInstructionRegistry (0x578...)
• Function: addComputeInstruction(string calldata hash, string calldata url)
  • hash: The SHA256 checksum you generated in the previous step.
  • url: The public URL of your Docker image (e.g., docker.io/your-username/your-image:latest).

Step 5: Use Your New Instruction

Your new computeInstructionId is now ready to be used. You will need to get it approved by any DataDAO whose data you wish to process. Once approved, you can use this ID when you submit jobs, as detailed in Tutorial: Querying Data on Vana.