NETSoon

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.

Programhub_registry
Program idABjgHL8TcjxUjx6vfwsVQyvxiXR6pFgMkeESgwK6CbDm
Version0.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.

SettingLocal validator
deposit_lamports1,000,000,000 (1 SOL)
registration_fee_bps500, so the registration fee is 5% of the deposit
cooldown_epochs1
inactivity_epochs4
min_members4 (n_min)
code_min_len, code_max_len3 and 8

The live values are served by GET /v1/registry/config.

Accounts

AccountAddress
RegistryPDA ["registry"]
FeeVaultPDA ["fee_vault"]
HubPDA ["hub", code]
MembershipPDA ["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.

FieldTypeMeaning
authoritypubkeythe upgrade authority that initialized the registry
fee_destinationpubkeywhere sweep_fees sends the fee vault's balance
fee_vaultpubkeythe FeeVault address
deposit_lamportsu64the deposit a hub registration locks in the hub account
registration_fee_bpsu16registration fee, in basis points of the deposit
cooldown_epochsu64epochs after a leave or move takes effect before the validator can change again
inactivity_epochsu64a hub is releasable once the epoch is past its last active epoch by more than this
min_membersu32members a hub needs in an epoch to count as active (n_min)
code_min_lenu8a code is code_min_len..=code_max_len characters, each A-Z
code_max_lenu8the longest code accepted
hubs_registeredu64hubs ever registered. The next hub's id is this plus one
bumpu8the 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.

FieldTypeMeaning
bumpu8the 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.

FieldTypeMeaning
idu64unique per registration: a code registered again after a release gets a new id
code[u8; 8]the code, padded with zero bytes
locationLocationwhere the hub is; Location
registrantpubkeywho registered the hub and receives the deposit back on release
deposit_lamportsu64held in this account above its rent
membersu32members in effect during counted_epoch
joiningu32joins that take effect at counted_epoch + 1
leavingu32departures that take effect at counted_epoch + 1
counted_epochu64the epoch the three counts above were last brought up to
created_epochu64the epoch the hub was registered
last_active_epochu64the 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
bumpu8the 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.

FieldTypeMeaning
identitypubkeythe validator identity
hubpubkeythe member's hub, or the default key when it has none
hub_idu64the id of hub when the member joined it
joined_epochu64the epoch of the join or move that led to hub
effective_epochu64the first epoch the membership in hub counts
pendingPendinga 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_hubpubkeythe hub of a pending move
pending_hub_idu64the id of pending_hub
pending_epochu64the epoch the pending change takes effect
cooldown_until_epochu64no join, leave or move before this epoch
bumpu8the PDA bump

Location

FieldTypeMeaning
xi32metres from the Earth's centre toward 0° latitude, 0° longitude
yi32metres toward 0° latitude, 90° east
zi32metres toward the North Pole

Pending

VariantIndexMeaning
None0no change waiting
Leave1a leave takes effect at pending_epoch
Move2a move to pending_hub takes effect at pending_epoch

Config

FieldTypeMeaning
fee_destinationpubkeywhere sweep_fees sends the fee vault's balance
deposit_lamportsu64the deposit per hub
registration_fee_bpsu16the registration fee, in basis points of the deposit, at most 10,000
cooldown_epochsu64epochs after a leave or move takes effect before the next change
inactivity_epochsu64epochs past its last active epoch after which a hub is releasable
min_membersu32members a hub needs in an epoch to be active (n_min)
code_min_lenu8the shortest code accepted, at least 1
code_max_lenu8the 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.

InstructionSignersDoes
initializethe program's upgrade authoritycreates the registry and the fee vault with the configuration
register_hubregistrantregisters a hub; deposit into the hub account, fee into the fee vault
join_hubidentity, payerjoins a hub from the next epoch
leave_hubidentityleaves at the next epoch boundary; starts the cooldown
move_hubidentitymoves to another hub at the next epoch boundary; starts the cooldown
release_hubanyonecloses an inactive hub; deposit and rent back to the registrant
sweep_feesanyonesends 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.

ArgTypeMeaning
configConfigthe registry's configuration
#AccountWritableSignerAddressMeaning
0authorityyesyesthe program's upgrade authority; pays for both accounts
1registryyesPDA ["registry"]created
2fee_vaultyesPDA ["fee_vault"]created
3programABjgHL8TcjxUjx6vfwsVQyvxiXR6pFgMkeESgwK6CbDmthis program
4program_datathis program's ProgramData, whose upgrade authority must be authority
5system_programSystem 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.

ArgTypeMeaning
codestringcapitals A to Z, within the registry's length range
locationLocationECEF in whole metres, 6,300 to 6,400 km from the Earth's centre
#AccountWritableSignerAddressMeaning
0registrantyesyespays the deposit, the fee and the rent
1registryyesPDA ["registry"]
2hubyesPDA ["hub", code]created
3fee_vaultyesreceives the fee
4system_programSystem program
5event_authorityPDA ["__event_authority"]self-CPI event signer
6programthis 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.

#AccountWritableSignerAddressMeaning
0payeryesyespays the membership's rent
1identityyesthe validator identity
2registryPDA ["registry"]
3hubyesthe hub to join
4membershipyesPDA ["member", identity]created on the first join
5system_programSystem program
6event_authorityPDA ["__event_authority"]self-CPI event signer
7programthis 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.

#AccountWritableSignerAddressMeaning
0identityyesthe validator identity
1registryPDA ["registry"]
2hubyesthe member's hub, checked against the membership; may have been released since the member joined
3membershipyesPDA ["member", identity]
4event_authorityPDA ["__event_authority"]self-CPI event signer
5programthis 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.

#AccountWritableSignerAddressMeaning
0identityyesthe validator identity
1registryPDA ["registry"]
2from_hubyesthe member's hub, checked against the membership; may have been released since the member joined
3to_hubyesthe hub to move to
4membershipyesPDA ["member", identity]
5event_authorityPDA ["__event_authority"]self-CPI event signer
6programthis 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.

#AccountWritableSignerAddressMeaning
0registryPDA ["registry"]
1hubyesclosed
2registrantyesthe hub's registrant; receives the deposit and the rent
3event_authorityPDA ["__event_authority"]self-CPI event signer
4programthis 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.

#AccountWritableSignerAddressMeaning
0registryPDA ["registry"]
1fee_vaultyes
2destinationyesthe registry's fee_destination
3event_authorityPDA ["__event_authority"]self-CPI event signer
4programthis 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

EventFieldsEmitted by
FeesSweptdestination: pubkey; lamports: u64sweep_fees
HubRegisteredhub: pubkey; id: u64; code: [u8; 8]; location: Location; registrant: pubkey; deposit_lamports: u64; fee_lamports: u64; epoch: u64register_hub
HubReleasedhub: pubkey; id: u64; code: [u8; 8]; registrant: pubkey; returned_lamports: u64; epoch: u64release_hub
MemberJoinedidentity: pubkey; hub: pubkey; hub_id: u64; effective_epoch: u64join_hub
MemberLeavingidentity: pubkey; hub: pubkey; hub_id: u64; effective_epoch: u64; cooldown_until_epoch: u64leave_hub
MemberMovingidentity: pubkey; from_hub: pubkey; from_hub_id: u64; to_hub: pubkey; to_hub_id: u64; effective_epoch: u64; cooldown_until_epoch: u64move_hub

Errors

Anchor custom errors, returned as custom program error: 0x… with the code below.

CodeNameMessage
6000NotUpgradeAuthorityOnly the program's upgrade authority can initialize the registry
6001InvalidConfigThe configuration is out of range
6002InvalidCodeA hub code is capital letters A-Z within the registry's length range
6003InvalidLocationThe location is not an ECEF point near the Earth's surface, in metres
6004AlreadyMemberThe validator is already a member of a hub
6005NotAMemberThe validator is not a member of a hub
6006WrongHubThe hub account is not the member's hub
6007SameHubThe validator is already in that hub
6008MembershipPendingThe membership takes effect at the next epoch boundary
6009ChangePendingA leave or move is already waiting for the next epoch boundary
6010CooldownActiveThe validator's cooldown has not ended
6011HubNotInactiveThe hub has not been inactive for the registry's period
6012NothingToSweepThe fee vault holds nothing above its rent