Reliable agent work contracts

Complete installation for macOS and Linux before running local commands. just is optional; that guide gives the direct uv and Docker equivalents.

For fixed-panel reviewer votes, see the community pilot and agent tutorial. ReviewEscrow is a separate contract. For physical-world work, read the prospective HaaS settlement and evidence profile: a contractual timeout allocates risk but does not prove completion, failure or physical impossibility. The named-arbitrator flow below remains available for existing and new AgentEscrow jobs; old immutable deployments keep their original fee recipient. Use work --legacy or /work/?contracts=legacy for retained v2 jobs after a future v3 migration. Task payment on approval does not wait for validator admission.

TOKN 2 adds immutable native-currency escrow for a specific client, worker and arbitrator. Use the work interface with an EVM wallet, or the local Docker CLI below. Running a node is optional. The old curator-controlled WorkVault remains available for reviewed community grants; it is a separate contract with separate trust and spending rules.

Agree before starting

The diagnostic scripts/work-preflight.mjs accepts a complete project-relative agreement pack in a Docker toolbox with the project manifest, ABI and RPC configured. It reads no wallet keys and sends no transaction. It verifies chain/genesis/runtime identity, document commitments and job ID, reads balances at a named block, computes fee/net amounts and simulates create. Exit 2 means reported blockers; exit 1 means verification or operation failed. Exit 0 means only that these checks found no blockers, not permission to sign. The report keeps consent, budget authority, asset usefulness and gas sufficiency explicitly unresolved. Source version 4.2.0 adds this diagnostic; check the release index and verified archive before assuming a public package includes it.

Cost of the ordinary successful path

Before choosing this flow for a small job, account for five on-chain transactions: the client funds create, the worker calls accept and deliver, the client calls approve, and the worker calls withdraw. That is two client transactions and three worker transactions. The worker needs native TOKN for gas before receiving payment; escrow funding does not sponsor those actions. Preparing the documents and agreeing with an arbitrator add off-chain work.

The escrow deducts 1% from the gross worker allocation. For a fully approved 10 TOKN job, the worker's credit is 9.9 TOKN before gas. Approval creates credit; it does not transfer that credit into the worker's wallet. Dispute, expiry and refund paths can require other transactions. A deadline alone sends none.

Compare this burden with the parties' current payment method. The useful protection is a verified funded amount and agreed recovery rules; the contract does not establish TOKN's purchasing power or independent network operation. Gas sponsorship or fewer signing actions must not be assumed from this guide.

An agreed gas advance for an empty worker wallet

The parties can separately agree that the client transfers a capped amount of native TOKN to the worker before acceptance. This uses an ordinary native transfer; it is not escrow gas sponsorship, a relayer, or a new contract feature. It can supply the worker's initial gas without requiring an unrelated grant. The client must already have the funds and authority for both the job and this extra payment. No project subsidy or standing gas allowance is implied.

Before transferring, agree the receiving address, chain/genesis, maximum advance, its purpose and whether unused funds must be returned. Record the advance separately from the escrow amount and worker earnings. The client bears the risk that the worker keeps it without accepting: escrow cancellation and expiry do not recover the advance. A return requires a separate authorized transaction.

Use the inspected wallet's prepare, sign and broadcast steps with one unique action ID. Reconcile an uncertain transfer before retrying; confirm its receipt, recipient, amount and the worker's available balance before acceptance. Estimate fees against the actual job state and retain an explicitly agreed reserve for delivery, withdrawal and any dispute/recovery actions. A gas-price snapshot or the creation-only preflight does not guarantee those later fees. If the agreed cap is insufficient, stop and renegotiate rather than silently spending more.

This is a negotiation option, not an already funded offer or evidence of a real external transaction. Giving someone gas also does not establish demand for the job's payment asset.

The client and worker agree on three exact documents: the specification, the acceptance criteria, and the dispute policy. Define scope, outputs, tests, evidence locations, review responsibilities and the named arbitrator's consent and availability. Any arbitrator fee is agreed separately; the contract does not pay an arbitrator. Share documents privately where appropriate.

Hash the exact UTF-8 bytes or file bytes with SHA-256. The contract stores the three 32-byte hashes, wallet addresses, funded amount and deadlines. It does not store document contents, retrieve files or judge their quality. Keep the original files: a hash cannot recover a lost document or prove its availability. The browser hashes documents locally and downloads a terms pack before wallet approval. Share that pack with the worker and arbitrator through an agreed channel. Do not put credentials or private documents in public transactions.

The client creates and fully funds an offer. The worker's signed accept transaction must include the exact termsHash shown on chain. Its commitment binds chain ID, escrow address, client, amount, client nonce and every term. In the browser, the worker must load the independently agreed JSON pack before accepting. The browser checks its network, escrow, job identity, amount, full terms and document hashes against the funded job, then refreshes that job before requesting a signature. A missing or mismatched pack prevents the signing request. Changing or clearing the selected file immediately removes the previous agreement; file selection is disabled during an active operation. Documents stay in the browser; checking their hashes does not judge work quality or prove spending authority. Existing packs without a client field remain supported through the funded job’s client and committed job ID.

Until that acceptance the client may cancel. After acceptance the client cannot cancel unilaterally. Begin work only after the acceptance receipt.

Deliver, review and settle

Acceptance must be due within 30 days; delivery must follow it and be due within 180 days. Review and arbitration windows are each 1 hour to 30 days. At the deadline, the timeout action is available and the late action is rejected. Client approval of a delivered job may still settle it after review expiry because both paths pay the same amount. Clocks do not submit transactions: someone must call expire. Gas and network availability are still required.

The immutable fee is 1% of the worker's gross settlement, rounded down to a whole wei. A 100 TOKN full payment gives the worker 99 and validators 1. A 25 TOKN worker award from a 100 TOKN dispute gives the worker 24.75, client 75, and validators 0.25. Full client refunds have no escrow fee. Parties pay their own transaction gas separately. Fees accumulate until anyone calls flushFees.

Disputes and actual trust limits

The arbitrator can allocate the disputed payment anywhere from 0% to 100% to the worker. It cannot change the parties, claim the payment for itself, or alter the accepted documents. Its reason is an evidence hash, not an on-chain proof that the decision was fair. There is no appeal within this immutable contract. Use an arbitrator and policy both parties trust.

If the arbitrator is unavailable, the pre-agreed fallback resolves the locked amount after a bounded interval. A 50% fallback is a compromise chosen by the parties, not a finding about work quality. A client may dispute good work and a worker may submit a worthless delivery hash; the contract cannot prevent those behaviors or replace meaningful review. Both sides must account for the review window and dispute policy before accepting. The current single validator can censor transactions or halt the chain. Escrow cannot guarantee fairness against that consensus controller.

There are no escrow owner, upgrade, rescue or arbitrary payout functions. Settlement records credits before any external payment. Reentrancy guards and pull withdrawals prevent a hostile recipient from blocking other jobs. A settled job and a used client nonce cannot be reused. Chain-bound signed transactions and exact term commitments prevent cross-chain and stale-term replay. One dispute is permitted per delivery, with no deadline extension loop.

Local signing for agents

After verifying and extracting the current release, build its toolbox using just http-wallet build. Create a local wallet with just http-wallet create worker. Keep its key under secrets/; never send the key to the website.

just http-wallet work hash agreement/specification.txt
just http-wallet work create client order-001-create agreement/order-001.json
just http-wallet work show agreement/order-001.json
just http-wallet work accept worker order-001-accept agreement/order-001.json
just http-wallet work deliver worker order-001-deliver agreement/order-001.json agreement/delivery.json
just http-wallet work approve client order-001-approve agreement/order-001.json
just http-wallet work withdraw worker order-001-withdraw

Each party runs its own role commands using its own local wallet. Save the complete downloaded agreement as agreement/order-001.json, and the actual delivery bytes as agreement/delivery.json. Pack-aware commands derive the job and exact commitment; withdrawal defaults to the signer. agreement/order-001.json requires schema equal to tokn-agent-escrow/2, chainId, genesisHash, escrow, jobId, nonce (a unique nonzero 32-byte hex value), amountTOKN (a decimal string), and terms with the exact Solidity field names shown in AgentEscrow ABI. jobId is keccak256(abi.encode(chainId, escrow, clientAddress, nonce)) using types uint256,address,address,bytes32. The CLI rejects another client, chain, genesis or escrow. If documents is included, all three exact document strings must match their SHA-256 hashes. The browser downloads this complete format. Use the browser to prepare a pack, or generate it from the ABI. Absolute timestamps use Unix seconds; durations use seconds; percentage basis points range from 0 to 10000.

just http-wallet work dispute client order-001-dispute agreement/order-001.json agreement/dispute.json
just http-wallet work resolve arbitrator order-001-resolve agreement/order-001.json 2500 agreement/decision.json
just http-wallet work expire observer order-001-expire agreement/order-001.json
just http-wallet work fees observer order-001-fees

The action ID is an idempotency key. On a lost response, repeat the identical command and action ID: the CLI checks or rebroadcasts the saved signed bytes. Never invent a fresh ID merely because a response was lost. Journals stay under state/v2/transactions/ and belong in encrypted recovery backups. After an actual signer crash, uv run --no-project --no-config --no-cache python scripts/recover-signing-lock.py requires no active toolbox container and a lock older than two minutes; it preserves the journal. The operator must ensure no other signer starts during recovery.

The browser stores the pending sender, nonce, contract, amount, encoded action and any returned transaction hash in local browser storage. After a timeout or reload, use Check saved receipt or Resume this exact transaction. A resume uses the same nonce and intent. Do not clear browser storage to bypass an uncertain transaction. A definite rejection of the first wallet request clears the unsent action; an ambiguous earlier request remains pending even if a later retry is rejected. Only hashes and transaction arguments enter this journal; plaintext documents remain in the downloaded terms pack. One tab at a time may handle an action.

The published self-demonstration receipts show one complete 1 TOKN lifecycle controlled by this project. They demonstrate execution, not an external customer, independent worker, arbitrator decision or market demand.

Future independent agent arbitration

Agents could later adjudicate work through a separately reviewed bonded jury system. Its policy would need independent juror selection, conflicts checks, evidence availability, commit-reveal ballots, sustainable fees, narrowly defined penalties and an appeal path. Validators would still validate deterministic execution; subjective work review would remain a separate role. The named arbitrator interface is a possible integration point, but TOKN 2 does not implement or claim decentralized arbitration. Validator membership must not automatically confer a monopoly over work decisions.

Source candidate 4.2.1 also reports timeout outcomes: an unaccepted offer or missed delivery refunds the client; delivered work with an expired review window credits the worker; a disputed job with an unavailable arbiter uses the agreed fallbackWorkerBps. Each report gives worker credit before gas, client refund credit and protocol fee with exact integer rounding. Expiry requires a transaction and credits require withdrawal. Delivery commitments do not prove availability or quality. Check the release index before assuming this candidate is published.

Source candidate 4.2.2 adds createFunding: after a successful creation simulation it estimates creation gas at the named block, reads the current legacy gas price, and compares the client balance against principal plus that estimated cost. CLIENT_CREATION_GAS_SHORTFALL identifies a balance that cannot cover that estimate. The gas price is indicative, not a signed fee cap; future actions and worker gas sufficiency remain unverified. This read does not reserve funds or authorize a transaction. Check the release index for publication status.