> For the complete documentation index, see [llms.txt](https://docs.optimex.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.optimex.com/optimex-revolutionizing-bitcoin-finance/primary-building-blocks/optimex-staking.md). # Optimex Staking **Optimex Staking** is a decentralized validator management system that enables **Node Operators** to stake collateral (native tokens or ERC-20s) and participate in the **Optimex Protocol** as validators. The system provides a complete lifecycle for validator onboarding, staking, registration, and exit. It integrates with **Chainlink Functions** to enable off-chain challenge verification while maintaining on-chain enforcement, ensuring validators remain accountable and the network stays secure. ### Why Staking Matters Inside Optimex * Aligns validator incentives by requiring bonded collateral before they can participate in Optimex execution. * Gives governance fine-grained controls to freeze, slash, or unlock capital in response to network events. * Provides a clean lifecycle for node operators: onboard, stake, register, serve, exit, and withdraw. * Extends the core staking flow with a Chainlink-powered challenge system to arbitrate verification off-chain but enforce resolutions on-chain.
### Validator Onboarding and Offboarding Procedure
Validator Onboarding Procedure
The following outlines the step-by-step process for becoming a **`Validator`** in the **Optimex Staking Protocol**: **Step 1: Deploy a `Staker` Node:**\ Call `createStaker(owner)` on the `StakerManager` contract, where `owner` is the Ethereum wallet address. A new `OptimexStakingNode` contract is deployed and initialized with the provided address as the owner. The node starts in the `INACTIVE` state.\ **Note:** Anyone can deploy an `OptimexStakingNode`, but only the `owner` can configure and operate it. **Step 2: Configure deposit tokens:**\ As the node owner, call `setToken(token, true)` on your Staker Node for each token you want to use as collateral.\ Supported tokens: * Native token (`ETH`): represented as `address(0)`. * ERC-20 tokens: provide the token contract address. **Step 3: Set `metadataURL` (optional):**\ Call `setMetadataUrl(url)` on your Staker Node to provide an external URL for retrieving the node’s metadata. This metadata can be used by off-chain systems to display information about your validator node. **Step 4: Deposit collateral:**\ Call `deposit(token, amount)` for each token you want to stake. Tokens are deposited into your Staker Node contract. They are in a **`deposited`** state and can still be withdrawn until they are **locked**. Ensure you deposit sufficient collateral to meet the minimum staking requirements before proceeding to registration. **Step 5: Request registration:**\ Call `register()` on your Staker Node contract. Ensure the following: * Your node is in the `INACTIVE` state. * The system is not in a global freeze state (`frozenAll` must be `false`). * You do not have a pending request that has not yet expired. A registration request is created with an expiration timestamp (`currentTime + requestWindow`). You cannot submit another request until the current request window expires. **Step 6: Wait for Governance approval:**\ Wait for `OptimexStakingGovernance` to review and approve your registration request. Upon approval, Governance calls `approveRegistration(staker, tokens, amounts)` on the `ValidatorManager` contract. Governance specifies which tokens and amounts to lock from your deposits. The approval must occur before your request expires.\ After approval: * Your deposited tokens are locked (moved from the **`deposited`** state to the **`staked`** state). * Your node status changes from `INACTIVE` to `ACTIVE`.\ **Note:** If your request expires before approval, you must submit a new registration request. **Step 7: Complete `Validator` onboarding:**\ Your node is now `ACTIVE`, and you can begin performing validator duties. Your staked tokens remain locked and cannot be withdrawn. Governance can freeze your node if issues arise. Governance can slash your staked tokens for violations. You can request to exit the validator set at any time.
Validator Offboarding Procedure
The following outlines the step-by-step process for exiting the validator set and withdrawing your staked assets in the **Optimex Staking Protocol**. **Step 1: Request `Exit`:**\ Call `exit()` on your Staker Node contract. Ensure the following: * Your node is in the `ACTIVE` state. * The system is not in a global freeze state (`frozenAll` must be `false`). * You do not have a pending request that has not yet expired. * An exit request is created with an expiration timestamp (`currentTime + requestWindow`). You cannot submit another request until the current request window expires. The `requestWindow` is a cooldown period that prevents rapid request spam and ensures requests have a valid time window for governance review. In most cases, it also provides time for keyshare updates and cleanup of pending duties. **Step 2: Wait for `Governance` approval:**\ Wait for `OptimexStakingGovernance` to review and approve your exit request. Upon approval, Governance calls `approveExit(staker)` on the `ValidatorManager` contract. The approval must occur before your request expires. After approval: * Your node status changes from `ACTIVE` to `INACTIVE`. * Your collateral remains in the **`staked`** state, and an unlock timestamp is set (`currentTime + requestWindow`). * Your tokens remain locked until the unlock timestamp is reached. This waiting period provides a security buffer that allows for final checks, such as community disputes or challenges. **Note:** If your request expires before approval, you must submit a new exit request. **Step 3: Wait for `unlock` period:**\ Wait until the unlock timestamp is reached. You cannot unstake your tokens until this timestamp has passed. You can monitor the unlock timestamp using `unlockTimestamps(staker)` on the `ValidatorManager` contract. Once `block.timestamp >= unlockTimestamp`, you can proceed to unstake. **Note:** `Governance` or `Slasher` can extend the unlock timestamp if needed by calling `extendUnlock()`. This adds another `requestWindow` period to the unlock time. The unlock timestamp can be extended before it expires. **Step 4: Un-stake your tokens:**\ Call `unstake(tokens)` on your Staker Node contract, where `tokens` is an array of all token addresses you want to unstake. Ensure the following: * Your node is in the `INACTIVE` state. * The current timestamp is greater than or equal to the unlock timestamp. * The system is not in a global freeze state (`frozenAll` must be `false`). **Notes:** * You must unstake the **full amount** of each token; partial unstaking is not supported. * You must specify **all** staked tokens in a single call. * The unlock timestamp is cleared after unstaking. **Results:**\ Your staked tokens are unlocked (moved from the **`staked`** state to the **`deposited`** state). Tokens are now available for withdrawal. **Step 5: Withdraw your tokens:**\ Call `withdraw(to, token, amount)` for each token you want to withdraw. Tokens are transferred from your Staker Node contract to the specified recipient address. **Note:** You can withdraw tokens in multiple transactions if needed. Withdraw only what you need, as any remaining deposited tokens can stay in the contract for future use.
Validator Slashing & Challenge Procedure The following outlines the step-by-step process for submitting a challenge, handling global freeze/unfreeze, and executing the slashing procedure in the **Optimex Staking Protocol**.
**Step 1: Submit a `Challenge` request:**\ The **Challenger** calls `challenge(typeOfChallenge, gasLimit, request)` on the `ChallengeForwarder` contract. A **challenge fee** is collected upon submission. A challenge request is sent to the `FunctionsRouter` contract operated by **Chainlink**. *Off-chain process (by **Chainlink**):*\ The request is forwarded to the **Chainlink DON** for off-chain verification. A verification script analyzes the challenge data and determines whether the validator’s behavior is malicious. **Step 2: Chainlink DON response:**\ The **Chainlink DON** calls `fulfillRequest(challengeId, response, err)` on the `ChallengeForwarder` contract once verification is complete. The response either: * Confirms the validator’s misbehavior, or * Rejects the challenge. The response is recorded and stored in the `challenges[challengeId]` mapping in the `ChallengeForwarder` contract. If the proof is confirmed as **true**, the freezing and slashing phase is triggered. **Step 3: Emergency Freeze — Freeze All `Stakers`:**\ Upon confirmation from the **Chainlink DON**, the `ChallengeForwarder` calls `freezeAll()` on the `ValidatorManager` contract. The global `frozenAll` flag is set to `true`, effectively freezing all stakers: * No staker can submit registration or exit requests. * No staker can perform unstaking actions. *Note:* An owner of a staker contract can still withdraw tokens that are **not** in the `staked` (locked) state. **Step 4: `Governance` decision — Freeze / Unfreeze / Slash:**\ The **Governance** interacts with the `ValidatorManager` contract to perform the following actions: * Calls `unfreeze(stakers)` to unfreeze innocent stakers. * Calls either: * `freeze(stakers)` to freeze misbehaving stakers, or * `slash(staker, tokens, amount)` to penalize misbehaving stakers. On freezing: Each specified staker’s status changes from `ACTIVE` to `FROZEN`.\ On slashing: The specified stakers have their staked tokens slashed, and the slashed tokens are transferred to the `OptimexStaking` contract for further handling. Finally, it calls `unfreezeAll()` to clear the global `frozenAll` flag so normal operations can resume: * Stakers with `ACTIVE` status can resume normal validator duties. * Stakers with `FROZEN` status remain individually frozen. **Step 5: Compensation:**\ Calls `distribute(to, token, amount)` on the `ChallengeForwarder` to refund the challenge fee to the **Challenger** who successfully submitted a valid challenge. Calls `distribute(to, token, amount)` on the `OptimexStaking` contract to compensate affected victims or the **Challenger**, as determined by governance.
--- # 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 current page URL with the `ask` query parameter: ``` GET https://docs.optimex.com/optimex-revolutionizing-bitcoin-finance/primary-building-blocks/optimex-staking.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.