Get the current on-chain state of an Idios contract.

Returns all contract fields including status, payment, collateral, dispute_fee, delivery_hash, expiry_block, mode, and asset_id.

Status values: Open(0), Active(1), AwaitingApproval(2), Disputed(3), Settled(4), Refunded(5), ResolvedToAlice(6), ResolvedToBob(7), Closed(8), Voided(9), Cancelled(10).

Use this to check contract state before deciding what action to take. This call is read-only and does not require wallet funds.

Read the current Beam block height from the wallet's node.

Call this before creating a contract so you can choose a future expiry_block (the contract requires expiry_block to be in the future). Add a margin to the returned height: current + 10000 is roughly 7 days, current + 2000 is a short test window.

Returns the current block height, or an error message.

Get your own Beam pubkey for the Idios contract.

This is the value a counterparty uses to name you in a contract: it goes in worker_pubkey when a requester calls create_contract_a or create_contract_b. It is derived from your wallet and the Idios contract, so it stays the same for this wallet on this contract.

Share it with a counterparty so they can create a contract with you. This call is read-only and does not require wallet funds.

Returns your pubkey as a hex string, or an error message.

Create a Mode B (Reviewed settlement) Idios escrow contract.

Locks payment from your wallet into escrow. The worker must then call commit_collateral to begin work. After delivery, you review and approve or dispute. If you do nothing within review_window_blocks, the worker can claim via claim_after_timeout.

Use Mode B for any work where a human or agent needs to judge the output: custom AI agents, automation pipelines, consulting, data labelling, model fine-tuning where exact output hash is not known in advance.

Args: job_id: Unique integer ID you choose. Must not already exist on chain. worker_pubkey: Worker's Beam pubkey from their Idios dapp or get_key action. payment: Payment amount in groth (1 BEAM = 100,000,000 groth). asset_id: 0 for BEAM, 47 for NPH (USD-pegged stablecoin). expiry_block: Block height when contract expires. Use current_block + 10000 for ~7 days. review_window_blocks: How long requester has to approve/dispute after delivery. 2000 blocks is roughly 33 hours. Pass 0 (or omit) to use the contract default set at deploy time. dispute_fee: Amount the requester locks if they file a dispute. It pays the voting arbitrators regardless of outcome; neither party gets it back. required_collateral: Minimum collateral in groth the worker must commit. The contract rejects any commit below this floor. 0 (default) = no floor. spec_hash: Optional SHA-256 hash (64 char hex) of the job specification, stored on chain for later reference. Omit or pass "" for none. subnet_id: Subnet identifier (default 1). epoch: Epoch (default 1).

Returns confirmation once contract is on chain, or error message.

Create a Mode A (Hash-verified settlement) Idios escrow contract.

Locks payment from your wallet. The expected output hash is locked in at creation time. When the worker submits the same hash, the contract auto-settles and releases payment. No human approval needed.

Use Mode A for deterministic outputs where the exact deliverable is agreed before the contract starts: a specific model file, dataset, or any output with a known SHA-256 hash.

Both parties must agree on result_hash before the contract is created. The worker should send you the hash of their deliverable in advance for you to verify before locking it in.

Args: job_id: Unique integer ID you choose. Must not already exist on chain. worker_pubkey: Worker's Beam pubkey from their Idios dapp or get_key action. payment: Payment amount in groth (1 BEAM = 100,000,000 groth). asset_id: 0 for BEAM, 47 for NPH (USD-pegged stablecoin). expiry_block: Block height when contract expires. Use current_block + 10000 for ~7 days. result_hash: SHA-256 hash of the expected deliverable file (64-char hex string). required_collateral: Minimum collateral in groth the worker must commit. The contract rejects any commit below this floor. 0 (default) = no floor. spec_hash: Optional SHA-256 hash (64 char hex) of the job specification, stored on chain for later reference. Omit or pass "" for none. subnet_id: Subnet identifier (default 1). epoch: Epoch (default 1).

Returns confirmation once contract is on chain, or error message.

Create up to 50 Mode B escrow contracts in ONE wallet transaction.

This is swarm payroll: an orchestrator agent that has split work across many worker agents locks payment for all of them at once, privately. One transaction, one network fee, every child contract created Open. Each worker then commits collateral to their own contract and the normal Mode B lifecycle (deliver, review, approve or dispute, claim) runs per contract from there.

All contracts in the batch are created by this wallet as the requester. The wallet must hold the SUM of all payments plus one network fee. Batch creation is Mode B only, and specs cannot carry required_collateral or spec_hash; create those contracts individually with create_contract_b.

Each spec is an object with these fields: job_id (int, required): unique ID you choose, unused on chain, and not repeated inside the batch. worker_pubkey (str, required): that worker's pubkey for this contract (from their get_key). payment (int, required): payment in groth (1 BEAM = 100,000,000). asset_id (int, required): 0 for BEAM, 47 for NPH. expiry_block (int, required): future block height. current + 10000 is roughly 7 days. dispute_fee (int, required): locked if the requester disputes; it pays the voting arbitrators win or lose. review_window_blocks (int, optional, default 0): approval window after delivery. 0 uses the contract default. subnet_id (int, optional, default 1). epoch (int, optional, default 1).

Args: specs: List of 1 to 50 spec objects as described above.

Returns a summary of the created contracts, or an error message.

Commit collateral to an Open Idios contract as the worker (Bob).

This locks your collateral into escrow alongside the requester's payment. Both sides now have funds at risk. After committing, the contract moves to Active status and you can submit delivery.

You must be the worker whose pubkey was used to create the contract. The asset type is read from chain, not from this call.

Args: job_id: The contract ID to commit to. collateral: Amount in groth to lock as collateral. Typically 50% of payment. If you lose a dispute, you lose this collateral.

Returns confirmation once collateral is on chain, or error message.

Submit delivery hash for an Active Idios contract as the worker (Bob).

For Mode A: if delivery_hash matches the result_hash locked at creation, the contract auto-settles immediately and you can claim funds.

For Mode B: contract moves to AwaitingApproval. The requester has review_window_blocks to approve or dispute. If they do nothing, call claim_after_timeout once the window expires.

Send the actual deliverable file to the requester off-chain (via whatever channel you agreed). The file never touches the blockchain.

Args: job_id: The contract ID to submit delivery for. delivery_hash: SHA-256 hash of your deliverable (64-char hex string). Generate with: sha256sum yourfile (Linux/Mac) or Get-FileHash yourfile -Algorithm SHA256 (Windows PowerShell).

Returns confirmation of submission, or error message.

Approve a delivered Mode B contract as the requester (Alice).

Use this after reviewing the worker's deliverable and confirming it meets the agreed specification. Once approved, the worker can claim their payment plus collateral.

Only use after thoroughly testing the deliverable. Approval cannot be reversed once confirmed on chain.

Args: job_id: The contract ID to approve.

Returns confirmation of approval, or error message.

Cancel an Active or AwaitingApproval contract by mutual agreement, with everyone made whole.

The contract requires signatures from BOTH the requester and the worker on one transaction. In the current implementation both signatures come from this wallet, so mutual cancel works when the same wallet holds both roles (self dealing tests, or contracts where both pubkeys were derived from this wallet). True cross wallet co signing is not implemented yet.

On success the payment returns to the requester and the collateral to the worker in the cancel transaction itself; there is no separate claim step. The contract reaches the terminal Cancelled state. Not allowed from Open (nothing to mutually cancel) or Disputed (the arbitrator owns the outcome).

Args: job_id: The contract ID to cancel.

Returns confirmation of cancellation, or error message.

Dispute a delivered Mode B contract as the requester (Alice).

Use this if the deliverable does not meet the agreed specification. Filing a dispute locks the dispute_fee from the contract. The registered arbitrators then vote on chain to resolve it.

After disputing, contact the arbitrator at @tappyoak on Telegram or Discord with the contract ID, your role (requester), and a description of why the work does not meet spec. The resolution is final.

The dispute winner receives payment + collateral only. The dispute fee is split among the consensus voting arbitrators, never awarded to either party. Use view_dispute to follow the vote and the payout flags.

Args: job_id: The contract ID to dispute.

Returns confirmation of dispute filing, or error message.

Get the on chain dispute record for a Disputed or Resolved contract.

Use this to follow an arbitration vote and to check payout state after resolution. Fields returned:

• frozen_n, threshold: arbitrator set size and votes needed, frozen when the dispute was filed.

• vc_alice, vc_bob: current vote counts for the requester and the worker.

• resolution: 0 none yet, 1 the requester (Alice) won, 2 the worker (Bob) won.

• winner_paid: 1 once the winner has claimed. A Resolved contract stays at status 6 or 7 forever, so this flag is the ONLY signal that the payout happened. Never retry claim_funds when winner_paid is 1.

• fee_share, fee_remainder, remainder_swept: how the dispute fee was split among the consensus voting arbitrators, and whether the remainder went to the treasury.

• bond_encumbered: 1 while this dispute holds a lien on the worker's reputation bond (the bond cannot be reclaimed until the dispute ends).

Read only, needs no wallet funds.

Args: job_id: The contract ID whose dispute to inspect.

Returns the dispute record as JSON with a one line interpretation, or an error message.

Claim funds from a Settled or Resolved Idios contract.

Call this after the contract reaches one of these states:

• Settled (status=4): worker claims payment + collateral

• ResolvedToBob (status=7): worker won the dispute, claims payment + collateral

• ResolvedToAlice (status=6): requester won the dispute, claims payment + collateral A refunded contract (status=5) returns funds directly and needs no claim.

The dispute winner receives payment + collateral only. The dispute fee is split among the consensus voting arbitrators, never awarded to a party.

A Resolved contract stays at status 6 or 7 forever, even after the winner is paid. This tool checks the winner_paid flag via view_dispute before claiming, and reports "already claimed" instead of firing a call that would halt on chain.

The amounts are read from chain by the contract; only job_id is sent.

Args: job_id: The contract ID to claim from.

Returns confirmation of claim, or error message.

Claim funds as the worker after the review window expires without requester action.

Use this for Mode B contracts in AwaitingApproval status where the requester has not approved or disputed within the review_window_blocks set at creation. This protects workers from requesters going silent indefinitely.

Check view_contract first to confirm the review window has passed before calling this. If the window has not yet expired, the call will fail on chain.

Args: job_id: The contract ID to claim from after timeout.

Returns confirmation of claim, or error message.

Refund an expired Idios contract as the requester (Alice).

Valid in two situations, both requiring the contract's expiry_block to have passed:

• Open (worker never committed collateral): your payment is returned.

• Active (worker committed collateral but never delivered): your payment is returned, and the worker's collateral is forfeited to the protocol treasury as a non-delivery penalty. You never receive the worker's collateral yourself, so a tight expiry cannot be used to seize their stake.

Funds are returned in the refund transaction itself. No separate claim is needed afterwards. Refund is not possible once a delivery has been submitted (AwaitingApproval or later); use approve, dispute, or the dispute resolution flow instead.

Args: job_id: The contract ID to refund.

Returns confirmation of refund, or error message.

Void a Disputed contract that the arbitrator never resolved.

This is the recovery path for a stale dispute. It is permissionless: anyone can call it once arbitrator_timeout_blocks have passed since the dispute was filed. The condition is strict: current block height must be GREATER than dispute_filed_block + arbitrator_timeout_blocks. A call exactly on the boundary fails; it succeeds from the next block.

arbitrator_timeout_blocks is a per contract deployment parameter, not a universal constant. Never assume a value: compute eligibility from dispute_filed_block in view_contract plus the timeout of the contract this server is configured for. On the production contract it is 20160 blocks, roughly 14 days; test deployments may use far shorter values.

Voiding moves the contract to Voided status. Neither party wins: each side then reclaims its own principal. After voiding, the requester calls void_claim_requester to reclaim the payment and the worker calls void_claim_node to reclaim the collateral. The dispute fee is forfeited to the protocol treasury.

Check view_contract for dispute_filed_block and get_chain_info for the current height before calling. If the timeout has not passed, the call fails on chain.

Args: job_id: The Disputed contract ID to void.

Returns confirmation of voiding, or error message.

Reclaim your payment from a Voided contract as the requester (Alice).

Use this after a stale dispute was voided via void_dispute. Returns the full payment you locked at contract creation. The amount is read from chain and can only be claimed once. Your dispute fee is not returned; it is forfeited to the protocol treasury.

Args: job_id: The Voided contract ID to reclaim payment from.

Returns confirmation of the claim, or error message.

Reclaim your collateral from a Voided contract as the worker (Bob).

Use this after a stale dispute was voided via void_dispute. Returns the full collateral you committed. The amount is read from chain and can only be claimed once.

Args: job_id: The Voided contract ID to reclaim collateral from.

Returns confirmation of the claim, or error message.

Sweep forfeited funds to the protocol treasury.

Only succeeds if this wallet holds the treasury key (the wallet that deployed the contract). Collects exactly two kinds of forfeited funds: the worker's collateral from a Refunded contract that went through the Active path (worker committed, never delivered), or the dispute fee from a Voided contract. Each can be swept once. The call fails for any other wallet or any other contract state.

Args: job_id: The Refunded or Voided contract ID to sweep.

Returns confirmation of the sweep, or error message.

Post a worker reputation bond on the Idios contract.

The bond is a slashable stake tied to your worker pubkey (the same key counterparties put in worker_pubkey when creating contracts with you). It signals skin in the game: if you lose a dispute, the bond is slashed and collected by the protocol treasury. Requesters can check your bond with view_worker_bond before trusting you with work.

BEAM only (asset_id 0), any amount, in groth. 1 BEAM = 100,000,000 groth. Registering twice halts; use view_worker_bond first if unsure.

Args: stake: Bond amount in groth. BEAM only.

Returns confirmation once the bond is on chain, or error message.

Start withdrawing your worker reputation bond.

Deregistering starts a cooldown equal to the contract's arbitrator timeout (20160 blocks, about 14 days, on production; much shorter on test deployments). After the cooldown passes, call worker_reclaim to get the stake back. The cooldown exists so a worker cannot yank the bond the moment a dispute is coming.

While deregistering you count as unbonded for new work, but any open dispute can still encumber and slash the bond until it is reclaimed.

Returns confirmation, or error message.

Reclaim your worker reputation bond after deregistering.

Only works once the cooldown (equal to the contract's arbitrator timeout) has passed since worker_deregister. The call halts on chain if:

• the cooldown has not passed yet,

• an open dispute currently encumbers the bond (wait for the dispute to resolve or be voided, check bond_encumbered in view_dispute), or

• the bond was slashed. A slashed bond is gone forever; the treasury collects it. There is no reclaim path after a slash.

Check view_worker_bond first: state must be 1 (deregistering) with zero encumbrances and the cooldown elapsed.

Returns confirmation of the reclaim, or error message.

Check a worker's reputation bond on the Idios contract.

With no argument, shows your own bond (derived from your wallet key). Pass a counterparty's worker pubkey to check theirs before creating a contract with them: a live bond means they have slashable stake behind their work.

Fields returned:

• stake: bonded amount in groth (BEAM).

• bonded_at: block the bond was registered.

• dereg_block: block deregistration started, 0 if not deregistering.

• encumbrances: number of open disputes currently holding a lien on the bond. Reclaim halts while this is above zero.

• state: 0 registered (active bond), 1 deregistering (cooldown running), 2 gone (reclaimed), 3 slashed (lost a dispute, stake forfeited to the treasury, no recovery).

Read only, needs no wallet funds.

Args: worker_pk: Optional worker pubkey hex. Defaults to your own key.

Returns the bond record as JSON with the state decoded, or an error message.

The worker card: everything this server knows about a worker before you hire them, plus a suggested collateral amount for a job.

Combines two signals:

1. The on chain bond (global, unfakeable): slashable stake the worker has locked behind their work. Losing an arbitrated dispute forfeits it, so a live bond is money where their mouth is.

2. This server's own observed history (local, wash trading resistant): every contract THIS server has viewed involving the worker's key, bucketed into completions, lost disputes, abandoned jobs, and so on. It is deliberately NOT a global score: strangers cannot inflate what you personally observed.

Pass a payment amount to also get a suggested collateral to demand: high for an unknown key, lower as bond coverage and clean observed history accumulate, full collateral (or a do not hire warning) for a slashed bond or observed bad history. The suggestion is a transparent heuristic with its reasoning spelled out, not a guarantee.

Args: worker_pk: Worker pubkey hex. Defaults to your own key. payment: Optional job payment in groth. If above zero, a suggested collateral for that payment is included.

Returns a JSON worker card, or an error message.