Signal Format — NTL Specification

Version: beta_0.0.0

Overview

An NTL signal is the atomic unit of data transfer. This document specifies the binary format, field definitions, encoding rules, and validation requirements for signals.

Wire Format

Signals are encoded in CBOR (RFC 8949) by default. The wire format consists of a fixed header followed by a CBOR-encoded body.

Header (8 bytes)

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|    Magic (0x4E544C)   | Ver |T| Flags         | Body Length    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                    Body Length (continued)                     |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Field	Bits	Description
Magic	24	`0x4E544C` (“NTL” in ASCII)
Version	4	Protocol version (0-15)
Type	4	Signal type enum
Flags	8	Bitfield (see below)
Body Length	24	CBOR body length in bytes

Flags

Bit	Name	Description
0	`ENCRYPTED`	Payload is encrypted
1	`COMPRESSED`	Body is compressed (LZ4)
2	`TRACE`	Signal carries a propagation trace
3	`CORRELATION`	Signal has a correlation ID
4	`PRIORITY`	Signal has elevated priority
5-7	Reserved	Must be 0

Body (CBOR)

The body is a CBOR map with the following fields:

{
  "id": bytes(16),           ; ULID - REQUIRED
  "origin": bytes(32),       ; Node public key hash - REQUIRED
  "sig": bytes(variable),    ; Cryptographic signature - REQUIRED
  "ts": uint64,              ; Timestamp nanoseconds - REQUIRED
  "w": float32,              ; Weight 0.0-1.0 - REQUIRED
  "ttl": uint16,             ; Time-to-live hops - REQUIRED
  "p": bytes(variable),      ; Payload - REQUIRED
  "enc": uint8,              ; Encoding enum - OPTIONAL (default: CBOR)
  "scope": uint8,            ; Propagation scope - OPTIONAL (default: weighted)
  "cor": bytes(16),          ; Correlation ID - OPTIONAL
  "trace": [bytes(32)...],   ; Node ID path - OPTIONAL
  "tags": [text...],         ; Searchable tags - OPTIONAL
  "del": uint8,              ; Delivery class - OPTIONAL (default: best-effort)
}

Field Definitions

id (Signal Identifier)

Type: ULID (16 bytes)
Requirement: REQUIRED
Description: Universally unique, lexicographically sortable identifier. Generated by the emitting node. MUST be unique across the network.

origin (Origin Node)

Type: 32 bytes (BLAKE3 hash of node public key)
Requirement: REQUIRED
Description: Identifies the node that originally emitted this signal. Used for signature verification and trust scoring.

sig (Signature)

Type: Variable-length bytes
Requirement: REQUIRED
Description: Cryptographic signature over the signal body (excluding the signature field itself). Generated using the active crypto module. Receiving nodes MUST verify the signature before processing.

ts (Timestamp)

Type: Unsigned 64-bit integer
Requirement: REQUIRED
Description: Nanoseconds since Unix epoch (1970-01-01T00:00:00Z). Used for ordering, deduplication, and TTL expiry.

w (Weight)

Type: 32-bit float
Requirement: REQUIRED
Constraints: MUST be in range [0.0, 1.0]
Description: Signal priority and intensity. Affects activation thresholds and propagation priority.

ttl (Time-to-Live)

Type: Unsigned 16-bit integer
Requirement: REQUIRED
Constraints: MUST be > 0 on emission. Decremented at each hop.
Description: Maximum number of hops this signal may traverse. When TTL reaches 0, the signal MUST NOT be propagated further.

p (Payload)

Type: Variable-length bytes
Requirement: REQUIRED (may be empty)
Description: The actual data carried by the signal. Encoding determined by the enc field.

enc (Encoding)

Type: Unsigned 8-bit integer
Requirement: OPTIONAL (default: 0 = CBOR)
Values:

Value	Encoding
0	CBOR
1	Protobuf
2	Raw bytes
3-127	Reserved
128-255	Custom (application-defined)

scope (Propagation Scope)

Type: Unsigned 8-bit integer
Requirement: OPTIONAL (default: 1 = Weighted)
Values:

Value	Scope
0	Flood
1	Weighted
2	Targeted
3	Gradient
4-127	Reserved
128-255	Custom

Signal Types

Value	Type	Description
0	Data	Carries a data payload
1	Query	Requests data from the network
2	Event	Notifies of a state change
3	Command	Requests an action
4	Heartbeat	Maintains synapse liveness
5	Discovery	Announces node capability
6	Receipt	Reports the outcome of an acknowledged signal
7-14	Reserved	Future protocol use
15	Custom	Application-defined

del (Delivery Class)

Type: Unsigned 8-bit integer
Requirement: OPTIONAL (default: 0 = best-effort)
Values:

Value	Class	Guarantee
0	`best-effort`	None; may be silently absorbed
1	`acknowledged`	At-least-once, or the sender learns it failed
2-255	Reserved	—

The delivery class is part of the signed body, so an intermediate node cannot downgrade it. A node that does not support acknowledged MUST reject such a signal with a negative receipt rather than accept it and degrade silently. See delivery-semantics.

Receipt Signals

A Receipt (type 6) reports the outcome of an acknowledged signal. It MUST set cor to the identifier of the signal it acknowledges, and MUST use scope Targeted toward that signal’s origin. Its payload is a CBOR map:

{
  "status": text,     ; "delivered" | "rejected" - REQUIRED
  "hops":   uint16,   ; hops taken to reach the handler - REQUIRED
  "reason": text,     ; REQUIRED when status = "rejected"
}

reason takes one of the values enumerated in delivery-semantics §2.2. A Receipt MUST NOT itself be acknowledged — receipts are not acknowledged, so the protocol cannot recurse.

Signal type 6 was named Ack in 0.1.0-draft. The wire value is unchanged; the type now carries a structured outcome rather than bare confirmation, since a plain acknowledgement cannot express why a signal failed.

Validation Rules

A signal is valid if and only if:

The magic bytes are 0x4E544C
The version is supported by the receiving node
The body length matches the actual CBOR body size
All REQUIRED fields are present
The id is a valid ULID
The w (weight) is in range [0.0, 1.0]
The ttl is > 0
The sig (signature) verifies against the origin node’s public key
The ts (timestamp) is not in the future (with 30-second tolerance)
The signal id has not been seen before (deduplication)
The del (delivery class) is a value this node supports

Nodes MUST drop invalid signals and MUST NOT propagate them. Validation MUST be ordered cheapest-first: magic bytes, version, size, TTL, and deduplication before signature verification (rule 8). Verifying first lets an attacker impose expensive asymmetric cryptography with malformed traffic; see threat-model §5. Dropping is silent for best-effort signals. For an acknowledged signal that fails rules 1-7 or 9, the node cannot trust the origin field enough to reply and MUST drop silently; for one that fails only rule 11, it MUST emit a negative receipt with reason unsupported_type.

Maximum Signal Size

The maximum signal size (header + body) is 1 MB (1,048,576 bytes). Signals exceeding this size MUST be rejected. For payloads exceeding 1 MB, applications SHOULD use chunked signals with correlation IDs to reassemble at the destination.

​Overview

​Wire Format

​Header (8 bytes)

​Flags

​Body (CBOR)

​Field Definitions

​id (Signal Identifier)

​origin (Origin Node)

​sig (Signature)

​ts (Timestamp)

​w (Weight)

​ttl (Time-to-Live)

​p (Payload)

​enc (Encoding)

​scope (Propagation Scope)

​Signal Types

​del (Delivery Class)

​Receipt Signals

​Validation Rules

​Maximum Signal Size

Overview

Wire Format

Header (8 bytes)

Flags

Body (CBOR)

Field Definitions

id (Signal Identifier)

origin (Origin Node)

sig (Signature)

ts (Timestamp)

w (Weight)

ttl (Time-to-Live)

p (Payload)

enc (Encoding)

scope (Propagation Scope)

Signal Types

del (Delivery Class)

Receipt Signals

Validation Rules

Maximum Signal Size