Docs Reference
Hub Registry program
The hub_registry Solana program. Every account, instruction, event and error, and how to read hub and membership state at an epoch.
hub_registry is the Solana program where hubs are registered by code and location with a deposit, and where validators join them by identity. Joins, leaves and moves take effect at the next epoch boundary. A hub that stays below its member floor past the inactivity period can be released by anyone. Epoch always means the Solana Clock epoch.
| Program | hub_registry |
| Program id | ABjgHL8TcjxUjx6vfwsVQyvxiXR6pFgMkeESgwK6CbDm |
| Version | 0.1.0 |
The program id is the same on every cluster. The IDL and its TypeScript types are hub_registry.json and hub_registry.ts, built with Anchor 0.31.1.
Configuration
The registry is configured once, by the program's upgrade authority, in initialize. There is no update instruction.
| Setting | Local validator |
|---|---|
deposit_lamports | 1,000,000,000 (1 SOL) |
registration_fee_bps | 500, so the registration fee is 5% of the deposit |
cooldown_epochs | 1 |
inactivity_epochs | 4 |
min_members | 4 (n_min) |
code_min_len, code_max_len | 3 and 8 |
The live values are served by GET /v1/registry/config.
Accounts
| Account | Address |
|---|---|
| Registry | PDA ["registry"] |
| FeeVault | PDA ["fee_vault"] |
| Hub | PDA ["hub", code] |
| Membership | PDA ["member", identity] |
Registry
The configuration and the count of hubs ever registered.
Discriminator: 2f ae 6e f6 b8 b6 fc da, then the fields in order, Borsh-encoded.
| Field | Type | Meaning |
|---|---|---|
authority | pubkey | the upgrade authority that initialized the registry |
fee_destination | pubkey | where sweep_fees sends the fee vault's balance |
fee_vault | pubkey | the FeeVault address |
deposit_lamports | u64 | the deposit a hub registration locks in the hub account |
registration_fee_bps | u16 | registration fee, in basis points of the deposit |
cooldown_epochs | u64 | epochs after a leave or move takes effect before the validator can change again |
inactivity_epochs | u64 | a hub is releasable once the epoch is past its last active epoch by more than this |
min_members | u32 | members a hub needs in an epoch to count as active (n_min) |
code_min_len | u8 | a code is code_min_len..=code_max_len characters, each A-Z |
code_max_len | u8 | the longest code accepted |
hubs_registered | u64 | hubs ever registered. The next hub's id is this plus one |
bump | u8 | the PDA bump |
FeeVault
Registration fees sit in this account's lamports above its rent. No key signs for it; sweep_fees sends them to fee_destination.
Discriminator: c0 b2 45 e8 3a 95 9d 84, then the fields in order, Borsh-encoded.
| Field | Type | Meaning |
|---|---|---|
bump | u8 | the PDA bump |
Hub
One registered hub. The deposit sits in the account's lamports above its rent.
Discriminator: 8f bd 04 78 a9 ea 0e 7d, then the fields in order, Borsh-encoded.
| Field | Type | Meaning |
|---|---|---|
id | u64 | unique per registration: a code registered again after a release gets a new id |
code | [u8; 8] | the code, padded with zero bytes |
location | Location | where the hub is; Location |
registrant | pubkey | who registered the hub and receives the deposit back on release |
deposit_lamports | u64 | held in this account above its rent |
members | u32 | members in effect during counted_epoch |
joining | u32 | joins that take effect at counted_epoch + 1 |
leaving | u32 | departures that take effect at counted_epoch + 1 |
counted_epoch | u64 | the epoch the three counts above were last brought up to |
created_epoch | u64 | the epoch the hub was registered |
last_active_epoch | u64 | the last epoch with at least min_members members in effect, as of counted_epoch. Equal to created_epoch for a hub that has never been active |
bump | u8 | the PDA bump |
Membership
One validator identity's membership, its pending change and its cooldown.
Discriminator: e7 8d b4 62 6d a8 af a6, then the fields in order, Borsh-encoded.
| Field | Type | Meaning |
|---|---|---|
identity | pubkey | the validator identity |
hub | pubkey | the member's hub, or the default key when it has none |
hub_id | u64 | the id of hub when the member joined it |
joined_epoch | u64 | the epoch of the join or move that led to hub |
effective_epoch | u64 | the first epoch the membership in hub counts |
pending | Pending | a leave or move waiting for pending_epoch. From that epoch on it is in effect, whether or not an instruction has written it into hub yet |
pending_hub | pubkey | the hub of a pending move |
pending_hub_id | u64 | the id of pending_hub |
pending_epoch | u64 | the epoch the pending change takes effect |
cooldown_until_epoch | u64 | no join, leave or move before this epoch |
bump | u8 | the PDA bump |
Location
| Field | Type | Meaning |
|---|---|---|
x | i32 | metres from the Earth's centre toward 0° latitude, 0° longitude |
y | i32 | metres toward 0° latitude, 90° east |
z | i32 | metres toward the North Pole |
Pending
| Variant | Index | Meaning |
|---|---|---|
None | 0 | no change waiting |
Leave | 1 | a leave takes effect at pending_epoch |
Move | 2 | a move to pending_hub takes effect at pending_epoch |
Config
| Field | Type | Meaning |
|---|---|---|
fee_destination | pubkey | where sweep_fees sends the fee vault's balance |
deposit_lamports | u64 | the deposit per hub |
registration_fee_bps | u16 | the registration fee, in basis points of the deposit, at most 10,000 |
cooldown_epochs | u64 | epochs after a leave or move takes effect before the next change |
inactivity_epochs | u64 | epochs past its last active epoch after which a hub is releasable |
min_members | u32 | members a hub needs in an epoch to be active (n_min) |
code_min_len | u8 | the shortest code accepted, at least 1 |
code_max_len | u8 | the longest code accepted, at most 8 |
Instructions
Every instruction but initialize emits its event by self CPI, so its accounts end with event_authority and program.
| Instruction | Signers | Does |
|---|---|---|
initialize | the program's upgrade authority | creates the registry and the fee vault with the configuration |
register_hub | registrant | registers a hub; deposit into the hub account, fee into the fee vault |
join_hub | identity, payer | joins a hub from the next epoch |
leave_hub | identity | leaves at the next epoch boundary; starts the cooldown |
move_hub | identity | moves to another hub at the next epoch boundary; starts the cooldown |
release_hub | anyone | closes an inactive hub; deposit and rent back to the registrant |
sweep_fees | anyone | sends the fee vault's balance above rent to fee_destination |
initialize
Creates Registry and FeeVault. Only the upgrade authority recorded in the program's ProgramData account can call it, so the configuration cannot be set by whoever sends the first transaction after a deploy. registration_fee_bps is at most 10,000; code_min_len is at least 1, at most code_max_len, which is at most 8.
Discriminator: af af 6d 1f 0d 98 9b ed.
| Arg | Type | Meaning |
|---|---|---|
config | Config | the registry's configuration |
| # | Account | Writable | Signer | Address | Meaning |
|---|---|---|---|---|---|
| 0 | authority | yes | yes | the program's upgrade authority; pays for both accounts | |
| 1 | registry | yes | PDA ["registry"] | created | |
| 2 | fee_vault | yes | PDA ["fee_vault"] | created | |
| 3 | program | ABjgHL8TcjxUjx6vfwsVQyvxiXR6pFgMkeESgwK6CbDm | this program | ||
| 4 | program_data | this program's ProgramData, whose upgrade authority must be authority | |||
| 5 | system_program | System program |
register_hub
Creates the hub under code. The registrant pays deposit_lamports into the hub account and deposit_lamports × registration_fee_bps / 10,000 into the fee vault. The code is capitals A to Z within the registry's length range. The location is a point between 6,300 km and 6,400 km from the Earth's centre. The hub gets the next id, hubs_registered + 1.
Discriminator: 6a 26 08 a8 ea 75 14 44.
| Arg | Type | Meaning |
|---|---|---|
code | string | capitals A to Z, within the registry's length range |
location | Location | ECEF in whole metres, 6,300 to 6,400 km from the Earth's centre |
| # | Account | Writable | Signer | Address | Meaning |
|---|---|---|---|---|---|
| 0 | registrant | yes | yes | pays the deposit, the fee and the rent | |
| 1 | registry | yes | PDA ["registry"] | ||
| 2 | hub | yes | PDA ["hub", code] | created | |
| 3 | fee_vault | yes | receives the fee | ||
| 4 | system_program | System program | |||
| 5 | event_authority | PDA ["__event_authority"] | self-CPI event signer | ||
| 6 | program | this program |
join_hub
The validator identity joins a hub. The membership is created on the identity's first join and counts from the next epoch. A first join starts no cooldown. payer pays the membership's rent, so an operator wallet can pay while the validator identity signs; both may be the same key.
Discriminator: 4e bd d6 1b 13 ad ce 67.
Args: none.
| # | Account | Writable | Signer | Address | Meaning |
|---|---|---|---|---|---|
| 0 | payer | yes | yes | pays the membership's rent | |
| 1 | identity | yes | the validator identity | ||
| 2 | registry | PDA ["registry"] | |||
| 3 | hub | yes | the hub to join | ||
| 4 | membership | yes | PDA ["member", identity] | created on the first join | |
| 5 | system_program | System program | |||
| 6 | event_authority | PDA ["__event_authority"] | self-CPI event signer | ||
| 7 | program | this program |
leave_hub
The membership ends at the next epoch boundary. Accepted once the membership is in effect, nothing is pending and the cooldown is over.
Discriminator: 87 4e fd b5 1d 2b f9 76.
Args: none.
| # | Account | Writable | Signer | Address | Meaning |
|---|---|---|---|---|---|
| 0 | identity | yes | the validator identity | ||
| 1 | registry | PDA ["registry"] | |||
| 2 | hub | yes | the member's hub, checked against the membership; may have been released since the member joined | ||
| 3 | membership | yes | PDA ["member", identity] | ||
| 4 | event_authority | PDA ["__event_authority"] | self-CPI event signer | ||
| 5 | program | this program |
move_hub
The member changes hub at the next epoch boundary, under the same conditions as a leave.
Discriminator: 25 47 b0 2a 9b 8d 72 26.
Args: none.
| # | Account | Writable | Signer | Address | Meaning |
|---|---|---|---|---|---|
| 0 | identity | yes | the validator identity | ||
| 1 | registry | PDA ["registry"] | |||
| 2 | from_hub | yes | the member's hub, checked against the membership; may have been released since the member joined | ||
| 3 | to_hub | yes | the hub to move to | ||
| 4 | membership | yes | PDA ["member", identity] | ||
| 5 | event_authority | PDA ["__event_authority"] | self-CPI event signer | ||
| 6 | program | this program |
release_hub
Closes a hub whose epoch is past last_active_epoch + inactivity_epochs. The deposit and the account's rent return to the registrant, and the code is free to register again. It does not wait for the last member to leave; the new hub at that address has a new id.
Discriminator: 5d c6 bc 5d 12 16 e1 24.
Args: none.
| # | Account | Writable | Signer | Address | Meaning |
|---|---|---|---|---|---|
| 0 | registry | PDA ["registry"] | |||
| 1 | hub | yes | closed | ||
| 2 | registrant | yes | the hub's registrant; receives the deposit and the rent | ||
| 3 | event_authority | PDA ["__event_authority"] | self-CPI event signer | ||
| 4 | program | this program |
sweep_fees
Sends everything the fee vault holds above its rent to the registry's fee_destination. Anyone can call it, since the destination is fixed in the registry.
Discriminator: af e1 62 47 76 42 22 94.
Args: none.
| # | Account | Writable | Signer | Address | Meaning |
|---|---|---|---|---|---|
| 0 | registry | PDA ["registry"] | |||
| 1 | fee_vault | yes | |||
| 2 | destination | yes | the registry's fee_destination | ||
| 3 | event_authority | PDA ["__event_authority"] | self-CPI event signer | ||
| 4 | program | this program |
Reading the state
A hub's count and a membership at any epoch e are known from their own accounts, without a crank.
Members of a hub at epoch e. members when e equals counted_epoch; members + joining − leaving when e is later.
A membership at epoch e. When pending is not None and e ≥ pending_epoch, the change is in effect: since pending_epoch the member is in pending_hub (a move) or in no hub (a leave). Otherwise the member belongs to hub, counting from effective_epoch. The next instruction on the membership writes a change in effect into hub.
A membership whose hub was released. Its hub_id differs from the id of the hub account at that address, or the account is gone. It counts for no hub; the identity leaves or moves as usual.
Hub activity. A hub is active in an epoch when at least min_members memberships are in effect in it. Every instruction that touches a hub first brings its counts up to the current epoch and advances last_active_epoch; between two instructions the count does not change, so no epoch is missed. A hub never active has last_active_epoch equal to created_epoch.
Releasable. e > last_active_epoch + inactivity_epochs. A new hub's period counts from its creation epoch, so it has inactivity_epochs epochs to gather its members.
Cooldown. cooldown_until_epoch is the epoch a leave or move takes effect plus cooldown_epochs. With a cooldown of 1, a move sent in epoch E is in effect from E+1 and the next change is accepted from E+2.
The stake floor, ρ_min = 1 %% of total stake, is applied by the proposer schedule from a stake snapshot; on chain, last_active_epoch tracks the member floor.
Events
| Event | Fields | Emitted by |
|---|---|---|
FeesSwept | destination: pubkey; lamports: u64 | sweep_fees |
HubRegistered | hub: pubkey; id: u64; code: [u8; 8]; location: Location; registrant: pubkey; deposit_lamports: u64; fee_lamports: u64; epoch: u64 | register_hub |
HubReleased | hub: pubkey; id: u64; code: [u8; 8]; registrant: pubkey; returned_lamports: u64; epoch: u64 | release_hub |
MemberJoined | identity: pubkey; hub: pubkey; hub_id: u64; effective_epoch: u64 | join_hub |
MemberLeaving | identity: pubkey; hub: pubkey; hub_id: u64; effective_epoch: u64; cooldown_until_epoch: u64 | leave_hub |
MemberMoving | identity: pubkey; from_hub: pubkey; from_hub_id: u64; to_hub: pubkey; to_hub_id: u64; effective_epoch: u64; cooldown_until_epoch: u64 | move_hub |
Errors
Anchor custom errors, returned as custom program error: 0x… with the code below.
| Code | Name | Message |
|---|---|---|
| 6000 | NotUpgradeAuthority | Only the program's upgrade authority can initialize the registry |
| 6001 | InvalidConfig | The configuration is out of range |
| 6002 | InvalidCode | A hub code is capital letters A-Z within the registry's length range |
| 6003 | InvalidLocation | The location is not an ECEF point near the Earth's surface, in metres |
| 6004 | AlreadyMember | The validator is already a member of a hub |
| 6005 | NotAMember | The validator is not a member of a hub |
| 6006 | WrongHub | The hub account is not the member's hub |
| 6007 | SameHub | The validator is already in that hub |
| 6008 | MembershipPending | The membership takes effect at the next epoch boundary |
| 6009 | ChangePending | A leave or move is already waiting for the next epoch boundary |
| 6010 | CooldownActive | The validator's cooldown has not ended |
| 6011 | HubNotInactive | The hub has not been inactive for the registry's period |
| 6012 | NothingToSweep | The fee vault holds nothing above its rent |