Task subscriptions

Task Subscription Management

Subscribe to Task

POST /task_subscribe

Submits a transaction to subscribe a node to a specific task.

Request Body

{
    "task_small_id": 123,
    "node_badge_id": "0xab2..",
    "price_per_compute_unit": 10,
    "max_num_compute_units": 100,
    "gas": "0x789",
    "gas_budget": 1000,
    "gas_price": 10
}

Request Fields

• task_small_id (integer): ID of the task to subscribe to

• node_small_id (integer, optional): ID of the node to subscribe (if omitted, uses all registered nodes)

• price_per_compute_unit (integer): Price per compute unit the node will charge

• max_num_compute_units (integer): Maximum compute units the node will process per stack

• gas (string): Object ID of the gas object to pay for the transaction

• gas_budget (integer): Maximum gas units allowed for the transaction

• gas_price (integer): Price per gas unit in MIST

Response Status Codes

• 200 OK: Successfully submitted task subscription transaction

• 500 Internal Server Error: Failed to submit the transaction

Response

{
    "tx_digest": "0xabc"
}

Update Task Subscription

POST /task_update_subscription

Updates an already existing node subscription to a Task.

Request Body:

{ 
    "task_small_id": 123, 
    "node_badge_id": "0xab2..", 
    "price_per_compute_unit": 15, 
    "max_num_compute_units": 150, 
    "gas": "0x789", // optional
    "gas_budget": 1000, // optional
    "gas_price": 10 // optional
}

Request Fields

• task_small_id (integer): ID of the task subscription to update

• node_badge_id (string): Object ID of the node badge

• price_per_compute_unit (integer): New price per compute unit the node will charge

• max_num_compute_units (integer): New maximum compute units the node will process per stack

• gas (string): Object ID of the gas object to pay for the transaction

• gas_budget (integer): Maximum gas units allowed for the transaction

• gas_price (integer): Price per gas unit in MIST

Response Status Codes

• 200 OK: Successfully submitted task subscription update transaction

• 500 Internal Server Error: Failed to submit the transaction

Response

{
    "tx_digest": "0xabc"
}

Unsubscribe from Task

POST /task_unsubscribe

Submits a transaction to unsubscribe a node from a specific task.

Request Body

{
    "task_small_id": 123,
    "node_badge_id": "0xab2..",
    "gas": "0x789",
    "gas_budget": 1000,
    "gas_price": 10
}

Request Fields

• task_small_id (integer): ID of the task to unsubscribe from

• node_small_id (integer, optional): ID of the node to unsubscribe (if omitted, uses all registered nodes)

• gas (string): Object ID of the gas object to pay for the transaction

• gas_budget (integer): Maximum gas units allowed for the transaction

• gas_price (integer): Price per gas unit in MIST

Response Status Codes

• 200 OK: Successfully submitted task unsubscription transaction

• 500 Internal Server Error: Failed to submit the transaction

Response

{
    "tx_digest": "0xabc"
}

Notes

• A node must be registered before subscribing to tasks

• The price_per_compute_unit determines the node's compensation for processing requests

• The max_num_compute_units limits the size of stacks the node will accept

• Unsubscribing from a task:

  • Prevents the node from receiving new stacks for that task

  • Does not affect existing stack commitments

  • Can be reversed by subscribing again

• Both operations return a transaction digest for tracking the transaction status

Example Error Responses

{
    "error": "Failed to submit node task subscription tx"
}

{
    "error": "Failed to submit node task unsubscription tx"
}