ADR 11: Developer Tooling Integration Surface and Agent Onboarding

Changelog

• 2026-05-12: Initial draft

Status

DRAFT

Dependencies

• ADR-1: Standard Template and Design Guidelines — this ADR follows the format defined in ADR-1
• ADR-3: Agent Participation Expectations — agents integrating with Terp must follow the four principles defined in ADR-3
• ADR-4: Sovereign Custody & Authentication — agent authentication uses smart account authenticators defined in ADR-4
• ADR-5: HashMerchant — agents querying external chain data use HashMerchant interfaces
• ADR-9: LM-Augmented Development and Semantic Tooling — QMD, Trailmark, and TensorZero pipeline available to agents
• ADR-10: Community Working Groups — agents coordinate with relevant working groups per ADR-10 structure

Abstract

This ADR defines the complete integration surface for external agents, developers, and automated systems to interact with Terp Network. It specifies two layers: the technical surface (what APIs, client libraries, CLI tools, contract interfaces, and generated type packages exist) and the integration workflow (how a new agent or developer discovers these surfaces, authenticates, and begins contributing effectively). The schema-driven type generation pipeline — cargo schema -> ts-cosmwasm-codegen -> zod objects -> proto format -> go-package, rust crate types -> python binding types -> md table — ensures that every integration surface is derived from a single canonical source, maintaining consistency across all language targets. This ADR serves as the entry point for any system that needs to make effective contact with Terp Network.

Context and Problem Statement

Terp Network exposes a complex software surface: a Cosmos SDK chain with gRPC/REST endpoints, CosmWasm smart contracts with JSON-based execute/query interfaces, a CLI tool (o-line) for deployment orchestration, semantic search (QMD) for knowledge retrieval, and code graph analysis (Trailmark) for architectural understanding. Each of these surfaces has its own authentication model, data format, and interaction pattern.

For a new agent or developer, the questions are:

1. What exists? What APIs, contracts, and tools are available?
2. How do I authenticate? How do I prove identity and authorization?
3. What types do I use? How do I get type-safe access in my preferred language?
4. How do I discover context? How do I understand the codebase and protocol without reading every file?
5. How do I contribute? What is the path from first contact to productive contribution?

Without a defined integration surface and onboarding workflow, each agent must reverse-engineer these answers independently, leading to inconsistent integrations, stale type definitions, and duplicated discovery effort.

Decision Drivers

• Single source of truth: all client types must derive from the canonical schema, not manual definitions
• Language parity: agents should have equally capable client libraries in TypeScript, Go, Rust, and Python
• Discoverability: the integration surface must be self-documenting — an agent should be able to enumerate available interfaces programmatically
• Authentication consistency: all surfaces should use the same authentication model (ADR-4 smart accounts)
• Minimal friction: onboarding a new agent should take minutes, not days
• Reproducibility: any agent should be able to reproduce the type generation pipeline from source

Considered Options / Alternatives

• Ad-hoc integrations per agent: each agent discovers and wraps APIs independently. No shared types, no consistency. Fast to start but diverges quickly.
• Centralized SDK with auto-generated clients: single maintained SDK that all agents consume. Consistent but creates a maintenance bottleneck and coupling.
• Schema-driven pipeline with per-language outputs (selected): one canonical schema (from cargo schema) feeds a generation pipeline that produces type-safe packages in each target language. Agents consume the generated packages. Consistent types, no coupling to a single SDK implementation, and the pipeline is reproducible.

Decision Outcome

We adopt the schema-driven pipeline as the standard integration method. The pipeline has two tracks: the type generation track (producing client packages) and the discovery track (providing context and onboarding).

Track 1: Type Generation Pipeline

All CosmWasm contract types and Cosmos SDK module types are generated from a single canonical source:

cargo schema
    │
    ▼
JSON Schema files (*.json)
    │
    ├─► ts-cosmwasm-codegen ─► TypeScript client + zod validators
    │
    ├─► proto format ─► .proto files
    │       │
    │       ├─► go-package (cosmos-sdk-go proto generation)
    │       │
    │       ├─► rust crate types (prost-build)
    │       │
    │       └─► python binding types (betterproto)
    │
    └─► md table ─► human-readable API reference in docs

Step 1: cargo schema

Each CosmWasm contract exposes a schema command that generates JSON Schema files for its instantiate, execute, query, and sudo messages. These schemas are the canonical type definitions.

# Generate schemas from contract source
cd contracts/cw-infuser && cargo schema
cd contracts/cw-shitstrap && cargo schema
cd contracts/terp721-account && cargo schema

Step 2: ts-cosmwasm-codegen

The JSON schemas are consumed by @cosmwasm/ts-codegen to produce TypeScript client classes with full type safety and zod runtime validators.

# Generate TypeScript clients
cosmwasm-ts-codegen generate \
  --schema ./schemas \
  --out ./ts-clients \
  --name terp-contracts

Outputs:

• ts-clients/cw-infuser/CwInfuserClient.ts — execute and query methods
• ts-clients/cw-shitstrap/CwShitstrapClient.ts — execute and query methods
• ts-clients/terp721-account/Terp721AccountClient.ts — execute and query methods
• ts-clients/index.ts — barrel export
• Zod validators for each message type (runtime validation)

Step 3: proto format

Cosmos SDK module types are defined as Protocol Buffer messages. The cargo schema JSON is transformed into .proto definitions for chain-level modules.

# Generate proto definitions from schema
schema-to-proto --input ./schemas --output ./proto/terp

Step 4: per-language package generation

From the .proto files:

• Go: buf generate with buf.gen.yaml → Go module with gRPC client stubs
• Rust: prost-build → Rust crate with proto-derived types and client
• Python: betterproto → Python package with async gRPC client

# Go package
buf generate --template buf.gen.yaml ./proto

# Rust crate
cargo build --features proto-gen

# Python bindings
python -m betterproto ./proto --output ./python-clients/terp

Step 5: md table generation

A final step produces human-readable markdown tables documenting every message type, field, and type annotation. These tables are ingested into the Terp documentation site.

schema-to-md --input ./schemas --output ./docs/api-reference.md

Track 2: Discovery and Onboarding

An agent or developer entering the Terp Network ecosystem follows this workflow:

Phase 1: Authenticate

1. Generate or import a keypair using the o-line CLI or Keplr wallet
2. Register a Terp Account name via the Billboard minter (tabs.html)
3. The account is now a smart account (ADR-4) with configurable authenticators
4. For automated agents: use the o-line CLI to configure key material non-interactively

# Agent onboarding via o-line CLI
oline keys add agent-key --from-mnemonic "your mnemonic"
oline tx register-name agent-name --from agent-key

Phase 2: Discover the Surface

The integration surface is enumerated through three discovery mechanisms:

1. Contract registry: oline query wasm list-contract-by-code <code-id> lists all deployed contract instances
2. Schema endpoint: each CosmWasm contract exposes a /schema query returning its JSON Schema definitions
3. QMD search: oline-qmd search 'smart account authentication' -c abstract returns relevant ADRs, module specs, and source files

For programmatic discovery, the terp-actions.json manifest at terp.network/public/terp-actions.json lists all known contract addresses, code IDs, and their associated schema URIs.

Phase 3: Obtain Typed Access

# Pull latest generated types
npm install @terp/ts-clients    # TypeScript
go get github.com/terpnetwork/terp-go  # Go
pip install terp-py             # Python
cargo add terp-proto            # Rust

Each package provides:

• Typed execute/query methods for all CosmWasm contracts
• gRPC client stubs for all Cosmos SDK modules
• Zod/validator runtime checks (TypeScript/Python)
• Full JSDoc/docstring documentation from schema annotations

Phase 4: Contextual Understanding

Before contributing, an agent should ingest the Terp codebase into its semantic context:

1. Trailmark: build a code graph of the relevant repository
2. QMD: ingest the graph + source into a semantic collection
3. Query: use QMD to surface architectural context relevant to the task

This follows the workflow defined in ADR-9, Section "Adding a new project to the pipeline."

Phase 5: Contribute

Follow ADR-3 participation expectations:

• Use TensorZero for LM-assisted contributions (transparency principle)
• Submit PRs with ADR references and TensorZero episode metadata
• Apply the same quality gates as human contributions

Integration Surface Inventory

The following table enumerates every integration surface currently available:

Adding a New Integration Surface

When a new contract, module, or API is added to Terp Network:

1. Run cargo schema on the new contract to generate JSON Schema
2. Add the schema to the ts-cosmwasm-codegen configuration
3. Regenerate all language packages (just gen-types)
4. Add the new surface to the Integration Surface Inventory table in this ADR
5. If the surface requires authentication, document the authentication method referencing ADR-4
6. Update terp-actions.json with the new contract address and schema URI
7. Ingest the new contract source into the appropriate QMD collection

Consequences

Positive

• Single canonical schema ensures type consistency across all language targets
• Agents can onboard in minutes: authenticate, discover, pull types, contribute
• Schema-driven pipeline is fully reproducible — any agent can regenerate types from source
• QMD and Trailmark provide semantic context that raw API docs cannot
• The inventory table gives agents a single place to discover all available surfaces

Negative

• Schema pipeline maintenance: changes to cargo schema output format require updates to all generators
• Language parity is aspirational — TypeScript and Go will likely be the most complete; Python and Rust may lag
• The onboarding workflow assumes local QMD/Trailmark setup, which has an initial cost (per ADR-9 negative consequences)

Neutral / Trade-offs

• The pipeline is linear (schema → types) — there is no automated reverse path from a type change back to a schema amendment
• Contract addresses in terp-actions.json are per-chain — testnet and mainnet addresses differ, and the manifest must be chain-aware
• The discovery mechanisms (contract registry, schema endpoint, QMD) serve different audiences — agents may prefer QMD, while traditional developers may prefer the contract registry

Backwards Compatibility

Fully additive. No existing code, contracts, or on-chain behavior changes. Existing integrations continue to work. This ADR defines a standard and workflow — adopting it is optional but recommended for new integrations.

Test Cases

• Verify cargo schema in cw-infuser produces valid JSON Schema for InstantiateMsg, ExecuteMsg, and QueryMsg
• Verify ts-cosmwasm-codegen produces TypeScript clients that compile without errors
• Verify proto-generated Go package compiles and the gRPC client can connect to a testnet node
• Verify oline-qmd search 'smart account' -c abstract returns ADR-4 and related module specs
• Verify terp-actions.json lists all deployed contract addresses for the current chain ID
• Verify a new agent can authenticate, discover the surface, and execute a query within 30 minutes of starting
• Verify the Integration Surface Inventory table includes entries for all surfaces listed in the inventory section

Further Discussions / Open Questions

• Should we publish generated type packages to npm/PyPI/crates.io automatically on contract deployment?
• How to handle schema versioning when a contract is migrated to a new code ID?
• Should the terp-actions.json manifest include ABI-like documentation beyond addresses?
• What is the minimum QMD collection set required for effective agent onboarding?
• Should there be a "Terp SDK" meta-package that bundles all language targets plus CLI tools?

References

• ADR-1: Standard Template and Design Guidelines
• ADR-3: Agent, LLM, and Automation Participation Expectations
• ADR-4: Sovereign Custody & Authentication Specifications
• ADR-5: HashMerchant — Verifiable Merkle Reflection Market
• ADR-9: LM-Augmented Development and Semantic Tooling
• ADR-10: Community Working Groups and Resource Coordination
• @cosmwasm/ts-codegen: https://github.com/CosmWasm/ts-codegen
• Cosmos SDK proto generation: https://docs.cosmos.network/main/building-modules/proto-messages
• Protocol Buffers: https://protobuf.dev
• o-line CLI: ~/.cargo/bin/oline
• QMD wrapper: ~/.oline/scripts/oline-qmd
• Project knowledge graph workflow: ~/daily-driver/daily-driver/terp/project-knowledge-graph-creation -workflow.md