E2E Encrypted
P2P Protocol

1. Cryptographic Stack

All peer-to-peer encryption uses modern, well-audited primitives. Each connection generates fresh ephemeral keys — no long-term key material is reused across sessions.

X25519 Key Exchange

256-bit ephemeral Curve25519 keypairs generated per connection. Each side produces a 32-byte public key and derives a 32-byte shared secret via Diffie-Hellman. The ephemeral nature ensures forward secrecy — compromising one session reveals nothing about past or future sessions.

ChaCha20-Poly1305 AEAD

Authenticated Encryption with Associated Data. 256-bit key, 96-bit nonce (64-bit counter + 32-bit zero padding), 16-byte authentication tag per message. Provides both confidentiality and integrity — any tampering is detected and the message is rejected.

HKDF-SHA256 Key Derivation

The shared secret from X25519 is never used directly. HKDF-SHA256 derives separate send and receive keys using distinct labels:

send_key = HKDF-SHA256(shared_secret, label="sost-p2p-key-a")
recv_key = HKDF-SHA256(shared_secret, label="sost-p2p-key-b")

The initiator uses key-a to send and key-b to receive; the responder reverses this. Each direction has an independent 64-bit nonce counter starting at 0, incremented per message.

2. Encryption Modes

Node operators can configure their encryption policy via the --encryption flag. Three modes are supported:

3. Handshake Flow

The connection handshake establishes encryption before any protocol data is exchanged. The EKEY exchange happens first, then VERS/VACK, then all subsequent messages are encrypted.

    Initiator                          Responder
    ─────────                          ─────────
        │                                  │
        │──── EKEY (pubkey_a, 32B) ───────>│
        │                                  │
        │<─── EKEY (pubkey_b, 32B) ────────│
        │                                  │
        │  [Both derive shared_secret via X25519]
        │  [HKDF-SHA256 → send_key, recv_key]
        │                                  │
        │════════ ENCRYPTED CHANNEL ═══════│
        │                                  │
        │──── VERS (version, height) ─────>│
        │                                  │
        │<─── VACK (version, height) ──────│
        │                                  │
        │══ HANDSHAKE COMPLETE ════════════│
        │                                  │
        │  [GETB, BLCK, TXXX, PING/PONG]  │
        │  [All messages encrypted]        │
        │                                  │

Timeout: If EKEY is not received within 10 seconds of connection, the peer is disconnected. If VERS/VACK is not completed within 30 seconds, the peer is disconnected and scored for misbehavior.

4. Protocol Commands

All commands use the same 12-byte frame header. Command names are 4-byte ASCII identifiers padded with null bytes if shorter.

5. Block Sync Flow

When a node discovers a peer with a higher best height, it initiates block synchronization. Blocks are requested and delivered in batches of up to 100.

    Node (behind)                      Peer (ahead)
    ─────────────                      ────────────
        │                                  │
        │  [VERS/VACK: peer height > ours]│
        │                                  │
        │── GETB (height=1000, n=100) ────>│
        │                                  │
        │<──── BLCK (block 1000) ──────────│
        │<──── BLCK (block 1001) ──────────│
        │<──── BLCK (block 1002) ──────────│
        │          ...                     │
        │<──── BLCK (block 1099) ──────────│
        │<──── DONE ──────────────────────│
        │                                  │
        │  [Validate & connect blocks]    │
        │                                  │
        │── GETB (height=1100, n=100) ────>│
        │                                  │
        │<──── BLCK (block 1100) ──────────│
        │          ...                     │
        │<──── BLCK (block 1155) ──────────│
        │<──── DONE ──────────────────────│
        │                                  │
        │  [Sync complete: heights match]  │
        │                                  │

Sync Parameters

6. Encrypted Frame Format

Once the EKEY handshake is complete, all messages are wrapped in an encrypted frame. The frame header is sent in plaintext (so the receiver knows how much ciphertext to read), but the payload is encrypted.

┌──────────────────────────────────────────────────────────┐
│                    ENCRYPTED FRAME                        │
├──────────┬──────────┬─────────────┬─────────────┬────────┤
│  magic   │   cmd    │ payload_len │ ciphertext  │  tag   │
│  4 bytes │ 4 bytes  │   4 bytes   │   N bytes   │ 16 B   │
├──────────┼──────────┼─────────────┼─────────────┼────────┤
│ 0x534F5354│ "BLCK"  │  len(ct)    │ ChaCha20    │ Poly   │
│  "SOST"  │ "GETB"  │  + 16       │  encrypted  │ 1305   │
│          │ "TXXX"  │             │  payload    │  MAC   │
│          │  etc.   │             │             │        │
└──────────┴──────────┴─────────────┴─────────────┴────────┘

Header (12 bytes, plaintext):
  magic:       0x534F5354 ("SOST") — identifies SOST protocol frames
  cmd:         4-byte ASCII command identifier
  payload_len: total encrypted payload size including 16-byte auth tag

Encrypted payload:
  ciphertext:  ChaCha20 encrypted message body (N bytes)
  tag:         Poly1305 16-byte authentication tag

The payload_len field includes the 16-byte Poly1305 tag, so actual plaintext length = payload_len - 16. Maximum payload_len = 4,194,304 bytes (4 MB). Any frame exceeding this is rejected and the peer is banned.

Nonce Management

Each direction maintains an independent 64-bit nonce counter, starting at 0 and incremented after each message. The nonce is not transmitted — both sides track it implicitly. If counters desync (decryption fails), the connection is terminated immediately.

7. Frame Header

Every P2P message begins with a fixed 12-byte header, whether encrypted or plaintext. This header is always sent unencrypted so the receiver can determine the message type and allocate the correct buffer size.

Offset  Size   Field         Description
──────  ────   ─────         ───────────
  0      4     magic         0x534F5354 ("SOST") — protocol identifier
  4      4     cmd           ASCII command (e.g., "EKEY", "BLCK", "GETB")
  8      4     payload_len   Payload size in bytes (network byte order)
──────  ────
 12 bytes total

Magic Bytes

Any frame that does not begin with 0x534F5354 is immediately rejected. This allows quick rejection of non-SOST traffic and port-scanning probes.

Payload Size Limits

Maximum message size: 4 MB (4,194,304 bytes). The payload_len field is a 32-bit unsigned integer but values above 4 MB are rejected at the frame parser level. A peer sending an oversized frame is disconnected and receives ban points.

8. DoS Protection

The P2P layer implements multiple defensive mechanisms to prevent denial-of-service attacks, resource exhaustion, and misbehaving peers.

Rate Limiting

Peer Limits

Ban Scoring

Each peer accumulates misbehavior points for protocol violations. When a peer reaches the ban threshold, it is disconnected and its IP is blocked for the ban duration.

Misbehavior examples:

• Sending an invalid block: +20 points
• Sending an invalid transaction: +10 points
• Oversized message: +50 points
• Invalid magic bytes: +100 points (immediate ban)
• Handshake timeout: +25 points
• Duplicate EKEY: +50 points
• Wrong genesis hash in VERS: +100 points (immediate ban)

E2E Encryption (Phase XIII+XIV)

Deal channels now use true end-to-end encryption. The relay is blind transport — it cannot read message content.

Cryptographic Stack

Prekey Architecture

What the Relay Can and Cannot Do