Ozcorps.UuidV8 1.0.0

Ozcorps.UuidV8

RFC 9562 UUIDv8 generator for .NET. Produces time-ordered, monotonic GUIDs with a cryptographically random tail.

Bit layout

Without NodeId (default):
┌────────────────────────┬─────┬──────────────┬──────┬─────────────────────────────────────────────────────────────┐
│     48-bit unix_ts_ms  │ v=8 │  12-bit seq  │ 0b10 │                       62-bit random                        │
└────────────────────────┴─────┴──────────────┴──────┴─────────────────────────────────────────────────────────────┘

With NodeId:
┌────────────────────────┬─────┬──────────────┬──────┬────────────────┬────────────────────────────────────────────┐
│     48-bit unix_ts_ms  │ v=8 │  12-bit seq  │ 0b10 │ 10-bit node_id │                  52-bit random             │
└────────────────────────┴─────┴──────────────┴──────┴────────────────┴────────────────────────────────────────────┘

• 48 bits — Unix timestamp in milliseconds (time-ordered)
• 4 bits — version = 8
• 12 bits — monotonic sequence counter (up to 4 096 IDs/ms per node before auto-advancing the clock)
• 2 bits — variant = 0b10 (RFC 4122 / RFC 9562)
• 10 bits — optional node identifier (0–1023), guarantees cross-machine uniqueness
• 52 / 62 bits — cryptographically random (RandomNumberGenerator)

Installation

dotnet add package Ozcorps.UuidV8

Usage

Standalone (no DI)

// Default options — no NodeId, 62 random bits
Guid id = UuidV8Generator.NewId();

// Per-call options
Guid id = UuidV8Generator.NewId(new UuidV8Options { NodeId = 1 });

Configure once at startup

UuidV8Generator.Configure(new UuidV8Options { NodeId = 1 });

// Everywhere in your app:
Guid id = UuidV8Generator.NewId();

With dependency injection

Use the Ozcorps.UuidV8.EntityFrameworkCore package for IServiceCollection integration.

NodeId

NodeId is a 10-bit value (0–1023). Assign a unique value per machine or application instance to guarantee global uniqueness across nodes. When 0 (default), those bits are filled with random data — safe for single-node or low-collision scenarios.

Thread safety

UuidV8Generator is fully thread-safe. The internal sequence counter and timestamp are protected by a lock.

Compatibility

Targets net8.0 — works on .NET 8, 9, and 10+.