idios

# Idios

**Private escrow and settlement for AI and other compute on Beam.**

Pay for AI and compute work privately. Verifiable delivery, escrowed payment, on chain dispute resolution. No public record of amounts or parties.

**[Website](https://honeytones.github.io/idios-site/)** · **[AI and compute use cases](https://honeytones.github.io/idios-site/private-ai-escrow.html)** · **[Latest Release](https://github.com/honeytones/idios/releases/latest)** · **[Live Explorer](https://explorer.0xmx.net/?network=mainnet&type=contract&id=41ef8be50f0d727a919b5f5e64f7e66d5ec04442bb4f536f664e38b765e4921f)**

[![idios MCP server](https://glama.ai/mcp/servers/honeytones/idios/badges/score.svg)](https://glama.ai/mcp/servers/honeytones/idios)

> "Pay privately. Verify on chain. Dispute when needed."

---

## Demo

An AI agent takes a job, privately subcontracts two parts to other agents, reviews and pays each, then settles with the client, all on Beam mainnet with amounts and parties hidden the whole way.

[![asciicast](https://asciinema.org/a/3LjY52dHpejWZT0F.svg)](https://asciinema.org/a/3LjY52dHpejWZT0F)

---

## Why

Public payment rails leak. Every contract, every payment, every counterparty becomes part of a permanent searchable record. For AI inference, model training, scientific compute, work that involves proprietary inputs, private data, or competitive operations, that visibility is a dealbreaker.

Idios solves the payment and settlement privacy problem. Payment is locked in private escrow on [Beam](https://beam.mw). The worker locks collateral. Settlement happens on chain with full privacy of amounts and parties. Beam's MimbleWimble protocol hides amounts and identities at the base layer. Idios is what you get when you build escrow on that foundation.

ERC-8183 standardises the same starting primitive on Ethereum, a Job with escrowed payment for AI agent work. Idios is a separate and more complete protocol on Beam, not a port of it. It adds worker collateral and working dispute resolution, neither of which ERC-8183 has today, and it settles privately with amounts and parties hidden. Idios uses its own roles: Requester, Worker, and Arbitrator.

---

## How it works

Two settlement modes, picked per contract at creation time.

### Hash verified Settlement (Mode A)

For deterministic work where the correct output is a specific hash known in advance.

1. Requester locks payment, declares the expected result hash.
2. Worker locks collateral.
3. Worker delivers work and submits the result hash on chain.
4. If hashes match, the contract atomically releases payment plus collateral to the worker. Done.

No arbitrator involvement. Settlement is mechanical once hashes match.

### Reviewed Settlement (Mode B)

For non deterministic or open ended work where the requester needs to review the output.

1. Requester locks payment, sets a review window and dispute fee.
2. Worker locks collateral.
3. Worker delivers work (uploaded out of band or via IPFS, hash recorded on chain).
4. Requester reviews the work and either:
   - **Approves**, allowing the worker to claim payment + collateral.
   - **Disputes**, locking the dispute fee and pushing the case to arbitration.
   - **Does nothing** until the review window expires, after which the worker can claim payment + collateral via timeout.
5. If disputed, the M of N arbitrator registry resolves to either party by voting. The winner claims payment + collateral. The dispute fee pays the consensus voting arbitrators, never the winner.

Funds always flow to the right party. Arbitrators decide who wins a dispute and earn the dispute fee for the work of judging it, but never touch the payment or collateral.

### Two phase claim

Idios uses a two phase claim pattern. Authorisation steps (approve, claim_after_timeout, and dispute resolution by M of N voting) set the contract status but never move funds. The beneficiary then calls `claim` to actually receive the payout, signed by their own key. This works around a Beam BVM constraint where a single kernel cannot cleanly sign for one party while routing funds to another.

---

## Status

**Live on Beam mainnet** ✅

- v2 contract (Upgradable3, in place upgrades) on cid 41ef8be5. Originally deployed as v6 at block 3905992 (15 June 2026), upgraded in place to M of N v1 at block 3914637 (21 June 2026), upgraded in place again to v2 at block 3938963 (8 July 2026)
- M of N arbitration live: global arbitrator registry, voting based dispute resolution (N is 1 today). Registration hardened in v2: BEAM only, 10 BEAM minimum stake, admin co signed
- Worker reputation bonds live (v2): a worker can lock a standing slashable bond; losing an arbitrated dispute slashes it to the treasury
- Mode A end to end plus all four Mode B resolution paths verified end to end with real funds, and the full v2 slash lifecycle (bond, encumbrance, slash, treasury sweep) proven on mainnet before the production upgrade
- Dapp 3.3.0 published, supports both modes via UI

**Verified resolution paths (real funds on mainnet during development; the job IDs below are from the v5 and v6 deployments that preceded the in place M of N upgrade):**

| Path | Status flow | Job |
|------|-------------|-----|
| Mode A hash match | Open → Active → Closed (single tx) | 22224 |
| Mode B approve | Open → Active → AwaitingApproval → Settled → Closed | 11112, 33335 |
| Mode B dispute, resolved to worker | Open → Active → AwaitingApproval → Disputed → ResolvedToBob | 11113 |
| Mode B dispute, resolved to requester | Open → Active → AwaitingApproval → Disputed → ResolvedToAlice | 11114 |
| Mode B timeout | Open → Active → AwaitingApproval → Settled → Closed | 11115 |
| Mode B arbitrator timeout void | Open → Active → AwaitingApproval → Disputed → Voided | 20002 |

---

## Contract

```
CID: 41ef8be50f0d727a919b5f5e64f7e66d5ec04442bb4f536f664e38b765e4921f
Current version: v2 (SID a61f3a93), upgraded in place from M of N v1 on 8 July 2026 at block 3938963
Version history: v6 (deploy) -> M of N v1 (21 June 2026, block 3914637) -> v2 (8 July 2026, block 3938963); cid unchanged throughout
Deployed at block: 3905992 (original v6 deploy; cid unchanged across all Upgradable3 upgrades)
Constructor params: default_review_window=10080, arbitrator_timeout_blocks=20160, upgrade_delay=1440, min_approvers=1
Explorer: https://explorer.0xmx.net/?network=mainnet&type=contract&id=41ef8be50f0d727a919b5f5e64f7e66d5ec04442bb4f536f664e38b765e4921f
```

### Roles

| Role | Description |
|------|-------------|
| `user` | Requester (Alice) or worker (Bob) interacting with the contract lifecycle. Workers can also hold a reputation bond (v2). |
| `arbitrator` | Member of the M of N arbitrator registry. Registers with a stake (BEAM only, 10 BEAM minimum, admin co signed in v2), votes on disputed contracts, and claims a reward share |
| `manager` | Deploy and view contract params (one shot, used during contract setup) |
| `treasury` | Protocol treasury, set at deploy from the deploying wallet. Collects forfeited worker collateral from Active refunds, dispute fees from voided disputes, and slashed worker bonds (v2) via `sweep` and `slash_sweep`. |

### Actions per role

**user actions**

| Action | Description |
|--------|-------------|
| `create_a` | Create a Mode A contract (Hash verified Settlement). Locks payment. |
| `create_b` | Create a Mode B contract (Reviewed Settlement). Locks payment, sets review window and dispute fee. |
| `commit` | Worker locks collateral, status moves to Active. |
| `submit_delivery` | Worker submits result hash. In Mode A, pays out atomically if the hash matches and the contract moves straight to Closed. In Mode B, sets AwaitingApproval. |
| `approve` | Requester approves Mode B delivery, status moves to Settled (no funds yet). |
| `dispute` | Requester disputes Mode B delivery, locks dispute fee, status moves to Disputed. |
| `claim_after_timeout` | Worker claims after review window expires (Mode B), status moves to Settled. |
| `claim` | Beneficiary collects funds (payment + collateral) from a Settled, ResolvedToBob, or ResolvedToAlice contract. A Settled claim moves the status to Closed. A Resolved contract keeps its 6/7 status forever; the `winner_paid` flag in `view_dispute` records the payout. Mode A contracts pay out automatically and cannot be claimed. |
| `refund` | Requester reclaims their payment from an expired contract (Open or Active). On the Active path the worker's collateral is forfeited to the treasury. Status moves to Refunded. |
| `void_dispute` | Permissionless. Anyone can void a dispute the arbitrator never resolved, once `arbitrator_timeout_blocks` have passed since it was filed. Status moves to Voided. |
| `void_claim_requester` | Requester reclaims their payment from a Voided contract. |
| `void_claim_node` | Worker reclaims their collateral from a Voided contract. |
| `view_job` | Read current job state. |
| `view_dispute` | Read the M of N dispute record for a job: frozen N and threshold, tallies, resolution, and whether the worker's bond is encumbered by it (v2). |
| `worker_register` | Lock a standing reputation bond (v2). BEAM only, any amount, keyed to the worker's contract pubkey. Slashable: losing an arbitrated dispute forfeits the whole bond to the treasury. |
| `worker_deregister` | Begin withdrawing the reputation bond. Starts the reclaim cooldown. |
| `worker_reclaim` | Recover the bond in full after the cooldown (= `arbitrator_timeout_blocks`). Halts while any open dispute encumbers the bond, and forever if the bond was slashed. |
| `view_worker_bond` | Read a worker bond: stake, state, encumbrance count. Defaults to your own key; pass `worker_pk` to inspect another worker's bond. |
| `get_key` | Returns the user's pubkey for this contract. (Worker shares this with requester before create.) |

**arbitrator actions** (M of N, v2 hardened registry)

| Action | Description |
|--------|-------------|
| `register` | Join the global arbitrator registry, posting a `s