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.
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:
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.
|
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
Assigning and Revoking
Pool rows are fixed. Assigning and revoking never change a row's address — only whether it is taken or free:
-
Assign — the first free slot is handed out: the lowest index whose
idis<null>. A new client always fills the earliest gap in the pool. -
Revoke — the row is not deleted; its identity fields (
id, name, keys, timestamps) are set to<null>. The IPv4/IPv6 pair stays in place in the pool and becomes reusable.
The upshot: revoking never breaks the address sequence — it only frees that index, and the next client fills it. Pool addresses are always contiguous; the only thing that changes is which index is taken.
What Happens on CIDR Change?
When the CIDR prefix is changed, the pool is rebuilt from scratch. Client identities (keys, name, UUID) are preserved.
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:
The IPv4 gap here reports a break in the pool's address sequence — a
sign of corruption. It has nothing to do with a revoked (free) slot: a free slot is the pool's
normal state and is not an error.