Metadata-Version: 2.3
Name: fourword
Version: 2.3.0
Requires-Python: >=3.10
Project-URL: GitHub, https://github.com/nercone-dev/fourword/
Description-Content-Type: text/markdown

![](https://assets.nercone.dev/images/thumbnail/fourword.png)

# FourWord
A new random identifier generation method capable of chronological sorting

## Overview
This is a new method for generating random identifiers.
It is designed for use as primary keys in databases and similar applications.

It includes a timestamp at the beginning and uses Base32 Hex as the character set for text conversion, allowing for sorting in chronological order.
Since Z is used instead of = for padding, it should be usable anywhere alphanumeric characters are supported.

To minimize the possibility of collisions while also preventing overflow, the timestamp is not fixed but occupies 1/4 of the total bit length.
This means that simply increasing the total bit length increases the length of the timestamp, allowing for longer continuous usage.

However, a trade-off is that increasing the bit length results in unnecessary leading zeros in the timestamp section.

## Etymology
The "Four" in the name comes from the fact that the timestamp occupies 1/4 of the bit length.
It is also a play on the word "Forward."

## Python Library
```sh
# Install using pip
pip3 install fourword

# Install using uv
uv pip install fourword

# Add to Project using uv
uv add fourword
```

```python
from fourword.lib import FourWord

fourword = FourWord(bits=256)
print(fourword.text)
print(fourword.timestamp.isoformat())
```

```sh
# Show usage
fourword --help
# Generate FourWord ID with default 256 bits
fourword g
# Generate FourWord ID with custom 512 bits
fourword g --bits 512
# Generate FourWord ID and Show with details
fourword g --detail
# Decode FourWord ID and Show with details
fourword i 32OD9FEO1M8G0I7A0CMGMC599N14NJQ9SQAJPT3TRATETRAMBKTGZZZZ
```

You can generate and analyze FourWord using the `fourword` library in Python.

The Python library also includes a `fourword` CLI command.

## Specifications
FourWord is represented as the following byte sequence (big-endian):

```
[ (Total bits/4) bit UNIX timestamp (UTC, ns) ] + [ (Total bits/4*3) bit CSPRNG ]
```

For example, when the total bit length is 256 bits, the timestamp is 64 bits and the random part is 192 bits.

The ratio is fixed so that when retrieving the timestamp from an ID, the exact length can be easily determined without needing a separator.

## Formats
Unlike other methods, FourWord does not strictly require text conversion. It supports multiple formats.

### Text

Text conversion uses a variant of Base32 Hex.

As mentioned above, Z is used instead of = as the padding character, but otherwise, it is identical to Base32 Hex.

**Example**

```
32OD9FEO1M8G0I7A0CMGMC599N14NJQ9SQAJPT3TRATETRAMBKTGZZZZ
```

### Compact Text

Uses Base62 (`0-9A-Za-z`) as the character set.
The byte sequence is interpreted as a big-endian arbitrary-precision integer and converted to Base62.
Zero-padded with `0` at the front so that the same bit length always produces a fixed-length output.

Approximately 76% the length of the Text format.
For example, at 256 bits, the Text format is 56 characters while Compact Text fits in 43 characters.

Note that since Base62 is not a power of 2, bitwise operations cannot be used and arbitrary-precision integer arithmetic is required for decoding.
It also cannot be used in case-insensitive environments.

**Example**

```
5r0NHGp8VYQuT2sVX1OZNDXn9XRg3qar5CsaahtCi7f
```

### Readable Text

Based on the Text format, with the following modifications for human readability:

- Character set is lowercased (`0-9, A-V` → `0-9, a-v`)
- Padding is omitted (since bit length is fixed, it can be restored during decoding)
- A hyphen (`-`) is inserted every 8 characters

**Example**

```
32od9feo-1m8g0i7a-0cmgmc59-9n14njq9-sqajpt3t-ratetram-bktg
```

### Decimal

Interprets the byte sequence as a big-endian unsigned integer, adds `2^N` (where N is the total bit length), and converts to decimal.

```
Decimal = 2^N + (byte_sequence as big-endian unsigned integer)
```

The result always has a fixed number of digits for a given bit length, allowing the bit length to be determined from the digit count alone during decoding.

**Decoding**

Determine N from the digit count, then subtract 2^N to recover the original byte sequence.

**Example**

```
126960030975124059975555195172296441085516613467993543348259724366939612929339
```

### Hex

Simply interprets the byte sequence as a binary number and converts it to hexadecimal.

**Example**

```
18b0d4bdd80d910048ea032d0b30a94dc24bcf49e6953cf47ddabaeeed565d3b
```

## Collision Probability
IDs with different timestamps do not collide. The values below represent the worst-case scenario (all IDs generated within the same nanosecond).

| Bits | Random bit width | IDs for 10⁻¹⁸ collision prob. | IDs for 10⁻⁹ collision prob. | IDs for 50% collision prob. |
|---:|---:|:---|:---|:---|
| 256 | 192 bit | approx 1.12 × 10²⁰ | approx 3.54 × 10²⁴ | approx 9.33 × 10²⁸ |
| 512 | 384 bit | approx 8.88 × 10⁴⁸ | approx 2.81 × 10⁵³ | approx 7.39 × 10⁵⁷ |
| 768 | 576 bit | approx 7.03 × 10⁷⁷ | approx 2.22 × 10⁸² | approx 5.85 × 10⁸⁶ |
| 1024 | 768 bit | approx 5.57 × 10¹⁰⁶ | approx 1.76 × 10¹¹¹ | approx 4.64 × 10¹¹⁵ |
| 1280 | 960 bit | approx 4.41 × 10¹³⁵ | approx 1.40 × 10¹⁴⁰ | approx 3.67 × 10¹⁴⁴ |
| 1536 | 1152 bit | approx 3.50 × 10¹⁶⁴ | approx 1.11 × 10¹⁶⁹ | approx 2.91 × 10¹⁷³ |
| 1792 | 1344 bit | approx 2.77 × 10¹⁹³ | approx 8.76 × 10¹⁹⁷ | approx 2.31 × 10²⁰² |
| 2048 | 1536 bit | approx 2.20 × 10²²² | approx 6.94 × 10²²⁶ | approx 1.83 × 10²³¹ |

## Overflow Timing
Each bit length will overflow at the following times:

| Bits | Timestamp bit width | Max seconds | Overflow timing (approx) |
|---:|---:|:---|:---|
| 256 | 64 bit | approx 1.84 × 10¹⁰ s | approx 2554 years |
| 512 | 128 bit | approx 3.40 × 10²⁹ s | approx 1.08 × 10²² years later |
| 768 | 192 bit | approx 6.28 × 10⁴⁸ s | approx 1.99 × 10⁴¹ years later |
| 1024 | 256 bit | approx 1.16 × 10⁶⁸ s | approx 3.67 × 10⁶⁰ years later |
| 1280 | 320 bit | approx 2.14 × 10⁸⁷ s | approx 6.77 × 10⁷⁹ years later |
| 1536 | 384 bit | approx 3.94 × 10¹⁰⁶ s | approx 1.25 × 10⁹⁹ years later |
| 1792 | 448 bit | approx 7.27 × 10¹²⁵ s | approx 2.30 × 10¹¹⁸ years later |
| 2048 | 512 bit | approx 1.34 × 10¹⁴⁵ s | approx 4.25 × 10¹³⁷ years later |

## License
The source code and library within this repository are free to use under the MIT License.

Credit is not required for software that utilizes the FourWord specification itself or for data generated using FourWord.
