Repository navigation
DXP-1353: Describe GenLayer Chain as an Arbitrum Orbit L2, not a ZK Stack chain #969
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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 of the L2 request, then `GEN.executeInflationRequest()` (L1) | Anyone (permissionless) | Bounded, cost-based GEN reward for `executeInflationRequest()`, minted to caller. | **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,42 @@ 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:** `executeTransaction` on the canonical Arbitrum **Outbox** (L1), then `GEN.executeInflationRequest(epochTo, gasPrice, gasLimit)` on the **L1** GEN token contract. | ||
|
|
||
| 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. | ||
| Each epoch's inflation makes a round trip between GenLayer Chain (an Arbitrum Orbit L2) and its parent chain: | ||
|
|
||
| 1. The L2 Staking contract requests the next window of inflation by sending an L2→L1 message through `ArbSys`. | ||
| 2. Once the assertion that contains the message is confirmed on L1, after the chain's challenge period, anyone executes the message through the canonical Outbox. This approves that exact epoch and gas parameters on GEN for one day. | ||
| 3. Anyone then calls `GEN.executeInflationRequest()` with those parameters. GEN mints the inflation once and sends it to L2 as a retryable ticket through the chain's `ERC20Inbox`. On L2, `ArbitrumInflationEscrow` hands it to Staking. | ||
| 4. After Staking receives it, the escrow sends an acknowledgement back through `ArbSys`. Executing that acknowledgement through the Outbox, again after confirmation, closes the transfer on L1. Only one inflation transfer can be open at a time. | ||
|
|
||
| Steps 2 to 4 **cannot happen on-chain by themselves**: an L2→L1 message can only be executed on L1 after its assertion is confirmed, so someone has to submit the Outbox executions and the request off-chain. | ||
|
|
||
| <Callout type="error" emoji="🛑"> | ||
| **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 the requested inflation is delivered to L2. **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. | ||
| </Callout> | ||
|
|
||
| **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 confirmed inflation request or acknowledgement is waiting in the Outbox, and whenever GEN has an approved request. Check an approval 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 | ||
| ); | ||
| // True while the exact (epochTo, gasPrice, gasLimit) request is approved, | ||
| // not yet issued, and within its one-day window. | ||
| bool approved = GEN.isInflationRequestApproved(epochTo, gasPrice, gasLimit); | ||
| ``` | ||
|
|
||
| **Reward:** on a successful INFLATION relay, the caller is paid | ||
| **Reward:** a successful `executeInflationRequest()` mints its caller a bounded GEN reward based on the gas that call used, emitting `KeeperRewardPaid`. The Outbox executions and the proof generation are not reimbursed. The full inflation principal goes to Staking. | ||
|
|
||
| ``` | ||
| reward = totalInflation × incentivePercentage / 10000 | ||
| ``` | ||
| **Recovery:** if the L2 delivery fails, the principal stays in the escrow and anyone can call `ArbitrumInflationEscrow.retry()` on L2. A ticket that is still live can be redeemed or kept alive. `GEN.retryInflationDelivery()` resends the same request, paid entirely by the caller; it never mints the principal again. | ||
|
|
||
| **Cadence:** submit each step as soon as it becomes executable. Outbox executions wait for assertion confirmation, so do not assume a fixed delay. | ||
|
|
||
| **Replay protection, not idempotency.** Each step can succeed only once, and a repeated call **reverts**; it is not a silent no-op: | ||
|
|
||
| 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. | ||
| - An Outbox message can be executed once. Executing it again reverts in the Outbox (`AlreadySpent`). | ||
| - A successful `executeInflationRequest()` deletes its approval. Calling it again with the same parameters reverts with `ArbitrumRequestNotApproved`, as does a call after the one-day window. | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Document recovery for an approved request that expires before issuance. Line 42 grants the approval for one day after the Outbox execution. Line 68 states that a spent Outbox message cannot run again. Line 69 states that Document the procedure that restores an expired, unissued request. If no such procedure exists, state that explicitly and describe the resulting effect on epoch progression.
|
||
| - `executeInflationRequest()` also reverts with `InflationTransferPending` while an earlier transfer is still open, and with `InflationAlreadyRealized` if `epochTo` is not beyond the last issued epoch. | ||
|
|
||
| **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. | ||
| Before submitting, check the state so a duplicate costs nothing: simulate the call (`eth_call`), call `GEN.isInflationRequestApproved(epochTo, gasPrice, gasLimit)`, and compare `epochTo` with `GEN.lastInflationEpoch()`. When several keepers race, expect the losers' transactions to revert and pay gas; only the first call that lands is rewarded. | ||
|
|
||
| --- | ||
|
|
||
|
|
@@ -164,7 +173,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). | ||
|
|
||
| <Callout type="info"> | ||
| 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 L2 burn sends the GEN to L1 as a withdrawal through `ArbSys`. Completing it on L1 requires one further off-chain step: once the assertion that contains the withdrawal is confirmed, execute it through the canonical Outbox. That delivers the GEN to `ArbitrumGENBridge`, and GEN burns exactly the withdrawn amount. This step does **not** pay a keeper reward. See the staking system specification for the full burn flow. | ||
| </Callout> | ||
|
|
||
| **Reward:** none. | ||
|
|
@@ -191,14 +200,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. | ||
| **Reference implementations.** The consensus repository ships reference scripts for the multi-step relay flows — the Orbit keeper at `scripts/arbitrum/runKeeper.ts` runs one inflation or burn step per operation file (`execute-outbox`, `init`, `execute-request`, `retry`, `redeem-ticket`, `keepalive-ticket`). Use it as a starting point for a production keeper: it checks the Outbox proof and the request identity, simulates first, and sends only when asked. | ||
|
|
||
| **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. | ||
| - **Check for a reward before assuming one.** Only the inflation relayer (for `executeInflationRequest()`), 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. | ||
| - **Know which calls are idempotent.** Stuck-tx healing and quarantine GC are safe to retry: non-applicable calls are no-ops. Inflation relay steps are not: each succeeds once and a duplicate reverts (see [replay protection](#inflation-relayer)), so simulate before sending. | ||
| - **Watch gas vs. reward.** For the paid roles, compare the estimated reward (e.g. the gas-based `executeInflationRequest()` reward, or the pending slash amount) against the transaction cost before submitting. | ||
|
|
||
| ## Related Resources | ||
|
|
||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Distinguish allowlist rejection from an upstream error.
If an operator uses the documented proxy allowlist, the node rejects a non-allowlisted
zks_*method with-32601without forwarding it. This text says every method is forwarded and attributes the error to the chain. Describe the allowlist exception so operators can identify where the rejection occurred.