From e7530925677f491cca0bc702b353c10b79b3d1ab Mon Sep 17 00:00:00 2001 From: kirilaa Date: Mon, 12 Oct 2026 12:25:10 +0200 Subject: [PATCH 1/9] docs: describe GenLayer Chain as an Arbitrum Orbit chain GenLayer Chain moved from its ZK Stack deployment to a custom-gas-token Arbitrum Orbit chain that settles to Ethereum, with GEN as the native gas token (consensus v0.6). Replace every zkSync / ZK Stack description of the chain and expand the GenLayer Chain integration page with what exchanges and integrators need: GEN as an ERC-20 on Ethereum and native asset on the chain, retryable deposits and Outbox withdrawals, ArbSys block numbers, Arbitrum receipt fields, and the difference between sequencer inclusion, Ethereum settlement and protocol finality. Asimov and Bradbury still serve their pre-v0.6 chain endpoints, so the Networks page keeps them and states that they move to Orbit with v0.6 rather than publishing the unreleased Orbit testnet endpoints. The node API reference drops the zks_* proxy section; validator setup now asks for GenLayer Chain HTTP + WebSocket RPC (provider or Nitro full node). The sanitized config placeholders no longer say ZKSync. The zksync rate-limit group keys stay because node v0.5.14 still ships them and the block is synced from the node repository. --- .github/scripts/sanitize-config.sh | 6 +-- .../api-references/genlayer-node/content.mdx | 6 +-- content/validators/config.yaml | 6 +-- pages/FAQ.mdx | 4 +- pages/api-references/genlayer-node.mdx | 6 +-- pages/developers/networks.mdx | 8 ++- .../core-concepts/rollup-integration.mdx | 51 ++++++++++++++++--- .../what-is-genlayer.mdx | 2 +- pages/validators/setup-guide.mdx | 16 +++--- pages/validators/upgrade.mdx | 2 +- scripts/retrofit/retrofit.js | 2 +- 11 files changed, 73 insertions(+), 36 deletions(-) diff --git a/.github/scripts/sanitize-config.sh b/.github/scripts/sanitize-config.sh index 116ec6fe6..9367de245 100644 --- a/.github/scripts/sanitize-config.sh +++ b/.github/scripts/sanitize-config.sh @@ -22,9 +22,9 @@ echo "Sanitizing config file: $CONFIG_FILE" # Use yq to: # Replace RPC URLs / provider with TODO placeholders yq -i ' - .rollup.genlayerchainrpcurl = "TODO: Set your GenLayer Chain ZKSync HTTP RPC URL here" | - .rollup.genlayerchainwebsocketurl = "TODO: Set your GenLayer Chain ZKSync WebSocket RPC URL here" | - .rollup.provider = "TODO: Set your GenLayer Chain ZKSync provider" + .rollup.genlayerchainrpcurl = "TODO: Set your GenLayer Chain HTTP RPC URL here" | + .rollup.genlayerchainwebsocketurl = "TODO: Set your GenLayer Chain WebSocket RPC URL here" | + .rollup.provider = "TODO: Set your GenLayer Chain RPC provider" ' "$CONFIG_FILE" echo "Config sanitization completed" diff --git a/content/api-references/genlayer-node/content.mdx b/content/api-references/genlayer-node/content.mdx index 9d641012c..d490b1a3b 100644 --- a/content/api-references/genlayer-node/content.mdx +++ b/content/api-references/genlayer-node/content.mdx @@ -14,7 +14,7 @@ ${debugMethods.join('\n\n')} ## Ethereum Compatibility -The GenLayer Node also supports Ethereum-compatible methods that are proxied to the underlying infrastructure. These methods follow the standard [Ethereum JSON-RPC specification](https://ethereum.org/en/developers/docs/apis/json-rpc/) and are prefixed with `eth_`. +The GenLayer Node also supports Ethereum-compatible methods that are proxied to the underlying GenLayer Chain, an Arbitrum Orbit chain. These methods follow the standard [Ethereum JSON-RPC specification](https://ethereum.org/en/developers/docs/apis/json-rpc/) and are prefixed with `eth_`. **Examples of supported Ethereum methods:** @@ -24,10 +24,6 @@ The GenLayer Node also supports Ethereum-compatible methods that are proxied to - `eth_call` - And other standard Ethereum JSON-RPC methods -## zkSync Compatibility - -[zkSync-compatible](https://docs.zksync.io/zksync-protocol/api/zks-rpc) methods are also supported and proxied to the underlying infrastructure. These methods are prefixed with `zksync_`. - ## Usage Examples ### cURL diff --git a/content/validators/config.yaml b/content/validators/config.yaml index 487236428..be163a72b 100644 --- a/content/validators/config.yaml +++ b/content/validators/config.yaml @@ -1,8 +1,8 @@ # rollup configuration rollup: - genlayerchainrpcurl: "TODO: Set your GenLayer Chain ZKSync HTTP RPC URL here" # GenLayer Chain RPC URL - genlayerchainwebsocketurl: "TODO: Set your GenLayer Chain ZKSync WebSocket RPC URL here" # GenLayer Chain WebSocket URL - provider: "TODO: Set your GenLayer Chain ZKSync provider" # Rollup operator name; surfaces as the "provider" label on RPC-driven metrics. Set explicitly per deployment. + genlayerchainrpcurl: "TODO: Set your GenLayer Chain HTTP RPC URL here" # GenLayer Chain RPC URL + genlayerchainwebsocketurl: "TODO: Set your GenLayer Chain WebSocket RPC URL here" # GenLayer Chain WebSocket URL + provider: "TODO: Set your GenLayer Chain RPC provider" # Rollup operator name; surfaces as the "provider" label on RPC-driven metrics. Set explicitly per deployment. # consensus contracts configuration consensus: # Testnet - Phase 5 diff --git a/pages/FAQ.mdx b/pages/FAQ.mdx index 8e9e3b339..ac87f2cff 100644 --- a/pages/FAQ.mdx +++ b/pages/FAQ.mdx @@ -8,7 +8,7 @@ description: "Frequently asked questions about GenLayer: Intelligent Contracts,
What is GenLayer? - GenLayer is the **adjudication layer for the agentic economy**. It uses decentralized AI-validator consensus to resolve contracts that require judgment, not just code. It's built as an L2 on zkSync Elastic Chain, anchoring to Ethereum's security. Contracts on GenLayer — called **Intelligent Contracts** — can interpret language, process images, fetch live web data, and reach consensus on contested or subjective outcomes. See [What is GenLayer](/understand-genlayer-protocol/what-is-genlayer). + GenLayer is the **adjudication layer for the agentic economy**. It uses decentralized AI-validator consensus to resolve contracts that require judgment, not just code. It runs on GenLayer Chain, an Arbitrum Orbit L2 that settles to Ethereum and uses GEN as its native gas token. Contracts on GenLayer — called **Intelligent Contracts** — can interpret language, process images, fetch live web data, and reach consensus on contested or subjective outcomes. See [What is GenLayer](/understand-genlayer-protocol/what-is-genlayer).
@@ -99,7 +99,7 @@ description: "Frequently asked questions about GenLayer: Intelligent Contracts, - Token holders delegate stake to validators, incentivizing honest behavior - Multiple validators independently verify each transaction - Appeals provide a failsafe — dishonest validators get slashed - - The system anchors to Ethereum via zkSync for finality + - GenLayer Chain is an Arbitrum Orbit rollup that settles to Ethereum
diff --git a/pages/api-references/genlayer-node.mdx b/pages/api-references/genlayer-node.mdx index aebb731f2..36abfb92e 100644 --- a/pages/api-references/genlayer-node.mdx +++ b/pages/api-references/genlayer-node.mdx @@ -1084,7 +1084,7 @@ Retrieves the full execution trace for a transaction, including the return data, ## Ethereum Compatibility -The GenLayer Node also supports Ethereum-compatible methods that are proxied to the underlying infrastructure. These methods follow the standard [Ethereum JSON-RPC specification](https://ethereum.org/en/developers/docs/apis/json-rpc/) and are prefixed with `eth_`. +The GenLayer Node also supports Ethereum-compatible methods that are proxied to the underlying GenLayer Chain, an Arbitrum Orbit chain. These methods follow the standard [Ethereum JSON-RPC specification](https://ethereum.org/en/developers/docs/apis/json-rpc/) and are prefixed with `eth_`. **Examples of supported Ethereum methods:** @@ -1094,10 +1094,6 @@ The GenLayer Node also supports Ethereum-compatible methods that are proxied to - `eth_call` - And other standard Ethereum JSON-RPC methods -## zkSync Compatibility - -[zkSync-compatible](https://docs.zksync.io/zksync-protocol/api/zks-rpc) methods are also supported and proxied to the underlying infrastructure. These methods are prefixed with `zksync_`. - ## Usage Examples ### cURL diff --git a/pages/developers/networks.mdx b/pages/developers/networks.mdx index e8d468daf..850366da5 100644 --- a/pages/developers/networks.mdx +++ b/pages/developers/networks.mdx @@ -7,7 +7,11 @@ import AddToWallet from '../../components/AddToWallet' # Networks -GenLayer operates as two layers: the **GenLayer RPC** handles intelligent contract operations (`gen_*` methods), while the **GenLayer Chain** is the underlying L2 (zkSync Elastic Chain) that handles standard Ethereum operations (`eth_*` methods). The GenLayer RPC also passes through all `eth_*` and `zks_*` calls to the underlying chain, so you can use either endpoint for standard wallet operations. +GenLayer operates as two layers: the **GenLayer RPC** handles intelligent contract operations (`gen_*` methods), while the **GenLayer Chain** is the underlying L2—an Arbitrum Orbit chain that settles to Ethereum and uses GEN as its native gas token—that handles standard Ethereum operations (`eth_*` methods). The GenLayer RPC also passes through all `eth_*` calls to the underlying chain, so you can use either endpoint for standard wallet operations. See [GenLayer Chain integration](/understand-genlayer-protocol/core-concepts/rollup-integration) for how the chain, bridge, and settlement work. + + +GenLayer Chain runs on Arbitrum Orbit from consensus v0.6. Testnet Asimov and Bradbury keep the endpoints and chain ID listed below until they upgrade to v0.6; this page will list the new endpoints and contract addresses when they move. + For the full RPC reference, see [GenLayer Node API](/api-references/genlayer-node). @@ -104,7 +108,7 @@ Local development with full control. Requires [GenLayer Studio](/developers/inte ## GenLayer Chain (L2) -The underlying zkSync Elastic Chain that GenLayer runs on. You typically don't need to interact with this directly — the GenLayer RPC passes through all `eth_*` calls. But if you need direct L2 access (e.g., token transfers, contract debugging at the EVM level), you can add this chain to your wallet. +The underlying Arbitrum Orbit chain that GenLayer runs on. GEN is its native currency, so balances and gas are in GEN. You typically don't need to interact with this directly — the GenLayer RPC passes through all `eth_*` calls. But if you need direct L2 access (e.g., token transfers, contract debugging at the EVM level), you can add this chain to your wallet. | Setting | Value | |:--|:--| diff --git a/pages/understand-genlayer-protocol/core-concepts/rollup-integration.mdx b/pages/understand-genlayer-protocol/core-concepts/rollup-integration.mdx index a4c4576a0..b28651fb5 100644 --- a/pages/understand-genlayer-protocol/core-concepts/rollup-integration.mdx +++ b/pages/understand-genlayer-protocol/core-concepts/rollup-integration.mdx @@ -1,19 +1,25 @@ --- -description: "Learn how GenLayer Chain, its consensus contracts, validator nodes, GenVM, and Ethereum settlement fit together." +description: "Learn how GenLayer Chain, an Arbitrum Orbit chain that settles to Ethereum, fits together with the consensus contracts, validator nodes, GenVM, and the GEN token." --- +import { Callout } from "nextra-theme-docs"; + # GenLayer Chain integration -GenLayer Chain is an EVM-compatible chain built with the ZK Stack. It hosts ordinary Solidity contracts and the consensus contracts that coordinate Intelligent Contract execution. GenVM is a separate execution environment operated by nodes; it is not an EVM precompile or an Ethereum rollup execution engine. +GenLayer Chain is an EVM-compatible [Arbitrum Orbit](https://docs.arbitrum.io/launch-arbitrum-chain/a-gentle-introduction) chain that settles to Ethereum and uses GEN as its native gas token. It hosts ordinary Solidity contracts and the consensus contracts that coordinate Intelligent Contract execution. GenVM is a separate execution environment operated by nodes; it is not an EVM precompile or part of the rollup's execution engine. + + + Consensus v0.6 and later run on the Arbitrum Orbit GenLayer Chain. Public testnets move to it as they upgrade to v0.6; check [Networks](/developers/networks) for the current endpoints of each network. + ```mermaid %%{init: {"flowchart": {"curve": "basis", "nodeSpacing": 48, "rankSpacing": 54, "htmlLabels": true}}}%% flowchart TB Client(["Wallet or application"]) - Ethereum[("Ethereum")] + Ethereum[("Ethereum
GEN ERC-20 and rollup contracts")] subgraph Onchain["Onchain layer"] - Chain["GenLayer Chain
EVM + consensus contracts"] + Chain["GenLayer Chain (Arbitrum Orbit)
EVM + consensus contracts"] end subgraph Offchain["Validator execution layer"] @@ -23,7 +29,7 @@ flowchart TB Client -->|"EVM JSON-RPC"| Chain Client -->|"GenLayer JSON-RPC"| Node - Ethereum <-->|"bridge and settlement"| Chain + Ethereum <-->|"canonical bridge and settlement"| Chain Chain -->|"events and reads"| Node Node -->|"signed consensus transaction"| Chain @@ -67,6 +73,39 @@ Every Intelligent Contract has a Ghost contract on GenLayer Chain at the same ad The shared address gives wallets and EVM contracts one destination even though execution and balances span two environments. See [accounts and addresses](/understand-genlayer-protocol/core-concepts/accounts-and-addresses) and [messages](/developers/intelligent-contracts/features/messages). +## GEN on Ethereum and on GenLayer Chain + +GEN is an ERC-20 token on Ethereum. On GenLayer Chain it is the **native currency**, in the same way ETH is native on Ethereum: account balances, transfers, EVM gas, staking, and Intelligent Contract fee budgets all use native GEN with 18 decimals. Accounts do not need ETH or any other token to transact on GenLayer Chain. + +GEN moves between the two chains only through the chain's canonical Arbitrum bridge: + +- **Ethereum to GenLayer Chain.** Deposits and messages enter through the chain's ERC-20 Inbox as *retryable tickets*. A retryable is normally redeemed automatically on GenLayer Chain. If automatic redemption fails, anyone can redeem it manually before it expires. +- **GenLayer Chain to Ethereum.** Withdrawals and messages leave through the `ArbSys` system contract. They can be executed on Ethereum through the Outbox only after the rollup assertion that contains them is confirmed, which happens after the chain's challenge period. A sequencer receipt or an L2 event alone cannot authorize an action on Ethereum. + +The protocol uses the same path for its own token flows. Inflation is minted on Ethereum and delivered to the staking contract on GenLayer Chain as a retryable ticket; staking acknowledgements and burns travel back through the Outbox. These steps are permissionless—see [network keeper roles](/validators/network-keeper-roles). + +## Blocks, time, and fees + +- **Block numbers.** The consensus contracts record GenLayer Chain block numbers, read through `ArbSys.arbBlockNumber()`. On Arbitrum chains, Solidity's `block.number` returns an approximate Ethereum block number instead, so do not compare it with consensus block fields. Phase windows and timeouts use block timestamps. +- **EVM gas.** Gas on GenLayer Chain covers execution on the chain plus the cost of posting transaction data to the parent chain. Both components are charged in GEN. +- **Intelligent Contract fees.** The fee budget of an Intelligent Contract transaction is separate from the EVM gas of the enclosing transaction. See the [economic model](/understand-genlayer-protocol/core-concepts/economic-model). + +## Integrating with GenLayer Chain + +Exchanges, wallets, and indexers can treat GenLayer Chain as an Arbitrum-based EVM chain: + +- Use standard Ethereum tooling and `eth_*` JSON-RPC methods against the GenLayer Chain RPC or the GenLayer RPC, which passes `eth_*` calls through. Chain IDs and endpoints are listed on [Networks](/developers/networks). +- Track GEN on GenLayer Chain as the native asset, not as an ERC-20 token. On Ethereum, track it as an ERC-20 token. +- Expect Arbitrum transaction types and receipt fields, such as the internal system transaction at the start of each block and `gasUsedForL1` in receipts. Current Ethereum libraries handle them; custom decoders may need updates. +- Plan for the challenge period on withdrawals to Ethereum. Deposits from Ethereum arrive after their retryable ticket is redeemed. +- Use the Intelligent Contract transaction status from the GenLayer RPC to decide whether an Intelligent Contract outcome is final, as described below. + ## Settlement and protocol finality are different -GenLayer Chain inherits its rollup settlement properties from its ZK Stack and Ethereum configuration. Separately, an Intelligent Contract transaction reaches **protocol finality** only after its consensus decision and appeal window complete. Applications must use the Intelligent Contract transaction status—not only the enclosing EVM transaction receipt—to determine whether an outcome is final. +GenLayer Chain transactions reach several levels of confirmation: + +1. **Sequencer inclusion.** The chain's sequencer orders the transaction into a block. This is the confirmation most EVM tooling reports. +2. **Ethereum settlement.** The chain posts its transaction data and state assertions to Ethereum. An assertion is confirmed after the challenge period; only then can its withdrawals and messages execute on Ethereum. +3. **Protocol finality.** An Intelligent Contract transaction is final only after its consensus decision and appeal window complete. + +Applications must use the Intelligent Contract transaction status—not only the enclosing EVM transaction receipt—to determine whether an outcome is final. See [finality](/understand-genlayer-protocol/core-concepts/optimistic-democracy/finality). diff --git a/pages/understand-genlayer-protocol/what-is-genlayer.mdx b/pages/understand-genlayer-protocol/what-is-genlayer.mdx index 0b5364971..36665a416 100644 --- a/pages/understand-genlayer-protocol/what-is-genlayer.mdx +++ b/pages/understand-genlayer-protocol/what-is-genlayer.mdx @@ -52,7 +52,7 @@ flowchart TB ### GenLayer Chain -GenLayer Chain is an EVM-compatible ZK Stack chain. Solidity consensus contracts record transaction order, committee assignments, votes, appeals, and final outcomes. For the consensus process, this onchain state is authoritative. +GenLayer Chain is an EVM-compatible [Arbitrum Orbit](/understand-genlayer-protocol/core-concepts/rollup-integration) chain that settles to Ethereum and uses GEN as its native gas token. Solidity consensus contracts record transaction order, committee assignments, votes, appeals, and final outcomes. For the consensus process, this onchain state is authoritative. ### Validator nodes diff --git a/pages/validators/setup-guide.mdx b/pages/validators/setup-guide.mdx index f1204d636..29a47a534 100644 --- a/pages/validators/setup-guide.mdx +++ b/pages/validators/setup-guide.mdx @@ -195,11 +195,13 @@ Possible options: See the [GenVM Configuration](/validators/genvm-configuration) page for partner credits, provider setup, and the greybox fallback strategy. -#### ZKSync Full Node for the GenLayer Chain +#### GenLayer Chain RPC Access -Each validator needs access to a [ZKSync Full Node](https://docs.zksync.io/zksync-era/tooling/external-node) connected to the GenLayer chain. Validators use this node to read the chain state and submit transactions. +Each validator needs an HTTP RPC endpoint and a WebSocket endpoint for the [GenLayer Chain](/understand-genlayer-protocol/core-concepts/rollup-integration). Validators use them to read the chain state and events and to submit transactions. The WebSocket endpoint is required for new-block and log subscriptions. -One full node can be shared between multiple validators. The optimal validator-to-node ratio is currently under evaluation. +GenLayer Chain is an Arbitrum Orbit chain, so you can use a GenLayer Chain RPC provider or run your own [Arbitrum Nitro full node](https://docs.arbitrum.io/run-arbitrum-node/run-full-node) for the chain. Testnet Asimov and Bradbury use the GenLayer Chain endpoints listed on [Networks](/developers/networks) until they upgrade to consensus v0.6. + +One chain node can be shared between multiple validators. The optimal validator-to-node ratio is currently under evaluation. ### Setup @@ -268,9 +270,9 @@ You can use the following example configuration. **Note:** For most users, you w ```yaml copy # rollup configuration rollup: - genlayerchainrpcurl: "TODO: Set your GenLayer Chain ZKSync HTTP RPC URL here" # GenLayer Chain RPC URL - genlayerchainwebsocketurl: "TODO: Set your GenLayer Chain ZKSync WebSocket RPC URL here" # GenLayer Chain WebSocket URL - provider: "TODO: Set your GenLayer Chain ZKSync provider" # Rollup operator name; surfaces as the "provider" label on RPC-driven metrics. Set explicitly per deployment. + genlayerchainrpcurl: "TODO: Set your GenLayer Chain HTTP RPC URL here" # GenLayer Chain RPC URL + genlayerchainwebsocketurl: "TODO: Set your GenLayer Chain WebSocket RPC URL here" # GenLayer Chain WebSocket URL + provider: "TODO: Set your GenLayer Chain RPC provider" # Rollup operator name; surfaces as the "provider" label on RPC-driven metrics. Set explicitly per deployment. # consensus contracts configuration consensus: # Testnet - Phase 5 @@ -661,7 +663,7 @@ Once you have configured everything, you are ready to start the node. - Consensus contract configuration and accessibility - GenVM module connectivity and health status - LLM provider configuration and API connectivity - - Network configuration and ZKSync node accessibility + - Network configuration and GenLayer Chain RPC accessibility 5. Run the node diff --git a/pages/validators/upgrade.mdx b/pages/validators/upgrade.mdx index 0802f772e..7ab02e22a 100644 --- a/pages/validators/upgrade.mdx +++ b/pages/validators/upgrade.mdx @@ -54,7 +54,7 @@ Breaking changes involve a new consensus deployment. The old database is incompa ### v0.4.x to v0.5.0 (Breaking) - The two consensus contract addresses (`contractmainaddress` and `contractdataaddress`) have been replaced by a single `consensusaddress` field. Do not copy your old consensus config — use the new example `config.yaml`. -- The GenLayer Chain ZKSync RPC URLs (`genlayerchainrpcurl` and `genlayerchainwebsocketurl`) have changed. Update both the HTTP RPC and WebSocket URLs in your `config.yaml` to the new endpoints. +- The GenLayer Chain RPC URLs (`genlayerchainrpcurl` and `genlayerchainwebsocketurl`) have changed. Update both the HTTP RPC and WebSocket URLs in your `config.yaml` to the new endpoints. - Database must be wiped (the node creates a fresh one on startup). - Re-staking is required — breaking changes involve a new consensus deployment, so you must stake again using the [validator wizard](/validators/setup-guide#using-the-validator-wizard). diff --git a/scripts/retrofit/retrofit.js b/scripts/retrofit/retrofit.js index 110fc607f..16efbd58f 100644 --- a/scripts/retrofit/retrofit.js +++ b/scripts/retrofit/retrofit.js @@ -46,7 +46,7 @@ const EXCLUDED_FILES = [ ]; const CANON = `Project context — GenLayer documentation (docs.genlayer.com): -GenLayer is the first Intelligent Blockchain: an L2 (on zkSync Elastic Chain, anchored to Ethereum) whose smart contracts — called Intelligent Contracts, written in Python — can natively access the web, call LLMs, and reach consensus on non-deterministic, subjective outcomes. Consensus mechanism: Optimistic Democracy; validators agree on non-deterministic outputs via the Equivalence Principle. Execution environment: GenVM. Dev tools: GenLayer CLI, GenLayer Studio (browser IDE), GenLayerJS / GenLayerPY SDKs, GenLayer Testing Suite (genlayer-test). Networks: Localnet, Studionet, Testnet Asimov. +GenLayer is the first Intelligent Blockchain: an L2 (an Arbitrum Orbit chain that settles to Ethereum, with GEN as its native gas token) whose smart contracts — called Intelligent Contracts, written in Python — can natively access the web, call LLMs, and reach consensus on non-deterministic, subjective outcomes. Consensus mechanism: Optimistic Democracy; validators agree on non-deterministic outputs via the Equivalence Principle. Execution environment: GenVM. Dev tools: GenLayer CLI, GenLayer Studio (browser IDE), GenLayerJS / GenLayerPY SDKs, GenLayer Testing Suite (genlayer-test). Networks: Localnet, Studionet, Testnet Asimov. Canonical terminology — always use exactly these names: "Intelligent Contract" (never "AI contract" or "smart contract 2.0"), "Optimistic Democracy", "Equivalence Principle", "GenVM", "GenLayer Studio". You may read other files in this repository (e.g. public/llms.txt, sibling pages in the same directory) to stay consistent with how concepts are described elsewhere.`; From 9c25adc024e3e10bd982f12381f674379ba06896 Mon Sep 17 00:00:00 2001 From: kirilaa Date: Mon, 12 Oct 2026 12:25:10 +0200 Subject: [PATCH 2/9] docs: document the Orbit inflation relay for keepers The inflation relayer no longer proves zkSync batches through GEN.executeL2Message. On Orbit the round trip is: Staking request via ArbSys, Outbox execution after assertion confirmation, permissionless GEN.executeInflationRequest within the one-day approval, retryable delivery to the inflation escrow, and an Outbox acknowledgement before the next request. The percentage incentive is replaced by a capped gas reimbursement minted on top of the tranche. Burns are native ArbSys withdrawals completed through the Outbox. The private-repo script pointer is replaced by Arbitrum's public messaging guides. --- pages/validators/network-keeper-roles.mdx | 49 +++++++++++------------ 1 file changed, 24 insertions(+), 25 deletions(-) diff --git a/pages/validators/network-keeper-roles.mdx b/pages/validators/network-keeper-roles.mdx index 1c6be363e..fc9df9cad 100644 --- a/pages/validators/network-keeper-roles.mdx +++ b/pages/validators/network-keeper-roles.mdx @@ -17,7 +17,7 @@ Today the GenLayer Foundation operates a baseline set of these keepers so the ne | Role | Function | Who may call | Reward | Risk if idle | |---|---|---|---|---| -| **Inflation relayer** | `GEN.executeL2Message()` (L1) | Anyone (permissionless) | `incentivePercentage` × epoch inflation, minted to caller. | **Epoch progression halts network-wide.** L2 cannot advance past `inflationEpoch`. | +| **Inflation relayer** | Outbox execution, then `GEN.executeInflationRequest()` (Ethereum); retryable redemption (GenLayer Chain) | Anyone (permissionless) | Bounded gas reimbursement in GEN for `executeInflationRequest()`, when the keeper policy enables it. | **Epoch progression halts network-wide.** L2 cannot advance past `inflationEpoch`. | | **Epoch advancer** | `Staking.epochAdvance()` (L2) | Anyone (permissionless) | None | Epochs stop advancing; fees/inflation are not distributed. | | **Validator primer** | `Staking.validatorPrime(validator)` (L2) | Anyone, on behalf of a validator | 1% of any slash that fires (only when a slash is pending and caller ≠ validator). Healthy validator → none. | Validator misses selection; pending slashes go unenforced. | | **Appellant** | SDK/CLI appeal operation (`topUpAndSubmitAppeal`) | Anyone (permissionless, payable) | Successful appeal returns 2.5× the bond: principal plus 1.5× profit. | Incorrect results are not challenged. | @@ -34,33 +34,32 @@ Today the GenLayer Foundation operates a baseline set of these keepers so the ne ## Inflation Relayer -**Function:** `GEN.executeL2Message(batchNumber, txIndex, batchIndex, message, proof, l2GasPrice, l2GasLimit)` on the **L1** GEN token contract. +**Functions:** the canonical Arbitrum `Outbox` on Ethereum, `GEN.executeInflationRequest(epochTo, gasPrice, gasLimit)` on the Ethereum GEN token contract, and retryable-ticket redemption on GenLayer Chain. -Each epoch's inflation makes a round trip: the L2 Staking contract requests it, L1 mints and bridges it back, and L2 receives it. The middle step — proving the L2→L1 message on L1 and relaying it — **cannot happen on-chain**, because zkSync L2→L1 messages can only be proved after the L2 batch has finalized on L1 (roughly an hour on real networks). Someone has to call `executeL2Message()` off-chain to complete the round trip. +GEN inflation is minted on Ethereum and delivered to the Staking contract on GenLayer Chain, so each inflation tranche makes a round trip over the chain's canonical Arbitrum bridge: + +1. **Request (GenLayer Chain → Ethereum).** When `Staking.epochAdvance()` sees that delivered inflation is running low, Staking sends an inflation request to Ethereum through `ArbSys` and emits `InflationRequestedFromL2`. +2. **Execute the Outbox message (Ethereum).** After the rollup assertion containing the request is confirmed, anyone executes it through the Outbox with its Merkle proof. The GEN bridge receiver authenticates the message and approves the request on GEN for one day (`ArbitrumInflationRequestApproved`). +3. **Execute the request (Ethereum).** Anyone calls `GEN.executeInflationRequest(epochTo, gasPrice, gasLimit)` with the approved parameters. GEN mints the tranche and sends it to GenLayer Chain as a retryable ticket through the chain's ERC-20 Inbox. +4. **Deliver (GenLayer Chain).** The retryable is normally redeemed automatically, delivering the GEN to the inflation escrow, which credits Staking and raises `inflationEpoch`. If automatic redemption fails, anyone can redeem the ticket before it expires; if the Staking call fails, the escrow keeps the GEN and anyone can call `ArbitrumInflationEscrow.retry()`. +5. **Acknowledge (GenLayer Chain → Ethereum).** After Staking accepts the GEN, the escrow sends a delivery acknowledgement back through `ArbSys`. Once its assertion is confirmed, anyone executes it through the Outbox so GEN records the delivery. Only one inflation transfer can be outstanding, so the next request cannot be executed until this acknowledgement lands. + +Steps 2 and 5 **cannot happen on-chain by themselves**: an L2→L1 message can execute only after its assertion is confirmed on Ethereum, which takes the chain's challenge period. Someone has to submit those transactions off-chain. - **This role gates the entire network's epoch progression.** The L2 `Staking.epochAdvance()` can only move forward while `epoch + 1 <= inflationEpoch`, and `inflationEpoch` only rises when `executeL2Message()` is successfully relayed on L1. **If no one relays inflation, epoch progression halts network-wide** once the current epoch catches up to `inflationEpoch`. This is the single most important keeper to keep running. + **This role gates the entire network's epoch progression.** The L2 `Staking.epochAdvance()` can only move forward while `epoch + 1 <= inflationEpoch`, and `inflationEpoch` only rises when inflation is delivered to Staking. **If no one relays inflation, epoch progression halts network-wide** once the current epoch catches up to `inflationEpoch`. Staking requests inflation ahead of the current epoch, but this is still the single most important keeper to keep running. -**When to call:** whenever an inflation request message is pending relay. Pre-check any candidate message — and estimate the reward — with the L1 view helper: +**When to call:** whenever a request or acknowledgement is waiting in the Outbox after confirmation, and whenever a request is approved but not yet executed. Pre-check a request before submitting: ```solidity -// Returns (pending, rewards): whether the message still needs relaying, -// and the estimated GEN reward for relaying it. -(bool pending, uint256 rewards) = GEN.isL2MessagePending( - batchNumber, txIndex, batchIndex, message -); -``` - -**Reward:** on a successful INFLATION relay, the caller is paid - -``` -reward = totalInflation × incentivePercentage / 10000 +// True while the request is approved on Ethereum and has not expired or been executed. +bool ready = GEN.isInflationRequestApproved(epochTo, gasPrice, gasLimit); ``` -minted to `msg.sender` on L1, emitting `IncentiveRewardPaid(caller, reward)`. The reward is **carved out of** that epoch's inflation, not minted on top — total new supply is `fees + totalInflation` regardless of the incentive. +**Reward:** a successful `executeInflationRequest()` reimburses the caller in GEN, minted on Ethereum and emitted as `KeeperRewardPaid`. The reward is the gas the call used plus a fixed overhead, priced at the lower of the paid gas price and a policy maximum, converted to GEN with the rollup's fee-token exchange rate, plus a premium, and capped at a policy maximum. A zero-cap policy disables it. Outbox executions and retryable redemptions are not reimbursed. The full inflation tranche still goes to Staking; the reward is not deducted from it. -**Cadence:** relay each pending inflation message shortly after its L2 batch finalizes on L1 (about hourly on testnet, gated by batch finalization). Relaying is idempotent per target epoch — a duplicate request for an already-requested epoch is a safe no-op — so a keeper that occasionally double-submits does no harm. +**Cadence:** follow the confirmation of each request and acknowledgement on Ethereum. Duplicate submissions are safe: an executed or expired approval reverts, and a late duplicate ticket cannot credit Staking twice. --- @@ -68,7 +67,7 @@ minted to `msg.sender` on L1, emitting `IncentiveRewardPaid(caller, reward)`. Th **Function:** `Staking.epochAdvance()` on the L2 Staking contract. -Advances the network from the current epoch to the next. On each advance it distributes the finalized epoch's fees and inflation to validators, developers, and the DAO, requests the next window of inflation from L1 (see [Inflation Relayer](#inflation-relayer)), and — when the burn threshold is met — auto-triggers [token burning](#burn-trigger). +Advances the network from the current epoch to the next. On each advance it distributes the finalized epoch's fees and inflation to validators, developers, and the DAO, requests the next window of inflation from Ethereum (see [Inflation Relayer](#inflation-relayer)), and — when the burn threshold is met — auto-triggers [token burning](#burn-trigger). **When to call:** once the current epoch's minimum duration has elapsed and its transactions are resolved. In normal operation this is driven automatically; a keeper only needs to step in if advancement stalls. @@ -164,7 +163,7 @@ Removes accumulated burnable GEN (unclaimed inflation, the post-incentive slashe **When to call:** almost never manually. Burning fires **automatically inside `epochAdvance()`** whenever the accumulated `burning` balance meets the configured `burnThreshold`. The manual call is a **fallback** for flushing balances that sit **below** the threshold, or when threshold automation is disabled (`burnThreshold = 0`, the default). - Completing a burn on L1 requires two further off-chain operator steps (`finalizeWithdrawal` then a BURN-payload `executeL2Message`) that pair with the L2 emission. Those steps do **not** pay the inflation relayer reward. See the staking system specification for the full burn flow. + The burn leaves GenLayer Chain as a native GEN withdrawal through `ArbSys`. After its assertion is confirmed, someone must execute the withdrawal through the Outbox on Ethereum; GEN then burns exactly the withdrawn amount. Refunded bridge gas collected by the inflation fee vault is burned the same way through `burnFees()`. These steps do **not** pay a keeper reward. **Reward:** none. @@ -191,14 +190,14 @@ Paginated garbage collection that reclaims **expired** quarantine records. It on **Network endpoints and contract addresses.** Keepers need the L2 Staking / consensus contract address and the L1 GEN token address for the target network. The L2 consensus `AddressManager` address and the chain RPC/WebSocket URLs for each testnet live in the [Network-Specific Consensus Configuration](/validators/setup-guide#network-specific-consensus-configuration) section of the setup guide. From the CLI, `genlayer network info` prints the active network's configuration and contract addresses. -**Reference implementations.** The consensus repository ships reference scripts for the multi-step relay flows — the inflation relayer's proof-fetch-and-execute logic lives at `scripts/consensus_flows/staking/executeL2Message.ts`, alongside companion scripts for the other staking flows. Use these as a starting point for a production keeper: they show how to fetch the L2 receipt, poll `zks_getL2ToL1LogProof` until the batch is finalized, and submit the L1 call. +**Bridge tooling.** The inflation and burn flows use the chain's canonical Arbitrum bridge, so standard Arbitrum tooling applies: see Arbitrum's guides to [L2-to-L1 messages](https://docs.arbitrum.io/how-arbitrum-works/deep-dives/l2-to-l1-messaging) for building Outbox proofs and executing confirmed messages, and to [L1-to-L2 messages](https://docs.arbitrum.io/how-arbitrum-works/deep-dives/l1-to-l2-messaging) for redeeming retryable tickets. A keeper also needs the Ethereum GEN token address and the chain's canonical Inbox, Bridge, and Outbox addresses for the target network. **Practical guidance:** -- **Prioritize the inflation relayer.** It is the only keeper whose absence halts the whole network, and the only one that pays a standing reward. Everything else is a backstop to already-automated behavior. -- **Check for a reward before assuming one.** Only the inflation relayer (via `incentivePercentage`), the validator primer (only on an actually-enforced slash), and the appellant (only on a successful appeal) ever pay. The rest are unpaid liveness/hygiene work. -- **Expect idempotency.** Inflation relays, stuck-tx healing, and quarantine GC are all safe to retry or double-submit — duplicate or non-applicable calls are no-ops, not errors. -- **Watch gas vs. reward.** For the paid roles, compare the estimated reward (e.g. `isL2MessagePending`'s `rewards`, or the pending slash amount) against the transaction cost before submitting. +- **Prioritize the inflation relayer.** It is the only keeper whose absence halts the whole network, and the only one that can pay a standing reward. Everything else is a backstop to already-automated behavior. +- **Check for a reward before assuming one.** Only the inflation relayer (gas reimbursement for `executeInflationRequest()`, when enabled), the validator primer (only on an actually-enforced slash), and the appellant (only on a successful appeal) ever pay. The rest are unpaid liveness/hygiene work. +- **Expect idempotency.** Inflation relays, stuck-tx healing, and quarantine GC are all safe to retry or double-submit — duplicate or non-applicable calls either revert or are no-ops, with no side effects. +- **Watch gas vs. reward.** For the paid roles, compare the expected reward (the capped gas reimbursement, or the pending slash amount) against the transaction cost before submitting. ## Related Resources From 3eb22ce54d724ddfe5a814a69567e8cbbb130c15 Mon Sep 17 00:00:00 2001 From: kirilaa Date: Mon, 12 Oct 2026 12:25:10 +0200 Subject: [PATCH 3/9] docs: align the staking guide with v0.6 staking contracts Checked against genlayer-consensus main (v0.6): - validatorJoin takes the operator public key and a possession proof; the no-argument and address overloads no longer exist. - validatorView returns a struct; size exits with validatorSelfSharesOf. - Staking.validatorClaim pays the ValidatorWallet; owners claim through validatorWallet.validatorClaim(), which forwards to the owner. - There is no payable delegatorDeposit; top up with delegatorJoin. - delegatorClaim is callable only by the delegator. - Claims also wait for pricing and slash settlement, and epoch 1 is skipped only when inflation for epoch 2 has already been delivered. - Operator rotation is a delayed two-step transfer. Fixes the broken CLI staking anchor and refreshes the troubleshooting table with the current error names. --- pages/developers/staking-guide.mdx | 128 ++++++++++-------- .../optimistic-democracy/staking.mdx | 2 +- .../optimistic-democracy/unstaking.mdx | 2 +- 3 files changed, 75 insertions(+), 57 deletions(-) diff --git a/pages/developers/staking-guide.mdx b/pages/developers/staking-guide.mdx index df228bdc8..14c023f3c 100644 --- a/pages/developers/staking-guide.mdx +++ b/pages/developers/staking-guide.mdx @@ -5,14 +5,16 @@ import { Callout } from "nextra-theme-docs"; # Staking Contract Guide -The Staking Contract Guide explains how developers can interact directly with GenLayer staking smart contracts for consensus-level staking operations. It includes Solidity code examples for both validator and delegator operations. +The Staking Contract Guide explains how developers can interact directly with GenLayer staking smart contracts for consensus-level staking operations. It includes Solidity code examples for both validator and delegator operations. The examples use `genStaking` for the Staking contract on GenLayer Chain and `validatorWallet` for a validator's ValidatorWallet contract. To understand the concepts behind staking, including the epoch system, shares vs stake, validator selection weights, and reward distribution, see [Staking in GenLayer](/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking). - For CLI-based staking operations (recommended for most users), see the [GenLayer CLI Staking Commands](/api-references/genlayer-cli#staking-operations-testnet). + For CLI-based staking operations (recommended for most users), see the [GenLayer CLI Staking Commands](/api-references/genlayer-cli#staking-operations). The CLI and [genlayer-js](/api-references/genlayer-js/staking) also build the operator key proof that joining requires. +Stake is denominated in GEN, the native token of GenLayer Chain, so staking calls send GEN as `msg.value`. The minimums, unbonding periods, and epoch durations below are current defaults that governance can change. Read the minimums from the Staking contract with `validatorMinStake()` and `delegatorMinStake()` instead of hardcoding them. + ## Validator Operations ### Joining as a Validator @@ -20,20 +22,21 @@ To understand the concepts behind staking, including the epoch system, shares vs **Requirements:** - Minimum stake: **42,000 GEN** tokens - Must run a validator node for consensus participation +- An operator key whose possession you can prove - A single address can create multiple validators -**Method 1: Owner as Operator** +The caller becomes the validator **owner**. The **operator** is derived from the public key you register, and the possession proof shows that you control that key: ```solidity -address validatorWallet = genStaking.validatorJoin{value: 42000 ether}(); +uint256[2] memory operatorPubKey = [pubKeyX, pubKeyY]; // operator public key +bytes memory possessionProof = ...; // signature by the operator key over its possession message +address validatorWallet = genStaking.validatorJoin{value: 42000 ether}( + operatorPubKey, + possessionProof +); ``` -**Method 2: Separate Operator Address (Recommended)** - -```solidity -address operatorAddress = 0x...; -address validatorWallet = genStaking.validatorJoin{value: 42000 ether}(operatorAddress); -``` +Use your own key to operate the node yourself, or a separate hot key for cold/hot separation (recommended). The possession message is bound to the wallet factory and the caller; generate the key and proof with the GenLayer CLI (`genlayer staking validator-join` or the wizard) or with `validatorJoin({ amount, registration })` in genlayer-js. Save the returned **ValidatorWallet address** - you'll need it for all future operations. @@ -43,12 +46,12 @@ address validatorWallet = genStaking.validatorJoin{value: 42000 ether}(operatorA - Deposits activate **2 epochs after joining** - `validatorPrime()` is automatically called by your validator node each epoch - Monitor priming for proper activation within 2 epochs -- Operator address cannot be reused or be the zero address -- If the operator is already assigned to another validator, the transaction reverts +- The operator cannot be the zero address, and cannot already operate another owner's validator +- To rotate the operator later, the owner calls `initiateOperatorTransfer` on the ValidatorWallet, then `completeOperatorTransfer` after the operator-transfer delay (or `cancelOperatorTransfer`) **Post-Join Steps:** 1. Save the `validatorWallet` address -2. Start your validator node using the operator address +2. Start your validator node using the operator key 3. Monitor that `validatorPrime(validatorWallet)` executes each epoch 4. Wait 2 epochs and verify activation @@ -59,11 +62,12 @@ validatorWallet.validatorDeposit{value: 10000 ether}(); ``` **Key Points:** -- Call through the ValidatorWallet contract only +- Call through the ValidatorWallet contract only; only the wallet owner can call it - Deposits follow the **epoch +2 activation rule** - Your validator node automatically calls `validatorPrime()` to commit the deposit - No minimum for additional deposits - Cannot deposit zero value +- Deposits revert while a slash against the validator is being settled **Activation Timeline:** ``` @@ -77,12 +81,12 @@ Epoch N+2: validatorPrime() → deposit activated **Step 1: Calculate Shares** ```solidity -uint256[8] memory validatorState = genStaking.validatorView(validatorWallet); -uint256 currentShares = validatorState[1]; -uint256 currentStake = validatorState[0]; +uint256 currentShares = genStaking.validatorSelfSharesOf(validatorWallet); uint256 sharesToExit = (currentShares * 30) / 100; // Exit 30% ``` +`genStaking.validatorView(validatorWallet)` returns a `ValidatorView` struct with the validator's stake (`vStake`, `dStake`), pool shares (`vShares`, `dShares`), pending operations, and ban and priming state. + **Step 2: Initiate Exit** ```solidity @@ -94,7 +98,8 @@ validatorWallet.validatorExit(sharesToExit); **Important Notes:** -- Exited tokens stop earning rewards immediately +- Exited shares stop counting toward stake and selection weight immediately +- The withdrawal is priced at the validator's next priming; it still receives its share of rewards for the epochs it served and stays exposed to slashing for them - Tokens are locked for **7 epochs** before claiming - Each exit creates a separate withdrawal @@ -102,30 +107,30 @@ validatorWallet.validatorExit(sharesToExit); ``` Epoch 10: validatorExit() called → unbonding starts Epochs 11-16: Locked period -Epoch 17: validatorClaim() available +Epoch 17: earliest validatorClaim() ``` ### Claiming Withdrawn Funds as a Validator +The owner claims through the ValidatorWallet, which collects the matured withdrawals and forwards them to the owner: + ```solidity -uint256 tokensReceived = genStaking.validatorClaim(validatorWallet); +validatorWallet.validatorClaim(); ``` **Important Notes:** - Must wait **7 full epochs** after calling `validatorExit()` -- Claims are permissionless - anyone can trigger them -- Tokens are sent to the validator wallet's owner address +- A withdrawal is claimable only after it has been priced and any slashing for the epochs it served has been settled; until then a claim pays nothing - Multiple exits can be claimed in a single call -- Returns the total GEN received +- `genStaking.validatorClaim(validatorWallet)` is permissionless, but it pays the ValidatorWallet, not the owner; the owner still calls `validatorWallet.validatorClaim()` to receive the funds **Checking Claim Availability:** ```solidity uint256 exitEpoch = 10; -uint256 claimableAtEpoch = exitEpoch + 7; -uint256 currentEpoch = genStaking.epoch(); -if (currentEpoch >= claimableAtEpoch) { - genStaking.validatorClaim(validatorWallet); +uint256 claimableAtEpoch = exitEpoch + 7; // current default unbonding period +if (genStaking.epoch() >= claimableAtEpoch) { + validatorWallet.validatorClaim(); } ``` @@ -137,7 +142,7 @@ if (currentEpoch >= claimableAtEpoch) { **Requirements:** - Minimum delegation: **42 GEN** per validator -- Target validator must exist and be active +- Target validator must be a registered validator - Can delegate to multiple validators **Basic Delegation:** @@ -158,6 +163,7 @@ genStaking.delegatorJoin{value: 500 ether}(validator3); **Important Notes:** - Follows the **epoch +2 activation rule** - The validator's node automatically calls `validatorPrime()` to commit your delegation +- Delegating to a validator that is below its own minimum stake is allowed, but that validator is not selected until it meets the minimum - Choose validators with good uptime - Smaller validators often provide higher returns - Cannot delegate zero value @@ -169,15 +175,15 @@ genStaking.delegatorJoin{value: 500 ether}(validator3); ### Depositing as a Delegator +To add to an existing delegation, call `delegatorJoin()` again for the same validator: + ```solidity -genStaking.delegatorDeposit{value: 500 ether}(validatorWallet); +genStaking.delegatorJoin{value: 500 ether}(validatorWallet); ``` **Important Notes:** -- Use `delegatorDeposit()` to add to existing delegations - Follows the **epoch +2 activation rule** - The validator's node automatically calls `validatorPrime()` -- No minimum for additional deposits - Rewards automatically compound ### Withdrawing as a Delegator @@ -200,8 +206,8 @@ genStaking.delegatorExit(validatorWallet, sharesToExit); **Important Notes:** -- Can exit partial amounts -- Stop earning rewards immediately after exit +- Can exit partial amounts, but a partial exit cannot leave the delegation below the minimum; exit all shares instead +- Exited shares stop counting toward stake immediately; the withdrawal is priced at the validator's next priming - Tokens are locked for **7 epochs** - Exit each validator separately if delegating to multiple @@ -209,22 +215,23 @@ genStaking.delegatorExit(validatorWallet, sharesToExit); ``` Epoch 5: delegatorExit() called Epochs 6-11: Locked period -Epoch 12: delegatorClaim() available +Epoch 12: earliest delegatorClaim() ``` ### Claiming Withdrawn Funds as a Delegator ```solidity uint256 tokensReceived = genStaking.delegatorClaim( - delegatorAddress, + msg.sender, // must be the delegator validatorWallet ); ``` **Important Notes:** - Must wait **7 full epochs** after calling `delegatorExit()` -- Claims are permissionless - anyone can trigger them +- Only the delegator can claim; calls from any other address revert with `UnauthorizedDelegatorClaim` - Tokens are sent to the delegator's address +- A withdrawal is claimable only after it has been priced and any slashing for the epochs it served has been settled - Claim from each validator separately if delegated to multiple **Multi-Validator Claim Example:** @@ -245,11 +252,12 @@ Epoch 0 is the **genesis bootstrapping period** with special rules designed to f Epoch 0 is the **bootstrapping period** before the network becomes operational. During epoch 0: -- **No transactions are processed** - the network is not yet active +- **No transactions are processed** - the network accepts Intelligent Contract transactions only from epoch 2 - **No consensus occurs** - validators are not yet participating - Stakes are registered and prepared for activation in epoch 2 +- The epoch lasts at least its configured minimum duration (14 days by default; later epochs last at least 1 day) -**Important**: The network transitions directly from epoch 0 to epoch 2 (epoch 1 is skipped). Validators and delegators who stake in epoch 0 become active in epoch 2. +**Important**: When epoch 0 ends, the network normally moves directly to epoch 2 (epoch 1 is skipped). The skip requires the inflation for epoch 2 to have been delivered from Ethereum; otherwise the network waits in epoch 1 until it arrives. Validators and delegators who stake in epoch 0 become active in epoch 2. ### Special Rules for Epoch 0 @@ -271,8 +279,11 @@ Epoch 0 is the **bootstrapping period** before the network becomes operational. **Joining:** ```solidity -// In epoch 0, any amount is accepted (no 42,000 GEN minimum) -address validatorWallet = genStaking.validatorJoin{value: 1000 ether}(operatorAddress); +// In epoch 0, any non-zero amount is accepted (no 42,000 GEN minimum) +address validatorWallet = genStaking.validatorJoin{value: 1000 ether}( + operatorPubKey, + possessionProof +); // Stake is registered for activation in epoch 2 // No need to call validatorPrime() in epoch 0 @@ -290,7 +301,7 @@ address validatorWallet = genStaking.validatorJoin{value: 1000 ether}(operatorAd No. Validators who join in epoch 0: - Have their stake registered during epoch 0 -- Become active automatically in epoch 2 (epoch 1 is skipped) **only if they have at least 42,000 GEN staked** +- Become active automatically in epoch 2 **only if they have at least 42,000 GEN staked** - Must start calling `validatorPrime()` in epoch 2 for continued participation in epoch 4+ @@ -302,7 +313,7 @@ No. Validators who join in epoch 0: **Joining:** ```solidity -// In epoch 0, any amount is accepted (no 42 GEN minimum) +// In epoch 0, any non-zero amount is accepted (no 42 GEN minimum) genStaking.delegatorJoin{value: 10 ether}(validatorWallet); // Delegation is registered for activation in epoch 2 @@ -316,7 +327,7 @@ genStaking.delegatorJoin{value: 10 ether}(validatorWallet); **Is a delegation made in epoch 0 active in epoch 2?** -Yes. Delegations made in epoch 0 become active in epoch 2 (epoch 1 is skipped). Unlike normal epochs where you wait +2 epochs, epoch 0 delegations activate as soon as the network becomes operational. +Yes. Delegations made in epoch 0 become active in epoch 2. Unlike normal epochs where you wait +2 epochs, epoch 0 delegations activate as soon as the network becomes operational. ### Activation Timeline Comparison @@ -353,7 +364,7 @@ This is because there's no existing stake pool to calculate a ratio against. Sta ### Transitioning from Epoch 0 to Epoch 2 -When the network advances from epoch 0 to epoch 2 (epoch 1 is skipped): +When the network advances from epoch 0 to epoch 2: 1. **Epoch 0 stakes that meet minimums become active** - validators need 42,000 GEN, delegators need 42 GEN 2. **Normal minimum requirements apply** for new joins/deposits @@ -370,7 +381,7 @@ A: Yes, any non-zero amount is accepted during epoch 0. However, you will **not A: In epoch 2. Unlike normal epochs with a +2 delay, epoch 0 delegations activate when the network becomes operational. **Q: Do I need to call validatorPrime() in epoch 0?** -A: No. Priming is not required during epoch 0. Your node should start calling it automatically when epoch 2 begins (epoch 1 is skipped). +A: No. Priming is not required during epoch 0. Your node should start calling it automatically when epoch 2 begins. **Q: Will my epoch 0 stake still be active after epoch 0 ends?** A: Yes, if you meet the minimum requirements. Stakes from epoch 0 carry forward and remain active in all subsequent epochs. @@ -385,8 +396,11 @@ A: You'll be excluded from validator selection in epoch 4, but your stake remain ### Scenario 1: Becoming a Validator ```solidity -address validatorWallet = genStaking.validatorJoin{value: 42000 ether}(operatorAddress); -// Start validator node with operator address +address validatorWallet = genStaking.validatorJoin{value: 42000 ether}( + operatorPubKey, + possessionProof +); +// Start validator node with the operator key // Monitor: Epoch N joined, N+1 staged, N+2 active ``` @@ -408,13 +422,12 @@ genStaking.delegatorClaim(msg.sender, validator1); ### Scenario 3: Partial Validator Exit ```solidity -uint256[8] memory state = genStaking.validatorView(validatorWallet); -uint256 currentShares = state[1]; +uint256 currentShares = genStaking.validatorSelfSharesOf(validatorWallet); uint256 sharesToExit = (currentShares * 25) / 100; // Exit 25% validatorWallet.validatorExit(sharesToExit); // After 7 epochs: -genStaking.validatorClaim(validatorWallet); +validatorWallet.validatorClaim(); ``` --- @@ -424,7 +437,7 @@ genStaking.validatorClaim(validatorWallet); ### For Validators 1. **Ensure node health**: Your validator node automatically calls `validatorPrime()` -2. **Use separate keys**: Cold wallet for owner, hot wallet for operator +2. **Use separate keys**: Cold wallet for owner, hot key for operator 3. **Monitor priming**: Verify deposit activation occurs as expected 4. **Monitor quarantine status**: Check if your validator is quarantined 5. **Maintain high uptime**: Downtime leads to idleness strikes @@ -454,12 +467,16 @@ genStaking.validatorClaim(validatorWallet); | Error | Cause | Solution | |-------|-------|----------| | `ValidatorBelowMinimumStake` | Stake below 42,000 GEN | Deposit at least 42,000 GEN when joining | -| `OperatorAlreadyAssigned` | Operator address in use | Choose a different operator address | +| `InvalidOperatorAddress` | Zero operator, or deposit not sent through a joined ValidatorWallet | Register a valid operator key; deposit through `validatorWallet.validatorDeposit()` | +| `OperatorAlreadyAssigned` | Operator key in use by another owner's validator | Choose a different operator key | | `ValidatorMayNotDepositZeroValue` | Zero deposit amount | Deposit a non-zero amount | -| `ValidatorExitExceedsShares` | Exiting more shares than owned | Check shares with `validatorView()` | +| `ValidatorSlashInProgress` | A slash against the validator is being settled | Wait for priming to settle the slash, then retry | +| `ValidatorExitExceedsShares` | Exiting more shares than owned | Check shares with `validatorSelfSharesOf()` | +| `DelegatorExitWouldBeBelowMinimum` | Partial exit would leave less than the minimum delegation | Exit all shares or keep at least the minimum | +| `UnauthorizedDelegatorClaim` | Claim sent by an address other than the delegator | Send `delegatorClaim()` from the delegator's address | | Validator not selected | Node not priming | Ensure node runs and calls `validatorPrime()` | | Stake not activating | Priming not occurring | Monitor node for automatic `validatorPrime()` calls | -| Cannot claim withdrawn funds | Unbonding not complete | Verify 7 epochs have passed with `genStaking.epoch()` | +| Claim returns 0 | Unbonding not complete, withdrawal not yet priced, or slashing not yet settled | Verify the unbonding period has passed with `genStaking.epoch()` and that the validator has been primed | | Delegation not earning | Validator issues | Check if validator is quarantined/banned; consider switching | --- @@ -469,4 +486,5 @@ genStaking.validatorClaim(validatorWallet); - [Staking Concepts](/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking) - How staking works in GenLayer - [Unstaking](/understand-genlayer-protocol/core-concepts/optimistic-democracy/unstaking) - Unstaking process details - [Slashing](/understand-genlayer-protocol/core-concepts/optimistic-democracy/slashing) - Slashing penalties and conditions -- [GenLayer CLI Staking Commands](/api-references/genlayer-cli#staking-operations-testnet) - CLI reference for staking +- [GenLayer CLI Staking Commands](/api-references/genlayer-cli#staking-operations) - CLI reference for staking +- [genlayer-js staking methods](/api-references/genlayer-js/staking) - SDK reference for staking diff --git a/pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking.mdx b/pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking.mdx index 43aa44fac..c52eede2d 100644 --- a/pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking.mdx +++ b/pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking.mdx @@ -38,7 +38,7 @@ flowchart TB ``` - The **owner key** joins, deposits, exits, claims, changes the operator, and controls the validator identity. Keep it offline when practical. -- The **operator key** signs activations, proposals, commits, and reveals. It is the hot key configured on the node and can be replaced by the owner. +- The **operator key** signs activations, proposals, commits, and reveals. It is the hot key configured on the node. The owner registers its public key with a proof of possession when joining and can replace it later through a delayed two-step operator transfer. - The **ValidatorWallet** is a smart contract created when the validator joins. It is the validator's onchain identity and holds its stake accounting. It has no private key. diff --git a/pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/unstaking.mdx b/pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/unstaking.mdx index b218e17bf..15763aadf 100644 --- a/pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/unstaking.mdx +++ b/pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/unstaking.mdx @@ -30,7 +30,7 @@ flowchart TB 1. The validator owner or delegator chooses a positive number of shares and submits an exit. 2. The protocol stages the withdrawal and processes it through the validator's epoch records and `validatorPrime()`. 3. Once removed from active stake, those shares no longer contribute to selection weight or earn rewards. -4. After the unbonding period, anyone can trigger the claim for the beneficiary. Funds go to the owner or delegator, not the caller. +4. After the unbonding period, and once any slashing for the epochs the stake served has been settled, the beneficiary claims the GEN. A delegator claims directly from the Staking contract; only the delegator can submit that claim. A validator owner claims through the ValidatorWallet, which forwards the GEN to the owner. Under the current rules, the exit epoch still earns its normal rewards, and the unbonding period is seven epochs measured from the exit request. These values are protocol parameters. From ee7fd1171906873983092cf99d2589b3b1662faa Mon Sep 17 00:00:00 2001 From: kirilaa Date: Mon, 12 Oct 2026 12:25:10 +0200 Subject: [PATCH 4/9] docs: guard against zkSync and pre-v0.6 staking regressions Extend check-v06-release-docs to forbid zkSync / ZK Stack wording on the chain, network, keeper, node API and staking pages, require the Orbit inflation call and the join possession proof, and reject the removed validatorView array layout and payable delegatorDeposit. The staking guide and GenLayer Chain integration page join the internal-link check. --- scripts/check-v06-release-docs.js | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/scripts/check-v06-release-docs.js b/scripts/check-v06-release-docs.js index 88de59cc6..6cd27eff1 100644 --- a/scripts/check-v06-release-docs.js +++ b/scripts/check-v06-release-docs.js @@ -8,6 +8,7 @@ const failures = []; const releaseDocs = [ "pages/developers/consensus-v06-migration.mdx", + "pages/developers/staking-guide.mdx", "pages/developers/error-reference.mdx", "pages/developers/networks.mdx", "pages/developers/decentralized-applications/architecture-overview.mdx", @@ -34,6 +35,7 @@ const releaseDocs = [ "pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/slashing.mdx", "pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/deterministic-violations-and-tribunals.mdx", "pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/protocol-randomness.mdx", + "pages/understand-genlayer-protocol/core-concepts/rollup-integration.mdx", "pages/understand-genlayer-protocol/core-concepts/transactions/transaction-execution.mdx", "pages/understand-genlayer-protocol/core-concepts/transactions/transaction-statuses.mdx", "pages/validators/network-keeper-roles.mdx", @@ -189,6 +191,24 @@ for (const relativePath of [ forbidText(relativePath, "genlayer network testnet-bradbury", "pre-v0.40 network selection syntax"); } +for (const relativePath of [ + "pages/FAQ.mdx", + "pages/api-references/genlayer-node.mdx", + "pages/developers/networks.mdx", + "pages/developers/staking-guide.mdx", + "pages/understand-genlayer-protocol/what-is-genlayer.mdx", + "pages/understand-genlayer-protocol/core-concepts/rollup-integration.mdx", + "pages/validators/network-keeper-roles.mdx", +]) { + forbidText(relativePath, "zksync", "pre-Orbit zkSync reference"); + forbidText(relativePath, "ZK Stack", "pre-Orbit ZK Stack reference"); +} +requireText(keepers, "executeInflationRequest", "Orbit inflation request execution"); +forbidText(keepers, "executeL2Message", "zkSync inflation relay call"); +const stakingGuide = "pages/developers/staking-guide.mdx"; +requireText(stakingGuide, "possessionProof", "operator key possession proof on join"); +forbidText(stakingGuide, "uint256[8]", "pre-v0.6 validatorView array layout"); +forbidText(stakingGuide, "genStaking.delegatorDeposit{", "nonexistent payable delegatorDeposit"); for (const relativePath of releaseDocs) { const content = read(relativePath); From 99d998a75acf6216369134e787a9e4b947279979 Mon Sep 17 00:00:00 2001 From: kirilaa Date: Mon, 12 Oct 2026 12:36:51 +0200 Subject: [PATCH 5/9] docs: separate pre-v0.6 testnets, native deposits and failed delivery Address review on #671: - Networks and setup guide label the listed chain endpoint as the pre-v0.6 testnet chain and limit the Nitro full-node option to networks running v0.6. - Native GEN deposits through the Inbox are credited on inclusion and do not create a retryable; retryables apply to messages and contract calls such as inflation delivery. - The inflation relayer's "When to call" list now includes failed retryable redemption (redeem or keepalive) and deferred escrow delivery (ArbitrumInflationEscrow.retry()). --- pages/developers/networks.mdx | 2 +- .../core-concepts/rollup-integration.mdx | 4 ++-- pages/validators/network-keeper-roles.mdx | 9 ++++++++- pages/validators/setup-guide.mdx | 2 +- 4 files changed, 12 insertions(+), 5 deletions(-) diff --git a/pages/developers/networks.mdx b/pages/developers/networks.mdx index 850366da5..7637e7221 100644 --- a/pages/developers/networks.mdx +++ b/pages/developers/networks.mdx @@ -108,7 +108,7 @@ Local development with full control. Requires [GenLayer Studio](/developers/inte ## GenLayer Chain (L2) -The underlying Arbitrum Orbit chain that GenLayer runs on. GEN is its native currency, so balances and gas are in GEN. You typically don't need to interact with this directly — the GenLayer RPC passes through all `eth_*` calls. But if you need direct L2 access (e.g., token transfers, contract debugging at the EVM level), you can add this chain to your wallet. +The underlying chain that GenLayer runs on. From consensus v0.6 it is an Arbitrum Orbit chain; the endpoint below is the pre-v0.6 testnet chain that Asimov and Bradbury use until they upgrade. GEN is its native currency, so balances and gas are in GEN. You typically don't need to interact with this directly — the GenLayer RPC passes through all `eth_*` calls. But if you need direct L2 access (e.g., token transfers, contract debugging at the EVM level), you can add this chain to your wallet. | Setting | Value | |:--|:--| diff --git a/pages/understand-genlayer-protocol/core-concepts/rollup-integration.mdx b/pages/understand-genlayer-protocol/core-concepts/rollup-integration.mdx index b28651fb5..1e5fef75d 100644 --- a/pages/understand-genlayer-protocol/core-concepts/rollup-integration.mdx +++ b/pages/understand-genlayer-protocol/core-concepts/rollup-integration.mdx @@ -79,7 +79,7 @@ GEN is an ERC-20 token on Ethereum. On GenLayer Chain it is the **native currenc GEN moves between the two chains only through the chain's canonical Arbitrum bridge: -- **Ethereum to GenLayer Chain.** Deposits and messages enter through the chain's ERC-20 Inbox as *retryable tickets*. A retryable is normally redeemed automatically on GenLayer Chain. If automatic redemption fails, anyone can redeem it manually before it expires. +- **Ethereum to GenLayer Chain.** Native GEN deposits go through the chain's ERC-20 Inbox and are credited to the recipient once the sequencer includes them; they do not create a ticket to redeem. Messages and contract calls, including the protocol's inflation deliveries, are sent as *retryable tickets*. A retryable is normally redeemed automatically on GenLayer Chain. If automatic redemption fails, anyone can redeem it manually before it expires. - **GenLayer Chain to Ethereum.** Withdrawals and messages leave through the `ArbSys` system contract. They can be executed on Ethereum through the Outbox only after the rollup assertion that contains them is confirmed, which happens after the chain's challenge period. A sequencer receipt or an L2 event alone cannot authorize an action on Ethereum. The protocol uses the same path for its own token flows. Inflation is minted on Ethereum and delivered to the staking contract on GenLayer Chain as a retryable ticket; staking acknowledgements and burns travel back through the Outbox. These steps are permissionless—see [network keeper roles](/validators/network-keeper-roles). @@ -97,7 +97,7 @@ Exchanges, wallets, and indexers can treat GenLayer Chain as an Arbitrum-based E - Use standard Ethereum tooling and `eth_*` JSON-RPC methods against the GenLayer Chain RPC or the GenLayer RPC, which passes `eth_*` calls through. Chain IDs and endpoints are listed on [Networks](/developers/networks). - Track GEN on GenLayer Chain as the native asset, not as an ERC-20 token. On Ethereum, track it as an ERC-20 token. - Expect Arbitrum transaction types and receipt fields, such as the internal system transaction at the start of each block and `gasUsedForL1` in receipts. Current Ethereum libraries handle them; custom decoders may need updates. -- Plan for the challenge period on withdrawals to Ethereum. Deposits from Ethereum arrive after their retryable ticket is redeemed. +- Plan for the challenge period on withdrawals to Ethereum. Native GEN deposits from Ethereum are credited once the sequencer includes them. - Use the Intelligent Contract transaction status from the GenLayer RPC to decide whether an Intelligent Contract outcome is final, as described below. ## Settlement and protocol finality are different diff --git a/pages/validators/network-keeper-roles.mdx b/pages/validators/network-keeper-roles.mdx index fc9df9cad..dc84d1f66 100644 --- a/pages/validators/network-keeper-roles.mdx +++ b/pages/validators/network-keeper-roles.mdx @@ -50,7 +50,14 @@ Steps 2 and 5 **cannot happen on-chain by themselves**: an L2→L1 message can e **This role gates the entire network's epoch progression.** The L2 `Staking.epochAdvance()` can only move forward while `epoch + 1 <= inflationEpoch`, and `inflationEpoch` only rises when inflation is delivered to Staking. **If no one relays inflation, epoch progression halts network-wide** once the current epoch catches up to `inflationEpoch`. Staking requests inflation ahead of the current epoch, but this is still the single most important keeper to keep running. -**When to call:** whenever a request or acknowledgement is waiting in the Outbox after confirmation, and whenever a request is approved but not yet executed. Pre-check a request before submitting: +**When to call:** whenever + +- a request or acknowledgement is waiting in the Outbox after confirmation; +- a request is approved on Ethereum but not yet executed; +- an inflation retryable failed automatic redemption — redeem it on GenLayer Chain before it expires, or extend its lifetime with a keepalive; or +- the inflation escrow holds an undelivered request because the Staking call failed (`DeliveryDeferred`) — call `ArbitrumInflationEscrow.retry()`. + +Pre-check a request before submitting: ```solidity // True while the request is approved on Ethereum and has not expired or been executed. diff --git a/pages/validators/setup-guide.mdx b/pages/validators/setup-guide.mdx index 29a47a534..eddfda06f 100644 --- a/pages/validators/setup-guide.mdx +++ b/pages/validators/setup-guide.mdx @@ -199,7 +199,7 @@ See the [GenVM Configuration](/validators/genvm-configuration) page for partner Each validator needs an HTTP RPC endpoint and a WebSocket endpoint for the [GenLayer Chain](/understand-genlayer-protocol/core-concepts/rollup-integration). Validators use them to read the chain state and events and to submit transactions. The WebSocket endpoint is required for new-block and log subscriptions. -GenLayer Chain is an Arbitrum Orbit chain, so you can use a GenLayer Chain RPC provider or run your own [Arbitrum Nitro full node](https://docs.arbitrum.io/run-arbitrum-node/run-full-node) for the chain. Testnet Asimov and Bradbury use the GenLayer Chain endpoints listed on [Networks](/developers/networks) until they upgrade to consensus v0.6. +On networks running consensus v0.6, GenLayer Chain is an Arbitrum Orbit chain, so you can use a GenLayer Chain RPC provider or run your own [Arbitrum Nitro full node](https://docs.arbitrum.io/run-arbitrum-node/run-full-node) for the chain. Testnet Asimov and Bradbury have not upgraded yet: connect them to their existing GenLayer Chain endpoints (see [Networks](/developers/networks)); a Nitro node does not serve that chain. One chain node can be shared between multiple validators. The optimal validator-to-node ratio is currently under evaluation. From 81a62851d45fe2da38db058e3d2638a52f33768e Mon Sep 17 00:00:00 2001 From: Edgars Date: Thu, 19 Nov 2026 10:05:48 +0000 Subject: [PATCH 6/9] docs: complete the Orbit architecture correction Correct the dApp chain description and preserve opt-in zkSync RPC forwarding for compatible upstreams. Extend the release documentation checks to catch both regressions. --- content/api-references/genlayer-node/content.mdx | 4 ++++ pages/api-references/genlayer-node.mdx | 4 ++++ .../decentralized-applications/architecture-overview.mdx | 2 +- scripts/check-v06-release-docs.js | 7 ++++++- 4 files changed, 15 insertions(+), 2 deletions(-) diff --git a/content/api-references/genlayer-node/content.mdx b/content/api-references/genlayer-node/content.mdx index 610ab70ad..10f9615a1 100644 --- a/content/api-references/genlayer-node/content.mdx +++ b/content/api-references/genlayer-node/content.mdx @@ -34,6 +34,10 @@ The GenLayer Node also supports Ethereum-compatible methods that are proxied to - `eth_call` - And other standard Ethereum JSON-RPC methods +## zkSync Compatibility + +The node can forward `zks_*` methods to an upstream that supports the [zkSync JSON-RPC API](https://docs.zksync.io/zksync-protocol/api/zks-rpc). Set `node.rpc.endpoints.zksync.enabled` to `true` to enable forwarding for a compatible upstream. Keep the default value of `false` on Bradbury Phase 2, which runs on Arbitrum Orbit. + ## Usage Examples ### cURL diff --git a/pages/api-references/genlayer-node.mdx b/pages/api-references/genlayer-node.mdx index 8c30fe0d4..de28a841b 100644 --- a/pages/api-references/genlayer-node.mdx +++ b/pages/api-references/genlayer-node.mdx @@ -1657,6 +1657,10 @@ The GenLayer Node also supports Ethereum-compatible methods that are proxied to - `eth_call` - And other standard Ethereum JSON-RPC methods +## zkSync Compatibility + +The node can forward `zks_*` methods to an upstream that supports the [zkSync JSON-RPC API](https://docs.zksync.io/zksync-protocol/api/zks-rpc). Set `node.rpc.endpoints.zksync.enabled` to `true` to enable forwarding for a compatible upstream. Keep the default value of `false` on Bradbury Phase 2, which runs on Arbitrum Orbit. + ## Usage Examples ### cURL diff --git a/pages/developers/decentralized-applications/architecture-overview.mdx b/pages/developers/decentralized-applications/architecture-overview.mdx index 0790082bf..8d16a87f0 100644 --- a/pages/developers/decentralized-applications/architecture-overview.mdx +++ b/pages/developers/decentralized-applications/architecture-overview.mdx @@ -20,7 +20,7 @@ Fee-charging writes carry an explicit policy for consensus time units, execution ### Consensus Layer The consensus layer implements GenLayer's Optimistic Democracy mechanism to ensure reliable and secure execution of transactions using a validator-driven commit-reveal scheme. It also handles appeals and transaction finality to maintain integrity and fairness. -It is built on ZK-stack rollups to provide scalability and cost-efficiency, secure state updates, and anchoring to Ethereum's security model. +The consensus contracts run on [GenLayer Chain](/understand-genlayer-protocol/core-concepts/rollup-integration), an Arbitrum Orbit L2 that settles to Ethereum and uses GEN as its native gas token. ### Execution Environment The execution environment (the GenVM) is the engine that executes Intelligent Contracts. It supports both deterministic and non-deterministic operations, enabling AI integration and web data access. diff --git a/scripts/check-v06-release-docs.js b/scripts/check-v06-release-docs.js index 6cd27eff1..3e30835ff 100644 --- a/scripts/check-v06-release-docs.js +++ b/scripts/check-v06-release-docs.js @@ -193,7 +193,7 @@ for (const relativePath of [ for (const relativePath of [ "pages/FAQ.mdx", - "pages/api-references/genlayer-node.mdx", + "pages/developers/decentralized-applications/architecture-overview.mdx", "pages/developers/networks.mdx", "pages/developers/staking-guide.mdx", "pages/understand-genlayer-protocol/what-is-genlayer.mdx", @@ -202,7 +202,12 @@ for (const relativePath of [ ]) { forbidText(relativePath, "zksync", "pre-Orbit zkSync reference"); forbidText(relativePath, "ZK Stack", "pre-Orbit ZK Stack reference"); + forbidText(relativePath, "ZK-stack", "pre-Orbit ZK Stack reference"); } +const nodeApi = "pages/api-references/genlayer-node.mdx"; +requireText(nodeApi, "## zkSync Compatibility", "preserved zkSync compatibility section anchor"); +requireText(nodeApi, "node.rpc.endpoints.zksync.enabled", "conditional zkSync upstream forwarding config"); +requireText(nodeApi, "default value of `false` on Bradbury Phase 2", "disabled zkSync forwarding on Orbit"); requireText(keepers, "executeInflationRequest", "Orbit inflation request execution"); forbidText(keepers, "executeL2Message", "zkSync inflation relay call"); const stakingGuide = "pages/developers/staking-guide.mdx"; From c4e0dd18bb45aced4a01cdca092602ac2427344f Mon Sep 17 00:00:00 2001 From: Edgars Date: Thu, 19 Nov 2026 10:26:41 +0000 Subject: [PATCH 7/9] docs: correct Orbit keeper recovery and staking examples Use the delegating contract's address through share lookup and claim. Distinguish queued exits from priming and unpaid claims from active-slash reverts. Document caller-funded ticket recovery, conditional keeper rewards, and Nitro transaction decoding for indexers. --- pages/developers/staking-guide.mdx | 38 ++++++++++--------- .../optimistic-democracy/unstaking.mdx | 6 +-- .../core-concepts/rollup-integration.mdx | 2 +- pages/validators/network-keeper-roles.mdx | 18 +++++---- scripts/check-v06-release-docs.js | 5 +++ 5 files changed, 39 insertions(+), 30 deletions(-) diff --git a/pages/developers/staking-guide.mdx b/pages/developers/staking-guide.mdx index 14c023f3c..7a5a1c375 100644 --- a/pages/developers/staking-guide.mdx +++ b/pages/developers/staking-guide.mdx @@ -46,7 +46,7 @@ Use your own key to operate the node yourself, or a separate hot key for cold/ho - Deposits activate **2 epochs after joining** - `validatorPrime()` is automatically called by your validator node each epoch - Monitor priming for proper activation within 2 epochs -- The operator cannot be the zero address, and cannot already operate another owner's validator +- The operator must be a nonzero address. If you register a separate hot key, it must be unused by any validator wallet, including your own. If you register the caller's own key, that address can operate multiple wallets. - To rotate the operator later, the owner calls `initiateOperatorTransfer` on the ValidatorWallet, then `completeOperatorTransfer` after the operator-transfer delay (or `cancelOperatorTransfer`) **Post-Join Steps:** @@ -98,8 +98,8 @@ validatorWallet.validatorExit(sharesToExit); **Important Notes:** -- Exited shares stop counting toward stake and selection weight immediately -- The withdrawal is priced at the validator's next priming; it still receives its share of rewards for the epochs it served and stays exposed to slashing for them +- After epoch 0, an exit immediately removes the shares from the owner's available balance and queues the withdrawal. When priming processes that withdrawal, it prices the shares and updates active stake and selection weight. +- The withdrawal still receives its share of rewards for the epochs it served and remains exposed to slashing for those epochs. - Tokens are locked for **7 epochs** before claiming - Each exit creates a separate withdrawal @@ -120,7 +120,8 @@ validatorWallet.validatorClaim(); **Important Notes:** - Must wait **7 full epochs** after calling `validatorExit()` -- A withdrawal is claimable only after it has been priced and any slashing for the epochs it served has been settled; until then a claim pays nothing +- Staking pays only withdrawals that have matured, have been priced, and have cleared the slash-settlement window. If none qualify, the Staking call returns zero. +- If a slash is actively being processed for the validator, the claim reverts with `ValidatorSlashInProgress`. Retry after priming finishes processing the slash. - Multiple exits can be claimed in a single call - `genStaking.validatorClaim(validatorWallet)` is permissionless, but it pays the ValidatorWallet, not the owner; the owner still calls `validatorWallet.validatorClaim()` to receive the funds @@ -138,6 +139,8 @@ if (genStaking.epoch() >= claimableAtEpoch) { ## Delegator Operations +In these Solidity examples, the contract calling `genStaking` owns the delegation. It uses `address(this)` to look up its shares and claim its GEN. Give it a payable `receive()` function so it can accept the payout. If you delegated directly from a wallet, submit the claim from that wallet and pass its address as the delegator. + ### Joining as a Delegator **Requirements:** @@ -190,8 +193,10 @@ genStaking.delegatorJoin{value: 500 ether}(validatorWallet); **Step 1: Calculate Shares** +The v0.6 `IGenLayerStaking` interface returns a `Shares` value. Import `Shares` from the consensus contracts' `contracts/types/Quantities.sol` and unwrap it before doing arithmetic. + ```solidity -uint256 currentShares = genStaking.sharesOf(msg.sender, validatorWallet); +uint256 currentShares = Shares.unwrap(genStaking.sharesOf(address(this), validatorWallet)); uint256 sharesToExit = (currentShares * 50) / 100; // Exit 50% ``` @@ -207,7 +212,7 @@ genStaking.delegatorExit(validatorWallet, sharesToExit); **Important Notes:** - Can exit partial amounts, but a partial exit cannot leave the delegation below the minimum; exit all shares instead -- Exited shares stop counting toward stake immediately; the withdrawal is priced at the validator's next priming +- After epoch 0, an exit immediately removes the shares from your available balance. When priming processes the withdrawal, it prices the shares and updates the validator's active delegated stake and selection weight. - Tokens are locked for **7 epochs** - Exit each validator separately if delegating to multiple @@ -221,10 +226,7 @@ Epoch 12: earliest delegatorClaim() ### Claiming Withdrawn Funds as a Delegator ```solidity -uint256 tokensReceived = genStaking.delegatorClaim( - msg.sender, // must be the delegator - validatorWallet -); +uint256 tokensReceived = genStaking.delegatorClaim(address(this), validatorWallet); ``` **Important Notes:** @@ -237,9 +239,9 @@ uint256 tokensReceived = genStaking.delegatorClaim( **Multi-Validator Claim Example:** ```solidity -genStaking.delegatorClaim(msg.sender, validator1); -genStaking.delegatorClaim(msg.sender, validator2); -genStaking.delegatorClaim(msg.sender, validator3); +genStaking.delegatorClaim(address(this), validator1); +genStaking.delegatorClaim(address(this), validator2); +genStaking.delegatorClaim(address(this), validator3); ``` --- @@ -412,11 +414,11 @@ genStaking.delegatorJoin{value: 2000 ether}(validator2); genStaking.delegatorJoin{value: 1500 ether}(validator3); // Later, exit from one validator -uint256 shares = genStaking.sharesOf(msg.sender, validator1); +uint256 shares = Shares.unwrap(genStaking.sharesOf(address(this), validator1)); genStaking.delegatorExit(validator1, shares); -// After 7 epochs: -genStaking.delegatorClaim(msg.sender, validator1); +// Once the withdrawal is claimable: +genStaking.delegatorClaim(address(this), validator1); ``` ### Scenario 3: Partial Validator Exit @@ -468,9 +470,9 @@ validatorWallet.validatorClaim(); |-------|-------|----------| | `ValidatorBelowMinimumStake` | Stake below 42,000 GEN | Deposit at least 42,000 GEN when joining | | `InvalidOperatorAddress` | Zero operator, or deposit not sent through a joined ValidatorWallet | Register a valid operator key; deposit through `validatorWallet.validatorDeposit()` | -| `OperatorAlreadyAssigned` | Operator key in use by another owner's validator | Choose a different operator key | +| `OperatorAlreadyAssigned` | The separate hot key already operates a validator wallet | Use an unused hot key, or register the caller's own key for self-operation | | `ValidatorMayNotDepositZeroValue` | Zero deposit amount | Deposit a non-zero amount | -| `ValidatorSlashInProgress` | A slash against the validator is being settled | Wait for priming to settle the slash, then retry | +| `ValidatorSlashInProgress` | A deposit or claim reverted during an active slash | Retry after priming finishes processing the slash | | `ValidatorExitExceedsShares` | Exiting more shares than owned | Check shares with `validatorSelfSharesOf()` | | `DelegatorExitWouldBeBelowMinimum` | Partial exit would leave less than the minimum delegation | Exit all shares or keep at least the minimum | | `UnauthorizedDelegatorClaim` | Claim sent by an address other than the delegator | Send `delegatorClaim()` from the delegator's address | diff --git a/pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/unstaking.mdx b/pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/unstaking.mdx index 15763aadf..90c2d0327 100644 --- a/pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/unstaking.mdx +++ b/pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/unstaking.mdx @@ -27,8 +27,8 @@ flowchart TB linkStyle default stroke:#7C879C,stroke-width:1.8px; ``` -1. The validator owner or delegator chooses a positive number of shares and submits an exit. -2. The protocol stages the withdrawal and processes it through the validator's epoch records and `validatorPrime()`. +1. After epoch 0, the validator owner or delegator submits an exit. The requested shares immediately leave the holder's available balance. +2. The protocol queues the withdrawal. When `validatorPrime()` processes it, the contract prices the shares and updates the validator's active stake and selection weight. 3. Once removed from active stake, those shares no longer contribute to selection weight or earn rewards. 4. After the unbonding period, and once any slashing for the epochs the stake served has been settled, the beneficiary claims the GEN. A delegator claims directly from the Staking contract; only the delegator can submit that claim. A validator owner claims through the ValidatorWallet, which forwards the GEN to the owner. @@ -42,7 +42,7 @@ The owner key controls validator exits and claims. The node's operator key canno ## Delegator exits -A delegator exits shares separately for each validator pool. Multiple matured withdrawals can be claimed together according to the staking contract's accounting. During unbonding, exited stake earns no rewards and remains subject to the protocol rules attached to the withdrawal record. +A delegator exits shares separately for each validator pool. One claim can collect multiple matured withdrawals from the same pool. Each withdrawal includes rewards and remains exposed to slashing for the epochs the stake served. Use current contract views or the SDK to calculate shares and claimability; do not convert a desired GEN amount to shares using a stale exchange rate. diff --git a/pages/understand-genlayer-protocol/core-concepts/rollup-integration.mdx b/pages/understand-genlayer-protocol/core-concepts/rollup-integration.mdx index 137245259..cf45f340f 100644 --- a/pages/understand-genlayer-protocol/core-concepts/rollup-integration.mdx +++ b/pages/understand-genlayer-protocol/core-concepts/rollup-integration.mdx @@ -96,7 +96,7 @@ Exchanges, wallets, and indexers can treat GenLayer Chain as an Arbitrum-based E - Use standard Ethereum tooling and `eth_*` JSON-RPC methods against the GenLayer Chain RPC or the GenLayer RPC, which passes supported `eth_*` calls through. Chain IDs and endpoints are listed on [Networks](/developers/networks). - Track GEN on GenLayer Chain as the native asset, not as an ERC-20 token. On Ethereum, track it as an ERC-20 token. -- Expect Arbitrum transaction types and receipt fields, such as the internal system transaction at the start of each block and `gasUsedForL1` in receipts. Current Ethereum libraries handle them; custom decoders may need updates. +- If you index full blocks, use a decoder that supports Nitro transaction types. For example, upstream go-ethereum v1.17.10 returns `transaction type not supported` for Nitro's internal system transaction (type `0x6a`), so a full-block read can fail. If you only need transaction hashes, request `eth_getBlockByNumber` with its second argument set to `false`. Receipts also include Arbitrum-specific fields such as `gasUsedForL1`. - Plan for the challenge period on withdrawals to Ethereum. Native GEN deposits from Ethereum are credited once the sequencer includes them. - Use the Intelligent Contract transaction status from the GenLayer RPC to decide whether an Intelligent Contract outcome is final, as described below. diff --git a/pages/validators/network-keeper-roles.mdx b/pages/validators/network-keeper-roles.mdx index dc84d1f66..83254dfac 100644 --- a/pages/validators/network-keeper-roles.mdx +++ b/pages/validators/network-keeper-roles.mdx @@ -17,7 +17,7 @@ Today the GenLayer Foundation operates a baseline set of these keepers so the ne | Role | Function | Who may call | Reward | Risk if idle | |---|---|---|---|---| -| **Inflation relayer** | Outbox execution, then `GEN.executeInflationRequest()` (Ethereum); retryable redemption (GenLayer Chain) | Anyone (permissionless) | Bounded gas reimbursement in GEN for `executeInflationRequest()`, when the keeper policy enables it. | **Epoch progression halts network-wide.** L2 cannot advance past `inflationEpoch`. | +| **Inflation relayer** | Outbox execution, then `GEN.executeInflationRequest()` (Ethereum); retryable redemption (GenLayer Chain) | Anyone (permissionless) | May receive a capped GEN reimbursement if the keeper policy enables it and the fee quote succeeds. | **Epoch progression halts network-wide.** L2 cannot advance past `inflationEpoch`. | | **Epoch advancer** | `Staking.epochAdvance()` (L2) | Anyone (permissionless) | None | Epochs stop advancing; fees/inflation are not distributed. | | **Validator primer** | `Staking.validatorPrime(validator)` (L2) | Anyone, on behalf of a validator | 1% of any slash that fires (only when a slash is pending and caller ≠ validator). Healthy validator → none. | Validator misses selection; pending slashes go unenforced. | | **Appellant** | SDK/CLI appeal operation (`topUpAndSubmitAppeal`) | Anyone (permissionless, payable) | Successful appeal returns 2.5× the bond: principal plus 1.5× profit. | Incorrect results are not challenged. | @@ -50,12 +50,12 @@ Steps 2 and 5 **cannot happen on-chain by themselves**: an L2→L1 message can e **This role gates the entire network's epoch progression.** The L2 `Staking.epochAdvance()` can only move forward while `epoch + 1 <= inflationEpoch`, and `inflationEpoch` only rises when inflation is delivered to Staking. **If no one relays inflation, epoch progression halts network-wide** once the current epoch catches up to `inflationEpoch`. Staking requests inflation ahead of the current epoch, but this is still the single most important keeper to keep running. -**When to call:** whenever +**When to intervene** -- a request or acknowledgement is waiting in the Outbox after confirmation; -- a request is approved on Ethereum but not yet executed; -- an inflation retryable failed automatic redemption — redeem it on GenLayer Chain before it expires, or extend its lifetime with a keepalive; or -- the inflation escrow holds an undelivered request because the Staking call failed (`DeliveryDeferred`) — call `ArbitrumInflationEscrow.retry()`. +- **Confirmed Outbox message.** Execute the waiting request or acknowledgement on Ethereum. Once a request is approved, call `GEN.executeInflationRequest` within its one-day approval window. +- **Live ticket.** If automatic redemption fails, redeem the ticket on GenLayer Chain before expiry or extend its lifetime with a keepalive. +- **Ticket expired before escrow registration.** On Ethereum, approve the GEN contract to spend the replacement ticket fee, then call `GEN.retryInflationDelivery(id, gasPrice, gasLimit, maxExternalFee)` for the outstanding request. The caller funds the replacement, which registers the same request with zero call value. The original ticket's refunded GEN funds delivery. If registration happens before the refund arrives, call `ArbitrumInflationEscrow.retry()` on GenLayer Chain once the escrow has the funds. +- **Registered and funded request.** If Staking rejected delivery and the escrow emitted `DeliveryDeferred`, call `ArbitrumInflationEscrow.retry()` on GenLayer Chain to retry with the GEN already there. Pre-check a request before submitting: @@ -64,7 +64,9 @@ Pre-check a request before submitting: bool ready = GEN.isInflationRequestApproved(epochTo, gasPrice, gasLimit); ``` -**Reward:** a successful `executeInflationRequest()` reimburses the caller in GEN, minted on Ethereum and emitted as `KeeperRewardPaid`. The reward is the gas the call used plus a fixed overhead, priced at the lower of the paid gas price and a policy maximum, converted to GEN with the rollup's fee-token exchange rate, plus a premium, and capped at a policy maximum. A zero-cap policy disables it. Outbox executions and retryable redemptions are not reimbursed. The full inflation tranche still goes to Staking; the reward is not deducted from it. +**Gas reimbursement.** A successful `executeInflationRequest()` can leave the keeper paying the full gas cost. A zero reward cap disables reimbursement. If the fee quote fails, the inflation request still succeeds and GEN emits `KeeperRewardUnavailable`. When a quote succeeds under an enabled policy, read the GEN amount from `KeeperRewardPaid` on Ethereum. + +The quote caps both gas units (including a fixed overhead) and gas price, converts the cost to GEN, applies the policy premium, and caps the final amount. GEN mints the reward separately and delivers the full inflation tranche to Staking. Keepers cover their own Outbox, ticket replacement, and redemption costs. **Cadence:** follow the confirmation of each request and acknowledgement on Ethereum. Duplicate submissions are safe: an executed or expired approval reverts, and a late duplicate ticket cannot credit Staking twice. @@ -203,7 +205,7 @@ Paginated garbage collection that reclaims **expired** quarantine records. It on - **Prioritize the inflation relayer.** It is the only keeper whose absence halts the whole network, and the only one that can pay a standing reward. Everything else is a backstop to already-automated behavior. - **Check for a reward before assuming one.** Only the inflation relayer (gas reimbursement for `executeInflationRequest()`, when enabled), the validator primer (only on an actually-enforced slash), and the appellant (only on a successful appeal) ever pay. The rest are unpaid liveness/hygiene work. -- **Expect idempotency.** Inflation relays, stuck-tx healing, and quarantine GC are all safe to retry or double-submit — duplicate or non-applicable calls either revert or are no-ops, with no side effects. +- **Check ticket and escrow status before retrying.** A duplicate cannot credit Staking twice, but each replacement ticket costs the caller GEN. Redeem a live ticket or retry a registered escrow request before paying for a replacement. - **Watch gas vs. reward.** For the paid roles, compare the expected reward (the capped gas reimbursement, or the pending slash amount) against the transaction cost before submitting. ## Related Resources diff --git a/scripts/check-v06-release-docs.js b/scripts/check-v06-release-docs.js index 3e30835ff..dfaa2a9a2 100644 --- a/scripts/check-v06-release-docs.js +++ b/scripts/check-v06-release-docs.js @@ -209,11 +209,16 @@ requireText(nodeApi, "## zkSync Compatibility", "preserved zkSync compatibility requireText(nodeApi, "node.rpc.endpoints.zksync.enabled", "conditional zkSync upstream forwarding config"); requireText(nodeApi, "default value of `false` on Bradbury Phase 2", "disabled zkSync forwarding on Orbit"); requireText(keepers, "executeInflationRequest", "Orbit inflation request execution"); +requireText(keepers, "GEN.retryInflationDelivery(", "expired inflation ticket recovery"); +requireText(keepers, "KeeperRewardUnavailable", "successful relay with an unavailable fee quote"); forbidText(keepers, "executeL2Message", "zkSync inflation relay call"); const stakingGuide = "pages/developers/staking-guide.mdx"; requireText(stakingGuide, "possessionProof", "operator key possession proof on join"); forbidText(stakingGuide, "uint256[8]", "pre-v0.6 validatorView array layout"); forbidText(stakingGuide, "genStaking.delegatorDeposit{", "nonexistent payable delegatorDeposit"); +if (/genStaking\.(?:delegatorClaim|sharesOf)\(\s*msg\.sender\b/.test(read(stakingGuide))) { + failures.push(`${stakingGuide}: use the delegating contract's address for its shares and claims`); +} for (const relativePath of releaseDocs) { const content = read(relativePath); From 5c8fbe801584f4269aecefd2755a4a57dd5c2803 Mon Sep 17 00:00:00 2001 From: Edgars Date: Thu, 19 Nov 2026 10:42:06 +0000 Subject: [PATCH 8/9] docs: distinguish Bradbury AnyTrust data availability from settlement Carry the Bradbury clarification from #969 into the Orbit guide. Describe committee storage, certificate posting to Sepolia, and the full-data fallback separately from state assertion confirmation. --- .../core-concepts/rollup-integration.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pages/understand-genlayer-protocol/core-concepts/rollup-integration.mdx b/pages/understand-genlayer-protocol/core-concepts/rollup-integration.mdx index cf45f340f..ef3995ad8 100644 --- a/pages/understand-genlayer-protocol/core-concepts/rollup-integration.mdx +++ b/pages/understand-genlayer-protocol/core-concepts/rollup-integration.mdx @@ -9,7 +9,7 @@ import { Callout } from "nextra-theme-docs"; GenLayer Chain is an EVM-compatible [Arbitrum Orbit](https://docs.arbitrum.io/launch-arbitrum-chain/a-gentle-introduction) chain that settles to Ethereum and uses GEN as its native gas token. It hosts ordinary Solidity contracts and the consensus contracts that coordinate Intelligent Contract execution. GenVM is a separate execution environment operated by nodes; it is not an EVM precompile or part of the rollup's execution engine. - Consensus v0.6 and later run on the Arbitrum Orbit GenLayer Chain, starting with Testnet Bradbury Phase 2. Check [Networks](/developers/networks) for the current endpoints. + Testnet Bradbury Phase 2 runs consensus v0.6 on Arbitrum Orbit and settles to Ethereum Sepolia. It uses [AnyTrust](https://docs.arbitrum.io/how-arbitrum-works/deep-dives/anytrust-protocol) for data availability. Normally, a committee stores the batch data and signs a certificate, which the sequencer posts to Sepolia. If the sequencer cannot obtain a certificate, it can post the full batch data to Sepolia. See [Networks](/developers/networks) for the current endpoints. ```mermaid @@ -87,7 +87,7 @@ The protocol uses the same path for its own token flows. Inflation is minted on ## Blocks, time, and fees - **Block numbers.** The consensus contracts record GenLayer Chain block numbers, read through `ArbSys.arbBlockNumber()`. On Arbitrum chains, Solidity's `block.number` returns an approximate Ethereum block number instead, so do not compare it with consensus block fields. Phase windows and timeouts use block timestamps. -- **EVM gas.** Gas on GenLayer Chain covers execution on the chain plus the cost of posting transaction data to the parent chain. Both components are charged in GEN. +- **EVM gas.** Gas on GenLayer Chain covers execution on the chain and a share of the cost of posting batches to the parent chain. Both components are charged in GEN. - **Intelligent Contract fees.** The fee budget of an Intelligent Contract transaction is separate from the EVM gas of the enclosing transaction. See the [economic model](/understand-genlayer-protocol/core-concepts/economic-model). ## Integrating with GenLayer Chain @@ -105,7 +105,7 @@ Exchanges, wallets, and indexers can treat GenLayer Chain as an Arbitrum-based E GenLayer Chain transactions reach several levels of confirmation: 1. **Sequencer inclusion.** The chain's sequencer orders the transaction into a block. This is the confirmation most EVM tooling reports. -2. **Ethereum settlement.** The chain posts its transaction data and state assertions to Ethereum. An assertion is confirmed after the challenge period; only then can its withdrawals and messages execute on Ethereum. +2. **Ethereum settlement.** The rollup posts state assertions to its Ethereum parent chain. Once an assertion is confirmed after the challenge period, its withdrawals and messages can execute on the parent chain. 3. **Protocol finality.** An Intelligent Contract transaction is final only after its consensus decision and appeal window complete. Applications must use the Intelligent Contract transaction status—not only the enclosing EVM transaction receipt—to determine whether an outcome is final. See [finality](/understand-genlayer-protocol/core-concepts/optimistic-democracy/finality). From 2be42aeeaece403f76af796eac9f0b1a81acd82c Mon Sep 17 00:00:00 2001 From: Edgars Date: Thu, 19 Nov 2026 12:10:11 +0000 Subject: [PATCH 9/9] Clarify that validator exits remain subject to pending slashes Document that a withdrawal remains exposed for the epochs it backed and explain how keepers advance settlement when the validator stops priming. --- pages/validators/network-keeper-roles.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/validators/network-keeper-roles.mdx b/pages/validators/network-keeper-roles.mdx index 83254dfac..d8a298764 100644 --- a/pages/validators/network-keeper-roles.mdx +++ b/pages/validators/network-keeper-roles.mdx @@ -105,7 +105,7 @@ deducted from the epoch's slashed pool before the remainder is burned. Priming a **Cadence:** validators prime themselves each epoch, so a keeper only needs to target validators that (a) have an enactable pending slash and are not priming, or (b) have stopped priming entirely. Related permissionless storage-cleanup helpers — `validatorClean(...)` and `delegatorClean(...)` — reclaim finalized deposit/withdrawal records and carry no reward. - Slashing is time-locked and lazy: a recorded penalty becomes enactable only 2 epochs after the event, and is applied at the next priming. A validator that **exits before being primed** can avoid a pending slash; the caller incentive exists partly to pay third parties to prime-and-slash before that happens. + **An exit keeps the withdrawn stake slashable for the epochs it backed.** A validator can claim the withdrawal only after it has been priced, the unbonding period has elapsed, and slashing for those epochs has been settled. If the validator stops priming, any keeper can call `validatorPrime(validator)` to advance settlement once the penalty’s review delay has elapsed (two epochs by default). ---