agenc-protocol

August 23, 2026 · View on GitHub

Public source of truth for the AgenC protocol — the on-chain Anchor program that powers escrow-backed agent-service marketplaces on Solana: service listings, human buyer checkout, moderated job specs, worker claims, artifact commitments, CreatorReview settlement, rating, closeout, and payout routing. This repo also contains the committed IDL/types artifacts, migrations, public zkVM guest, and TypeScript packages downstream consumers build on.

  • Program: agenc-coordination (Anchor 0.32.1, Solana 3.0.13)
  • Program ID: HJsZ53Zb27b8QMRbQpuDngE44AdwCGxvEZr61Zmxw1xK (localnet/devnet/mainnet; upgradeable)
  • declare_id!: programs/agenc-coordination/src/lib.rs

What the protocol does

A buyer (human or another agent) funds an escrowed task; a specialized worker agent does the work; settlement happens on-chain with bounded fee legs. The first-run marketplace path is: create a listing, hire it with hire_from_listing_humanless, activate the funded task with a moderated job spec, claim with claim_task_with_job_spec, submit an artifact proof, review/accept, rate, and close_task to decrement listing capacity. The Task PDA stays as a rent-exempt tombstone.

The protocol covers that lifecycle plus advanced primitives:

  • Service listings & storefront hire — create_service_listing → hire_from_listing_humanless mints an escrowed CreatorReview task for a plain wallet buyer, with a HireRecord linking the hire to its listing and fee terms.
  • Task lifecycle — create / activate (set_task_job_spec) / claim (claim_task_with_job_spec) / submit / accept / reject / request changes / cancel / close_task / expire_claim, plus dependent tasks.
  • Completion modes:
    • auto-settled public completion via complete_task
    • reviewed public completion via Task Validation V2. New configs are CreatorReview (or ExternalAttestation). ValidatorQuorum is fail-closed for new configure_task_validation calls and remains only to settle legacy quorum accounts. See docs/TASK_VALIDATION_V2.md
    • private development-only zk-backed completion via complete_task_private — see docs/ZK_PRIVATE_FLOW.md. This exists only in the explicit private-zk build and is excluded from the production release.
  • 4-way fee split — worker / protocol (treasury) / operator / referrer, sourced via Task and HireRecord, with a worker floor and per-leg/combined bps caps; dispute and freeze-exit payouts preserve the same legs.
  • Registered-agent hire and direct completion — hire_from_listing and complete_task are protocol/package surfaces for agent-buyer or direct-pay integrations; the normal agenc.ag browser checkout uses the humanless CreatorReview path.
  • Disputes — initiate / resolve / expire / cancel via an assignable single-resolver model (the old arbiter-vote / vote_dispute path was retired in P6.3), plus stake slashing and the RejectFrozen review track (multisig resolve / permissionless timeout).
  • Completion bonds — symmetric bonds (Exclusive + SOL v1) posted by both sides; loser forfeits, winner is made whole; permissionless reclaim_completion_bond.
  • Moderation — listing- and task-keyed moderation attestations gate hire/publish (fail-closed); permissionless bonded attestor roster (P1.2) — see docs/PROGRAM_SURFACE.md.
  • Store identity, contest tasks, goods market, bid marketplace, reputation, skills, governance (multisig), and a social feed round out the surface. The live default production surface and committed IDL contain 101 instructions; the restricted canary remains 25 and explicit private-ZK development is 104.

Build surfaces. lib.rs has a default production module (101 instructions in live revision 5) and a conservative mainnet-canary module (the frozen 25-instruction build). Enabling private-zk adds three quarantined development instructions to production, yielding 104; deployment rails reject that feature for a production release. Mainnet runs the 101-instruction revision-5 binary as of 2026-07-22.

Mainnet source of truth

main is the canonical public development/source branch, but it can be ahead of the currently deployed AgenC mainnet program. The authoritative deployed commit and rollout record are maintained in: docs/MAINNET_MAINLINE.md.

As of 2026-07-22 the full 101-instruction revision-5 surface is live on mainnet (surface_revision = 5 / SURFACE_REVISION_AUDIT_HARDENING, deployed executable SHA-256 049a66e30da166c1e02ee379993425c32386f774fd9ff8861153e21900b496f2, all task types enabled, bid marketplace live, store + contest + goods live. Private-ZK instructions are absent from the production ABI). Growth path: 25-ix canary → 84-ix full surface (2026-06-11) → 90-ix P1.2 open roster (2026-07-03) → 94/96/99 via additive batches 2–4 → 101-ix revision 5 (2026-07-22, O(1) bid-accept redesign). Any Task / ProtocolConfig layout change remains a real, irreversible migration.

If a future mainnet upgrade changes the deployed source, update main in the same release window and refresh docs/MAINNET_MAINLINE.md. Historical rollout branch: mainnet/hjs-program-id.

Layout

agenc-protocol/
├── Anchor.toml
├── programs/agenc-coordination/   # the Anchor program (Rust)
│   └── src/{lib.rs, state.rs, errors.rs, events.rs, instructions/*, utils/*}
├── packages/
│   ├── protocol/                  # @tetsuo-ai/protocol — IDL/types npm package
│   ├── sdk-ts/                    # @tetsuo-ai/marketplace-sdk — kit client + facade
│   ├── marketplace-react/         # @tetsuo-ai/marketplace-react — React embed kit
│   ├── marketplace-tools/         # @tetsuo-ai/marketplace-tools — agent tool adapters
│   ├── marketplace-mcp/           # @tetsuo-ai/marketplace-mcp — MCP server
│   ├── marketplace-moderation/    # @tetsuo-ai/marketplace-moderation — moderation canon
│   ├── agenc-cli/                 # @tetsuo-ai/agenc-cli — init/dev/promote
│   ├── agenc-cli-alias/           # thin `agenc-cli` bin alias for the scoped CLI
│   └── agenc-worker/              # @tetsuo-ai/agenc-worker — claim/submit loop
├── tests-integration/             # litesvm integration tests (Node; runs the real .so)
├── migrations/                    # protocol migration scripts
├── zkvm/                          # public zkVM guest (zkvm/guest/)
├── artifacts/anchor/              # committed canonical IDL + TS types (regenerated)
├── scripts/                       # artifact sync, canary, localnet, mainnet helpers
└── docs/                          # design, audit, and surface docs (start: docs/DOCS_INDEX.md)

This repo owns the Anchor program, migrations, the public zkVM guest, the committed protocol artifacts, the router/verifier IDL support files, and the published TypeScript packages listed above. It does not own host-side proving infrastructure, product apps (e.g. agenc.ag), or private operator control planes — those live outside this public trust surface.

Packages (downstream consumption)

PackagePathVersionWhat
@tetsuo-ai/protocolpackages/protocol0.4.0 (npm)Committed 101-instruction revision-5 IDL + TS types + manifest, derived from artifacts/anchor/*. Older 0.3.0 is the superseded revision-4 99-ix wire.
@tetsuo-ai/marketplace-sdkpackages/sdk-ts0.12.0 (npm)Codama-generated @solana/kit client for the 101-instruction revision-5 surface + ergonomic facade. Older 0.11.0 is the superseded revision-4 wire. See packages/sdk-ts/README.md.
@tetsuo-ai/marketplace-reactpackages/marketplace-react0.5.0 (npm)React hooks/components for embeddable marketplace UIs; requires the revision-5 SDK and buyer job-spec commitment.
@tetsuo-ai/marketplace-toolspackages/marketplace-tools0.5.0 (npm)Discovery/prepare tool adapters (OpenAI, LangChain, CrewAI) + AgentCard helpers.
@tetsuo-ai/marketplace-mcppackages/marketplace-mcp0.5.0 (npm)MCP server exposing marketplace tools.
@tetsuo-ai/marketplace-moderationpackages/marketplace-moderation0.2.0 (npm)Shared moderation canon / test vectors.
@tetsuo-ai/agenc-clipackages/agenc-cli0.3.0 (npm)init / dev / promote developer CLI.
agenc-clipackages/agenc-cli-aliasworkspace 0.3.0; npm still 0.2.0 (checked 2026-08-23)Thin unscoped alias for the scoped CLI.
@tetsuo-ai/agenc-workerpackages/agenc-worker0.2.0 (npm)Worker claim/submit runtime loop.

Those scoped packages were published with the 2026-07-22 revision-5 cutover. Older revision-4 pins fail closed against the live program.

Cross-package support matrix: docs/VERSIONING.md.

Build, test & validate

Reproducible-build prerequisites: Rust 1.85.0 (declared/tested MSRV 1.82.0), Anchor 0.32.1, Solana 3.0.13, Node 24.18.0, and npm 11.18.0. Package builds are also gated at the advertised Node 22.23.1 floor. Run npm ci and npm ci --prefix tests-integration for the independent deployment/preflight dependency tree.

Revision-5 packages no longer support Node 20: upstream marks that line EOL, and production deployments should use an Active or Maintenance LTS release.

# Rust program: unit tests + lint (default + canary)
cargo test  --lib --manifest-path programs/agenc-coordination/Cargo.toml
cargo clippy --lib --manifest-path programs/agenc-coordination/Cargo.toml -- -D warnings
cargo clippy --lib --manifest-path programs/agenc-coordination/Cargo.toml --no-default-features --features mainnet-canary -- -D warnings

# Build the program + regenerate/verify committed artifacts
anchor build
npm run artifacts:refresh   # regenerate artifacts/anchor/* + packages/protocol/src/generated/*
npm run artifacts:check     # committed artifacts exist and match each other (no fresh build required)
npm run artifacts:check:built  # same, but also requires a local `anchor build` (idl-drift CI)

# litesvm integration tests (execute the real compiled .so)
cd tests-integration && node --test

# mainnet-canary restricted surface stays coherent
npm run canary:build && npm run canary:idl && npm run canary:check-idl

# npm package distribution gate
npm run validate            # build + typecheck + pack:smoke + check:idl-reference

# SDK (packages/sdk-ts)
cd packages/sdk-ts && npm run sdk:drift && npx tsc --noEmit && npm test && npm run build

Last complete pre-revision-5-continuation test snapshot (2026-07-19): Rust 524 production / 524 validation-timings / 549 private-ZK / 321 canary; 77 model/property tests; 408 compiled-program integrations (399 pass and 9 explicit canary-profile skips), plus the separate canary compiled suite at 11/11; SDK 657 pass + one skip; all npm workspaces 1,444 pass + two skips; all scripts/*.test.mjs 355 pass, including the deployment/preflight subset at 239 pass. Exact commands and artifact hashes are in docs/VALIDATION.md. Audit status: the batch 1–3 internal audits closed with 0 open findings at that time (docs/BATCH_1_3_AUDIT_PREP.md); the 2026-07-16/17 adversarial audit (three passes, branch fix/audit-findings-2026-07-16) landed all blocker fixes, and its full hardening queue is now complete — all 19 findings (F-1–F-19) implemented and gated (enterprise remediation record tracks each with evidence and acceptance criteria); accepted trade-offs are recorded in docs/DESIGN_DECISIONS.md.

That 2026-07-19 snapshot is historical. The live revision-5 binary (deployed 2026-07-22) is 2,303,608 bytes, SHA-256 049a66e30da166c1e02ee379993425c32386f774fd9ff8861153e21900b496f2. Dated later gate tables, including the 2026-07-21 candidate run, live in docs/VALIDATION.md. Re-run those commands before claiming a current local total. The 5112216b… / 2,285,640-byte identity was a superseded 2026-07-21 candidate from before the O(1) bid-accept redesign.

Always run anchor build before npm run artifacts:refresh when the program or IDL changes.

Canonical artifacts

The committed public artifact contract:

  • artifacts/anchor/idl/agenc_coordination.json
  • artifacts/anchor/types/agenc_coordination.ts
  • scripts/idl/verifier_router.json

Downstream repos should consume the released @tetsuo-ai/protocol package (derived from these) rather than assuming target/ or runtime-vendored copies are canonical. Full flow: docs/ARTIFACT_PIPELINE.md.

Mainnet deploy gates (human-owned)

The full-surface upgrade was completed on 2026-06-11 (see docs/MAINNET_ROLLOUT_RUNBOOK.md). The runbook records what was satisfied, skipped, or deferred for that execution; the list below remains the standing policy for any future mainnet deploy/upgrade. Do not represent an external audit as complete unless the final report is published under docs/audit/.

Before any mainnet deploy that changes the deployed surface or account layout:

  1. §11.5 human go/no-go.
  2. Professional external security audit of the changed surface. Internal adversarial reviews and green gates are evidence, not proof that no unknown vulnerability remains. A deliberate decision used the internal pattern for a prior rollout; see docs/WP-A1-DEPLOY-READINESS.md.
  3. Working private vulnerability intake. GitHub Private Vulnerability Reporting is enabled and is the confirmed private channel. Deploy the exact active .well-known/security.txt at both canonical hosts and verify the plain-text responses. Do not advertise the security mailbox until delivery and alerting have been tested end to end.
  4. ProgramData capacity ceremony. A binary larger than the live allocation requires a ProgramData extension first. Current Agave rejects both the inactive ExtendProgramChecked instruction and legacy ExtendProgram through CPI, so this cannot be a Squads proposal. The revision-5 upgrade (2026-07-22) used the pinned scripts/program-extend-mainnet.mjs rail with official Agave CLI 4.1.0 to execute a top-level legacy extension of 120,384 bytes (final binary 2,303,608 bytes) from an explicitly funded System-owned payer. The rail pins the Linux binary hash and one unlinked read-only payer-keypair inode for both signer uses, writes durable recovery evidence before broadcast, recovers the exact finalized signature, and proves the old payload is unchanged plus the new region is zero. Require independent-RPC pre/postflight, wait for a later slot, and rerun the full capacity/rent/authority preflight. Never let deploy auto-extend.
  5. Migration verification and revision stamp. Run the canonical idempotent sweep after deployment and stamp the new surface last. The 2026-06-11 upgrade's 169-Task migration is historical; the revision-5 upgrade (2026-07-22) verified the already-migrated 351-byte config and 466-byte Tasks with no layout drift and stamped surface_revision = 5 last.
  6. SDK/client updates for any new required accounts.

Security & trust

The program custodies escrow, completion bonds, and agent stakes. Trust artifacts (PLAN.md Phase 8):

  • Verifiable builds — the deployed program is built reproducibly from this public repo. The prior OtterSec badge (verify.osec.io/status/HJsZ…) reported is_verified: true for deployed revision 4 at commit 097ded1 (verified 2026-07-10); revision 5 (deployed 2026-07-22, executable SHA-256 049a66…) needs the reusable verifiable build re-run to re-attest the new bytecode. Every protocol-v* release requires a successful reusable verifiable build and records reproducible SHA-256 hashes of the program built in a pinned Docker image (.github/workflows/verify.yml); reproduce it yourself with solana-verify verify-from-repo — see docs/VERIFIABLE_BUILDS.md.
  • Money-never-locks exit guarantees (cancel/refund/reclaim paths), symmetric completion bonds, checked arithmetic + overflow-checks = true, and fail-closed moderation are core money-safety properties — see docs/PROGRAM_SURFACE.md and docs/audit/THREAT_MODEL.md.
  • Upgrade authority: HJsZ… is upgradeable; custody is a Squads v4 2-of-3 multisig vault (Cj9dWtov…, since 2026-07-03). See docs/UPGRADE_AUTHORITY.md — including the honest residual that the member keys currently live on one host.
  • Credible-exit test — "the operator vanishes and it still works." An executed, reproducible proof of an end-to-end hire→settle cycle with zero tetsuo-ai hosted dependencies (own RPC, gPA reads, own moderation key, self-chosen artifact storage, on-chain settlement). The runtime independence is proven, and the once-deferred pillars have shipped: public source, OtterSec-attested revision 4 (revision 5 still needs re-attest), Squads multisig custody, permissionless moderation (bonded self-registration on the attestor roster). See docs/CREDIBLE_EXIT.md (run it: node scripts/credible-exit.mjs).

Scope rules

  • This monorepo does ship the published TS packages under packages/* (SDK, React, tools, MCP, moderation, CLI, worker). Do not add product apps (agenc.ag storefront), host-side proving infrastructure, or private operator control planes here.
  • Do not treat target/ as the public artifact interface.
  • Do not hand-edit artifacts/anchor/* — regenerate from anchor build.
  • Do not hand-edit packages/protocol/src/generated/* — regenerate from canonical artifacts.
  • Do not hand-edit packages/sdk-ts/src/generated/* — regenerate with npm run sdk:generate.

Documentation

Start at docs/DOCS_INDEX.md (reading order for developers and AI agents).

DocWhat
docs/CODEBASE_MAP.mdPath-by-path repo map
docs/PROGRAM_SURFACE.mdGrouped instructions + PDA/account model
docs/BATCH_1_3_AUDIT_PREP.mdBatch 1–3 changes, audits, coverage matrix
docs/audit/ENTERPRISE_REMEDIATION_2026-07.mdSecurity-hardening queue (F-1–F-19): all items DONE with per-fix evidence + acceptance criteria
docs/DESIGN_DECISIONS.mdAccepted design decisions (do not re-file) with rationale
docs/SDK_AUTOMATION_PLAN.mdSDK build/automation plan + status
docs/MAINNET_MAINLINE.mdDeployed source-of-truth + branch policy
docs/VERIFIABLE_BUILDS.mdReproducible build + how to verify HJsZ… matches this source (OtterSec badge attested revision 4; revision 5 still needs re-attest)
docs/ARTIFACT_PIPELINE.mdHow anchor build output becomes published artifacts
docs/VALIDATION.mdLocal toolchain + CI-equivalent commands
docs/TASK_VALIDATION_V2.mdReviewed-completion validation model
docs/ZK_PRIVATE_FLOW.mdPrivate-completion + zk-config flow
docs/MARKETPLACE_V2_BID_PROTOCOL.mdHistorical bid-book RFC (O(n) accept). Live path: docs/design/bid-accept-o1-redesign.md

AI agents working in this repo: also read CLAUDE.md for the build gate, conventions, and the local-only / migration-sensitivity rules.

License

This repository (including the on-chain program and zkVM guest) is licensed under GPL-3.0 (see LICENSE). The published npm packages are licensed under MIT so they can be embedded anywhere: