How to create data compute instruction?

🧠 What is a Compute Instruction?

A Compute Instruction is a Docker image that runs inside a secure TEE-based Vana’s Compute Engine and is the key to customizing how your application transforms query results. It receives a query result from the Query Engine (as a SQLite database) and outputs artifacts — typically JSON, CSV, images, or anything else your app needs.

Use cases include:

• Data normalization or aggregation
• Chart generation
• Embedding extraction
• AI model training or inference
• Synthetic data generation

🛠️ 1. Start with the Template

We provide a Python-based job template that handles basic setup for you.

👉 Template repo: vana-compute-job-template-py

Inside the template:

• query_results.db → contains the SQL result from your job query
• Modify worker.py → to load, process, and output your desired result
• Artifacts must be saved to /mnt/output/

Example output:

# /mnt/output/stats.json
{
  "user_count": 123,
  "locale_distribution": { "en-US": 90, "es-AR": 33 }
}

🐳 2. Build and Publish Your Docker Image

Once you've updated the logic, you need to build and host the image.

You can:

• Use GitHub Actions (already included in the template)
• Or build/push manually to a public Docker registry (e.g., Docker Hub, GitHub Container Registry)

Make sure the final image:

• Is publicly accessible via URL
• Is deterministic and verifiable (same input = same hash)

🔐 3. Generate the Image Checksum

Compute the SHA256 digest of your Docker image. This will be used to verify the integrity of the image when it’s pulled and executed.

Example using Docker:

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

Save the full hash — you’ll use it when registering the instruction.

📝 4. Register On-Chain

Register your compute instruction using the ComputeInstructionRegistry contract.

Solidity function:

function addComputeInstruction(
  string calldata hash,
  string calldata url
) external returns (uint256 instructionId)

• url: Publicly accessible Docker image link
• hash: SHA256 checksum of the image

This returns a computeInstructionId that you’ll use when submitting jobs.

Contract: ComputeInstructionRegistry -> 0x5786B12b4c6Ba2bFAF0e77Ed30Bf6d32805563A5

✅ 5. Done — Use It in Your Jobs

Once registered, your computeInstructionId is ready to use in the submitJob() flow.

📌

Note

You’ll also need approval from the DataDAO whose data you plan to use. See How to Access Data on Vana for full flow.