VORQ Docs
Concepts

Job lifecycle

How a job moves from quote to settlement, what each state means, and when funds move.

A job is an order on the JobRegistry contract. The coordinator relays every step, but each step is authorised by a signature from the client or the provider, and the contract decides whether it happens.

From quote to result

  1. Quote. The client signs an Order and posts it to POST /v1/jobs without payment. The coordinator answers 402 with the price and up to three candidate providers.
  2. Post. The client signs the payment authorization and posts the same order with it and the sealed payload. The coordinator stores the payload, relays post and answers 201. The job is open. An order no live provider's ask clears is held instead: the answer is 202, the job reads as open, and post is relayed when a provider takes it.
  3. Claim. A provider relays a signed claim through POST /evm/ops. The contract collects the client's payment. The job is claimed.
  4. Settle. The provider relays a signed settle with the sealed result. The contract pays out. The job is settled.
  5. Collect. The client polls GET /v1/jobs/{id} and fetches the result by result_cid.

A job can also end without a result:

  • Cancel. The owner cancels an open job with a signed Cancel.
  • Expiry. Nobody claims it before expires_at.
  • Fail. The provider that claimed it relays a signed fail.
  • Reclaim. The provider misses its SLA (claimed_at + sla_secs). Anyone may then call the contract's reclaim; the coordinator does so itself once a minute, so the client is refunded even if nobody else acts.

States

Chain stateended_becauseClient status
0 Open0queued
1 Claimed0in_progress
2 Settled1 settledcompleted
3 Ended3 provider fail, 4 reclaimfailed
3 Ended2 cancelled, 5 expiredcancelled

/evm/* routes report state and ended_because; /v1/jobs/{id} adds the client status.

Expiry is computed when the job is read: an open job whose expires_at has passed reads as state 3, ended_because 5. The expires_at second itself still counts as open. Nothing is written on chain for an expiry, so the owner can still cancel such a job, which then reads ended_because 2.

What a job costs

Rates are USD per million units. The order's ceiling, in USD, is

cap = (rate_in × units_in + rate_out × units_out) / 10^6

rounded up to the payment token's smallest unit ($0.000001 for USDC), and never below one such unit. units_in and units_out are ceilings: settlement bills what was used. The client authorises

amount = cap + fee + gas_fee,   fee = cap × fee_bps / 10000, rounded down to the smallest unit

fee_bps (the protocol fee) and gas_fee (a flat charge that covers relayed gas) are read from the JobRegistry; GET /evm/chain returns fee_bps, and every quote states both.

When funds move

  • Post, cancel, expiry. Nothing moves. The payment authorization is only used at claim.

  • Claim. The contract pulls amount from the owner.

  • Settle. The provider is paid

    charge = (rate_in × (prompt_tok − cached_tok) + rate_in_cached × cached_tok + rate_out × completion_tok) / 10^6

    rounded up to the smallest unit and never below one, at most cap. prompt_tok, cached_tok and completion_tok are the counts the provider's backend reported; rate_in_cached is the provider's rate for cached prompt tokens. The contract clamps prompt_tok to units_in, cached_tok to prompt_tok, completion_tok to units_out and rate_in_cached to rate_in. For media jobs prompt_tok is units_in and cached_tok is 0. The protocol fee on that charge and the gas_fee go to the treasury. The rest goes back to the owner.

  • Fail or reclaim. The owner gets back cap and the fee. The gas_fee goes to the treasury, because the gas was already spent.

A provider that fails a job within 300 seconds of claiming it takes no reputation penalty. Later fails, and reclaims, lower its reputation.

Timing rules

  • expires_at must be in the future and at most 24 hours ahead.
  • sla_secs must be an SLA the contract allows, at most 24 hours.
  • Signed cancel, claim, settle and fail messages carry issuedAt, which must be within 600 seconds of the coordinator's clock.

Who can see a job

The job book is public: every job's terms, state and content identifiers can be read by anyone. Payloads and results are sealed, so only the client and the provider that works the job can open them. See Payloads and file retention.

On this page