shadowflake 1.0.0

A Python implementation of the Shadowflake UXID format!

Shadowflake

Shadowflake — A high-volume-safe, order-preserving identifier.

---

---

Say hello to Shadowflake, the first of the UXID (Universal Extended Identity Descriptor) family!

What is a UXID?

UXIDs are a new system of identifiers, they are similar to UUIDs but allow extra descriptive information.

Shadowflake does this by behaving primarily as a universally unique, sortable identifier, but allowing you to optionally provide extra descriptive data.

What are Shadowflake's features?

Shadowflake acts as a universally unique identifier, which means it

• has a very large amount of possible values (2⁹⁸, to be exact),
• and is safe to use in decentralised systems.

But, Shadowflake has benefits over normal universally unique identifiers, too! Shadowflake is:

• lexicographically sortable,
• safe to expose publicly (it reveals near zero security-damaging information),
• and is chronologically sortable (up to 24 hours into the past).

How are Shadowflakes structured?

Shadowflakes consist of two main segments, the "core" and the "tail".

All fields of Shadowflakes are encoded with Crockford Base32.

The overall format of a Shadowflake is [SEQUENCE][MILLISECOND][ENTROPY][CORE CHECK SYMBOL]$[SYSTEM].[NODE].[ID]. Everything after the core check symbol is optional, but may be either all present or not present at all. Despite the separators in the tail, the fields are fixed length and may not be any smaller or longer than is standardised. The core check symbol is computed according to the algorithm specified as part of Crockford Base32.

For the exact details of each part of the Shadowflake, see below:

The core

Field	Bits	Range / Size	Description
Sequence	17	0–86,399	Rolling counter representing seconds since the anchor time, wrapping every 24 hours.
Millisecond	10	0–999	Sub-second counter incremented every millisecond.
Entropy	98	298 possible values	Cryptographically secure random data used to prevent collisions.

The tail

Field	Type	Bits	Base32 Chars	Description
System	ASCII	80	16	Logical system or protocol name. ASCII text encoded as bytes. (Max 10 characters)
Node	ASCII	80	16	Subsystem, node, or instance identifier. ASCII text encoded as bytes. (Max 10 characters)
ID	Integer	30	6	Application-specific numeric identifier. Encoded as an unsigned integer.

How do I install Shadowflake?

Shadowflake provides two methods of use, as a library in Python code, and as a standalone program. The standalone program is usable interactively, or as a simple CLI tool. If you want a nice, formatted interactive experience, install Shadowflake with the fancy extra.

The standalone program is usable without [fancy], it will just be a bit more ugly. If you want more info on the standalone program, run shadowflake --help.

With pip

pip install shadowflake

With uv

uv add shadowflake

or

uv pip install shadowflake

Usage

As a library

from shadowflake import Shadowflake

# Generate a simple Shadowflake
uuid = Shadowflake.generate()
print(uuid)  # e.g., "01234ABCDEFGHJKMNPQRSTV5"

# Generate with metadata
uuid = Shadowflake.generate(
    system="AUTH",
    node="API-01",
    id=12345
)
print(uuid)  # e.g., "01234ABCDEFGHJKMNPQRSTV5$..."

# Decode a Shadowflake
result = Shadowflake.decode(uuid)
print(result)

As a CLI tool

shadowflake generate
# ═══════════════════════════════════════════════════════════
#               Generated Shadowflake
# ═══════════════════════════════════════════════════════════
# 01G2XKMNPQRSTVWXYZ34567890AB
# ═══════════════════════════════════════════════════════════

shadowflake decode 01G2XKMNPQRSTVWXYZ34567890AB
# ═══════════════════════════════════════════════════════════
#               Decoded Shadowflake
# ═══════════════════════════════════════════════════════════
# sequence: 45123
# millisecond: 456
# entropy: 123456789012345678901234567890
# system: None
# node: None
# id: None
# valid: True
# ═══════════════════════════════════════════════════════════

License

Copyright (C) 2026 ItsThatOneJack

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.