Sessions And Task Queue

Last updated: 2026-06-28

Sessions group work, payment, routing policy, privacy policy, and model/session constraints. The task queue tracks the lifecycle of individual jobs assigned to miners. Router v2/v3 routes extend the task lifecycle with off-chain payloads and validation-oriented flows.

Select

Router or product selects a session based on route, model, mode, privacy, and payment policy.

Create

The request becomes a task with queue state, assignment policy, and optional off-chain payload references.

Execute

Miners accept work, run the configured runtime, and commit output or URN data.

Validate

Oracle and validator roles compare lifecycle state, results, policy, and quality expectations.

Close

The caller receives a result, consensus output, reference, verdict, or retry path.

stateDiagram-v2
  [*] --> SessionSelected: "router selects session"
  SessionSelected --> TaskCreated: "create task"
  TaskCreated --> Assigned: "assign miners"
  Assigned --> Acknowledged: "miner ack"
  Acknowledged --> Precommitted: "result hash / URN hash"
  Precommitted --> Committed: "result or off-chain URN"
  Committed --> Validated: "oracle / validator checks"
  Validated --> Closed: "result returned"
  Closed --> [*]

Task Lifecycle

1. A client, product, or router selects a session.
2. A task is created in the session queue.
3. Miners are assigned or acknowledge the task.
4. Miners precommit a hash or result reference.
5. Miners commit the result or off-chain URN.
6. Oracle/validator flows validate and close the task.
7. Router or product returns the result, consensus output, or verdict.

Session Responsibilities

Responsibility	Public meaning
Access and payment	A session defines who can use the route, how work is paid for, and which payment/rate-limit rules apply.
Model and capacity	A session is associated with model choice, mode, and node capacity.
Queue ownership	Tasks enter a queue where miner assignment, precommit, commit, and validation are tracked.
Privacy policy	Private sessions can restrict miners and use encrypted/off-chain payloads.
Result retrieval	Results may return inline, by reference, or as a validation verdict depending on route and policy.

On-Chain vs Off-Chain

Data	Typical location	Notes
Session metadata	Contract state	Fields vary by deployment and module version.
Task state	Session queue contracts	Includes status, miner assignment, and result references.
Prompt payload	Plain string or off-chain URN	v2/v3 completion routes can store prompts off-chain.
Result payload	Plain result or off-chain URN	Private/encrypted flows avoid plaintext result storage.
Large/encrypted blobs	Off-chain storage	On-chain records store references and hashes, not full payloads.

Route Relationship

• /api/v3/completions stores prompt payloads off-chain before submitting to the queue.
• /api/v3/delegate fans out work across predefined session pools.
• /api/v3/validate aggregates validation verdicts across predefined session pools.
• /api/v3/offchain/result lets assigned miners write signed off-chain results.

Precommit And Commit

A miner can acknowledge work, commit to a result hash or reference, then reveal or submit the final result. This helps the network separate assignment, execution, and result validation instead of treating inference as a single opaque HTTP call.

Stage	Why it exists
Assignment	Gives the miner a concrete task and policy.
Acknowledgement	Shows the miner has seen and accepted the task.
Precommit	Commits to an output or output reference before final reveal.
Commit	Publishes the result, encrypted blob, or off-chain URN.
Validation	Lets oracle/validator logic compare output, policy, and quality expectations.