Why this matters
- UUID v4 is unique but random — unusable for time-range queries on the transfers table.
- Database
SEQUENCEobjects become a single-node bottleneck when ShardPay shards horizontally. - Snowflake-style IDs embed timestamp and shard for sortability without a central DB round-trip per insert.
- A centralized sequencer is a single point of failure unless backed by Raft consensus.
Snowflake-style IDs at ShardPay
ShardPay encodes every transfer ID as 64 bits: 41-bit millisecond timestamp, 10-bit shard ID, 12-bit per-shard sequence. IDs are roughly time-ordered, unique cluster-wide, and decodable for debugging ("this transfer landed on shard 42 at 14:03 UTC").
Each ledger shard allocates sequence numbers locally until the millisecond bucket rolls over or the 12-bit sequence exhausts (4096/ms). On exhaustion the shard spins until the next millisecond — rare at ShardPay's per-shard throughput but load-tested to 4k transfers/ms per shard.
Walkthrough: support lookup by time range
A merchant disputes all transfers between 2pm and 3pm. Because IDs embed timestamp, ShardPay's support API computes min/max ID bounds for that window and queries only relevant shards. Without time-ordered IDs the team would full-scan UUID primary keys — unusable at billions of rows.
Key points
- Snowflake layout — timestamp + machine/shard + sequence bit fields packed into a
long. ShardPay'sTransferIdtype decodes shard and creation instant for routing support tickets without joining metadata tables. - Rough time order — IDs sort lexicographically by creation time within a shard; clock skew across shards can invert order by seconds. ShardPay uses Snowflake order for indexing and support, not for causal correctness — that stays with Lamport clocks on audit rows.
- Sequence exhaustion — when 4096 IDs fire in one millisecond on one shard, the generator waits for the next ms. ShardPay alerts if any shard hits exhaustion more than once per minute, signaling hot-account concentration.
- UUID v7 — time-ordered UUIDs (RFC draft) as an alternative to Snowflake; 128 bits, standard library support growing in Java 17+ ecosystems. ShardPay stayed on Snowflake for compact
longprimary keys in B-tree indexes. - Lease-based range — a coordinator assigns each node a block of IDs (e.g. 1–10000); the node allocates locally until the block runs out. ShardPay's batch settlement job uses lease ranges from etcd so millions of fee-line IDs never hit the DB sequence.
The rest of this guide is part of Pro
Free covers every fresher guide in full. Pro unlocks Senior, Staff and Architect guides across every track.
Still to come · 2 sections
- Raft-backed centralized sequencers
- Choosing an ID strategy
Test yourself
Answer these before moving on — recall is what makes it stick.