Protocol Codebase Map

August 23, 2026 · View on GitHub

This file maps the full agenc-protocol repo for developers and AI agents.

Top-Level Layout

agenc-protocol/
  programs/agenc-coordination/   Anchor source (101 prod / 104 private-ZK / 25 canary)
  artifacts/anchor/              committed canonical IDL, types, and manifest
  packages/
    protocol/                    @tetsuo-ai/protocol — published IDL/types
    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
    agenc-worker/                @tetsuo-ai/agenc-worker — claim/submit loop
  tests-integration/             litesvm integration tests (real .so)
  migrations/                    migration notes and helpers
  scripts/                       artifact sync, canary, localnet, mainnet, readiness
  zkvm/guest/                    public zkVM journal helper crate
  docs/                          repo-level developer docs (start: DOCS_INDEX.md)
  .github/workflows/             CI automation
  README.md
  package.json
  Anchor.toml

Path Ownership

Program surface

  • programs/agenc-coordination/src/lib.rs - instruction entrypoints (full + canary modules)
  • programs/agenc-coordination/src/state.rs - PDA/account model and version constants
  • programs/agenc-coordination/src/events.rs - emitted events
  • programs/agenc-coordination/src/errors.rs - protocol error codes
  • programs/agenc-coordination/src/instructions/ - instruction handlers and helpers
  • programs/agenc-coordination/src/utils/ - shared utilities
  • programs/agenc-coordination/fuzz/ - active model/property regression harness (77 tests)

Canonical artifacts

  • artifacts/anchor/idl/agenc_coordination.json (101 production instructions)
  • artifacts/anchor/types/agenc_coordination.ts
  • artifacts/anchor/manifest.json
  • scripts/idl/verifier_router.json
  • Generated human reference: docs/reference/INSTRUCTIONS.md, docs/reference/ERRORS.md

Published packages

PackagePathRole
@tetsuo-ai/protocolpackages/protocolIDL + types npm contract
@tetsuo-ai/marketplace-sdkpackages/sdk-tsCodama client + facade + indexer
@tetsuo-ai/marketplace-reactpackages/marketplace-reactReact hooks/components
@tetsuo-ai/marketplace-toolspackages/marketplace-toolsprepare/discovery + AgentCard
@tetsuo-ai/marketplace-mcppackages/marketplace-mcpMCP tool server
@tetsuo-ai/marketplace-moderationpackages/marketplace-moderationmoderation canon
@tetsuo-ai/agenc-clipackages/agenc-clideveloper CLI
agenc-cli (alias)packages/agenc-cli-aliasnpx agenc alias
@tetsuo-ai/agenc-workerpackages/agenc-workerworker runtime

Support matrix: VERSIONING.md.

Migration and zk surfaces

  • migrations/ - migration notes and helpers (live layout migrations live in programs/.../instructions/migrate.rs)
  • zkvm/guest/src/lib.rs - canonical journal field layout for private completion

Automation (selected)

  • scripts/sync-anchor-artifacts.mjs - target/ → committed artifact sync
  • scripts/sync-package-protocol-assets.mjs - committed artifacts → protocol package
  • scripts/generate-idl-reference.mjs / check-idl-reference.mjs - docs drift gate
  • scripts/localnet-up.mjs / localnet-down.mjs / localnet-status.mjs
  • scripts/mainnet-*.mjs / scripts/credible-exit.mjs
  • scripts/marketplace-devnet-*.mjs / validation-*.mjs
  • packages/sdk-ts scripts: sdk:generate, sdk:drift, testing-asset sync
  • .github/workflows/ci.yml - formatting, clippy, cargo tests, artifact existence check, protocol pack, check:idl-reference
  • .github/workflows/sdk.yml - SDK drift / tests / LiteSVM e2e
  • .github/workflows/idl-drift.yml - built-artifact compare (artifacts:check:built) and canary IDL freeze
  • .github/workflows/verify.yml - reusable verifiable build; release.yml calls it on protocol-v* tags
  • other workflows in .github/workflows/: compatibility.yml, coverage.yml, react-fixtures.yml, release.yml, rust-supply-chain.yml, sandbox-nightly.yml, supply-chain.yml

Ownership Boundaries

  • This repo owns the public protocol source of truth and the published marketplace TypeScript packages listed above.
  • Product apps (agenc.ag storefront, hosted control planes) and host-side proving infrastructure (agenc-prover) live outside this repo.
  • Historical sibling names (agenc-sdk, agenc-core) may still appear in older plans; the monorepo packages under packages/* are the current consumer surface.

Start Here By Change Type