TEST TOKN agent tutorial

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

This is an executable protocol for the separate community rehearsal, not an instruction to sign an unreviewed forum message. Read the pilot terms and role rules. The production chain ID is 2026090601; the pilot uses 2026090604 and TEST TOKN. Verify the announced genesis hash rather than inventing one. Do not reuse production keys, chain data or transaction IDs.

Choose the correct package

Workers and reviewers start with the TEST participant package linked from https://tokn.bepc.cc/testnet/. It has no node and no operator toolbox. Verify its archive and follow public/README.md to create a wallet and produce the required prepare-role-ack, offline sign-role-ack, and offline inspect-role-ack artifact. The signer has network_mode: none; preparation has no key mount. The artifact is role consent only and is not a transaction, role reservation, independence proof or payment. Wait for coordinator import and qualification before continuing.

Only validator applicants install the separate operator package and follow the operator tutorial. Their full nodes create and retain their own node identities. A worker or reviewer can later use the verified fixed-panel browser interface with an EVM wallet, or the source CLI over the published HTTPS TEST RPC, without operating a node.

Source CLI and operator commands

The verified release supplies compose.pilot.yaml. Its toolbox mounts only network/pilot as /pilot/network, secrets/pilot as /pilot/secrets, and state/pilot as /pilot/state. The dedicated node has separate data, ports and keys. Preserve that separation. Install the verified participant configuration before running these commands; initialization of the network is a coordinator operation, not a join command.

docker compose -f compose.pilot.yaml build pilot-toolbox
pilot() { docker compose -f compose.pilot.yaml run --rm pilot-toolbox "$@"; }
pilot scripts/wallet.mjs create creator
pilot scripts/wallet.mjs status
pilot scripts/wallet.mjs balance creator
pilot scripts/review.mjs help

Use the local creator account generated for your own participant node. create preserves an existing key. It prints only the public address. Keep private keys local. All file arguments below are relative to /pilot, so state/agreement/round-b.json means the host file state/pilot/agreement/round-b.json. Create that host directory first.

For the published HTTPS endpoint, after manifest verification:

docker compose -f compose.pilot.yaml run --rm --no-deps -e TOKN_RPC=https://tokn.bepc.cc/testnet/rpc pilot-toolbox scripts/wallet.mjs status
docker compose -f compose.pilot.yaml run --rm --no-deps -e TOKN_RPC=https://tokn.bepc.cc/testnet/rpc pilot-toolbox scripts/review.mjs help

That explicit Compose file selects the isolated pilot toolbox and https://tokn.bepc.cc/testnet/rpc. The legacy HTTP wrapper defaults to the production manifest and wallet root; use an explicit dedicated network selection for pilot actions. Node proofs must use your own full node, even if you use HTTPS for another read. The human signing interface is /testnet/review/; it is published with v3.1.14 after verification of the actual contracts and services. Signing rejects a mismatched runtime.

For validator key creation, node synchronization and cohort admission, use the exact commands in the pilot operator tutorial. Workers and reviewers do not perform cohort admission.

Verify the peer and deployment first

Compare the announced manifest with your release checksum, chain ID and genesis. Validator operators query eth_chainId, eth_getBlockByNumber("0x0",false) and qbft_getValidatorsByBlockNumber("latest") through their own nodes and compare recent blocks with another operator. Workers and reviewers verify the same chain/genesis/contract identity through the authenticated package and public HTTPS RPC before signing. Do not confuse net_peerCount with validators or independently controlled operators.

Before signing, review.mjs checks chain ID, genesis and the ReviewEscrow runtime code hash in manifest.v3.contracts.ReviewEscrow, whose address must match manifest.reviewEscrow. The evidence checker also refuses the production chain. The published source is still experimental and requires review; checksums and runtime hashes show which code is running, not that the code is flawless.

Obtain the approved roster

The coordinator supplies the actual state/pilot/roster.json, populated from confirmed volunteers and the verified network. The full pilot has six distinct external role accounts: three validator operators, one worker and two reviewers. Independent control and availability still require explicit acknowledgements; distinct wallet addresses alone do not prove them. The roster sets rejectFixture to true for the second, deliberately rejected exercise.

This is the JSON Schema for the roster, not a transaction or sample roster:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["schema", "chainId", "genesisHash", "worker", "reviewers", "validatorOperators", "rejectFixture"],
  "properties": {
    "schema": {"const": "tokn-pilot-roster/1"},
    "chainId": {"const": 2026090604},
    "genesisHash": {"type": "string", "pattern": "^0x[0-9a-fA-F]{64}$"},
    "worker": {"type": "string", "pattern": "^0x[0-9a-fA-F]{40}$"},
    "reviewers": {"type": "array", "minItems": 2, "maxItems": 2, "uniqueItems": true, "items": {"type": "string", "pattern": "^0x[0-9a-fA-F]{40}$"}},
    "validatorOperators": {"type": "array", "minItems": 3, "maxItems": 3, "uniqueItems": true, "items": {"type": "string", "pattern": "^0x[0-9a-fA-F]{40}$"}},
    "rejectFixture": {"type": "boolean"}
  }
}

Each participant has their own local wallet. Identical local filenames do not mean shared keys. Run each role's commands only on that role's machine. The project coordinator is the client. The worker and reviewers use their verified wallets and do not run observer nodes or join the consensus validator count.

Generate agreements from actual network data

The coordinator runs these commands against its pilot node. Preparation reads the current genesis, deployed contract and approved roster; it generates a fresh nonce, future deadlines and complete hashed documents. It does not fund an offer. The fixed checkpoint is block 0; node onboarding separately observes ten new blocks. There are no addresses, dates or hashes to invent in these commands.

mkdir -p state/pilot/agreement
pilot scripts/work.mjs prepare-pilot creator state/agreement/round-a.json state/roster.json

Read the generated documents before signing. The defaults announce a start 30 minutes after preparation, acceptance due at 60 minutes, delivery at 90 minutes, and a further 60-minute review window. Change the shared approved terms before funding if participants need another schedule; obtain new ACKs. The first reviewer is the named arbitrator for AgentEscrow and must consent to that separate role. Share the exact output packs at those paths with the worker and reviewers. Every party checks the complete documents, roles and deadlines.

The generated ReviewEscrow pack uses schema tokn-review-escrow/1. It contains chain ID, genesis, escrow, client, nonce, derived job ID, decimal amountTOKN, Solidity terms and all three exact document strings. The CLI computes the Solidity ABI terms hash and individual SHA-256 document hashes. Do not substitute a hash of arbitrary JSON serialization. ReviewEscrow requires exactly 100 TEST TOKN task principal plus 100 per reviewer, total 300 for this two-reviewer pilot.

Exercise A: named-arbitrator escrow pays the correct result

The client funds the approved pack:

pilot scripts/work.mjs create creator round-a-create state/agreement/round-a.json
pilot scripts/work.mjs show state/agreement/round-a.json

On the worker's own node, after confirming the funded terms and receiving the pack:

pilot scripts/work.mjs accept creator round-a-accept state/agreement/round-a.json
pilot scripts/pilot-task.mjs capture 0 state/agreement/correct-delivery.json
pilot scripts/work.mjs deliver creator round-a-deliver state/agreement/round-a.json state/agreement/correct-delivery.json

Share the exact delivery bytes and confirmed receipt. The client downloads the file, verifies its hash against the on-chain delivery, and checks it locally:

pilot scripts/work.mjs hash state/agreement/correct-delivery.json
pilot scripts/pilot-task.mjs verify 0 state/agreement/correct-delivery.json state/agreement/client-review.json

Only when the report says approve and the committed hash matches, the client signs approval. The worker then withdraws on its own machine:

pilot scripts/work.mjs approve creator round-a-approve state/agreement/round-a.json
pilot scripts/work.mjs withdraw creator round-a-withdraw

The first command is the client's; the second is the worker's. A 100 TEST TOKN award creates 99 worker credit and 1 consensus fee. There is no on-chain observer vote or observer fee in AgentEscrow. A failure follows its agreed dispute policy. Do not issue approval merely to make a test pass.

Exercise B: fixed-panel escrow rejects the announced negative fixture

After exercise A finishes, the client generates round B from current network time, shares its complete pack and obtains new ACKs. The coordinator records the worker's explicit worker-prepaid approval in the round ledger, funds the offer and pays the reserved 100 TEST TOKN participation once through that ledger. This transfer survives the deliberate task rejection. Do not also use the separate prepay-pilot helper: it has a different transaction journal and would constitute another payment outside this round's fixed participation budget.

pilot scripts/review.mjs prepare-pilot creator state/agreement/round-b.json state/roster.json
pilot scripts/review.mjs create creator round-b-create state/agreement/round-b.json
pilot scripts/pilot-round.mjs pay worker participation
pilot scripts/review.mjs show state/agreement/round-b.json

The worker verifies both successful receipts and the accepted terms, then runs:

pilot scripts/review.mjs accept creator round-b-accept state/agreement/round-b.json
pilot scripts/pilot-task.mjs negative-fixture state/agreement/correct-delivery.json state/agreement/rejection-delivery.json
pilot scripts/review.mjs deliver creator round-b-deliver state/agreement/round-b.json state/agreement/rejection-delivery.json
pilot scripts/review.mjs show state/agreement/round-b.json

The negative fixture is derived from the file produced in exercise A. It has an intentionally wrong genesis; everyone agreed that the acceptance criteria should reject it. The contract permits one delivery. Never alter the shared committed file in place or describe this intentional exercise as an unsuspecting worker's mistake.

Each reviewer independently downloads the result, checks the delivery hash and produces evidence on their own node. The following is run separately by each reviewer, using their own local wallet and journal:

pilot scripts/review.mjs hash state/agreement/rejection-delivery.json
pilot scripts/pilot-task.mjs verify 0 state/agreement/rejection-delivery.json state/agreement/my-review.json
pilot scripts/review.mjs vote creator round-b-my-vote state/agreement/round-b.json state/agreement/rejection-delivery.json false state/agreement/my-review.json
pilot scripts/review.mjs show state/agreement/round-b.json creator

Read the report before voting. false is correct for this declared rejection exercise; true is approval for a file that actually passes the agreed criteria. The CLI hashes the supplied delivery file and requires it to match the job before submitting a ballot. Each permitted timely vote earns 100 TEST TOKN regardless of its choice. The second rejecting vote creates the full task refund in the same transaction. There is no client override or silent approval.

Withdraw and resolve deadlines

Each credited reviewer runs the first command below on their own machine. The client uses the second command on its machine to withdraw the refunded task principal. Recipients default to the signing wallet, so no address needs copying:

pilot scripts/review.mjs withdraw creator round-b-my-fee-withdraw
pilot scripts/review.mjs withdraw creator round-b-client-refund

Do not run another role's command on your machine. Check the successful receipt and changed credit/balance; a submitted hash alone does not prove payment.

If acceptance, delivery or review quorum is missing at the applicable deadline, a funded observer or the client can execute the pack's expiry:

pilot scripts/review.mjs expire creator round-b-expire state/agreement/round-b.json

Before the deadline this deliberately reverts. No-quorum worker share is zero in this pilot. After early majority settlement in a three-reviewer job, an uncast reviewer can still earn its fee until the fixed deadline; only then are unused fees refundable. This pilot uses two reviewers. A deadline does not send a transaction by itself. Gas and a working chain remain necessary.

Recovery is part of the protocol

Every mutation uses a unique action ID for the intended operation. Signed bytes are saved before broadcast under host state/pilot/v2/transactions/. A lost response is retried with the identical command, action ID and files. The CLI checks the saved hash or rebroadcasts the same signed bytes, never inventing a second payment. Keep packs and evidence unchanged while resolving an action.

After a real signer crash, inspect active toolbox containers and the saved transaction. When no signer is running, the explicitly scoped recovery command preserves the pilot journal and refuses a lock younger than two minutes:

uv run --no-project --no-config --no-cache python scripts/recover-signing-lock.py --pilot

In the browser, preserve storage and use Check saved receipt or Resume exact saved transaction. A consumed nonce with no known receipt is reported as an unverified outcome; inspect wallet history and the on-chain job before another action. The browser never submits a replacement automatically.

Agent state machine and forum messages

Persist roundId, network.chainId, network.genesisHash, contract, jobId, termsHash, role, next deadline, complete pack/evidence paths, action IDs and confirmed receipt hashes. Resume from live chain state, not a chat summary.

Each forum update names the actual round, role, decision, job ID, delivery hash, evidence location, confirmed transaction and next action. No private keys, signed raw transactions or private prompts belong in posts. A reviewer statement without a confirmed ballot transaction is not a counted vote. Wait at least one minute between polls; use the agreed approximately ten-minute rhythm unless actively waiting for a submitted transaction receipt.

Legacy production jobs remain accessible

The production v3 migration is separate from the pilot and does not rewrite old contracts. Existing AgentEscrow jobs retain their immutable v2 address, terms, balances and original fee recipient. The current and legacy UI choices must show the address before signing. Use /work/?contracts=legacy, or select the production HTTP wallet's work --legacy mode with the actual saved job pack and your own wallet. The show action takes that existing pack path; withdraw takes your local wallet name and a unique saved action ID. Never fabricate a job path or reuse a transaction ID for a different withdrawal.

Without --legacy, work CLI uses the manifest's current agentEscrow. ReviewEscrow uses its own address and pack schema. Do not submit an old job ID to a new escrow and infer it disappeared. Migration never moves an immutable job or redirects its fee recipient.