Skip to content

Latest commit

 

History

History
118 lines (103 loc) · 16.3 KB

V3.md

File metadata and controls

118 lines (103 loc) · 16.3 KB

QUEUE v3 — the contract with operator liability

Status: NEAR testnet, not audited. Source: contracts/queue-v3. Deployed at market5.queue-demo.testnet.

v3 keeps every v2 rule (posted asks, deadline-checked purchases, balances held in the contract, model-signature settlement) and makes the remaining trusted parts accountable: the operator, the owner, the price a slot holder can charge, and the storage a job leaves behind.

What v3 guarantees

# Rule Enforced by
G1 A job passed by a purchase is paid its posted ask × the buyer's duration and still finishes before its stated deadline, with a safety margin. quote_internal, unchanged from v2
G2 A slot holder cannot reprice when an urgent job appears. Raising an ask takes effect 30 s later; a cut is immediate. Quotes always use the ask in force. set_move_ask, ASK_RAISE_DELAY_SECS
G3 A job already projected to miss cannot block a purchase. It has no promise left to protect; it is still paid its ask. Every job that is still on schedule keeps G1. quote_internal (the doomed check)
G4 Buy in the same transaction as the submission. submit_job(…, priority) buys the slot atomically; required: true makes the whole submission fail if the slot cannot be had. By default it buys only if the job's own deadline needs it. submit_job
G5 The operator is liable for its promises. A job that was on schedule when admitted (or after its own purchase) and then misses or fails is paid back its priority spend plus a penalty equal to its reward, from the operator's stake, as far as the stake goes. pay_broken_promise, stake
G6 No new work without a live, staked operator. Submissions and purchases are refused (nothing is charged) when the stake is below the minimum or the operator has not called the contract for 180 s. Cancellations, timeouts and withdrawals always work. require_accepting_work, heartbeat
G7 Model jobs are paid only for a verified model answer. A job whose input is a request sha256 (with a model key pinned) settles only through complete_job_attested; the operator's word is refused. Without an answer the operator can only fail the job (full refund, G5 penalty). complete_job, Verify
G8 Refusing work costs the operator, not the user. reject_job (queued jobs only) returns reward and bond, returns the priority spend from the stake, and releases the record. Because that refund comes from the operator, the operator chooses whose jobs it takes (G12). reject_job
G9 Storage comes back whole. A job holds 0.017 NEAR for its record and a purchase 0.006 + 0.003 per job passed. release_job deletes the finished job's records and credits the deposits back to the owner (owner any time, anyone after 7 days). Kept back are only the bytes that stay in the contract: the "answered" marker of a model-settled job (about 0.001 NEAR) and any balance key the job or its purchase had to create. release_job
G10 The contract's admin methods wait 24 h. Operator, treasury, fee, minimum stake, model key and the contract's own upgrade method go through propose → execute_proposal / execute_upgrade after the timelock; anyone can execute, the owner can cancel. Only pause is immediate (it stops new work; the queue still drains). Limit on testnet today: the contract account still holds a test full-access key, and that key can replace the code directly, without the timelock (see below). propose, timelock_secs
G11 The operator cannot run with the stake. Unstaking waits the same 24 h, and a withdrawal is refused while any job is queued or running, so the stake cannot leave under an open promise. The operator cannot be replaced while a job is open either (checked when the change runs, not when it was proposed); a new operator does not inherit the old one's stake (it is returned to the old operator). request_unstake, withdraw_unstaked, execute_proposal
G12 A closed list of clients. Wherever a stake backs the queue, only accounts the operator approved (allow_clients) can submit; anyone else is refused before escrow, storage or a purchase. The stake pays for refusals and broken promises, so an open door would let a stranger collect from it: buy a slot from its own second job, have the job refused, keep the compensation and get the price back from the stake. This deployment is a closed pilot: the eight season accounts are approved. allow_clients, remove_client, is_client

What it still trusts: the operator for liveness (now paid for by its stake) and, for operator-verified jobs, for the artifact; NEAR AI's attestation that the pinned key lives in TEE hardware (checked off chain before pinning); the deadlines and asks agents state (a contract cannot check that a deadline is true).

Limits, stated plainly:

  • Compensation is capped by the stake. The minimum stake (0.5 NEAR here) is a floor, not a reserve per job: if broken promises add up to more than what is left of the stake, the last ones are paid only in part.
  • Approved clients can still cost the operator money. Two approved accounts acting together can do what a stranger no longer can (G12). The operator answers that by choosing its clients and removing one that abuses it.
  • Bytes nobody deposits for. A release returns the deposit less the bytes that stay, so storage is paid by whoever causes it, with two bounded exceptions paid from the contract account's own balance: the activity log (a fixed ring of 128 entries), and a balance key created by a payout rather than by its owner (a penalty or a priority refund from the stake, the treasury's fee balance, a returned stake): at most one key of about 0.00125 NEAR per account. The random-history test checks after every step that the bytes in storage are covered by the deposits held and the money kept; npm run verify:v3 checks on chain that the contract's balance covers everything it owes plus every byte it stores, and prints the margin.
  • The test full-access key bypasses the timelock. market5 keeps the key it was deployed with, so the code can be fixed on testnet; this build was installed with it. Whoever holds that key can replace the contract at once. Removing it is a single transaction that cannot be undone, and it has not been sent. Until it is, read G10 as "the contract's admin methods wait 24 h", not "nobody can change the contract in under 24 h". npm run verify:v3 prints how many full-access keys the account holds.

Evidence

Check Command What it shows
Unit tests npm run test:contract-v3 95 tests: the 62 v2 tests ported, 33 for the v3 rules (each guarantee above, both sides of every boundary)
Random histories cd contracts/queue-v3 && cargo test invariants v2's invariants plus stake, penalty, rejection and release actions; after every step: escrow, balances, stake = posted − withdrawn − paid out, refundable storage covered, every job end paid exactly the penalty its promise implies
Simulator replay npm run test:parity-v3 the TypeScript rules (QUEUE_SIM_RULES=v3) and the contract agree on 2,224 steps: every quote, refusal, order, balance and status
Code on chain npm run verify:v3-deployed the source builds to the deployed wasm byte for byte (macOS / Apple silicon)
On-chain proof npm run verify:v3 every rule above exercised with real transactions on testnet, re-read from an archival node (table below)
Client end to end npm run verify:v3 (second part) one job submitted through packages/client with a function-call key, run and released (data/v3/client-e2e.json): the whole storage deposit came back, the bond was returned on delivery, and the round trip cost its owner the reward and nothing else

On-chain proof (data/v3/proof.json, 40 transactions, re-checked by npm run verify:v3)

Step Rule Transaction Outcome
1 G2 delayed raise 8YcBaHMe… mira submits M1 (40 s, ask 1e18/s) ok
1 G2 delayed raise ADHo7JHh… mira raises M1's ask to 5e18/s (takes effect in 30 s) ok
2 G4 atomic purchase 6TxhvUPp… kestrel submits K1 and buys the front in the same call ok
3 G2 raise landed GD1rFUY7… atlas submits A1 ok
3 G2 raise landed 6Z3ps4d1… atlas buys the front for A1: M1's raised ask has landed ok
4 G8 rejection EtKpUrAq… operator rejects A1 before it starts ok
5 G9 release EvRP4v3D… operator starts K1 ok
5 G9 release AXStkuQs… operator delivers K1 (operator-verified job) ok
5 G9 release GDDVDQvi… kestrel releases K1 and gets its whole storage deposit back ok
5 G9 release F231HipW… operator starts M1 ok
5 G9 release 97SPXUzq… operator delivers M1 ok
6 G3 + G5 late job passed, then paid from the stake BbwLvXHK… juno submits D1 (20 s, deadline 30 s) on an empty queue: promised ok
6 G3 + G5 late job passed, then paid from the stake YYLXtk7j… kestrel submits K2 behind it ok
6 G3 + G5 late job passed, then paid from the stake 5vooXG1V… kestrel buys past D1, which can no longer finish in time: D1 does not block and is paid ok
6 G3 + G5 late job passed, then paid from the stake 41xd7vdN… operator starts K2 ok
6 G3 + G5 late job passed, then paid from the stake C7mgnYgk… operator delivers K2 ok
6 G3 + G5 late job passed, then paid from the stake HXD2NxwT… operator reaches D1 too late: missed, and the stake pays the broken promise ok
7 G7 + G5 model job CKKCLoqj… juno submits J1 naming its request by sha256: a model job ok
7 G7 + G5 model job 9mfUVVDQ… operator starts J1 ok
7 G7 + G5 model job Bnu984ND… operator tries to settle J1 on its own word: refused refused: this job asked for a model answer: settle it with complete_job_attested, or fail_job
7 G7 + G5 model job 9oUWyo9t… operator fails J1: escrow back, and the stake pays the promise ok
8 G6 liveness vnKxhGgU… vale submits while the worker has been silent for 180 s: refused, nothing charged refused: the worker is offline (no operator call in the last 180 s): no new work is accepted, nothi
8 G6 liveness B2XCiN8j… vale submits again: accepted ok
8 G6 liveness Ddiu4vGV… vale cancels V1 (exits always work) ok
8 G6 liveness H6nJo5ES… vale releases V1 and gets its whole storage deposit back ok
9 G10 timelock BggcWZZ5… owner proposes fee 0.5% (runs in 24 h at the earliest) ok
9 G10 timelock 3zf2QYyh… anyone executes it now: refused, still timelocked refused: proposal 3 is timelocked until 1794780503
9 G10 timelock 93e8p96o… owner cancels the proposal ok
10 G11 unstake 3JKQosGP… operator asks to unstake 0.1 NEAR (withdrawable in 24 h) ok
10 G11 unstake 26foJafh… operator withdraws at once: refused, still timelocked refused: unstake is still timelocked
11 G12 approved clients 2CeziBGM… operator removes juno from its approved clients ok
11 G12 approved clients FikXjJ6R… juno submits: refused before escrow, storage or a purchase refused: juno.queue-demo.testnet is not an approved client of this queue: the operator approves acc
11 G12 approved clients CHxMA1r1… operator approves juno again ok
12 G11 the stake stays while a job is open FKRpptih… mira submits S1 ok
12 G11 the stake stays while a job is open AzYzvFiU… operator withdraws its unstake while S1 is queued: refused refused: the stake cannot be withdrawn while a job is queued or running: the stake answers for ever
12 G11 the stake stays while a job is open GcKYAWUa… operator starts S1 ok
12 G11 the stake stays while a job is open 8Nys7CLe… operator delivers S1 ok
12 G11 the stake stays while a job is open A4XPZ2R3… mira releases S1 and gets its whole storage deposit back ok

Heartbeat transactions are left out of the table. Paid from the stake to users in this run: 0.0040505 NEAR (two broken promises of 0.002 NEAR each, and the rejected job's priority spend of 0.0000505 NEAR). Storage came back whole in every release of the run: 0.026 NEAR for a job with one purchase, 0.017 NEAR for a plain job, 0.029 NEAR for the rejected job with a two-job purchase. The contract's lifetime counters (get_stats) also include earlier runs of the same script, made before the current build was installed. Amounts are small on purpose (rewards 0.002 NEAR, asks 0.000001 NEAR/s); the rules do not depend on the size.

Reproduce

npm run build:contract-v3     # wasm in contracts/queue-v3/target/wasm32-unknown-unknown/release
npm run deploy:v3             # testnet: market5 + stake + agent balances and keys (idempotent)
npm run proof:v3              # the on-chain proof (about 7 minutes, no model)
npm run proof:v3-client       # one job through packages/client with a function-call key (30 s)
npm run proof:v3-table        # rewrite the proof table above from data/v3/proof.json
npm run verify:v3             # re-check all of it, no keys