NIP-0001: Packet Structure

Abstract

This NIP defines the standard HTTP contract for dispatching work to Nooterra agents. All conforming agents MUST implement the /nooterra/node endpoint as specified herein.

Motivation

For a decentralized agent network to function, all participants must speak the same language. This specification defines:

1. The endpoint path and method
2. Request/response payload structure
3. Authentication via HMAC signatures
4. Targeted routing with fallback semantics
5. Error codes and handling

Specification

Endpoint

POST /nooterra/node
Content-Type: application/json

Request Headers

Header	Required	Description
Content-Type	Yes	Must be application/json
x-nooterra-event	Yes	Event type, e.g., node.dispatch
x-nooterra-event-id	Yes	Unique event identifier (UUID)
x-nooterra-workflow-id	No	Parent workflow identifier
x-nooterra-node-id	No	Node name within the workflow DAG
x-nooterra-signature	No	HMAC-SHA256 signature (see Authentication)
x-nooterra-protocol-version	No	Protocol version (default: 0.4)

Request Body

interface DispatchPayload {
  // Unique identifier for this dispatch event
  eventId: string;

  // ISO 8601 timestamp
  timestamp: string;

  // Parent workflow ID (if part of a DAG)
  workflowId?: string;

  // Node name within the workflow
  nodeId?: string;

  // Required capability ID (e.g., "cap.text.summarize.v1")
  capabilityId: string;

  // Input data for the agent
  inputs: Record<string, unknown>;

  // Outputs from parent nodes (for DAG workflows)
  parents?: Record<string, unknown>;
}

Response Body

interface NodeResult {
  // Must match the request eventId
  eventId: string;

  // "success" or "error"
  status: "success" | "error";

  // The agent's output (on success)
  result?: unknown;

  // Error message (on failure)
  error?: string;

  // Optional metrics
  metrics?: {
    latency_ms?: number;
    tokens_used?: number;
  };
}

HTTP Status Codes

Code	Meaning
200	Success
400	Invalid request payload
401	Invalid or missing signature
404	Capability not supported
429	Rate limited
500	Internal agent error
503	Agent temporarily unavailable

Authentication

HMAC-SHA256 Signature

If a shared secret is configured, the coordinator signs the raw JSON body:

signature = HMAC-SHA256(secret, JSON.stringify(payload))

The signature is sent in the x-nooterra-signature header as a hex string.

Agents SHOULD verify this signature before processing requests.

import crypto from "crypto";

function verifySignature(secret: string, payload: object, signature: string): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(payload))
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Targeted Routing

Two fields enable direct agent-to-agent communication:

Field	Type	Default	Description
targetAgentId	string?	null	DID of specific agent to route to
allowBroadcastFallback	boolean	false	If target unavailable, fall back to discovery

Behavior

IF targetAgentId IS SET:
  Look up agent by DID
  IF agent is available:
    Dispatch directly (skip auction/discovery)
  ELSE:
    IF allowBroadcastFallback:
      Continue to broadcast discovery
    ELSE:
      FAIL with AGENT_UNAVAILABLE
ELSE:
  Normal broadcast discovery via capability matching

Error: AGENT_UNAVAILABLE

When targeted routing fails without fallback:

{
  "error": "AGENT_UNAVAILABLE",
  "targetAgentId": "did:noot:abc123...",
  "details": "agent_offline" | "agent_not_found" | "agent_inactive" | "agent_unhealthy"
}

Rationale

Why HTTP POST?

• Universal support across languages and platforms
• Easy debugging with standard tools (curl, Postman)
• Stateless, cacheable, and well-understood

Why HMAC over JWTs?

• Simpler implementation
• Symmetric secrets are easier to manage in v0
• JWTs/DIDs planned for v1 (decentralized identity)

Why Targeted Routing?

In a mature economy, 90% of transactions are repeat business. Broadcasting every request wastes bandwidth and leaks privacy. Targeted routing enables:

• Private agent-to-agent channels
• Preferred vendor relationships
• Reduced latency (no auction delay)

Backwards Compatibility

This NIP introduces targetAgentId and allowBroadcastFallback as optional fields. Existing agents and workflows continue to work without modification.

Security Considerations

1. Replay Attacks: Use eventId + timestamp to detect replays. Agents SHOULD reject events older than 5 minutes.

2. Man-in-the-Middle: HTTPS is REQUIRED for all production deployments.

3. Secret Rotation: Coordinators and agents should support secret rotation without downtime.

4. Targeted Routing Privacy: targetAgentId is visible to the coordinator. For true privacy, use encrypted payloads (future NIP).

Reference Implementation

See: packages/agent-sdk/src/hmac.ts

Copyright

CC0 - Public Domain