> For the complete documentation index, see [llms.txt](https://docs.talus.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talus.network/reference/move/nexus_registry/leader.md).
# leader
* [Struct `LeaderCapabilitiesAdminCap`](#struct-leadercapabilitiesadmincap)
* [Struct `CapabilityManger`](#struct-capabilitymanger)
* [Struct `LeaderRegistry`](#struct-leaderregistry)
* [Struct `LeaderRegistryInnerV1`](#struct-leaderregistryinnerv1)
* [Struct `StakeManager`](#struct-stakemanager)
* [Struct `StakePosition`](#struct-stakeposition)
* [Struct `Metadata`](#struct-metadata)
* [Struct `Leader`](#struct-leader)
* [Struct `LeaderRegistryCreatedEvent`](#struct-leaderregistrycreatedevent)
* [Struct `LeaderUpsertedEvent`](#struct-leaderupsertedevent)
* [Struct `LeaderCapIssuedEvent`](#struct-leadercapissuedevent)
* [Struct `LeaderStatusChangedEvent`](#struct-leaderstatuschangedevent)
* [Struct `LeaderClaimedEvent`](#struct-leaderclaimedevent)
* [Struct `LeaderSuspensionSkippedEvent`](#struct-leadersuspensionskippedevent)
* [Struct `UnbondingDurationUpdatedEvent`](#struct-unbondingdurationupdatedevent)
* [Struct `MinStakeUsUpdatedEvent`](#struct-minstakeusupdatedevent)
* [Struct `MaxTransactionBudgetUpdatedEvent`](#struct-maxtransactionbudgetupdatedevent)
* [Struct `StakeDepositedEvent`](#struct-stakedepositedevent)
* [Struct `UnstakeRequestedEvent`](#struct-unstakerequestedevent)
* [Struct `UnstakeClaimedEvent`](#struct-unstakeclaimedevent)
* [Struct `StakeSlashedEvent`](#struct-stakeslashedevent)
* [Enum `LeaderStatus`](#enum-leaderstatus)
* [Constants](#constants)
* [Function `unbonding_duration_ms`](#function-unbonding_duration_ms)
* [Function `min_stake_us`](#function-min_stake_us)
* [Function `max_transaction_budget`](#function-max_transaction_budget)
* [Function `assert_transaction_budget`](#function-assert_transaction_budget)
* [Function `network_id`](#function-network_id)
* [Function `leader_stamp_id`](#function-leader_stamp_id)
* [Function `status_active`](#function-status_active)
* [Function `status_suspended`](#function-status_suspended)
* [Function `status_slashed`](#function-status_slashed)
* [Function `new_metadata`](#function-new_metadata)
* [Function `empty_metadata`](#function-empty_metadata)
* [Function `exists`](#function-exists)
* [Function `assert_registered`](#function-assert_registered)
* [Function `assert_execution_inputs_allowed`](#function-assert_execution_inputs_allowed)
* [Function `assert_output_objects_allowed`](#function-assert_output_objects_allowed)
* [Function `status`](#function-status)
* [Function `claim_token`](#function-claim_token)
* [Function `is_active`](#function-is_active)
* [Function `is_eligible`](#function-is_eligible)
* [Function `assert_active`](#function-assert_active)
* [Function `metadata`](#function-metadata)
* [Function `metadata_data`](#function-metadata_data)
* [Function `leader_pool_total`](#function-leader_pool_total)
* [Function `leader_total_shares`](#function-leader_total_shares)
* [Function `staker_active_shares`](#function-staker_active_shares)
* [Function `staker_pending_shares`](#function-staker_pending_shares)
* [Function `staker_total_shares`](#function-staker_total_shares)
* [Function `staker_value`](#function-staker_value)
* [Function `upsert_self`](#function-upsert_self)
* [Function `stake`](#function-stake)
* [Function `request_unstake`](#function-request_unstake)
* [Function `assert_leader_cap_matches_registry`](#function-assert_leader_cap_matches_registry)
* [Function `assert_current_leader_cap`](#function-assert_current_leader_cap)
* [Function `rank_active_leaders_uniform`](#function-rank_active_leaders_uniform)
* [Function `rank_active_leaders_stake_weighted`](#function-rank_active_leaders_stake_weighted)
* [Function `stamp_workflow_worksheet`](#function-stamp_workflow_worksheet)
* [Function `activate_and_claim`](#function-activate_and_claim)
* [Function `suspend_if_token`](#function-suspend_if_token)
* [Function `set_unbonding_duration_ms`](#function-set_unbonding_duration_ms)
* [Function `set_min_stake_us`](#function-set_min_stake_us)
* [Function `set_max_transaction_budget`](#function-set_max_transaction_budget)
* [Function `slash_stake`](#function-slash_stake)
* [Function `allow_address`](#function-allow_address)
* [Function `disallow_address`](#function-disallow_address)
* [Function `request_leader_cap`](#function-request_leader_cap)
* [Function `register`](#function-register)
### Struct `LeaderCapabilitiesAdminCap`
Admin capability for modifying the allowlist in \[CapabilityManger].
```move
public struct LeaderCapabilitiesAdminCap has key, store
```
Fields
`id: sui::object::UIDregistry: sui::object::ID`
#### Struct `CapabilityManger`
Leader capability issuer state stored inside \[LeaderRegistry].
```move
public struct CapabilityManger has store
```
Fields
`allowed_addresses: sui::vec_set::VecSet`Addresses allowed to request capabilities.[`network_id`](#nexus_registry_leader_network_id)`: sui::object::ID`Network ID used by all issued \[leader\_cap::OverNetwork] objects.`admin_cap_id: sui::object::ID`Shared leader admin capability object ID.`leader_cap_issuer:` [`nexus_primitives::owner_cap::CloneableOwnerCap`](/reference/move/nexus_primitives/owner_cap.md#nexus_primitives_owner_cap_CloneableOwnerCap)`<`[`nexus_registry::leader_cap::OverNetwork`](/reference/move/nexus_registry/leader_cap.md#nexus_registry_leader_cap_OverNetwork)`>`Issuer for \[leader\_cap::OverNetwork].
#### Struct `LeaderRegistry`
Shared registry for leader operator records and pooled stake.
This is intended to be created once (by the workflow package initializer) and shared.
```move
public struct LeaderRegistry has key
```
Fields
`id: sui::object::UID`
#### Struct `LeaderRegistryInnerV1`
Version one stored layout for \[[`LeaderRegistry`](#nexus_registry_leader_LeaderRegistry)].
```move
public struct LeaderRegistryInnerV1 has store
```
Fields
[`unbonding_duration_ms`](#nexus_registry_leader_unbonding_duration_ms)`: u64`Unbonding delay for stake withdrawals.[`min_stake_us`](#nexus_registry_leader_min_stake_us)`: u64`Minimum stake (in US base units) required for a leader to be eligible for ranking.[`max_transaction_budget`](#nexus_registry_leader_max_transaction_budget)`: u64`Maximum budget (in MIST) a leader may spend on a single transaction.`leaders: sui::vec_set::VecSet`Discoverable set of registered leader capability IDs.[`records`](#nexus_registry_leader_records)`: sui::table::Table`Per-leader record keyed by leader capability ID.`capabilities:` [`nexus_registry::leader::CapabilityManger`](#nexus_registry_leader_CapabilityManger)Capability issuer state.
#### Struct `StakeManager`
Per-leader stake accounting (stored inside \[Leader]).
```move
public struct StakeManager has store
```
Fields
`pool: sui::balance::Balance`Total pooled stake backing all shares for this leader.`total_shares: u64`Total stake shares for this leader. Users hold shares in \[[`StakePosition`](#nexus_registry_leader_StakePosition)]. Value is proportional: `value(shares) = pool * shares / total_shares`.`positions: sui::table::Table`Stake positions for third-party staking: `staker -> position`.
#### Struct `StakePosition`
Per-(leader, staker) stake position.
Pending shares remain exposed to slashing because they still participate in the pool.
```move
public struct StakePosition has drop, store
```
Fields
`active_shares: u64pending_shares: u64pending_requested_at_ms: std::option::Option`
#### Struct `Metadata`
Arbitrary operator-provided metadata for a leader record.
This module does not interpret these values. The only enforced constraint is a size bound: `bcs::to_bytes(&meta).length() <=` [`MAX_META_LEN`](#nexus_registry_leader_MAX_META_LEN).
```move
public struct Metadata has copy, drop, store
```
Fields
`data: sui::vec_map::VecMap`
#### Struct `Leader`
Per-leader record stored in \[LeaderRegistry].
The record is keyed by the leader's capability ID (`ID`) inside the registry table.
```move
public struct Leader has store
```
Fields
[`status`](#nexus_registry_leader_status)`:` [`nexus_registry::leader::LeaderStatus`](#nexus_registry_leader_LeaderStatus)Status of this leader.`meta:` [`nexus_registry::leader::Metadata`](#nexus_registry_leader_Metadata)Opaque operator metadata (optional; application-defined).`stake_manager:` [`nexus_registry::leader::StakeManager`](#nexus_registry_leader_StakeManager)``Per-leader stake accounting.[`claim_token`](#nexus_registry_leader_claim_token)`: vector`Unique ownership token of the current activation. Set to the activating transaction's own digest (`*ctx.digest()`), which Sui guarantees is globally unique. A suspension only takes effect if it presents the exact token on record, so only the instance that passes the current `Active` state can suspend it. The assumption is that each instance passes the correct token.
#### Struct `LeaderRegistryCreatedEvent`
Emitted when a new \[LeaderRegistry] is created.
```move
public struct LeaderRegistryCreatedEvent has copy, drop
```
Fields
`registry: sui::object::ID`
#### Struct `LeaderUpsertedEvent`
Emitted when a leader record is created or updated via \[upsert\_self].
```move
public struct LeaderUpsertedEvent has copy, drop
```
Fields
`registry: sui::object::IDleader_cap_id: sui::object::ID`[`status`](#nexus_registry_leader_status)`:` [`nexus_registry::leader::LeaderStatus`](#nexus_registry_leader_LeaderStatus)
#### Struct `LeaderCapIssuedEvent`
Emitted when a leader capability is issued and transferred.
This is the authoritative off-chain signal that a new leader cap ID exists for this registry/network.
```move
public struct LeaderCapIssuedEvent has copy, drop
```
Fields
`registry: sui::object::IDleader_cap_id: sui::object::IDnetwork: sui::object::ID`[`leader`](#nexus_registry_leader)`: address`
#### Struct `LeaderStatusChangedEvent`
Emitted when a leader's status changes, e.g. via \[set\_status], a suspension through \[suspend\_if\_token], or a `Suspended -> Active` transition in \[activate\_and\_claim].
```move
public struct LeaderStatusChangedEvent has copy, drop
```
Fields
`registry: sui::object::IDleader_cap_id: sui::object::IDold_status:` [`nexus_registry::leader::LeaderStatus`](#nexus_registry_leader_LeaderStatus)`new_status:` [`nexus_registry::leader::LeaderStatus`](#nexus_registry_leader_LeaderStatus)
#### Struct `LeaderClaimedEvent`
Emitted when a leader claims (or re-claims) ownership of the `Active` state via \[activate\_and\_claim]. [`claim_token`](#nexus_registry_leader_claim_token) is the activating transaction's own digest.
```move
public struct LeaderClaimedEvent has copy, drop
```
Fields
`registry: sui::object::IDleader_cap_id: sui::object::ID`[`claim_token`](#nexus_registry_leader_claim_token)`: vector`
#### Struct `LeaderSuspensionSkippedEvent`
Emitted when \[suspend\_if\_token] is called by an instance that does not own the current `Active` state (the presented token does not match the one on record). The suspension is skipped.
```move
public struct LeaderSuspensionSkippedEvent has copy, drop
```
Fields
`registry: sui::object::IDleader_cap_id: sui::object::IDattempted: vectorowner: vector`
#### Struct `UnbondingDurationUpdatedEvent`
Emitted when the registry's unbonding duration is updated.
```move
public struct UnbondingDurationUpdatedEvent has copy, drop
```
Fields
`registry: sui::object::ID`[`unbonding_duration_ms`](#nexus_registry_leader_unbonding_duration_ms)`: u64`
#### Struct `MinStakeUsUpdatedEvent`
Emitted when the registry's minimum eligible stake is updated.
```move
public struct MinStakeUsUpdatedEvent has copy, drop
```
Fields
`registry: sui::object::ID`[`min_stake_us`](#nexus_registry_leader_min_stake_us)`: u64`
#### Struct `MaxTransactionBudgetUpdatedEvent`
Emitted when the registry's per-transaction max budget is updated.
```move
public struct MaxTransactionBudgetUpdatedEvent has copy, drop
```
Fields
`registry: sui::object::ID`[`max_transaction_budget`](#nexus_registry_leader_max_transaction_budget)`: u64`
#### Struct `StakeDepositedEvent`
Emitted when stake is deposited into a leader pool and shares are minted.
```move
public struct StakeDepositedEvent has copy, drop
```
Fields
`registry: sui::object::IDleader_cap_id: sui::object::IDstaker: addressamount: u64minted_shares: u64total_shares: u64pool_total: u64at_ms: u64`
#### Struct `UnstakeRequestedEvent`
Emitted when a staker requests an unstake, locking shares until the unlock time.
```move
public struct UnstakeRequestedEvent has copy, drop
```
Fields
`registry: sui::object::IDleader_cap_id: sui::object::IDstaker: addressshares: u64unlock_at_ms: u64`
#### Struct `UnstakeClaimedEvent`
Emitted when a staker claims a matured unstake and receives the withdrawn US.
```move
public struct UnstakeClaimedEvent has copy, drop
```
Fields
`registry: sui::object::IDleader_cap_id: sui::object::IDstaker: addressshares: u64amount: u64at_ms: u64`
#### Struct `StakeSlashedEvent`
Emitted when a leader's pooled stake is slashed.
```move
public struct StakeSlashedEvent has copy, drop
```
Fields
`registry: sui::object::IDleader_cap_id: sui::object::IDamount: u64at_ms: u64`
#### Enum `LeaderStatus`
Leader liveness/eligibility status.
```move
public enum LeaderStatus has copy, drop, store
```
Variants
Variant `Active`Eligible for committee membership and off-chain work.Variant `Suspended`Temporarily disabled (operator error, maintenance, etc.).Variant `Slashed`Slashed/evicted (ineligible).
#### Constants
```move
#[error]
const ELeaderNotFound: vector = b"Leader not found";
```
```move
#[error]
const ELeaderNotRegistered: vector = b"Leader is not registered";
```
```move
#[error]
const ELeaderNotActive: vector = b"Leader is not active";
```
```move
#[error]
const ELeaderSlashed: vector = b"Leader is slashed";
```
```move
#[error]
const EInvalidMeta: vector = b"Invalid metadata";
```
```move
#[error]
const EInvalidAmount: vector = b"Invalid amount";
```
```move
#[error]
const ENotEnoughUs: vector = b"Not enough US";
```
```move
#[error]
const EInsufficientStake: vector = b"Insufficient stake";
```
```move
#[error]
const EStakePositionNotFound: vector = b"Stake position not found";
```
```move
#[error]
const EPendingUnstakeExists: vector = b"Pending unstake exists";
```
```move
#[error]
const ENoPendingUnstake: vector = b"No pending unstake";
```
```move
#[error]
const EUnstakeNotReady: vector = b"Unstake not ready";
```
```move
#[error]
const EEmptyLeaderSet: vector = b"Leader set is empty";
```
```move
#[error]
const EUnauthorized: vector = b"Unauthorized";
```
```move
#[error]
const EAddressNotAllowed: vector = b"Address is not allowed";
```
```move
#[error]
const ELeaderCapWrongNetwork: vector = b"Leader cap network mismatch";
```
```move
#[error]
const ELeaderCapObjectAccess: vector = b"Leader cap cannot be used as Tool object data";
```
```move
#[error]
const EMaxTransactionBudgetTooLow: vector = b"Max transaction budget below minimum";
```
```move
#[error]
const ETransactionBudgetExceeded: vector = b"Transaction gas charge exceeds network maximum";
```
Maximum metadata length (bytes).
```move
const MAX_META_LEN: u64 = 4096;
```
Default unbonding duration (in ms). This is a placeholder default.
```move
const DEFAULT_UNBONDING_DURATION_MS: u64 = 0;
```
Bootstrap minimum stake (in `$US` base units) required for leader eligibility. The maximum `u64` value is a fail-closed sentinel, not an economic policy. The protocol owner must set the intended policy before registering leaders.
```move
const DEFAULT_MIN_STAKE_US: u64 = 18446744073709551615;
```
Default maximum budget (in MIST) a leader may spend on a single transaction.
```move
const DEFAULT_MAX_TRANSACTION_BUDGET_MIST: u64 = 10000000000;
```
Minimum maximum-transaction-budget (in MIST) that can be configured (1 SUI).
```move
const MIN_TRANSACTION_BUDGET_MIST: u64 = 1000000000;
```
```move
const DOMAIN_UNIFORM_RANK: vector = vector[110, 101, 120, 117, 115, 95, 114, 101, 103, 105, 115, 116, 114, 121, 58, 58, 108, 101, 97, 100, 101, 114, 58, 58, 117, 110, 105, 102, 111, 114, 109, 95, 114, 97, 110, 107, 95, 118, 49];
```
```move
const DOMAIN_STAKE_WEIGHTED_RANK: vector = vector[110, 101, 120, 117, 115, 95, 114, 101, 103, 105, 115, 116, 114, 121, 58, 58, 108, 101, 97, 100, 101, 114, 58, 58, 115, 116, 97, 107, 101, 95, 119, 101, 105, 103, 104, 116, 101, 100, 95, 114, 97, 110, 107, 95, 118, 49];
```
#### Function `unbonding_duration_ms`
Returns the registry's unbonding delay (in milliseconds) for stake withdrawals.
```move
public fun unbonding_duration_ms(self: &nexus_registry::leader::LeaderRegistry): u64
```
#### Function `min_stake_us`
Returns the minimum stake (in US base units) a leader needs to be eligible for ranking.
```move
public fun min_stake_us(self: &nexus_registry::leader::LeaderRegistry): u64
```
#### Function `max_transaction_budget`
Returns the maximum budget (in MIST) a leader may spend on a single transaction.
```move
public fun max_transaction_budget(self: &nexus_registry::leader::LeaderRegistry): u64
```
#### Function `assert_transaction_budget`
Verifies that one reimbursed transaction respects the registry gas ceiling. It aborts with `ETransactionBudgetExceeded` before the caller mutates payment or scheduler state.
```move
public fun assert_transaction_budget(self: &nexus_registry::leader::LeaderRegistry, gas_charge: u64)
```
#### Function `network_id`
Returns the network ID shared by all leader capabilities issued by this registry.
```move
public fun network_id(self: &nexus_registry::leader::LeaderRegistry): sui::object::ID
```
#### Function `leader_stamp_id`
Anyone can query the expected stamp ID (for tool configuration). This is the same as the registry's object ID.
```move
public fun leader_stamp_id(self: &nexus_registry::leader::LeaderRegistry): sui::object::ID
```
#### Function `status_active`
Returns the `Active` leader status value.
```move
public fun status_active(): nexus_registry::leader::LeaderStatus
```
#### Function `status_suspended`
Returns the `Suspended` leader status value.
```move
public fun status_suspended(): nexus_registry::leader::LeaderStatus
```
#### Function `status_slashed`
Returns the `Slashed` leader status value.
```move
public fun status_slashed(): nexus_registry::leader::LeaderStatus
```
#### Function `new_metadata`
Creates a metadata container from pre-defined key/value pairs.
```move
public fun new_metadata(data: sui::vec_map::VecMap): nexus_registry::leader::Metadata
```
#### Function `empty_metadata`
Returns an empty metadata container.
```move
public fun empty_metadata(): nexus_registry::leader::Metadata
```
#### Function `exists`
Returns whether a leader record exists for the given capability ID.
```move
public fun exists(self: &nexus_registry::leader::LeaderRegistry, leader_cap_id: sui::object::ID): bool
```
#### Function `assert_registered`
Aborts with \[ELeaderNotRegistered] unless a record exists for the capability ID.
```move
public fun assert_registered(self: &nexus_registry::leader::LeaderRegistry, leader_cap_id: sui::object::ID)
```
#### Function `assert_execution_inputs_allowed`
Aborts when any execution input references an issued LeaderCap.
```move
public fun assert_execution_inputs_allowed(self: &nexus_registry::leader::LeaderRegistry, operation: &nexus_interface::agent::ExecutionSpec)
```
#### Function `assert_output_objects_allowed`
Aborts when any explicit output Object field references an issued LeaderCap.
```move
public fun assert_output_objects_allowed(self: &nexus_registry::leader::LeaderRegistry, output: &sui::vec_map::VecMap)
```
#### Function `status`
Returns the current status of a leader record.
Aborts with \[ELeaderNotFound] if the leader has no record.
```move
public fun status(self: &nexus_registry::leader::LeaderRegistry, leader_cap_id: sui::object::ID): nexus_registry::leader::LeaderStatus
```
#### Function `claim_token`
Returns the current ownership claim token for a leader record.
Aborts with \[ELeaderNotFound] if the leader has no record.
```move
public fun claim_token(self: &nexus_registry::leader::LeaderRegistry, leader_cap_id: sui::object::ID): vector
```
#### Function `is_active`
Returns whether a leader record exists and has status `Active`.
```move
public fun is_active(self: &nexus_registry::leader::LeaderRegistry, leader_cap_id: sui::object::ID): bool
```
#### Function `is_eligible`
Returns whether a leader is active and sufficiently staked.
```move
public fun is_eligible(self: &nexus_registry::leader::LeaderRegistry, leader_cap_id: sui::object::ID): bool
```
#### Function `assert_active`
Asserts that a leader is active.
Aborts with \[ELeaderNotActive] if the leader is missing or not active.
```move
public fun assert_active(self: &nexus_registry::leader::LeaderRegistry, leader_cap_id: sui::object::ID)
```
#### Function `metadata`
Returns the metadata for a leader record.
Aborts with \[ELeaderNotFound] if the leader has not registered a record.
```move
public fun metadata(self: &nexus_registry::leader::LeaderRegistry, leader_cap_id: sui::object::ID): &nexus_registry::leader::Metadata
```
#### Function `metadata_data`
Convenience getter for the underlying key/value map inside \[Metadata].
```move
public fun metadata_data(self: &nexus_registry::leader::Metadata): &sui::vec_map::VecMap
```
#### Function `leader_pool_total`
Returns the total pooled stake (in US base units) backing a leader.
Aborts with \[ELeaderNotFound] if the leader has no record.
```move
public fun leader_pool_total(self: &nexus_registry::leader::LeaderRegistry, leader_cap_id: sui::object::ID): u64
```
#### Function `leader_total_shares`
Returns the total stake shares outstanding for a leader.
Aborts with \[ELeaderNotFound] if the leader has no record.
```move
public fun leader_total_shares(self: &nexus_registry::leader::LeaderRegistry, leader_cap_id: sui::object::ID): u64
```
#### Function `staker_active_shares`
Returns a staker's active (non-pending) shares in a leader pool, or 0 if none.
Aborts with \[ELeaderNotFound] if the leader has no record.
```move
public fun staker_active_shares(self: &nexus_registry::leader::LeaderRegistry, leader_cap_id: sui::object::ID, staker: address): u64
```
#### Function `staker_pending_shares`
Returns a staker's pending (unstake-locked) shares in a leader pool, or 0 if none.
Aborts with \[ELeaderNotFound] if the leader has no record.
```move
public fun staker_pending_shares(self: &nexus_registry::leader::LeaderRegistry, leader_cap_id: sui::object::ID, staker: address): u64
```
#### Function `staker_total_shares`
Returns a staker's total (active plus pending) shares in a leader pool.
Aborts with \[ELeaderNotFound] if the leader has no record.
```move
public fun staker_total_shares(self: &nexus_registry::leader::LeaderRegistry, leader_cap_id: sui::object::ID, staker: address): u64
```
#### Function `staker_value`
Current stake value (in US base units) for a staker in the given leader pool.
Returns 0 if either:
* the leader has no shares, or
* the staker has no shares.
```move
public fun staker_value(self: &nexus_registry::leader::LeaderRegistry, leader_cap_id: sui::object::ID, staker: address): u64
```
#### Function `upsert_self`
Upsert the sender's leader record.
Requires a leader capability for this workflow instance.
Behavior:
* Keyed by `object::id(`[`leader_cap`](/reference/move/nexus_registry/leader_cap.md#nexus_registry_leader_cap)`)`.
* [`leader_cap`](/reference/move/nexus_registry/leader_cap.md#nexus_registry_leader_cap) must belong to this registry network.
* Updates metadata for an existing record when called by the holder of the leader cap.
* Enforces a size bound on `meta` via `bcs::to_bytes(&meta)` (see \[MAX\_META\_LEN]).
```move
public fun upsert_self(self: &mut nexus_registry::leader::LeaderRegistry, leader_cap: &nexus_primitives::owner_cap::CloneableOwnerCap, meta: nexus_registry::leader::Metadata)
```
#### Function `stake`
Stake `amount` in `$US` base units into a leader's pool.
Anyone can stake into any active leader. Staking mints shares for the caller based on the current pool value and total shares.
```move
public fun stake(self: &mut nexus_registry::leader::LeaderRegistry, leader_cap_id: sui::object::ID, pay_with: &mut sui::coin::Coin, amount: u64, clock: &sui::clock::Clock, ctx: &mut sui::tx_context::TxContext)
```
#### Function `request_unstake`
Request to unstake `amount` in `$US` base units from a leader pool.
Deposits mint `amount × total_shares / pool` shares using floor division (or one share per base unit for an empty pool), so they never mint more value than deposited. This withdrawal request locks `ceil(amount × total_shares / pool)` shares, ensuring the pending share amount covers the requested withdrawal at the current price. It then moves those shares from the caller's active position into a pending position and records the request timestamp.
```move
public fun request_unstake(self: &mut nexus_registry::leader::LeaderRegistry, leader_cap_id: sui::object::ID, amount: u64, clock: &sui::clock::Clock, ctx: &mut sui::tx_context::TxContext)
```
#### Function `assert_leader_cap_matches_registry`
```move
public fun assert_leader_cap_matches_registry(self: &nexus_registry::leader::LeaderRegistry, leader_cap: &nexus_primitives::owner_cap::CloneableOwnerCap)
```
#### Function `assert_current_leader_cap`
Asserts that the concrete leader capability belongs to and is currently listed by this registry.
```move
public fun assert_current_leader_cap(self: &nexus_registry::leader::LeaderRegistry, leader_cap: &nexus_primitives::owner_cap::CloneableOwnerCap)
```
#### Function `rank_active_leaders_uniform`
Return the top-2 leaders from a uniform deterministic ranking over all active leaders in this registry.
Aborts with \[EEmptyLeaderSet] if there are no eligible leaders (see \[is\_eligible]). If exactly one eligible leader remains, it is duplicated to produce a length-2 result.
```move
public fun rank_active_leaders_uniform(self: &nexus_registry::leader::LeaderRegistry, seed: &vector): vector
```
#### Function `rank_active_leaders_stake_weighted`
Return the top-2 leaders from a stake-weighted deterministic ranking over all active leaders in this registry.
Aborts with \[EEmptyLeaderSet] if there are no eligible leaders (see \[is\_eligible]). If exactly one eligible leader remains, it is duplicated to produce a length-2 result.
```move
public fun rank_active_leaders_stake_weighted(self: &nexus_registry::leader::LeaderRegistry, seed: &vector): vector
```
#### Function `stamp_workflow_worksheet`
Stamps a worksheet with this registry through the current runtime authority.
```move
public fun stamp_workflow_worksheet(_permit: &nexus_kernel::runtime_authority::RuntimePermit, self: &nexus_registry::leader::LeaderRegistry, worksheet: &mut nexus_primitives::proof_of_uid::ProofOfUID, data: vector)
```
#### Function `activate_and_claim`
Activate a leader and claim ownership of its `Active` state.
Sets [`status`](#nexus_registry_leader_status) `= Active` and writes a fresh ownership token = the activating transaction's own digest (`*ctx.digest()`), which Sui guarantees is globally unique. The off-chain instance learns this digest from the transaction receipt and remembers it, so it can later prove ownership when suspending.
Aborts with \[ELeaderSlashed] if the leader is `Slashed` (the only abort path); a slashed leader can never reclaim. Aborts with \[ELeaderNotFound] if no record exists.
```move
public fun activate_and_claim(self: &mut nexus_registry::leader::LeaderRegistry, leader_cap: &nexus_primitives::owner_cap::CloneableOwnerCap, ctx: &mut sui::tx_context::TxContext)
```
#### Function `suspend_if_token`
Suspend a leader only if the caller still owns the current `Active` state.
This never aborts on a mismatch — the expected race during a rolling restart (a departing instance that no longer owns the record) must be a cheap no-op, not an abort, because the shutdown suspend runs inside a bounded time budget.
Behavior:
* returns `false` (no-op) if [`status`](#nexus_registry_leader_status) `!= Active`;
* if [`claim_token`](#nexus_registry_leader_claim_token) `== token`: sets `Suspended`, emits \[LeaderStatusChangedEvent], returns `true`;
* otherwise: emits \[LeaderSuspensionSkippedEvent] and returns `false`.
Does not clear [`claim_token`](#nexus_registry_leader_claim_token); the next activation overwrites it. Aborts with \[ELeaderNotFound] if no record exists.
```move
public fun suspend_if_token(self: &mut nexus_registry::leader::LeaderRegistry, leader_cap: &nexus_primitives::owner_cap::CloneableOwnerCap, token: vector): bool
```
#### Function `set_unbonding_duration_ms`
Set the unbonding duration (in milliseconds) applied to \[request\_unstake].
This is an administrative action gated by the leader capabilities admin cap.
```move
public fun set_unbonding_duration_ms(self: &mut nexus_registry::leader::LeaderRegistry, admin: &mut nexus_registry::leader::LeaderCapabilitiesAdminCap, new_duration_ms: u64)
```
#### Function `set_min_stake_us`
Set the minimum stake (in US base units) required for leader eligibility.
This is an administrative action gated by the leader capabilities admin cap.
```move
public fun set_min_stake_us(self: &mut nexus_registry::leader::LeaderRegistry, admin: &mut nexus_registry::leader::LeaderCapabilitiesAdminCap, min_stake_us: u64)
```
#### Function `set_max_transaction_budget`
Set the maximum budget (in MIST) a leader may spend on a single transaction.
This is an administrative action gated by the leader capabilities admin cap. Aborts with \[EMaxTransactionBudgetTooLow] if the new value is below \[MIN\_TRANSACTION\_BUDGET\_MIST].
```move
public fun set_max_transaction_budget(self: &mut nexus_registry::leader::LeaderRegistry, admin: &mut nexus_registry::leader::LeaderCapabilitiesAdminCap, new_max_transaction_budget: u64)
```
#### Function `slash_stake`
Slash stake for a leader. Returns the slashed balance to the caller.
Slashing reduces the leader pool and therefore reduces share value for all stakers.
```move
public fun slash_stake(self: &mut nexus_registry::leader::LeaderRegistry, _slashing_cap: &nexus_primitives::owner_cap::CloneableOwnerCap, leader_cap_id: sui::object::ID, amount: u64, clock: &sui::clock::Clock): sui::balance::Balance
```
#### Function `allow_address`
Allow \[address] to request capabilities from this registry.
```move
public fun allow_address(self: &mut nexus_registry::leader::LeaderRegistry, admin: &mut nexus_registry::leader::LeaderCapabilitiesAdminCap, address: address)
```
#### Function `disallow_address`
Revoke \[address] from requesting capabilities.
```move
public fun disallow_address(self: &mut nexus_registry::leader::LeaderRegistry, admin: &mut nexus_registry::leader::LeaderCapabilitiesAdminCap, address: address)
```
#### Function `request_leader_cap`
Clone and transfer a leader capability to the sender.
The sender must be in the capabilities allowlist.
```move
public fun request_leader_cap(self: &mut nexus_registry::leader::LeaderRegistry, ctx: &mut sui::tx_context::TxContext): sui::object::ID
```
#### Function `register`
Register the sender as a leader in a single atomic flow:
1. clone and transfer \[leader\_cap::OverNetwork],
2. create the leader record,
3. store metadata and stake.
Requirements:
* sender is in the capabilities allowlist.
* `amount >=` [`min_stake_us`](#nexus_registry_leader_min_stake_us)`(self)` (eligible on registration).
```move
public fun register(self: &mut nexus_registry::leader::LeaderRegistry, pay_with: &mut sui::coin::Coin, amount: u64, meta: nexus_registry::leader::Metadata, clock: &sui::clock::Clock, ctx: &mut sui::tx_context::TxContext): sui::object::ID
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.talus.network/reference/move/nexus_registry/leader.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.