# Crypto — Solana BDN over QUIC

> A QUIC-only Solana block-dissemination network: low-latency feeds in, native TPU transaction delivery out, fanned out by the relay mesh.

<img src="/images/diagrams/crypto.png" alt="crypto data flow" />

The **crypto** modality is a [Solana](https://solana.com) **block-dissemination
network (BDN)** built entirely on ClutchCall's QUIC stack. It does two things,
both over QUIC and nothing else:

1. **Feeds in** — low-latency Solana data (slots, recent blockhash, priority
   fees) is ingested at the edge and republished as named [MoQT](https://datatracker.ietf.org/wg/moq/about/)
   tracks. Traders subscribe over QUIC and read each update the moment the relay
   fans it out.
2. **Transactions out** — a signed transaction is handed to the BDN, deduplicated,
   fanned out across the edge mesh, and landed directly on the current and next
   leader validators' **TPU** (Transaction Processing Unit) over Solana's native
   QUIC protocol.

There is **no gRPC and no WebSocket** on the client edge — the whole surface is
QUIC (HTTP/3 for the request/response calls, MoQT for the feed tracks, and raw
QUIC with `ALPN solana-tpu` for the leg out to validators). Clients that can't
negotiate QUIC are refused; there is no TCP fallback.

> **NOTE:**
> **No typed SDK ships for crypto yet.** Today you consume the BDN two ways: the
> QUIC submit/feeds **HTTP/3 API** (any HTTP/3 client), and the **raw MoQT client**
> (`@clutchcall/sdk/moqt`) for subscribing to feed tracks. A dedicated typed
> `Crypto` client is a **Preview** — see [SDK methods](./sdk-methods). Everything
> below is grounded in what runs today.

## When to use it

  - **Land transactions faster** — Submit a signed Solana tx once and have the BDN fan it out and land it on
    several upcoming leaders' TPUs in parallel — instead of a single RPC hop.
  - **Low-latency trader feeds** — Subscribe to slot / blockhash / priority-fee tracks over QUIC and get each
    update pushed the instant the edge sees it — no polling an RPC node.
  - **Bring your own ingest** — Point the ingest at your own gossip/Geyser endpoint to publish a private feed
    track scoped to your organization.
  - **Co-located edge mesh** — A root ingests and fans out to edge relays close to the validators they land
    on, shaving the network hop between you and the leader.

## Wire model

The BDN is a small set of MoQT track namespaces plus two HTTP/3 submit paths.

### Feed tracks (BDN → you)

Feeds are ordinary MoQT **frame tracks**: a namespace + name carrying opaque
binary objects, fanned out by the relay mesh. The public Solana mainnet feed
lives under the `sol/feed/mainnet` namespace:

| Track                               | Payload fields                              | Cadence |
| ----------------------------------- | ------------------------------------------- | ------- |
| `sol/feed/mainnet/slots`            | `{ slot }`                                  | push, every slot |
| `sol/feed/mainnet/blockhash`        | `{ slot, blockhash, lastValidBlockHeight }` | push, every N slots |
| `sol/feed/mainnet/priorityFee`      | `{ slot, p50, max }`                        | poll, every N slots |

A **private** feed (your own ingest endpoint) is published under
`sol/feed/<orgId>/…` and is visible only to your organization. You subscribe to
any of these with the raw MoQT client — see
[Subscribe to a feed track](./cookbook#subscribe-to-a-feed-track).

### Submit paths (you → BDN → validators)

A signed transaction is delivered over HTTP/3 with the raw tx as an
`application/octet-stream` body. Two routes:

| Route          | Path           | Behaviour |
| -------------- | -------------- | --------- |
| **BDN fan-out**| `POST /bdn/submit?leader=auto` | Ingests once, deduplicates, fans the tx across **all edges**; each edge lands it on its nearby leaders. |
| **Direct TPU** | `POST /tpu?host=auto`          | Sends straight to the **current + next leader** TPUs from this node, no fan-out. |

For both, `leader=auto` / `host=auto` resolves the leader schedule
automatically; pass an explicit `host:port` to target a specific validator TPU.
The first **64 bytes** of the transaction are its Solana signature and are used
as the BDN's **dedup key**, so re-submitting the same tx across edges lands it at
most once per leader.

## Lanes & QoS

| Concern             | How the BDN handles it                                       |
| ------------------- | ----------------------------------------------------------- |
| **Feed delivery**   | MoQT frame track — each object pushed on a QUIC stream, fanned out by the relay mesh. Late joiners get the newest object first. |
| **Tx delivery**     | Raw QUIC to the validator TPU with `ALPN solana-tpu`, an **ephemeral ed25519** client identity per connection. |
| **Dedup**           | A short-id cache keyed on the 64-byte signature, with a configurable `dedup_ttl_secs`, suppresses duplicate lands across the mesh. |
| **Leader fan-out**  | `fanout_leaders` (1–4) controls how many upcoming leaders a tx is landed on at once. |
| **Reliability**     | The transaction is data — a frame, not a media stream. There is no transcode and no loss-concealment: it lands verbatim or it doesn't. |

## Architecture

The BDN runs on the same [shard-per-core](/concepts/architecture) engine as
every other modality, so it inherits the platform's kernel-bypass data path:

  1. **Ingest (root)**
The root node subscribes to Solana data — from a public RPC `slotSubscribe`
    or your own gossip/Geyser endpoint — on a single shard and stamps each update
    into a MoQT frame object.
  2. **Fan-out (relay mesh)**
The relay mesh fans each feed object and each submitted tx to every subscribed
    edge over one QUIC connection per peer. Cross-shard hand-off uses lock-free
    **mcache / dcache rings**, so a feed never crosses a lock to reach a subscriber.
  3. **Land (edge → TPU)**
Each edge resolves the leader schedule (`getLeaderSchedule`), opens a raw QUIC
    connection to the leaders' TPU endpoints, and writes the transaction. The NIC
    fast path is **AF_XDP** with **eBPF/XSK** steering and **UMEM** zero-copy
    buffers, so the tx leaves the box with minimal kernel overhead.

> **TIP:**
> Because the edge sits *between* you and the validator, the BDN can land a tx on
> the **next** leader before it becomes current — front-running the slot boundary
> rather than racing it. That's what `fanout_leaders > 1` buys you.

## Discovery

Clients find the QUIC port via a DNS **HTTPS** resource record on the crypto
host (`alpn=h3`, the QUIC port in the record), the same mechanism the rest of the
platform uses for [HTTP/3 endpoint discovery](/concepts/architecture). Feed
tracks are discovered by subscribing to a namespace prefix — the relay holds the
subscribe even for a track that hasn't been announced yet, so you can subscribe
to a private feed before your ingest has published its first slot.

## Next

  - **[SDK methods](./sdk-methods)** — Subscribe to feeds with the MoQT client; the Preview typed `Crypto` surface.
  - **[Cookbook](./cookbook)** — Short tasks: subscribe a track, submit a tx, target a leader, tune dedup.
  - **[Recipes](./recipes)** — End-to-end: a feed-driven submitter and a private-feed consumer.