Balance System (Terazi)

Terazi is the balancing mechanism that deterministically pairs the pool of IPv4 and IPv6 addresses.

How It Works?

Terazi manages both protocol families through a single coordinate system: index.

When a subnet is created, IPv4 and IPv6 addresses are locked to each other through this index:

The essence of the structure is this: IPv4 capacity is taken as the base, and IPv6 shapes itself accordingly. When the prefix length changes, both protocols are resized simultaneously and symmetry is preserved under all conditions.

Loading Diagram

Please wait...

Prefix Conversion

Reference implementation — phantom_daemon/base/wallet/wallet.py:

Both protocols share the same host bit count. The IPv4 prefix directly determines the IPv6 prefix — two lines of conversion, guaranteed symmetry across two pools:

Loading Diagram

Please wait...

Pool Structure

Addresses are pre-populated in the database (wallet.db → users table). Each row is an IPv4/IPv6 pair. Empty slots wait as <null>. When a client is assigned, keys, name and timestamps are filled in.

0 assigned

5 free

/29

ipv4_address	ipv6_address	id	name	private_key_hex	public_key_hex	preshared_key_hex	created_at	updated_at
10.8.0.2	fd00:70:68::2	<null>	<null>	<null>	<null>	<null>	<null>	<null>
10.8.0.3	fd00:70:68::3	<null>	<null>	<null>	<null>	<null>	<null>	<null>
10.8.0.4	fd00:70:68::4	<null>	<null>	<null>	<null>	<null>	<null>	<null>
10.8.0.5	fd00:70:68::5	<null>	<null>	<null>	<null>	<null>	<null>	<null>
10.8.0.6	fd00:70:68::6	<null>	<null>	<null>	<null>	<null>	<null>	<null>

Simulated wallet.db users table — subnet /29 — 5 usable slots

What Happens on CIDR Change?

When the CIDR prefix is changed, the pool is rebuilt from scratch. Client identities (keys, name, UUID) are preserved.

IP addresses may change.

Clients are re-assigned sequentially from index 2 in their original creation order — any gaps from revoked clients are closed. If there are no gaps and the subnet base is unchanged, addresses may be preserved; however, this is not guaranteed. All WireGuard configurations must be re-exported.

Loading Diagram

Please wait...

Validation

The GET /api/core/network/validate endpoint verifies the pool's Terazi symmetry and structural integrity. Successful response:

If a Terazi index mismatch or address gap is detected, valid: false is returned with an error list:

Loading Diagram

Please wait...