Signal Format

Binary format specification for NTL signals

Version: 0.1.0-draft

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
}

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	Ack	Confirms signal receipt
7-14	Reserved	Future protocol use
15	Custom	Application-defined

Validation Rules

A signal is valid if and only if:

1. The magic bytes are 0x4E544C
2. The version is supported by the receiving node
3. The body length matches the actual CBOR body size
4. All REQUIRED fields are present
5. The id is a valid ULID
6. The w (weight) is in range [0.0, 1.0]
7. The ttl is > 0
8. The sig (signature) verifies against the origin node’s public key
9. The ts (timestamp) is not in the future (with 30-second tolerance)
10. The signal id has not been seen before (deduplication)

Nodes MUST silently drop invalid signals. Nodes MUST NOT propagate invalid signals.

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.