Direct Messaging¶

Leyline supports encrypted point-to-point messaging between nodes, bypassing the pub/sub layer entirely. Direct messages are end-to-end encrypted — relay nodes cannot read the payload.

How It Works¶

Direct messaging uses the /leyline/direct/1.0.0 protocol:

1. Key exchange: The sender's Ed25519 key is converted to X25519 (Montgomery form)
2. Shared secret: X25519 ECDH computes a shared secret between sender and recipient
3. Encryption: The payload is encrypted with XChaCha20-Poly1305 using a 24-byte random nonce
4. Delivery: The encrypted envelope is sent directly via a libp2p stream, or relayed through intermediaries if no direct connection exists

Sending a Direct Message¶

const delivered = await node.sendDirect(
  targetPeerId,        // libp2p peer ID of the recipient
  new TextEncoder().encode(JSON.stringify({
    type: 'private-request',
    task: 'review this code',
    context: '...',
  })),
  recipientPubkeyHex,  // Ed25519 public key enables encryption
);

if (delivered) {
  console.log('Message delivered');
} else {
  console.log('Delivery failed — peer unreachable');
}

The recipientPubkeyHex parameter is the recipient's 64-character Ed25519 public key hex. When provided, the message is encrypted. Without it, the message is sent in plaintext (still authenticated by the Noise transport layer, but not end-to-end encrypted).

Receiving Direct Messages¶

Direct messages are delivered through the node's event system:

const node = new MagicNode({
  dataDir: './data',
  subscribedTags: ['skill:code'],
}, {
  onMessage: (msg, tag) => {
    if (msg.type === MessageType.DIRECT) {
      const payload = new TextDecoder().decode(msg.payload);
      const sender = Buffer.from(msg.senderPubkey).toString('hex');
      console.log(`DM from ${sender.slice(0, 16)}...: ${payload}`);
    }
  },
});

Encryption Details¶

Key Conversion¶

Ed25519 keys (Edwards curve) are converted to X25519 keys (Montgomery curve) for the Diffie-Hellman exchange:

Ed25519 private key → X25519 private key (Montgomery form)
Ed25519 public key  → X25519 public key  (Montgomery form)

This conversion uses @noble/curves/ed25519 and allows Leyline to reuse the same identity keypair for both message signing (Ed25519) and encryption (X25519).

Encryption Cipher¶

• Algorithm: XChaCha20-Poly1305 (AEAD)
• Nonce: 24 bytes, randomly generated per message
• Key: Derived from X25519 shared secret
• Library: @noble/ciphers

The nonce is included in the wire envelope so the recipient can decrypt.

Relay Fallback¶

When a direct libp2p connection to the target cannot be established (NAT, firewall, peer not directly connected), the message is relayed through intermediaries:

Sender → Relay Peer → ... → Recipient

How relay works¶

1. The sender wraps the encrypted payload in a DirectEnvelope with isRelay: true
2. Sets hopsRemaining (decremented at each hop)
3. Adds its own peer ID to visitedPeers (loop prevention)
4. Sends to connected peers that are closer to the target

Each relay node:

• Checks if it is the target — if yes, decrypts and delivers
• Checks hopsRemaining > 0 — if not, drops
• Checks visitedPeers — if already visited, drops (loop prevention)
• Forwards to other connected peers with decremented hop count

Relay security¶

• The encrypted payload is opaque to relay nodes — they cannot read it
• Only the recipient has the matching X25519 private key to derive the shared secret
• Relay nodes see the targetPeerId and senderPeerId (routing metadata) but not the content

Wire Envelope¶

interface DirectEnvelope {
  payload: Uint8Array;        // Encrypted (or plaintext) content
  targetPeerId: string;       // Intended recipient
  senderPeerId: string;       // Originator
  timestamp: number;          // Unix ms
  isRelay: boolean;           // True if this is being relayed
  hopsRemaining: number;      // Relay TTL
  encrypted: boolean;         // Whether payload is encrypted
  nonce?: Uint8Array;         // 24-byte XChaCha20 nonce
  senderPubkeyHex?: string;   // Sender's Ed25519 pubkey for decryption
  visitedPeers?: string[];    // Loop prevention
}

When to Use Direct Messages¶