ISCC-ID

A globally unique, owned, and short identifier for digital assets.

The ISCC-ID is a 64-bit identifier constructed from a timestamp and a HUB-ID: - First 52 bits: UTC time in microseconds since UNIX epoch (1970-01-01T00:00:00Z) - Last 12 bits: ID of the timestamping HUB (0-4095)

With this structure: - A single HUB can issue up to 1 million timestamps per second until the year 2112 - The system supports up to 4096 timestamp HUBs (IDs 0-4095) - Timestamps are globally unique and support total ordering in both integer and base32hex forms - The theoretical maximum throughput is ~4 billion unique timestamps per second

ISCC-IDs are issued and digitally signed by authoritative ISCC-HUB servers in a federated system. A valid ISCC-ID is guaranteed to be bound to an owner represented by a cryptographic public key. The rules by which ISCC-IDs can be verified and resolved are defined by the ISCC Discovery Protocol (IDP).

The module also contains legacy support for the older v0 ISCC-ID format that was based on blockchain wallet addresses and similarity-hashes of ISCC-CODE units.

gen_iscc_id(timestamp = None, hub_id = 0, realm_id = 0)

Generate ISCC-ID from microsecond timestamp with the latest standard algorithm.

Parameters:

Name	Type	Description	Default
timestamp	int	Microseconds since 1970-01-01T00:00:00Z (must be < 2^52)	None
hub_id	int	HUB-ID that issued the ISCC-ID (0-4095)	0
realm_id	int	Realm ID for the ISCC-ID (0 for testnet, 1 for mainnet, default: 0)	0

Returns:

Type	Description
dict	Dictionary with the ISCC-ID under the key 'iscc'

Raises:

Type	Description
ValueError	If an input is invalid

gen_iscc_id_v1(timestamp = None, hub_id = 0, realm_id = 0)

Generate an ISCC-ID from a timestamp and a HUB-ID with algorithm v1.

If no arguments are provided, a new ISCC-ID is generated with the current system time and both hub_id and realm_id set to 0 (testnet).

The ISCC-IDv1 is a 64-bit identifier constructed from a timestamp and a HUB-ID: - First 52 bits: UTC time in microseconds since UNIX epoch (1970-01-01T00:00:00Z) - Last 12 bits: ID of the timestamping HUB (0-4095)

With this structure: - A single HUB can issue up to 1 million timestamps per second until the year 2112 - The system supports up to 4096 timestamp HUBs (IDs 0-4095) - Timestamps are globally unique and support total ordering in both integer and base32hex forms - The theoretical maximum system throughput is ~4 billion unique timestamps per second

If the ID space becomes crowded, it can be extended by introducing additional REALMS via ISCC-HEADER SUBTYPEs.

Issuing ISCC-IDs

ISCC-IDv1s are issued and digitally signed by authoritative ISCC-HUB servers in a federated system. A valid ISCC-IDv1 is guaranteed to be bound to an owner represented by a cryptographic public key. The rules by which ISCC-IDv1 can be verified and resolved are defined by the ISCC Discovery Protocol (IDP).

Timestamp Requirements

Timestamp issuing requires: - A time source with at least microsecond precision - Strictly monotonic (always increasing) integer timestamps - Measures to prevent front-running of actual time

Realm ID Reservations

Realm-ID 0 is reserved for testnet purposes. An ISCC-IDv1 with Realm-ID 0: - Is intended for testing and development - Should not be used in production systems - May not guarantee global uniqueness

Realm-ID 1 is the first operational mainnet Realm-ID for production use.

Technical Format

The ISCC-IDv1 has the following format: - Scheme Prefix: ISCC: - Base32-Encoded concatenation of: - 16-bit header: - MAINTYPE = "0110" (ISCC-ID) - SUBTYPE = "0000" (REALM, configurable via realm_id) - VERSION = "0001" (V1) - LENGTH = "0001" (64-bit) - 52-bit timestamp: Microseconds since 1970-01-01T00:00:00Z - 12-bit HUB-ID: The HUB ID (0-4095)

Parameters:

Name	Type	Description	Default
timestamp	int	Microseconds since 1970-01-01T00:00:00Z (must be < 2^52)	None
hub_id	int	HUB-ID that issued the ISCC-ID (0-4095)	0
realm_id	int	Realm ID for the ISCC-ID (0 for testnet, 1 for mainnet, default: 0)	0

Returns:

Type	Description
dict	Dictionary with the ISCC-ID under the key 'iscc'

Raises:

Type	Description
ValueError	If an input is invalid

gen_iscc_id_v0(iscc_code, chain_id, wallet, uc = 0)

Generate an ISCC-ID from an ISCC-CODE with uniqueness counter 'uc' with algorithm v0.

Parameters:

Name	Type	Description	Default
iscc_code	str	The ISCC-CODE from which to mint the ISCC-ID.	required
chain_id	int	Chain-ID of blockchain from which the ISCC-ID is minted.	required
wallet	str	The wallet address that signes the ISCC declaration	required
uc	int	Uniqueness counter of ISCC-ID.	0

Returns:

Type	Description
dict	ISCC object with an ISCC-ID

soft_hash_iscc_id_v0(iscc_code, wallet, uc = 0)

Calculate ISCC-ID hash digest from ISCC-CODE with algorithm v0.

Accepts an ISCC-CODE or any sequence of ISCC-UNITs.

Parameters:

Name	Type	Description	Default
iscc_code	str	ISCC-CODE	required
wallet	str	The wallet address that signes the ISCC declaration	required
uc	int	Uniqueness counter for ISCC-ID.	0

Returns:

Type	Description
bytes	Digest for ISCC-ID without header but including uniqueness counter.

iscc_id_incr(iscc_id)

Increment uniqueness counter of an ISCC-ID.

Note: Only ISCC-IDv0 supports uniqueness counters. ISCC-IDv1 uses timestamps and will raise an error if passed to this function.

Parameters:

Name	Type	Description	Default
iscc_id	str	Base32-encoded ISCC-ID.	required

Returns:

Type	Description
str	Base32-encoded ISCC-ID with counter incremented by one.

Raises:

Type	Description
ValueError	If the ISCC-ID is v1 (which doesn't support counters).

iscc_id_incr_v0(iscc_id)

Increment uniqueness counter of an ISCC-ID with algorithm v0.

Parameters:

Name	Type	Description	Default
iscc_id	str	Base32-encoded ISCC-ID.	required

Returns:

Type	Description
str	Base32-encoded ISCC-ID with counter incremented by one (without "ISCC:" prefix).

alg_simhash_from_iscc_id(iscc_id, wallet)

Extract similarity preserving hex-encoded hash digest from ISCC-ID

We need to un-xor the ISCC-ID hash digest with the wallet address hash to obtain the similarity preserving bytestring.