> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talaria.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a DDN message envelope

> Learn the encrypted message format accepted by Relay and Cache nodes

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

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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