Project Handoff

Demo

About

Handoff is an on-chain protocol for buying human judgment. AI agents produce most professional output today — reports, filings, contract reviews — but nobody qualified has looked at it. Handoff closes that gap: a requester agent posts an order, funds lock in escrow, a credentialed human expert claims it, reviews the work, and publishes a signed attestation. Payment releases on the signature, whatever the verdict — you bought judgment, not approval, so a reject is a delivered product and gets paid. The protocol runs two separate payment rails that are never conflated. The service fee is an x402 micropayment (0.5 HBAR) settled through the Blocky402 testnet facilitator — this is the HTTP 402 gate on the handoff_verify MCP tool that any AI agent session can call. The order value (e.g. 100 HBAR) is the price of the human judgment itself, locked in a threshold-key escrow account on Hedera. Different rails, different accounts, different sizes. The lifecycle is: POSTED → CLAIMED → DELIVERED → SETTLED. Orders and claims are published as HCS messages carrying only hashes — task content and expert notes stay off-chain in a content store, with the on-chain hash as the commitment. The expert signs the attestation by submitting an HCS message from their own Hedera account — the account signature is the attestation signature, and the platform is never in the signing path. After validation, the platform co-signs a transfer from the escrow to release payment. What ships: the x402 payment gate via Blocky402, threshold-key escrow with fund lock, HCS attestation signed by the expert's own account, a full expert web app (inbox → review workspace → sign), the handoff_verify MCP tool as a published npm package (@hedera-handoff/mcp-client) that any Claude Code session or Desktop apps can install without cloning the repo, and mirror-node settlement reads with transaction IDs threaded through to Hashscan. Known limits: Certification is an allowlist this week — the issuers and the scarcity are not here, only the interface (even though we're getting certification ID during onboarding) Disputes are stubbed — a rubber-stamp attestation gets paid, with m-of-n jury as the production answer.

How it's made

ARCHITECTURE: We have monorepo for this project that has following: - Libraries in packages/ - Deployables in apps/. - packages/schema is the treaty — it owns every zod schema, the schema_version constant, canonical hashing (deterministic serialization before hashing so two implementations produce the same digest), the money module (tinybars as bigint internally, strings at every boundary, all conversion in one tested module), the ChainAdapter interface, and MockChainAdapter. Nothing else in the repo imports the Hedera SDK directly — only packages/chain does. This seam let three people build in parallel from day one: the mock satisfied the same interface the real adapter would, so the MCP tool and the expert app never waited on chain work. HEDERA (PARTNER TECHNOLOGY — THE ENTIRE SETTLEMENT LAYER): HCS carries order envelopes and attestations as hash-only messages. The escrow is a 2-of-3 threshold-key account — platform verifier, schedule admin, and a guard key — so no single key can move funds. The expert's attestation is an HCS message submitted from their own Hedera account; the account signature is the attestation signature, keeping the platform out of the signing path entirely. Consensus timestamps are the source of truth for claim priority — UIs render optimistically but defer to the mirror node. Every Hedera call surfaces its transaction ID, threaded through to the client so settlement state is read from a mirror node, never inferred from "we sent it." X402 VIA BLOCKY402 (PARTNER TECHNOLOGY — PRIZE QUALIFICATION): The handoff_verify MCP endpoint is gated by HTTP 402. The server answers with a PAYMENT-REQUIRED header stating the price; the client builds a Hedera TransferTransaction, partially signs with its own ECDSA key, and retries with the payload in a PAYMENT-SIGNATURE header. The server posts to the Blocky402 testnet facilitator's /verify — verification gates serving, settlement happens last, so an order that fails to post leaves the caller's money untouched. The fee payer is discovered from the facilitator's /supported endpoint at startup, never hard-coded, because a rotated account fails verification silently. We speak x402 version 2 and read both v1 and v2 headers through @x402/core. MCP: The MCP client is published to npm (@hedera-handoff/mcp-client), so any agent session on any machine can order from the running service with claude mcp add handoff — nothing to clone. The key never leaves the caller's machine: the client signs locally, only signatures go over the wire, and the server validates the returned bytes against what it asked for. EXPERT APP: React, Tailwind, shadcn/ui. The expert pastes their Hedera private key at connect time (main philosophy is not to store the key in the backend, but for the sake of Expert app's UX and smooth flow, we've added email sign-in that we encrypt and keep the Key in our backend. In the future, we'll add secure key management and wrapping for the users). The inbox polls the mirror node REST API for the orders topic. The review workspace shows the document alongside a verdict panel (Approve / Approve with changes / Reject), a defects editor with enforced bounds (max items and max bytes per item, matching the HCS size limit), and a notes field. Signing submits the attestation to HCS from the expert's account and triggers the co-signed payout. Notable hack: Hedera's Schedule Service cannot debit a KeyList (threshold-key) account — we hit INVALID_SIGNATURE across eight isolated testnet runs while the control (a plain co-signed transfer, same account, same keys) succeeded every time. So instead of scheduled payments, the DELIVERED state co-signs a TransferTransaction directly. The escrow still locks at POSTED and the payout is still committed at claim time, but execution is a direct co-signed transfer, not a schedule firing. TOOLING: Five MCP servers checked into .mcp.json — our own handoff tool, Hedera's hosted Agent Kit (testnet), Hedera docs search, Linear for coordination, and Context7 for live SDK docs. A hard rule: never recall a Hedera SDK call from memory, always look it up through the docs servers first. Pre-commit hook runs gitleaks — no secrets in the repo, ever. CI runs typecheck, unit tests, and gitleaks on every push.