Atoma node daemon

Comprehensive documentation for the Atoma daemon API

Atoma Daemon API Documentation

The Atoma daemon provides a REST API for querying node state and submitting blockchain transactions. The daemon manages node operations, subscriptions, tasks, stacks, and attestation disputes.

Base URL

All API endpoints are relative to the daemon's base URL (e.g., http://localhost:3000).

Authentication

Currently, no authentication is required to access the API endpoints, as the Atoma daemon is supposed to be a standalone local service for ease of node operations.

Response Format

All responses are returned in JSON format. Successful responses will contain the requested data, while errors will return appropriate HTTP status codes with error messages.

Claimed Stack Management

Get All Claimed Stacks

GET /claimed_stacks

Returns all claimed stacks for registered nodes.

Get Node Claimed Stacks

GET /claimed_stacks/:id

Returns claimed stacks for a specific node.

Parameters

• id (path): Node small ID

Transaction Submission Endpoints

Register Node

POST /register

Submits a node registration transaction.

Request Body

{
  "gas": "0x123",
  "gas_budget": 1000,
  "gas_price": 10
}

Subscribe to Model

POST /model_subscribe

Subscribes a node to a specific model.

Request Body

{
  "model_name": "example_model",
  "echelon_id": 1,
  "node_badge_id": "0x123",
  "gas": "0x456",
  "gas_budget": 1000,
  "gas_price": 10
}

Subscribe to Task

POST /task_subscribe

Subscribes a node to a specific task.

Request Body

{
  "task_small_id": 123,
  "node_small_id": 456,
  "price_per_compute_unit": 10,
  "max_num_compute_units": 100,
  "gas": "0x789",
  "gas_budget": 1000,
  "gas_price": 10
}

Unsubscribe from Task

POST /task_unsubscribe

Unsubscribes a node from a specific task.

Request Body

{
  "task_small_id": 123,
  "node_small_id": 456,
  "gas": "0x789",
  "gas_budget": 1000,
  "gas_price": 10
}

Try Settle Stacks

POST /try_settle_stack_ids

Attempts to settle specified stacks.

Request Body

{
  "stack_small_ids": [123, 456],
  "num_claimed_compute_units": 50,
  "node_small_id": 789,
  "gas": "0x789",
  "gas_budget": 1000,
  "gas_price": 10
}

Submit Stack Settlement Attestations

POST /submit_stack_settlement_attestations

Submits attestations for stack settlement.

Request Body

{
  "stack_small_ids": [123, 456],
  "node_small_id": 789,
  "gas": "0x789",
  "gas_budget": 1000,
  "gas_price": 10
}

Claim Funds

POST /claim_funds

Claims funds from completed stacks.

Request Body

{
  "stack_small_ids": [123, 456],
  "node_small_id": 789,
  "gas": "0x789",
  "gas_budget": 1000,
  "gas_price": 10
}

Error Handling

The API uses standard HTTP status codes:

• 200 OK: Request successful

• 404 Not Found: Resource not found

• 500 Internal Server Error: Server-side error occurred

Error responses include a message describing the error:

{
  "error": "Failed to submit transaction"
}

Common Parameters

Many transaction submission endpoints share common parameters:

• gas: Gas object ID for transaction fee payment

• gas_budget: Maximum gas units allowed for transaction

• gas_price: Price per gas unit

• node_small_id: Optional node identifier (if not provided, applies to all registered nodes)

Notes

1. All transaction submission endpoints return a transaction digest that can be used to track the transaction status on the blockchain.

2. When working with stack settlement attestations, note that the attestation node index is offset by 1 since the 0th index is reserved for the original selected node.

3. The daemon maintains thread-safe access to shared resources through the use of Arc<RwLock> for the Sui client.

4. All endpoints are instrumented with tracing for debugging and monitoring purposes.