Submit Stack settlements and attestations

Stack Settlement Management

Try Settle Stacks

POST /try_settle_stack_ids

Submits a transaction to attempt settling one or more stacks for a node.

Request Body

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

Request Fields

• stack_small_ids (array of integers): IDs of the stacks to settle

• num_claimed_compute_units (integer): Number of compute units being claimed for settlement

• node_small_id (integer, optional): ID of the node settling the stacks

• 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 settlement transactions

• 500 Internal Server Error: Failed to submit transactions or retrieve stack data

Response

{
    "tx_digests": ["0xabc", "0xdef"]
}

Response Fields

• tx_digests (array of strings): Array of transaction digests, one for each stack settlement attempt

Submit Stack Settlement Attestations

POST /submit_stack_settlement_attestations

Submits attestation proof transactions for one or more stacks in settlement.

Request Body

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

Request Fields

• stack_small_ids (array of integers): IDs of the stacks requiring attestation

• node_small_id (integer, optional): ID of the attesting node (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 attestation transactions

• 500 Internal Server Error: Failed to submit transactions or retrieve necessary data

Response

{
    "tx_digests": ["0xabc", "0xdef"]
}

Response Fields

• tx_digests (array of strings): Array of transaction digests, one for each successful attestation submission

Notes

• Stack Settlement Process:

  1. Node attempts to settle stacks by submitting proof of computation

  2. Other nodes must provide attestations to verify the computation

  3. Settlement completes when required attestations are received

• Important Considerations:

  • The attestation node index is offset by 1 (0th index reserved for original selected node)

  • Multiple attestations may be required for each stack

  • Each stack generates its own transaction digest

  • Failed attestations must be retried separately

Example Error Responses

{
    "error": "Failed to get stack total hash"
}

{
    "error": "Failed to submit node attestation proof tx"
}

{
    "error": "Failed to parse attestation nodes"
}