Stateless region-aware routing. How the gateway routes users to the fastest, closest nodes with health-aware cohort selection.
The Gateway is the entry point for users connecting to the marketplace. It is a stateless, region-aware, health-aware routing layer that directs users to the fastest, closest nodes without introducing a centralized dependency.
The gateway considers seven signals when scoring nodes for cohort assignment, in descending priority:
| Signal | Description |
|---|---|
| Region match | Same cloud region or data center as the user |
| Country match | Same country, determined by IP geolocation |
| Continent match | Same continent when country data is unavailable |
| Coordinates | Geographic distance calculation using lat/lng when available |
| Health probes | Node response time and availability from recent probes |
| Client hints | Browser-reported RTT and connection quality (Sec-CH-RTT, Sec-CH-Downlink) |
Signals are combined into a weighted score. The gateway picks the highest-scoring nodes for the cohort, subject to the size constraints below.
Users get assigned to a cohort of nodes that will serve their requests:
| Parameter | Value |
|---|---|
| Minimum cohort size | 3 nodes |
| Target cohort size | ceil(N / 3) where N = total healthy nodes |
| Maximum cohort size | 8 nodes |
The cohort is the set of nodes that cross-check reads for a session. It does not decide which servers a visitor gets: those come from the measured route map.
| Parameter | Value |
|---|---|
| Probe interval | Every 15 seconds |
| Probe timeout | 1.5 seconds |
| Result cache TTL | 10 seconds |
Probes hit each node's health endpoint and record response time. Nodes that fail probes or exceed the timeout are marked unhealthy.
Unhealthy nodes enter quarantine with a TTL. While quarantined, a node is excluded from all cohort assignments. The quarantine TTL increases with repeated failures and resets after a node passes consecutive health checks. This prevents flapping nodes from degrading user experience.
The gateway routes based on what capabilities are needed for the user's current transaction. If a user wants to buy a Bitcoin ordinal, the gateway filters for nodes with all required capabilities:
btc_mempool_watch -- monitor mempool for the transactionbtc_block_watch -- track confirmationsord_index_read -- verify ordinal inscription databtc_psbt_share_store -- hold PSBT shares during signingprotocol_validate -- validate protocol eventsprotocol_attest -- sign attestations as a witnessOnly nodes advertising all required capabilities for the transaction type are included in the cohort.
The gateway verifies that all nodes in a cohort serve the same release hash. On each probe, the node reports its build hash. If a node is serving a different version from the majority of the cohort, it gets excluded. This ensures users always get a consistent marketplace experience -- no mixed-version rendering or API mismatches.
Any number of gateways can run independently:
The gateway exposes a /network/discover endpoint that returns the current list of known healthy nodes. This endpoint is used by:
The discovery response includes a genesis block hash for network identity verification. Nodes reject peers that report a different genesis hash, preventing cross-network contamination.
Beyond simple "healthy / unhealthy", each node publishes an effectiveStatus to the gateway via the descriptor publisher:
| Status | Meaning | Gateway Behavior |
|---|---|---|
READY | Fully booted, all caches warm, accepting traffic | Eligible for cohort and direct routing |
WARMING | Booted, but core caches still hydrating after restart or DB recovery | Excluded from user-facing routing; allowed for media replica reads |
DEGRADED | Operating but a non-critical subsystem is unhealthy | Routed to with a scoring penalty |
OFFLINE | Process is up but cannot serve real traffic (DB lost, MPC stuck, etc.) | Excluded from all routing |
The WARMING window matters because a node fresh out of restart can answer health probes while its query path is still cold. Routing real users to a warming node would mean the first few hundred requests slow-load every cache miss. The gateway holds users on READY peers until the warming node settles, while still allowing low-stakes operations like media replica fetches.
The transition out of WARMING is automatic: once the node's bring-up sequence reports done, the descriptor publisher flips the field and the gateway picks the node up on its next selection cycle.