Adapter Contract — NTL Specification

Version: beta_0.0.0

Implementation status. The Adapter trait this document specifies exists in ntl-core and is exercised by the test suite. No adapter implements it: adapters/web2, adapters/web3 and adapters/legacy are placeholder crates containing a single doc comment each, and no binary reads an [adapter.*] configuration table.This page is therefore normative and unimplemented at the same time — the contract is fixed, the implementations are not written. The adapter guides describe intended behaviour on top of it. Tracking: openNTL/ntl#14.

Overview

Adapters translate between NTL signals and external protocols. This document specifies the interface that all adapters MUST implement.

Interface

Adapter {
    // Translation
    ingest(external: ExternalPayload) -> Result<Signal>
    emit(signal: Signal) -> Result<ExternalPayload>

    // Metadata
    protocol() -> Protocol
    capabilities() -> AdapterCapabilities

    // Lifecycle
    start() -> Result
    stop() -> Result
    health() -> AdapterHealth
}

ExternalPayload

The generic container for external protocol data:

ExternalPayload {
    data: bytes,              // Raw payload
    content_type: string,     // MIME type
    metadata: Map<string, string>,  // Protocol-specific metadata
}

AdapterCapabilities

Adapters declare their capabilities:

AdapterCapabilities {
    can_ingest: bool,         // Can receive external → signal
    can_emit: bool,           // Can send signal → external
    bidirectional: bool,      // Supports persistent bidirectional channel
    correlation: bool,        // Supports request-response correlation
    streaming: bool,          // Supports streaming signals
}

Health States

State	Description	Behavior
`Healthy`	Operating normally	Full throughput
`Degraded`	Partial functionality	Reduced throughput, increased timeouts
`Unhealthy`	Not functioning	Queues signals, emits health warnings

Registration

Adapters MUST register with their node:

node.register_adapter(adapter) -> Result

Registered adapters:

Appear in node health checks
Are included in discovery signals
Can be queried via the node management interface

Correlation Requirements

Adapters that support correlation (request-response patterns) MUST:

Generate a signal with a unique ID for each incoming request
Hold the external connection open
Match response signals by correlation_id
Enforce a configurable timeout (default: 30 seconds)
Return an appropriate error to the external client on timeout

Standard Adapters

The NTL reference implementation MUST include:

Adapter	Protocol	Module ID
Web2	HTTP/1.1, HTTP/2, WebSocket, gRPC	`web2-v1`
Web3	EVM chains, DID verification	`web3-v1`
Legacy	REST, SOAP (configuration-driven)	`legacy-v1`

​Overview

​Interface

​ExternalPayload

​AdapterCapabilities

​Health States

​Registration

​Correlation Requirements

​Standard Adapters