Developer Guide

Integrate with aleph-onchain using the Rust SDK, TypeScript bindings, CLI, or HTTP API.

SDK Overview

HTTP API

The node exposes a REST API via axum. Authentication uses EIP-712 typed signatures.

Endpoints

Method	Path	Description
GET	/v1/status	Node health and status
GET	/v1/nodes	List active nodes
GET	/v1/nodes/:id	Node details
POST	/v1/jobs	Create a compute job
GET	/v1/jobs/:id	Job status
POST	/v1/jobs/:id/stop	Stop a running job
POST	/v1/storage	Upload content
GET	/v1/storage/:hash	Download content by hash
POST	/v1/messages	Submit a message
GET	/v1/messages/:hash	Retrieve a message
WS	/v1/ws	WebSocket for real-time events

Authentication (EIP-712)

API requests are authenticated using EIP-712 typed data signatures. Include the signature in the Authorization header.

// AuthPayload structure from aleph-api/src/auth.rs
struct AuthPayload {
    sender: Address,
    timestamp: u64,
    nonce: String,
    signature: Signature,
}

// TypedData domain
{
  "name": "aleph-onchain",
  "version": "1",
  "chainId": 42161
}

Creating a Compute Job

With Rust SDK

use aleph_sdk::{Client, JobRequest, ResourceRequirements};

let client = Client::new(rpc_url, private_key)?;

let job = client.create_job(JobRequest {
    content_hash: image_hash,
    resources: ResourceRequirements {
        vcpus: 4,
        memory_mib: 8192,
        storage_mib: 50_000,
        gpu_required: false,
        ..Default::default()
    },
    environment: vec![
        ("DATABASE_URL".into(), db_url),
    ],
}).await?;

println!("Job created: {:?}", job.job_id);

With HTTP API

curl -X POST https://api.aleph-onchain.io/v1/jobs \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content_hash": "QmYourImageHash",
    "resources": {
      "vcpus": 4,
      "memory_mib": 8192,
      "storage_mib": 50000
    },
    "environment": {
      "DATABASE_URL": "postgres://..."
    }
  }'

Uploading Storage

use aleph_sdk::Client;

let client = Client::new(rpc_url, private_key)?;

// Upload a file
let result = client.upload_file("./mydata.tar.gz").await?;
println!("Content hash: {}", result.content_hash);
println!("Size: {} bytes", result.size);

// Download by content hash
let data = client.download(&result.content_hash).await?;

Managing Domains

// Register a domain on-chain
let tx = domain_registry
    .registerDomain(
        "myapp.example.com".into(),
        job_id,
        443,  // target port
    )
    .send().await?;

// TLS certificates are automatically provisioned via ACME

WebSocket Events

// Connect to real-time events
const ws = new WebSocket("wss://api.aleph-onchain.io/v1/ws");

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  switch (msg.type) {
    case "job_status":
      console.log(`Job ${msg.job_id}: ${msg.status}`);
      break;
    case "heartbeat":
      console.log(`Node ${msg.node_id} alive`);
      break;
  }
};