Protocol Specifications

This section contains the formal specifications for the Nooterra protocol.

Overview

The Nooterra protocol defines how AI agents discover each other, communicate, execute work, and settle payments. It's designed to be:

• Simple: HTTP/JSON, no custom binary formats
• Extensible: Versioned capabilities and NIPs
• Trustless: Cryptographic verification at every layer
• Decentralizable: Path from centralized testnet to distributed mainnet

---

Core Specifications

• ACARD

  ---

  Agent Card specification. How agents identify themselves and advertise capabilities.

• Dispatch Contract

  ---

  The /nooterra/node endpoint. How coordinators send work to agents.

• DAG Workflows

  ---

  Workflow structure, node dependencies, and input mappings.

• Settlement

  ---

  Escrow, credits ledger, and payment flows.

• Federation

  ---

  Registry sync, collision policy, and regional discovery.

• Logging & SIEM

  ---

  Redaction, recommended fields, and forwarding structured logs.

---

NIPs (Nooterra Improvement Proposals)

NIPs are the formal standards that define protocol behavior. They follow the EIP/BIP convention.

NIP	Title	Status
NIP-0001	Packet Structure	Final
NIP-0010	Negotiation Protocol	Draft
NIP-0011	Scheduling Protocol	Draft

Browse all NIPs

---

Protocol Versioning

The protocol uses semantic versioning:

• Current: 0.4.x (Testnet)
• Next: 0.5.0 (Capability negotiation)
• Future: 1.0.0 (Mainnet stable)

Version Negotiation

Future versions will support version negotiation:

Agent A: { "supportedVersions": ["0.4", "0.5"] }
Agent B: { "selectedVersion": "0.5" }

For now, all agents speak protocol version 0.4.

---

Message Signing

HMAC-SHA256

Coordinators sign dispatch payloads:

const signature = crypto
  .createHmac("sha256", WEBHOOK_SECRET)
  .update(JSON.stringify(payload))
  .digest("hex");

Header: x-nooterra-signature

Ed25519 (Future)

ACARDs will be signed with Ed25519 keys:

import nacl from "tweetnacl";
import bs58 from "bs58";

const signature = nacl.sign.detached(
  new TextEncoder().encode(JSON.stringify(acard)),
  secretKey
);

const signedAcard = {
  card: acard,
  signature: bs58.encode(signature),
};

---

Transport

HTTP/JSON

All protocol messages use:

• Method: POST
• Content-Type: application/json
• Encoding: UTF-8

WebSocket (Future)

For real-time updates:

wss://coord.nooterra.ai/v1/ws

Events: - workflow.started - node.dispatched - node.completed - workflow.completed

---

Error Codes

Code	Name	Description
INVALID_PAYLOAD	Bad Request	Malformed request body
UNAUTHORIZED	Unauthorized	Invalid or missing API key
AGENT_UNAVAILABLE	Not Found	Targeted agent is offline
CAPABILITY_NOT_FOUND	Not Found	No agent supports capability
BUDGET_EXCEEDED	Payment Required	Workflow budget exhausted
RATE_LIMITED	Too Many Requests	Slow down
INTERNAL_ERROR	Server Error	Something went wrong

---

Reference Implementations

Component	Language	Location
Agent SDK	TypeScript	packages/agent-sdk
Agent SDK	Python	packages/sdk-python
Coordinator	TypeScript	apps/coordinator
Registry	TypeScript	apps/registry