DEV Community: Louis Franck M

Designing a topology-aware UUID v8-style Java library for distributed systems

Louis Franck M — Mon, 04 May 2026 10:28:23 +0000

Most ID libraries solve one problem well:

uniqueness

But in distributed systems, that is often not enough.

Sometimes you also want an identifier to help with:

- ordering
- tracing
- debugging
- understanding where it came from

That is why I built EUID, a Java library for generating sortable, decodable, topology-aware UUID v8-style identifiers.

With v0.2.0, I made the biggest change to the project so far: I split generation into two strategies instead of forcing one implementation to handle every workload.

Why EUID exists

Traditional UUIDs are great when you want opaque, globally unique values.

But they do not help much when your system also cares about:

time ordering
infrastructure visibility
decoding metadata from an ID
understanding distributed generation behavior

EUID is designed for those cases.

It uses a structured 128-bit layout with:

timestamp
region
shard
node
sequence

So the ID is not just unique — it can also be decoded and understood.

What changed in v0.2.0

The biggest change in v0.2.0 was the generator model.

Instead of one generation strategy, EUID now provides two:

FastEuidGenerator

Optimized for:

single-threaded use
thread-confined use
minimal overhead

ConcurrentEuidGenerator

Optimized for:

shared concurrent use
multi-threaded access to the same generator
better scalability under contention

This made the library much more honest.

Different workloads do not always need the same generator behavior, so the API now reflects that.

API example

Fast generator

EuidGenerator generator = EuidGenerators.fast(1, 1, 1);

Concurrent generator

EuidGenerator generator = EuidGenerators.concurrent(1, 1, 1);

Concurrent generator with custom block size

EuidGenerator generator = EuidGenerators.concurrent(1, 1, 1, 2048);

Decode support

One of the key goals of EUID is that IDs should be useful to inspect.

UUID id = EuidGenerators.fast(2, 3, 4).generate();

DecodedEuid decoded = EuidDecoder.decode(id);

System.out.println(decoded.getInstant());
System.out.println(decoded.getRegion());
System.out.println(decoded.getShard());
System.out.println(decoded.getNode());
System.out.println(decoded.getSequence());

That is useful for:

debugging distributed systems
tracing event origins
validating routing or sharding behavior

Base58 support

EUID also supports Base58 encoding for more compact external representation.

UUID id = EuidGenerators.fast(1, 1, 1).generate();

String encoded = EuidBase58Codec.encode(id);
UUID decoded = EuidBase58Codec.decode(encoded);

This is useful when you want:

shorter IDs
better readability
easier copy/paste in logs or URLs

Benchmarks

For v0.2.0, I also created a separate JMH benchmark project and benchmarked:

raw generation
multi-thread throughput
generation + toString()
Base58 encoding/decoding

Highlights for euid-core:0.2.0

Raw generation

* ConcurrentEuidGenerator: ~262.8M ops/s
* FastEuidGenerator: ~254.8M ops/s
* tested UUID v7 library: ~68.4M ops/s

Multi-thread

* FastEuidGenerator (per thread): ~850.7M ops/s
* ConcurrentEuidGenerator (per thread): ~848.2M ops/s
* ConcurrentEuidGenerator (shared): ~826.3M ops/s
* tested UUID v7 library: ~39.6M ops/s

Generate + toString()

* FastEuidGenerator: ~68.5M ops/s
* ConcurrentEuidGenerator: ~59.8M ops/s
* tested UUID v7 library: ~40.2M ops/s

Base58

* encode: ~1.4M to ~1.5M ops/s
* decode: ~2.07M ops/s

The benchmark results helped clarify an important point:

* raw generation is very fast
* string conversion changes the overall picture
* Base58 is useful, but comes with a real cost

What I learned

A few things became clear while working on this release:

One generator strategy was not enough

Different workloads genuinely benefit from different generation models.

Benchmarking needs discipline

Focused JMH runs gave much more meaningful results than broad mixed runs.

IDs can be operational tools

For some systems, an ID that carries structure is more useful than a purely opaque value.

When EUID makes sense

EUID is a good fit if you want:

sortable IDs
topology-aware IDs
decode support
strong throughput
more operational visibility from identifiers

It is probably not the right choice if:

you only need random uniqueness
you want fully opaque IDs
UUID v4 or UUID v7 already fully solves your use case

EUID is not trying to replace every UUID scenario.

It is aimed at systems that benefit from sortable, decodable, infrastructure-aware identifiers.

Current status

The project is currently at v0.2.0.

At this stage, I am more focused on:

documentation
benchmark communication
API clarity

than rushing to 1.0.0.

I would rather have a well-understood 0.2.x than a premature “stable” release.

Feedback welcome

I’d be very interested in feedback on:

the API design
the benchmark methodology
tradeoffs vs UUID v7
tradeoffs vs Snowflake-style IDs
real distributed-system use cases

louis-franck-moussima / euid-java

Core library for EUID — a fast, distributed, sortable unique ID generator for Java.

EUID — Topology-Aware UUID v8 for Java

EUID is a Java library for generating sortable, decodable, infrastructure-aware UUID v8 identifiers.

It is designed for distributed systems that need more than raw uniqueness:

time-ordered IDs for better database locality
embedded topology metadata (region, shard, node)
deterministic per-node sequencing
RFC 4122 / UUID v8-compatible layout
human-friendlier Base58 encoding
full decode support for observability and debugging

If you need identifiers that are not just unique, but also operationally meaningful, EUID gives you a structured alternative to purely random UUIDs.

Why EUID?

Traditional identifiers solve uniqueness, but they do not always help with:

ordered inserts in databases
infrastructure traceability
decoding where an ID came from
correlating events across distributed nodes

EUID is built for those cases.

In one sentence

EUID = sortable UUID v8 + topology metadata + deterministic sequencing

When to use EUID

EUID is a good…

View on GitHub

Designing a Structured UUID v8 Generator for Distributed Systems (EUID)

Louis Franck M — Tue, 10 Mar 2026 08:24:49 +0000

Unique identifiers are fundamental to modern software systems.
Databases, APIs, microservices, and event-driven architectures all rely on them.

Most developers simply use random UUIDs. But at scale, randomness can introduce limitations.

This article introduces EUID (Evolutionary Unique Identifier) — a structured UUID v8 generator designed for distributed systems and database-friendly indexing.

The Problem With Traditional UUIDs

UUID v4

The most commonly used UUID is version 4, which is completely random.

While this guarantees uniqueness, it has several drawbacks in large systems:

• no time ordering
• poor database index locality
• opaque identifiers
• no infrastructure awareness

When UUID v4 values are used as database primary keys, inserts become effectively random, which can fragment indexes and reduce performance.

UUID v7

The newer UUID v7 specification introduces time ordering.

It includes:

• a 48-bit timestamp
• random entropy bits

This greatly improves database performance because records are inserted in roughly chronological order.

However, UUID v7 remains intentionally random beyond the timestamp.

In some distributed systems, it can be useful for identifiers to contain information about the infrastructure that generated them.

A Different Approach: Structured Identifiers

Instead of relying on randomness, some distributed systems prefer structured identifiers.

Examples include:

• snowflake-style identifiers
• sharded database IDs
• topology-aware identifiers

The core idea is simple:

An identifier can encode where it was generated, not just when.

This can help with:

• debugging distributed systems
• tracing requests
• understanding data origin
• operational observability

This philosophy inspired the design of EUID.

Introducing EUID

EUID (Evolutionary Unique Identifier) is a UUID v8-compatible identifier that combines:

• time ordering
• topology encoding
• deterministic generation

Unlike random UUIDs, EUID identifiers are fully decodable.

From a single identifier you can determine:

• when it was generated
• which region generated it
• which shard handled it
• which node created it
• the sequence number

EUID Bit Layout

EUID uses the 128-bit UUID structure with the following layout:

Bits	Field
48	Timestamp (milliseconds)
4	Version (UUID v8)
6	Region
6	Shard
2	Variant
14	Node
48	Sequence

Timestamp

A 48-bit millisecond timestamp ensures time ordering and database-friendly indexing.

Region / Shard / Node

These fields encode distributed topology, allowing identifiers to carry infrastructure metadata.

Sequence

Each node maintains a monotonic sequence counter to generate multiple identifiers within the same millisecond.

Operational Observability Through Identifiers

One interesting side effect of structured identifiers is operational observability.

In many systems, identifiers are opaque.
When something fails in production, engineers often need to query logs or databases just to determine where an identifier originated.

Because EUID embeds topology information directly in the identifier, operational metadata can be extracted immediately.

From a single identifier you can determine:

• when it was generated
• which region produced it
• which shard handled the request
• which node created the identifier

Instead of being black boxes, identifiers become structured infrastructure signals.

Example Usage

Generating an identifier in Java:

EuidGenerator generator = new EuidGenerator(1, 1, 1);

UUID id = generator.generate();
System.out.println("EUID: " + id);

Example output:

019caad2-a445-8083-8005-000000000011

The identifier can then be decoded:

DecodedEuid decoded = EuidDecoder.decode(id);

System.out.println(decoded.getInstant());
System.out.println(decoded.getRegion());
System.out.println(decoded.getShard());
System.out.println(decoded.getNode());
System.out.println(decoded.getSequence());

Base58 Encoding

EUID also supports Base58 encoding, which produces shorter and more human-friendly identifiers.

Example:

1CYctoRWaz5VGXwscmiovG

Base58 avoids visually confusing characters such as:

• 0 and O
• l and I

This makes identifiers easier to use in URLs, logs, and APIs.

When Should You Use EUID?

EUID can be useful when you need:

• time-ordered identifiers
• database-friendly indexing
• infrastructure-aware IDs
• deterministic identifier structure

If you only need a random identifier, UUID v4 or UUID v7 may already be sufficient.

EUID is designed for systems where traceability and infrastructure awareness are important.

Open Source Project

The EUID library is open source and available on Maven Central.

GitHub repository:

[https://github.com/louis-franck-moussima/euid-java]

The project includes:

• a high-performance generator
• Base58 encoding support
• full decode capability
• unit tests and stress tests

Conclusion

Identifiers are often treated as opaque random values.

But in distributed systems, identifiers can carry valuable structural information.

EUID explores an alternative approach using UUID v8 with deterministic topology encoding, producing identifiers that are:

• time ordered
• infrastructure aware
• database friendly
• fully decodable

If you are interested in the project, feel free to explore the repository or try the library in your own systems.
Feedback and discussion are always welcome you can leave questions in comments.