Build a DDN message envelope - Talaria Developer Documentation

A DDN envelope is the package a Talaria client sends through Relay and Cache nodes. Think of it as an addressed, sealed parcel:

The outer fields tell nodes where and how to handle it.
The encrypted header carries protected routing or application metadata.
The payload carries encrypted message data.

Nodes validate the outer shape but do not need to decrypt your message.

Smallest practical shape

{
  "message_id": "9f8d6f08-bce5-4df5-b22b-bf8c6bd4e143",
  "to": "did:talaria:1111111111111111111111",
  "timestamp": "2026-07-24T16:30:00Z",
  "ttl": "24h",
  "payload": {
    "ciphertext_b64": "<encrypted-message>"
  },
  "encrypted_header": "<base64-encrypted-header>",
  "header_nonce": "<base64-nonce>",
  "header_key_id": "recipient-key-1",
  "schema_version": "1"
}

Required fields

Field	Meaning
`message_id`	A UUID generated once for this message
`to`	Recipient Talaria DID; `recipient` is accepted as an alternate name
`timestamp`	ISO-8601, epoch milliseconds, or epoch seconds
`payload`	The encrypted application payload
Encrypted header	Supply the flat encrypted-header fields or a `context` object

If using flat fields, supply encrypted_header, header_nonce, schema_version, and either header_key_id or header_key_epoch.

Common optional fields

Field	Purpose
`from`	Sender DID; `sender` and `source` are accepted alternates
`signature`	Base64 sender signature; when supplied, a sender DID is also required
`x_key_id`	Recipient encryption-key or target-device reference
`tag`	Compact DNS-like message category
`ttl`	Duration such as `15m`, `1h`, `24h`, or `7d`
`delivery_hint`	`standard`, `chunked`, `direct-to-cache`, or `realtime`

Unknown outer fields are rejected. This protects interoperability by preventing different clients from silently inventing incompatible headers.

Chunked messages

For a large encrypted object, send independently deliverable chunks. Each chunk has its own message_id and shares a UUID message_group_id.

{
  "delivery_hint": "chunked",
  "message_group_id": "e93e6c49-d280-4078-81bd-16f09be99e7e",
  "sequence_number": 0,
  "total_chunks": 3
}

sequence_number begins at 0 and must be less than total_chunks. Relay and Cache nodes do not reassemble or decrypt the content.

Sender signatures

Sender identity is optional at the envelope-validation layer. If you provide either the sender DID or signature, provide both. Nodes that verify the sender resolve the DID and check the signature against its authorized public key.

Straight to the point

JSON object only
UUID message_id
Valid recipient DID
Timestamp plus encrypted payload
Flat encrypted header or context
No unknown top-level fields
Encrypt before sending

​Smallest practical shape

​Required fields

​Common optional fields

​Chunked messages

​Sender signatures

​Straight to the point