From d0e161c9db4e672272e3324b6b38170f167fdc55 Mon Sep 17 00:00:00 2001 From: Edgars Date: Fri, 3 Jul 2026 11:48:05 +0100 Subject: [PATCH 1/3] docs(developers): add delegator, bridging, and integrator guides MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add three user/integrator-facing pages under pages/developers and wire them into the developers _meta.json navigation: - delegating-gen.mdx — end-user (non-CLI-first) delegator guide: choose a validator (explorer Validators view + `genlayer staking validators`), delegate, monitor/claim rewards, and switch validators. Documents that switching is NOT atomic (exit -> 7-epoch unbonding -> claim -> rejoin; no redelegate) and the epoch-0 relaxed rules. Cross-links the Genesis Epoch 0 section and staking concepts/guide. - bridging-gen.mdx — practical L1<->L2 bridging how-to: deposit L1->L2, withdraw L2->L1, zkSync-style finalization timing (batch must finalize on L1 before a withdrawal can be proven; ~1h expectation on real networks), and how to track a transfer. Bridge routes/addresses left network-specific (points at Networks), no addresses invented. - exchange-wallet-integration.mdx — exchange/wallet/indexer onboarding: chain model, chain IDs/RPC/WS, 0x address format, native GEN vs L1 representation, deposit detection, and conservative finality guidance. Points at Networks and the Node API for canonical values. Also fix two stale `#staking-operations-testnet` anchors in staking-guide.mdx (real heading slug is `#staking-operations`) and add cross-links to the new delegator guide. --- pages/developers/_meta.json | 3 + pages/developers/bridging-gen.mdx | 100 +++++++++ pages/developers/delegating-gen.mdx | 202 ++++++++++++++++++ .../exchange-wallet-integration.mdx | 120 +++++++++++ pages/developers/staking-guide.mdx | 5 +- 5 files changed, 428 insertions(+), 2 deletions(-) create mode 100644 pages/developers/bridging-gen.mdx create mode 100644 pages/developers/delegating-gen.mdx create mode 100644 pages/developers/exchange-wallet-integration.mdx diff --git a/pages/developers/_meta.json b/pages/developers/_meta.json index a289e997..fa4d88f5 100644 --- a/pages/developers/_meta.json +++ b/pages/developers/_meta.json @@ -1,6 +1,9 @@ { "networks": "Networks & RPCs", + "bridging-gen": "Bridging GEN (L1 ↔ L2)", + "exchange-wallet-integration": "Exchange & Wallet Integration", "intelligent-contracts": "Intelligent Contracts", "decentralized-applications": "Frontend & SDK Integration", + "delegating-gen": "Delegating GEN", "staking-guide": "Staking Contract Guide" } diff --git a/pages/developers/bridging-gen.mdx b/pages/developers/bridging-gen.mdx new file mode 100644 index 00000000..d5f7cebb --- /dev/null +++ b/pages/developers/bridging-gen.mdx @@ -0,0 +1,100 @@ +--- +description: "How to bridge GEN between Ethereum (L1) and the GenLayer Chain (L2): deposit L1 to L2, withdraw L2 to L1, understand finalization timing, and track a transfer." +--- + +import { Callout } from "nextra-theme-docs"; +import { Card, Cards } from "nextra-theme-docs"; + +# Bridging GEN (L1 ↔ L2) + +GenLayer runs as an **L2 on the zkSync Elastic Chain**, anchored to Ethereum for security. "Bridging" moves GEN between the two layers: a **deposit** brings GEN from Ethereum (L1) onto the GenLayer Chain (L2) so you can use it on GenLayer, and a **withdrawal** sends GEN from L2 back to L1. + +This is a practical how-to for token holders. It covers what to expect at each step, the timing that surprises people (withdrawals are not instant), and how to track a transfer while it settles. + + + **Exact bridge routes and contract addresses are network-specific and are not duplicated here.** Always start from the official [Networks](/developers/networks) page for the RPC endpoints, chain IDs, and explorer links of the network you're using, and use the bridge entry point published for that network. Do not send funds to an address you found in a guide, chat, or search result — verify it against the canonical network information first. + + +## Before you start + +Bridging touches two chains, so you need both set up: + +- **The GenLayer Chain (L2) in your wallet.** Add it from the [GenLayer Chain (L2)](/developers/networks#genlayer-chain-l2) section on the Networks page (it includes an "add to wallet" control). GEN is the **native** token on this chain — balances are denominated in wei (1 GEN = 10¹⁸ wei). +- **The corresponding L1 (Ethereum) network** in the same wallet, holding the GEN you want to deposit plus a little of the L1 gas token to pay for the deposit transaction. +- **Gas on both sides.** A deposit costs L1 gas; a withdrawal costs L2 gas to initiate and then L1 gas to finalize/claim on Ethereum. + + + GenLayer is built on the zkSync Elastic Chain, so bridging behaves like a standard zkSync-stack L2 bridge. If you've bridged on a zkSync-based rollup before, the mental model here is the same. The specifics — which L1, which bridge UI, which addresses — depend entirely on the network you're connecting to. + + +--- + +## Deposit: L1 → L2 + +Deposits are the fast direction. Bringing GEN from Ethereum onto the GenLayer Chain follows the standard rollup deposit flow: + +1. **Connect to the bridge** entry point for your target network (linked from the [Networks](/developers/networks) page) with the wallet that holds your L1 GEN. +2. **Select the deposit direction** (L1 → GenLayer Chain) and the amount of GEN. +3. **Approve and submit the L1 transaction.** Your wallet signs a transaction on Ethereum that locks/handles the GEN on L1 and instructs the rollup to credit it on L2. +4. **Wait for the L2 credit.** After the L1 transaction is included, the deposit is relayed to L2 and your L2 GEN balance updates. This direction typically completes on the order of minutes — far faster than a withdrawal — but the exact timing depends on L1 inclusion and the network's relay. + + + Once the deposit lands on L2, your GEN is the native currency of the GenLayer Chain — you can transfer it, pay fees with it, or [delegate it to a validator](/developers/delegating-gen). + + +--- + +## Withdraw: L2 → L1 + +Withdrawals are the slow direction, and the reason is fundamental to how zkSync-style rollups secure L2 → L1 messages. A withdrawal is a **two-phase** process: + +1. **Initiate on L2.** Submit the withdrawal transaction on the GenLayer Chain. This burns/locks the GEN on L2 and emits an L2 → L1 message. +2. **Finalize on L1.** After the L2 batch containing your withdrawal has been **committed, proven, and finalized on Ethereum**, you (or a relayer) submit a finalization/claim transaction on L1 that proves the withdrawal message and releases the GEN on Ethereum. + + + **A withdrawal cannot be proved on L1 until the L2 batch that includes it has finalized on Ethereum.** On real networks this settlement takes **on the order of an hour** (sometimes longer), because it depends on the rollup batching your transaction, submitting it to Ethereum, and the validity proof being verified there. The exact duration is network- and load-dependent — treat "about an hour" as a rough expectation, not a guarantee, and don't assume a withdrawal is stuck just because it hasn't finalized within a few minutes. + + + + **This is different from GenLayer transaction finality.** GenLayer's [Finality Window](/understand-genlayer-protocol/core-concepts/optimistic-democracy/finality) governs when an Intelligent Contract transaction's *result* is settled and no longer appealable — a consensus-layer concept. The withdrawal timing above is about the **L2 batch settling on Ethereum L1** so the bridge message can be proven. They are separate mechanisms with separate clocks; don't conflate the two. + + +Depending on the network's tooling, the L1 finalization step may be automatic (a relayer submits it for you) or manual (you return to the bridge and click "finalize/claim" once the batch has settled). Check the withdrawal instructions for your specific network. + +--- + +## Track a transfer + +Because a transfer spans two chains, you follow it on both: + +- **L2 side (GenLayer Chain).** Look up your deposit or withdrawal transaction on the **GenLayer Chain explorer** for your network — for the testnet that's the *Chain Explorer* linked on the [Networks](/developers/networks) page ([explorer.testnet-chain.genlayer.com](https://explorer.testnet-chain.genlayer.com/)). This confirms the L2 transaction was included and, for withdrawals, that the L2 → L1 message was emitted. +- **L1 side (Ethereum).** For a **deposit**, watch the L2 balance credit after your L1 transaction confirms. For a **withdrawal**, watch for the batch to finalize and then for your finalization/claim transaction on the L1 explorer — the GEN arrives on L1 only after that claim succeeds. +- **Bridge status page.** If the network's bridge UI shows a transfer/withdrawal status (e.g. "ready to finalize"), that is usually the clearest signal for when a withdrawal's L1 claim step becomes available. + + + Keep your transaction hashes. For a withdrawal you may need the L2 transaction hash to submit or look up the L1 finalization step later, especially if you close the bridge UI and come back after the batch settles. + + +--- + +## Common pitfalls + +| Pitfall | What to do | +|---|---| +| Expecting a withdrawal to arrive on L1 in minutes | Plan for the L2 batch to finalize on Ethereum first — on the order of an hour on real networks. The GEN is not lost; it's waiting to be provable. | +| Forgetting the L1 finalization step | A withdrawal is not complete until the L1 claim/finalize transaction succeeds. If your network's bridge doesn't auto-finalize, you must return and complete it. | +| No L1 gas to finalize | Keep some L1 gas token available to pay for the withdrawal's finalization transaction. | +| Using an address from an unofficial source | Only use the bridge entry point and addresses published for your network via the [Networks](/developers/networks) page. | +| Confusing GenLayer finality with L2→L1 settlement | GenLayer's appeal/Finality Window and the L2 batch's L1 finalization are different things with different timing. | + +--- + +## Related resources + + + + + + + + diff --git a/pages/developers/delegating-gen.mdx b/pages/developers/delegating-gen.mdx new file mode 100644 index 00000000..5519b0ba --- /dev/null +++ b/pages/developers/delegating-gen.mdx @@ -0,0 +1,202 @@ +--- +description: "A delegator's guide to staking GEN with a GenLayer validator: choose a validator, delegate, monitor and claim rewards, and switch validators safely." +--- + +import { Callout } from "nextra-theme-docs"; +import { Card, Cards } from "nextra-theme-docs"; + +# Delegating GEN: A Delegator's Guide + +Delegating lets you put your GEN to work without running a validator node yourself. You pick a validator, delegate your GEN to it, and share in the rewards that validator earns for participating in consensus — while the validator does the operational work of running the node. + +This guide is written for token holders. It walks through the whole lifecycle: choosing a validator, delegating, monitoring and claiming rewards, and switching to a different validator. For the concepts underneath delegation (epochs, shares vs. stake, validator weight, reward distribution), see [Staking in GenLayer](/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking). + + + Delegating is not the same as running a validator. As a delegator you never operate a node — you back an existing validator with your stake. If you want to run your own node instead, see the [Validator Setup Guide](/validators/setup-guide). + + +## How delegation works, in brief + +- You delegate GEN to a specific validator. Your delegation is tracked as **shares** in that validator's pool, not as a fixed token amount. +- Rewards **compound**: as the validator earns, the value of each share grows, so your position grows without any action on your part. +- Delegations follow the network's **epoch** timing. A new delegation activates **2 epochs after** you make it (with a special exception during the genesis bootstrap — see [Delegating during Epoch 0](#delegating-during-epoch-0)). +- Exiting is **not instant**. When you unstake, your GEN is locked for an **unbonding period of 7 epochs** before you can claim it back. + + + Because you hold **shares**, not a token balance, you always **exit by specifying a number of shares** (or a percentage of your shares), never a GEN amount. Keep this in mind for every unstake. + + +An epoch is a fixed time window in which the validator set is active; on the network, an epoch lasts one day. See [Epoch System](/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking#epoch-system) for details. + +--- + +## Step 1 — Choose a validator + +Your rewards and risk both depend on the validator you back. Evaluate candidates before committing. + +### Where to look + +- **Block explorer (no tooling required).** Open the explorer for your network and find its **Validators** view — it lists the active validator set with each validator's stake and status. On [Testnet Bradbury](/developers/networks#testnet-bradbury) that's [explorer-bradbury.genlayer.com](https://explorer-bradbury.genlayer.com); each network's explorer is linked from the [Networks](/developers/networks) page. +- **CLI (for a scriptable, always-current list).** The [GenLayer CLI](/api-references/genlayer-cli) prints the validator set with stake, status, and voting power: + + ```bash + genlayer staking validators + genlayer staking validators --all # also include banned validators + ``` + + To inspect a single validator's stake, shares, and live/banned status: + + ```bash + genlayer staking validator-info --validator 0xVALIDATOR_ADDRESS + ``` + +### What to evaluate + +| Signal | Why it matters | How to check | +|---|---|---| +| **Uptime / liveness** | Validators that miss their duties earn less and risk penalties, which drags on your rewards. | `live` field in `validator-info`; status column in the explorer. | +| **Not banned or quarantined** | A quarantined or banned validator is excluded from selection, so your delegation earns nothing while it's out. | `banned` field in `validator-info`; `genlayer staking validators --all` shows banned entries; `genlayer staking quarantined-validators` and `banned-validators` list them. | +| **Stake size** | Very large validators are heavily backed already; smaller (but reliable) validators can mean a larger share of that validator's rewards go to you. | Stake column in the explorer / `validators` output. | +| **Track record** | Consistent participation over time is a better signal than a single snapshot. | `genlayer staking validator-history --validator 0x...` shows recent per-epoch history. | + + + **Diversify.** You can delegate to more than one validator. Spreading your GEN across several reliable validators limits the impact if any single one has downtime or gets penalized. A downside of one validator does not affect delegations you hold with others. + + + + Rewards are never guaranteed and can be reduced by validator downtime or [slashing](/understand-genlayer-protocol/core-concepts/optimistic-democracy/slashing). Choosing a reliable validator is the single biggest lever you control. + + +--- + +## Step 2 — Delegate your GEN + +Make sure your wallet is connected to the right network first (RPC and chain ID are on the [Networks](/developers/networks) page), and that you hold enough GEN to cover your delegation plus transaction fees. + +### Minimum + +Under normal rules (epoch 2 onward), the minimum delegation is **42 GEN per validator**. During the genesis bootstrap (epoch 0) this minimum is relaxed — see [Delegating during Epoch 0](#delegating-during-epoch-0). + +### Delegate with the CLI + +```bash +genlayer staking delegator-join --validator 0xVALIDATOR_ADDRESS --amount 42gen +``` + +The `--amount` accepts a value in wei, or with a `gen` / `eth` suffix (for example `100gen`). To delegate to several validators, run the command once per validator with the address of each. + + + **When does it start earning?** Under normal rules, a new delegation activates **2 epochs after** you submit it. It begins accruing rewards once it's active, not the moment the transaction lands. Track the current epoch with `genlayer staking epoch-info`. + + +### Add more to an existing delegation + +To increase a delegation you already hold, delegate again to the **same validator** — additional deposits have no minimum, and rewards on your existing position keep compounding in the meantime. + +For the underlying contract-level calls (useful if you're integrating delegation into your own tooling rather than using the CLI), see the [Staking Contract Guide](/developers/staking-guide#delegator-operations). + +--- + +## Step 3 — Monitor and claim rewards + +### Rewards compound automatically + +You do **not** need to claim to keep earning. Rewards accrue into the validator's pool and raise the value of each share, so your delegated position grows on its own. Claiming is only needed when you want to withdraw GEN back to your wallet after unstaking (Step 4). + +### Check your position + +```bash +genlayer staking delegation-info --validator 0xVALIDATOR_ADDRESS +``` + +This shows your delegation with the given validator (defaulting to your signer address; pass `--delegator 0x...` to check another address). Because your position is denominated in shares, its GEN value moves as the pool earns. + +To see network-wide reward context for an epoch — total inflation, how much has been claimed, and how much is still unclaimed — use: + +```bash +genlayer staking epoch-info +genlayer staking epoch-info --epoch 4 # a specific (current or previous) epoch +``` + +See [Reward Distribution](/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking#reward-distribution) for how rewards are shared between a validator and its delegators. + +--- + +## Step 4 — Unstake and claim your GEN + +Unstaking is a two-phase process because of the unbonding period. + +**Phase 1 — Exit (start unbonding).** You specify how many **shares** to withdraw. Those shares stop earning immediately, and the corresponding GEN enters a **7-epoch** lock. + +```bash +# Withdraw a number of shares from a validator you delegate to +genlayer staking delegator-exit --validator 0xVALIDATOR_ADDRESS --shares SHARES +``` + +**Phase 2 — Claim (after unbonding).** Once 7 full epochs have passed since your exit, claim the GEN back to your address: + +```bash +genlayer staking delegator-claim --validator 0xVALIDATOR_ADDRESS +``` + +``` +Epoch 5: delegator-exit → unbonding starts, shares stop earning +Epochs 6–11: locked period (cannot claim yet) +Epoch 12: delegator-claim available +``` + + + Plan around the 7-epoch wait — that's roughly 7 days on the network. Exited GEN earns nothing during unbonding, so only exit what you actually intend to withdraw. Track eligibility with `genlayer staking epoch-info`. + + + + If you delegate to multiple validators, exit and claim from **each validator separately** — each delegation has its own shares and its own unbonding timer. + + +For the concept-level walkthrough of exits and cooldowns, see [Unstaking in GenLayer](/understand-genlayer-protocol/core-concepts/optimistic-democracy/unstaking). + +--- + +## Switching validators + +There is **no "redelegate" operation** on GenLayer. Moving your stake from one validator to another is not atomic — it is a full unstake from the old validator followed by a fresh delegation to the new one, with the unbonding period in between. Concretely: + +1. **Exit** your shares from your current validator: `genlayer staking delegator-exit --validator 0xOLD --shares SHARES`. +2. **Wait** the full **7-epoch** unbonding period (~7 days on the network). Your GEN is locked and earning nothing during this time. +3. **Claim** the released GEN back to your wallet: `genlayer staking delegator-claim --validator 0xOLD`. +4. **Delegate** the claimed GEN to the new validator: `genlayer staking delegator-join --validator 0xNEW --amount ...`. Remember this new delegation then takes **2 epochs** to activate. + + + **Switching is not instant and not free of downtime.** Between exiting the old validator and your new delegation activating, your GEN spends the unbonding period unstaked (no rewards) and then 2 more epochs pending activation. If you value continuity, consider building a new position with fresh GEN rather than moving an existing one — or diversifying across validators from the start so you rarely need to move stake at all. + + +--- + +## Delegating during Epoch 0 + +**Epoch 0 is the genesis bootstrapping period** before the network is operational. Its rules are deliberately relaxed to help the network launch, and they differ from everything above: + +- **Delegation is effectively free of the usual minimum** — any non-zero amount is accepted, so you can delegate below the normal 42 GEN threshold. +- **Below-minimum delegations are allowed to register**, but a delegation only becomes **active in epoch 2** if it meets the normal minimum by then. The network jumps straight from epoch 0 to epoch 2 (epoch 1 is skipped). +- **No rewards are earned in epoch 0**, because no transactions are processed yet. + +From **epoch 2 onward, normal rules apply**: the 42 GEN minimum, the +2-epoch activation delay, and the 7-epoch unbonding period all take effect. + + + If you delegate a below-minimum amount during epoch 0, top it up to at least **42 GEN** before epoch 2 begins, or that delegation will not activate. + + +The full epoch-0 rules — including validator behavior, share calculation, and the transition to epoch 2 — are documented in [Genesis Epoch 0](/developers/staking-guide#genesis-epoch-0). + +--- + +## Related resources + + + + + + + + + diff --git a/pages/developers/exchange-wallet-integration.mdx b/pages/developers/exchange-wallet-integration.mdx new file mode 100644 index 00000000..536e324b --- /dev/null +++ b/pages/developers/exchange-wallet-integration.mdx @@ -0,0 +1,120 @@ +--- +description: "Integrator guide for exchanges, wallets, and indexers onboarding GenLayer: chain IDs, RPC/WS endpoints, address formats, L1/L2 GEN, deposit detection, and finality guidance." +--- + +import { Callout } from "nextra-theme-docs"; +import { Card, Cards } from "nextra-theme-docs"; + +# Exchange & Wallet Integrator Guide + +This guide is for teams **onboarding GenLayer into existing infrastructure** — exchanges listing GEN, wallets adding the network, and indexers or custodians tracking balances and transfers. It orients you to the chain model, the endpoints and formats you'll integrate against, and the finality considerations that matter for crediting deposits. + + + **This page points at the canonical sources for concrete values rather than duplicating them.** Network IDs, RPC endpoints, and contract addresses change per network and over time. Always read the live values from the [Networks](/developers/networks) page and the validator [Setup Guide](/validators/setup-guide) before wiring anything up, and re-verify after network upgrades. + + +## Chain model + +GenLayer presents as **two layers**, and which one you integrate against depends on what you're doing: + +- **GenLayer RPC** — handles Intelligent Contract operations (`gen_*` methods) and also **passes through standard Ethereum (`eth_*`) calls** to the underlying chain. This is what wallets connect to for a unified experience. +- **GenLayer Chain (L2)** — the underlying **EVM-compatible zkSync Elastic Chain** that holds account balances and handles standard Ethereum operations. For exchange/custody workflows (balance tracking, native GEN transfers, deposit detection at the EVM level), this is the layer you'll typically index. + +The GenLayer Chain is a zkSync-stack L2 anchored to Ethereum (L1) for security. Because it's EVM-compatible, most existing Ethereum tooling and address handling applies directly. + +For the full method surface, see the [GenLayer Node API](/api-references/genlayer-node), which documents the supported `eth_*` methods (Ethereum compatibility) and the `zksync_`-prefixed methods proxied to the underlying zkSync infrastructure. + +--- + +## Endpoints, chain IDs, and currency + +Read the exact values from the [Networks](/developers/networks) page — do not hardcode them from this guide. For quick orientation, GenLayer exposes distinct environments, each with its own chain ID and RPC: + +- **Testnet Bradbury** and **Testnet Asimov** — see [Networks](/developers/networks#testnet-bradbury). Both currently share the same GenLayer **Chain** RPC and chain ID. +- **Studionet** (hosted dev) and **Localnet** (local dev) — separate chain IDs, useful for staging your integration before pointing at a testnet. +- **GenLayer Chain (L2)** — the underlying chain you'll index for balances/transfers; its RPC, chain ID, currency (**GEN**, 18 decimals), and chain explorer are in the [GenLayer Chain (L2)](/developers/networks#genlayer-chain-l2) section, which also provides an "add to wallet" control that emits the correct hex chain ID and native-currency metadata. + + + **WebSocket access.** The GenLayer Chain supports a WebSocket RPC in addition to HTTP (validator node config exposes it as `genlayerchainwebsocketurl`). If your indexer relies on subscriptions, confirm the current WS endpoint for your network from the canonical network information rather than assuming a URL. + + + + Both current testnets map to a **single shared GenLayer Chain ID**. If you key any internal routing or address-derivation on chain ID, account for the fact that Bradbury and Asimov are not distinguished by chain ID alone — distinguish them by the **GenLayer RPC endpoint** you connect to. + + +--- + +## Addresses + +GenLayer uses **Ethereum-style accounts**: addresses are `0x`-prefixed hexadecimal strings, and the account model has **Externally Owned Accounts** (controlled by private keys) and **Contract Accounts** (Intelligent Contracts). Standard Ethereum address handling — hex parsing, checksumming, key management — applies. See [Accounts and Addressing](/understand-genlayer-protocol/core-concepts/accounts-and-addresses) for the account model. + + + **Same address across both layers.** An Intelligent Contract's GEN balance is held by its "ghost contract" on the chain layer at the **same address**, so a given address refers to the same account whether you view it via the GenLayer RPC or directly on the GenLayer Chain. This simplifies balance tracking — you index one address space. + + +--- + +## The GEN token + +**GEN is the native token of the GenLayer Chain** (analogous to ETH on Ethereum), not an ERC-20 on that chain. Balances are denominated in **wei** (1 GEN = 10¹⁸ wei), and you read a balance with standard `eth_getBalance` against the chain RPC. + + + **On L1 vs L2.** GEN on the **GenLayer Chain (L2)** is the native currency, tracked via native-balance calls — there is no L2 ERC-20 token contract for it. For the **L1 (Ethereum) representation** of GEN and the bridge used to move it between layers, the relevant addresses and routes are **network-specific and published with the network's setup/bridge information — not in this guide**. Do not assume or reuse a token or bridge address from any other source; confirm it against the canonical network information before crediting or moving funds. See [Bridging GEN (L1 ↔ L2)](/developers/bridging-gen) for how transfers between layers work. + + +--- + +## Deposit detection + +For crediting user deposits of native GEN on the GenLayer Chain, the pattern mirrors any EVM chain: + +1. **Assign per-user deposit addresses** (or use a memo/tagging scheme if your custody model requires it) in the standard `0x` hex format. +2. **Follow new blocks** via the chain RPC (HTTP polling `eth_blockNumber` / `eth_getBlockByNumber`, or WebSocket subscriptions if available for your network). +3. **Match incoming native transfers** to your deposit addresses and read balances with `eth_getBalance`. Because GEN is native, watch native value transfers rather than ERC-20 `Transfer` logs. +4. **Wait for finality before crediting** (see below) — don't credit on first inclusion. + + + Because the GenLayer RPC passes through `eth_*` calls to the underlying chain, you can use standard Ethereum JSON-RPC clients. Point balance and block queries at the **GenLayer Chain** RPC for the cleanest view of native GEN movements at the EVM level. + + +--- + +## Finality guidance + +Frame confirmations **conservatively** — GenLayer has two distinct notions of "final," and crediting logic should respect the stronger one for your use case: + +- **L2 chain finality (settlement on Ethereum).** The GenLayer Chain is a zkSync-stack rollup: its blocks are batched, submitted to Ethereum L1, and finalized there via validity proofs. A transfer is only irreversibly settled once its batch has finalized on L1. For anything requiring L1-grade settlement (large deposits, withdrawals leaving the system), wait for L1 finalization rather than L2 inclusion alone. +- **GenLayer transaction finality (consensus).** For Intelligent Contract *results*, GenLayer uses a [Finality Window](/understand-genlayer-protocol/core-concepts/optimistic-democracy/finality) during which a transaction can be appealed; the result is only settled and irreversible after that window (see [transaction statuses](/understand-genlayer-protocol/core-concepts/transactions/transaction-statuses) — the terminal state is `finalized`). This matters if you're reacting to contract outcomes, not just native transfers. + + + The documentation does not publish a fixed block-confirmation count or a guaranteed L2→L1 settlement duration, and timing is network- and load-dependent. On real networks, L2→L1 settlement is on the **order of an hour**; treat that as an expectation to design around, not a contract. Choose a confirmation policy with margin, and verify current behavior against the network you're integrating before going live. + + + + Withdrawals off GenLayer inherit the rollup's L2→L1 timing — a withdrawal can't be proven on L1 until its L2 batch finalizes there. If your product exposes withdrawals to L1, surface this delay to users. See the withdrawal walkthrough in [Bridging GEN (L1 ↔ L2)](/developers/bridging-gen). + + +--- + +## Integration checklist + +- [ ] Pull chain IDs, RPC (HTTP + WS), currency, and explorer URLs from the [Networks](/developers/networks) page for **each** environment you support. +- [ ] Distinguish Bradbury vs. Asimov by **RPC endpoint**, not chain ID (they share one). +- [ ] Confirm the **L1 GEN representation and bridge route** from the network's canonical setup/bridge info — never hardcode a token or bridge address from a third-party source. +- [ ] Track native GEN via `eth_getBalance` and native transfers (not ERC-20 logs) on the GenLayer Chain. +- [ ] Set a **conservative confirmation/finality policy**; wait for L1 finalization for settlement-critical flows. +- [ ] Verify the current method surface and any `zksync_` proxying against the [GenLayer Node API](/api-references/genlayer-node). +- [ ] Re-validate all endpoints and addresses **after every network upgrade**. + +--- + +## Related resources + + + + + + + + + diff --git a/pages/developers/staking-guide.mdx b/pages/developers/staking-guide.mdx index df228bdc..67943757 100644 --- a/pages/developers/staking-guide.mdx +++ b/pages/developers/staking-guide.mdx @@ -10,7 +10,7 @@ The Staking Contract Guide explains how developers can interact directly with Ge 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). For a delegator-focused, non-CLI-first walkthrough, see [Delegating GEN](/developers/delegating-gen). ## Validator Operations @@ -469,4 +469,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 +- [Delegating GEN: A Delegator's Guide](/developers/delegating-gen) - End-user guide to picking a validator, delegating, and claiming rewards From d45e22f941f7c7a86b654244df79962ee5fc84ea Mon Sep 17 00:00:00 2001 From: Edgars Date: Thu, 19 Nov 2026 11:13:36 +0000 Subject: [PATCH 2/3] Document Orbit bridge transfers and Bradbury settlement for integrators --- pages/developers/bridging-gen.mdx | 38 +++++++++--------- pages/developers/delegating-gen.mdx | 8 ++-- .../exchange-wallet-integration.mdx | 39 ++++++++++--------- pages/developers/staking-guide.mdx | 4 +- 4 files changed, 45 insertions(+), 44 deletions(-) diff --git a/pages/developers/bridging-gen.mdx b/pages/developers/bridging-gen.mdx index d5f7cebb..5fe41343 100644 --- a/pages/developers/bridging-gen.mdx +++ b/pages/developers/bridging-gen.mdx @@ -7,12 +7,12 @@ import { Card, Cards } from "nextra-theme-docs"; # Bridging GEN (L1 ↔ L2) -GenLayer runs as an **L2 on the zkSync Elastic Chain**, anchored to Ethereum for security. "Bridging" moves GEN between the two layers: a **deposit** brings GEN from Ethereum (L1) onto the GenLayer Chain (L2) so you can use it on GenLayer, and a **withdrawal** sends GEN from L2 back to L1. +GenLayer Chain is an Arbitrum Orbit L2. A deposit moves ERC-20 GEN on Ethereum to native GEN on GenLayer Chain. A withdrawal returns native GEN to Ethereum as ERC-20 GEN. Bradbury Phase 2 settles to Ethereum Sepolia and uses AnyTrust for data availability. -This is a practical how-to for token holders. It covers what to expect at each step, the timing that surprises people (withdrawals are not instant), and how to track a transfer while it settles. +This guide follows a transfer through the canonical bridge from the first wallet signature to the balance change on the destination chain. - **Exact bridge routes and contract addresses are network-specific and are not duplicated here.** Always start from the official [Networks](/developers/networks) page for the RPC endpoints, chain IDs, and explorer links of the network you're using, and use the bridge entry point published for that network. Do not send funds to an address you found in a guide, chat, or search result — verify it against the canonical network information first. + Check your deployment on [Networks](/developers/networks). For Bradbury Phase 2, verify the chain ID and genesis hash. Obtain the canonical bridge route and L1 token address from the network’s official deployment information. If you cannot verify the route, stop before approving or sending GEN. ## Before you start @@ -24,7 +24,7 @@ Bridging touches two chains, so you need both set up: - **Gas on both sides.** A deposit costs L1 gas; a withdrawal costs L2 gas to initiate and then L1 gas to finalize/claim on Ethereum. - GenLayer is built on the zkSync Elastic Chain, so bridging behaves like a standard zkSync-stack L2 bridge. If you've bridged on a zkSync-based rollup before, the mental model here is the same. The specifics — which L1, which bridge UI, which addresses — depend entirely on the network you're connecting to. + Use the bridge for your specific GenLayer deployment. An Arbitrum One or Nova bridge address belongs to a different chain. --- @@ -33,10 +33,10 @@ Bridging touches two chains, so you need both set up: Deposits are the fast direction. Bringing GEN from Ethereum onto the GenLayer Chain follows the standard rollup deposit flow: -1. **Connect to the bridge** entry point for your target network (linked from the [Networks](/developers/networks) page) with the wallet that holds your L1 GEN. +1. **Connect to the canonical bridge** for your deployment with the wallet that holds your L1 GEN. Verify the parent network in your wallet. 2. **Select the deposit direction** (L1 → GenLayer Chain) and the amount of GEN. -3. **Approve and submit the L1 transaction.** Your wallet signs a transaction on Ethereum that locks/handles the GEN on L1 and instructs the rollup to credit it on L2. -4. **Wait for the L2 credit.** After the L1 transaction is included, the deposit is relayed to L2 and your L2 GEN balance updates. This direction typically completes on the order of minutes — far faster than a withdrawal — but the exact timing depends on L1 inclusion and the network's relay. +3. **Approve and deposit the GEN.** Check the spender and amount in the L1 token approval. Submit the native-token deposit through the chain’s ERC-20 Inbox. +4. **Verify the L2 credit.** When the sequencer includes the deposit, check the recipient’s native GEN balance. A native GEN deposit uses a direct Inbox credit. Contract calls and messages can use retryable tickets. Once the deposit lands on L2, your GEN is the native currency of the GenLayer Chain — you can transfer it, pay fees with it, or [delegate it to a validator](/developers/delegating-gen). @@ -46,20 +46,20 @@ Deposits are the fast direction. Bringing GEN from Ethereum onto the GenLayer Ch ## Withdraw: L2 → L1 -Withdrawals are the slow direction, and the reason is fundamental to how zkSync-style rollups secure L2 → L1 messages. A withdrawal is a **two-phase** process: +A [canonical withdrawal](https://docs.arbitrum.io/how-arbitrum-works/deep-dives/l2-to-l1-messaging) requires a transaction on each chain. -1. **Initiate on L2.** Submit the withdrawal transaction on the GenLayer Chain. This burns/locks the GEN on L2 and emits an L2 → L1 message. -2. **Finalize on L1.** After the L2 batch containing your withdrawal has been **committed, proven, and finalized on Ethereum**, you (or a relayer) submit a finalization/claim transaction on L1 that proves the withdrawal message and releases the GEN on Ethereum. +1. **Initiate on L2.** Select the L1 recipient and submit the withdrawal through the bridge. The L2 transaction uses `ArbSys` to create an L2-to-L1 message. Save its transaction hash. +2. **Claim on L1.** Wait for the rollup assertion covering the message to be confirmed on Ethereum after the deployment’s challenge period. Once the message is executable, you or a relayer can submit its inclusion proof to the L1 Outbox. A successful execution releases ERC-20 GEN to the L1 recipient. - **A withdrawal cannot be proved on L1 until the L2 batch that includes it has finalized on Ethereum.** On real networks this settlement takes **on the order of an hour** (sometimes longer), because it depends on the rollup batching your transaction, submitting it to Ethereum, and the validity proof being verified there. The exact duration is network- and load-dependent — treat "about an hour" as a rough expectation, not a guarantee, and don't assume a withdrawal is stuck just because it hasn't finalized within a few minutes. + **Check the message status before claiming.** The L2 receipt and publication of the batch are earlier milestones. The wait depends on the deployment’s challenge period and assertion confirmation. - **This is different from GenLayer transaction finality.** GenLayer's [Finality Window](/understand-genlayer-protocol/core-concepts/optimistic-democracy/finality) governs when an Intelligent Contract transaction's *result* is settled and no longer appealable — a consensus-layer concept. The withdrawal timing above is about the **L2 batch settling on Ethereum L1** so the bridge message can be proven. They are separate mechanisms with separate clocks; don't conflate the two. + The [GenLayer Finality Window](/understand-genlayer-protocol/core-concepts/optimistic-democracy/finality) governs appeals of Intelligent Contract results. The bridge uses the rollup assertion and the Outbox to determine when GEN can be claimed on Ethereum. -Depending on the network's tooling, the L1 finalization step may be automatic (a relayer submits it for you) or manual (you return to the bridge and click "finalize/claim" once the batch has settled). Check the withdrawal instructions for your specific network. +If the bridge offers a relayer, track its L1 execution transaction. Otherwise return to the bridge when the message becomes executable and submit the claim. --- @@ -67,12 +67,12 @@ Depending on the network's tooling, the L1 finalization step may be automatic (a Because a transfer spans two chains, you follow it on both: -- **L2 side (GenLayer Chain).** Look up your deposit or withdrawal transaction on the **GenLayer Chain explorer** for your network — for the testnet that's the *Chain Explorer* linked on the [Networks](/developers/networks) page ([explorer.testnet-chain.genlayer.com](https://explorer.testnet-chain.genlayer.com/)). This confirms the L2 transaction was included and, for withdrawals, that the L2 → L1 message was emitted. -- **L1 side (Ethereum).** For a **deposit**, watch the L2 balance credit after your L1 transaction confirms. For a **withdrawal**, watch for the batch to finalize and then for your finalization/claim transaction on the L1 explorer — the GEN arrives on L1 only after that claim succeeds. +- **L2 side (GenLayer Chain).** Use the Chain Explorer listed on [Networks](/developers/networks). Confirm the deposit credit or locate the withdrawal transaction and its L2-to-L1 message. +- **L1 side (Ethereum).** For a deposit, check the L1 deposit receipt and then confirm the L2 credit. For a withdrawal, find the successful Outbox execution on the parent-chain explorer and verify the recipient’s ERC-20 GEN balance. - **Bridge status page.** If the network's bridge UI shows a transfer/withdrawal status (e.g. "ready to finalize"), that is usually the clearest signal for when a withdrawal's L1 claim step becomes available. - Keep your transaction hashes. For a withdrawal you may need the L2 transaction hash to submit or look up the L1 finalization step later, especially if you close the bridge UI and come back after the batch settles. + Keep the L2 withdrawal hash so you can find the message and claim it when its assertion is confirmed. --- @@ -81,11 +81,11 @@ Because a transfer spans two chains, you follow it on both: | Pitfall | What to do | |---|---| -| Expecting a withdrawal to arrive on L1 in minutes | Plan for the L2 batch to finalize on Ethereum first — on the order of an hour on real networks. The GEN is not lost; it's waiting to be provable. | +| Expecting a withdrawal to arrive as soon as the L2 receipt appears | Track the message until its assertion is confirmed and the Outbox claim succeeds. | | Forgetting the L1 finalization step | A withdrawal is not complete until the L1 claim/finalize transaction succeeds. If your network's bridge doesn't auto-finalize, you must return and complete it. | | No L1 gas to finalize | Keep some L1 gas token available to pay for the withdrawal's finalization transaction. | -| Using an address from an unofficial source | Only use the bridge entry point and addresses published for your network via the [Networks](/developers/networks) page. | -| Confusing GenLayer finality with L2→L1 settlement | GenLayer's appeal/Finality Window and the L2 batch's L1 finalization are different things with different timing. | +| Using an address from another network | Verify the bridge and token against the deployment’s official information and the chain identity on [Networks](/developers/networks). | +| Confusing GenLayer finality with L2→L1 settlement | Follow the appeal window for an Intelligent Contract result and the Outbox message status for a bridge withdrawal. | --- diff --git a/pages/developers/delegating-gen.mdx b/pages/developers/delegating-gen.mdx index 5519b0ba..eda3e291 100644 --- a/pages/developers/delegating-gen.mdx +++ b/pages/developers/delegating-gen.mdx @@ -26,7 +26,7 @@ This guide is written for token holders. It walks through the whole lifecycle: c Because you hold **shares**, not a token balance, you always **exit by specifying a number of shares** (or a percentage of your shares), never a GEN amount. Keep this in mind for every unstake. -An epoch is a fixed time window in which the validator set is active; on the network, an epoch lasts one day. See [Epoch System](/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking#epoch-system) for details. +An epoch is a fixed time window in which the validator set is active; on the network, an epoch lasts one day. See [Epoch System](/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking#epoch-activation-and-priming) for details. --- @@ -36,7 +36,7 @@ Your rewards and risk both depend on the validator you back. Evaluate candidates ### Where to look -- **Block explorer (no tooling required).** Open the explorer for your network and find its **Validators** view — it lists the active validator set with each validator's stake and status. On [Testnet Bradbury](/developers/networks#testnet-bradbury) that's [explorer-bradbury.genlayer.com](https://explorer-bradbury.genlayer.com); each network's explorer is linked from the [Networks](/developers/networks) page. +- **Validator and staking UI.** On Bradbury Phase 2, use the [staking explorer](https://stakegen.com/explore/) to compare validators. Check the deployment details on [Networks](/developers/networks#testnet-bradbury) before connecting your wallet. - **CLI (for a scriptable, always-current list).** The [GenLayer CLI](/api-references/genlayer-cli) prints the validator set with stake, status, and voting power: ```bash @@ -118,7 +118,7 @@ genlayer staking epoch-info genlayer staking epoch-info --epoch 4 # a specific (current or previous) epoch ``` -See [Reward Distribution](/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking#reward-distribution) for how rewards are shared between a validator and its delegators. +See [Reward Distribution](/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking#rewards-and-risks) for how rewards are shared between a validator and its delegators. --- @@ -198,5 +198,5 @@ The full epoch-0 rules — including validator behavior, share calculation, and - + diff --git a/pages/developers/exchange-wallet-integration.mdx b/pages/developers/exchange-wallet-integration.mdx index 536e324b..a0e4a6c9 100644 --- a/pages/developers/exchange-wallet-integration.mdx +++ b/pages/developers/exchange-wallet-integration.mdx @@ -17,12 +17,12 @@ This guide is for teams **onboarding GenLayer into existing infrastructure** — GenLayer presents as **two layers**, and which one you integrate against depends on what you're doing: -- **GenLayer RPC** — handles Intelligent Contract operations (`gen_*` methods) and also **passes through standard Ethereum (`eth_*`) calls** to the underlying chain. This is what wallets connect to for a unified experience. -- **GenLayer Chain (L2)** — the underlying **EVM-compatible zkSync Elastic Chain** that holds account balances and handles standard Ethereum operations. For exchange/custody workflows (balance tracking, native GEN transfers, deposit detection at the EVM level), this is the layer you'll typically index. +- **GenLayer node RPC** handles Intelligent Contract operations (`gen_*`) and forwards supported Ethereum (`eth_*`) calls to the chain. Use a Phase 2-compatible node for Intelligent Contract operations on Bradbury. +- **GenLayer Chain (L2)** is the EVM-compatible Arbitrum Orbit chain that holds account balances and processes native GEN transfers. Connect to the chain RPC to index those transfers. -The GenLayer Chain is a zkSync-stack L2 anchored to Ethereum (L1) for security. Because it's EVM-compatible, most existing Ethereum tooling and address handling applies directly. +Bradbury Phase 2 settles to Ethereum Sepolia and uses AnyTrust for data availability. An AnyTrust certificate attests to batch data availability. Withdrawal eligibility depends on confirmation of the rollup assertion on the parent chain. -For the full method surface, see the [GenLayer Node API](/api-references/genlayer-node), which documents the supported `eth_*` methods (Ethereum compatibility) and the `zksync_`-prefixed methods proxied to the underlying zkSync infrastructure. +Use the [GenLayer Node API](/api-references/genlayer-node) to check which `eth_*` methods the node forwards. The optional `zks_*` compatibility proxy defaults to off on Bradbury Phase 2. Use standard Ethereum methods for Orbit integrations. --- @@ -30,16 +30,16 @@ For the full method surface, see the [GenLayer Node API](/api-references/genlaye Read the exact values from the [Networks](/developers/networks) page — do not hardcode them from this guide. For quick orientation, GenLayer exposes distinct environments, each with its own chain ID and RPC: -- **Testnet Bradbury** and **Testnet Asimov** — see [Networks](/developers/networks#testnet-bradbury). Both currently share the same GenLayer **Chain** RPC and chain ID. +- **Testnet Bradbury Phase 2** — [Networks](/developers/networks#testnet-bradbury) lists the chain RPC, chain ID and explorer. The chain RPC serves EVM requests. Intelligent Contract methods require a GenLayer node RPC. - **Studionet** (hosted dev) and **Localnet** (local dev) — separate chain IDs, useful for staging your integration before pointing at a testnet. - **GenLayer Chain (L2)** — the underlying chain you'll index for balances/transfers; its RPC, chain ID, currency (**GEN**, 18 decimals), and chain explorer are in the [GenLayer Chain (L2)](/developers/networks#genlayer-chain-l2) section, which also provides an "add to wallet" control that emits the correct hex chain ID and native-currency metadata. - **WebSocket access.** The GenLayer Chain supports a WebSocket RPC in addition to HTTP (validator node config exposes it as `genlayerchainwebsocketurl`). If your indexer relies on subscriptions, confirm the current WS endpoint for your network from the canonical network information rather than assuming a URL. + **WebSocket access.** Bradbury’s chain WebSocket requires a Conduit RPC key. Follow the configuration instructions on [Networks](/developers/networks#testnet-bradbury) before enabling subscriptions. - Both current testnets map to a **single shared GenLayer Chain ID**. If you key any internal routing or address-derivation on chain ID, account for the fact that Bradbury and Asimov are not distinguished by chain ID alone — distinguish them by the **GenLayer RPC endpoint** you connect to. + **Verify the deployment before crediting deposits.** Bradbury Phase 2 reuses chain ID 4221. Check the block-zero hash and AddressManager against [Networks](/developers/networks#testnet-bradbury) when onboarding or switching RPC providers. --- @@ -59,7 +59,7 @@ GenLayer uses **Ethereum-style accounts**: addresses are `0x`-prefixed hexadecim **GEN is the native token of the GenLayer Chain** (analogous to ETH on Ethereum), not an ERC-20 on that chain. Balances are denominated in **wei** (1 GEN = 10¹⁸ wei), and you read a balance with standard `eth_getBalance` against the chain RPC. - **On L1 vs L2.** GEN on the **GenLayer Chain (L2)** is the native currency, tracked via native-balance calls — there is no L2 ERC-20 token contract for it. For the **L1 (Ethereum) representation** of GEN and the bridge used to move it between layers, the relevant addresses and routes are **network-specific and published with the network's setup/bridge information — not in this guide**. Do not assume or reuse a token or bridge address from any other source; confirm it against the canonical network information before crediting or moving funds. See [Bridging GEN (L1 ↔ L2)](/developers/bridging-gen) for how transfers between layers work. + On the Ethereum parent chain, GEN is an ERC-20. Track that token’s events on L1 and native GEN balances on L2. Verify the L1 token and bridge addresses against the deployment’s official information. See [Bridging GEN](/developers/bridging-gen). --- @@ -68,30 +68,31 @@ GenLayer uses **Ethereum-style accounts**: addresses are `0x`-prefixed hexadecim For crediting user deposits of native GEN on the GenLayer Chain, the pattern mirrors any EVM chain: -1. **Assign per-user deposit addresses** (or use a memo/tagging scheme if your custody model requires it) in the standard `0x` hex format. +1. **Assign and monitor deposit addresses** in the standard `0x` hex format. For direct native transfers, identify the customer by the destination address. 2. **Follow new blocks** via the chain RPC (HTTP polling `eth_blockNumber` / `eth_getBlockByNumber`, or WebSocket subscriptions if available for your network). -3. **Match incoming native transfers** to your deposit addresses and read balances with `eth_getBalance`. Because GEN is native, watch native value transfers rather than ERC-20 `Transfer` logs. +3. **Verify each deposit.** For direct native transfers, match the recipient and value and check that the receipt succeeded in the canonical block. If you also accept transfers made by contracts, use a trace-capable provider to identify successful internal value transfers. `eth_getBalance` gives the current balance, not a history of deposits. 4. **Wait for finality before crediting** (see below) — don't credit on first inclusion. - Because the GenLayer RPC passes through `eth_*` calls to the underlying chain, you can use standard Ethereum JSON-RPC clients. Point balance and block queries at the **GenLayer Chain** RPC for the cleanest view of native GEN movements at the EVM level. + Full-block decoders must support Nitro system transactions, including type `0x6a`. If you only need hashes, request `eth_getBlockByNumber` with its second argument set to `false`. Fetch the relevant transaction and its receipt individually to verify the recipient, value and success before crediting it. --- ## Finality guidance -Frame confirmations **conservatively** — GenLayer has two distinct notions of "final," and crediting logic should respect the stronger one for your use case: +Choose the crediting threshold for each operation and record which signal the indexer requires. -- **L2 chain finality (settlement on Ethereum).** The GenLayer Chain is a zkSync-stack rollup: its blocks are batched, submitted to Ethereum L1, and finalized there via validity proofs. A transfer is only irreversibly settled once its batch has finalized on L1. For anything requiring L1-grade settlement (large deposits, withdrawals leaving the system), wait for L1 finalization rather than L2 inclusion alone. -- **GenLayer transaction finality (consensus).** For Intelligent Contract *results*, GenLayer uses a [Finality Window](/understand-genlayer-protocol/core-concepts/optimistic-democracy/finality) during which a transaction can be appealed; the result is only settled and irreversible after that window (see [transaction statuses](/understand-genlayer-protocol/core-concepts/transactions/transaction-statuses) — the terminal state is `finalized`). This matters if you're reacting to contract outcomes, not just native transfers. +- **Sequencer inclusion.** A successful L2 receipt records execution. Indexers can record a pending deposit at this point and track the containing block. +- **Ethereum settlement.** For a policy that requires a confirmed L2 state, wait for confirmation of the rollup assertion covering the transfer after the challenge period. Posting a batch or an AnyTrust certificate is an earlier event. +- **Intelligent Contract finality.** For a credit that depends on an Intelligent Contract outcome, check the GenLayer [transaction status](/understand-genlayer-protocol/core-concepts/transactions/transaction-statuses). The [Finality Window](/understand-genlayer-protocol/core-concepts/optimistic-democracy/finality) allows appeals before the result becomes final. - The documentation does not publish a fixed block-confirmation count or a guaranteed L2→L1 settlement duration, and timing is network- and load-dependent. On real networks, L2→L1 settlement is on the **order of an hour**; treat that as an expectation to design around, not a contract. Choose a confirmation policy with margin, and verify current behavior against the network you're integrating before going live. + Confirmation and challenge periods are deployment-specific. Use the parent-chain assertion status when your policy requires settlement. A fixed count of L2 blocks or elapsed minutes cannot establish that status. - Withdrawals off GenLayer inherit the rollup's L2→L1 timing — a withdrawal can't be proven on L1 until its L2 batch finalizes there. If your product exposes withdrawals to L1, surface this delay to users. See the withdrawal walkthrough in [Bridging GEN (L1 ↔ L2)](/developers/bridging-gen). + For a canonical withdrawal, show the L2 submission, the wait for assertion confirmation and the successful L1 Outbox claim as separate stages. See [Bridging GEN](/developers/bridging-gen). --- @@ -99,11 +100,11 @@ Frame confirmations **conservatively** — GenLayer has two distinct notions of ## Integration checklist - [ ] Pull chain IDs, RPC (HTTP + WS), currency, and explorer URLs from the [Networks](/developers/networks) page for **each** environment you support. -- [ ] Distinguish Bradbury vs. Asimov by **RPC endpoint**, not chain ID (they share one). +- [ ] Verify the Bradbury Phase 2 genesis hash and AddressManager alongside the chain ID. - [ ] Confirm the **L1 GEN representation and bridge route** from the network's canonical setup/bridge info — never hardcode a token or bridge address from a third-party source. - [ ] Track native GEN via `eth_getBalance` and native transfers (not ERC-20 logs) on the GenLayer Chain. -- [ ] Set a **conservative confirmation/finality policy**; wait for L1 finalization for settlement-critical flows. -- [ ] Verify the current method surface and any `zksync_` proxying against the [GenLayer Node API](/api-references/genlayer-node). +- [ ] Specify whether each credit requires sequencer inclusion, a confirmed assertion or a finalized Intelligent Contract result. +- [ ] Check the supported `eth_*` methods and test full-block decoding against a block containing a Nitro system transaction. - [ ] Re-validate all endpoints and addresses **after every network upgrade**. --- diff --git a/pages/developers/staking-guide.mdx b/pages/developers/staking-guide.mdx index 67943757..ded8a8a6 100644 --- a/pages/developers/staking-guide.mdx +++ b/pages/developers/staking-guide.mdx @@ -10,7 +10,7 @@ The Staking Contract Guide explains how developers can interact directly with Ge 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). For a delegator-focused, non-CLI-first walkthrough, see [Delegating GEN](/developers/delegating-gen). + For CLI-based staking operations (recommended for most users), see the [GenLayer CLI Staking Commands](/api-references/genlayer-cli/staking/staking). For a delegator-focused, non-CLI-first walkthrough, see [Delegating GEN](/developers/delegating-gen). ## Validator Operations @@ -469,5 +469,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) - CLI reference for staking +- [GenLayer CLI Staking Commands](/api-references/genlayer-cli/staking/staking) - CLI reference for staking - [Delegating GEN: A Delegator's Guide](/developers/delegating-gen) - End-user guide to picking a validator, delegating, and claiming rewards From 9a7219663e1bc852423d8398a9158cfb44d1d44d Mon Sep 17 00:00:00 2001 From: Edgars Date: Thu, 19 Nov 2026 11:41:59 +0000 Subject: [PATCH 3/3] Link the verified Bradbury bridge and correct exit-epoch rewards Use the Phase 2 Rollbridge route and its Sepolia GEN token. The Inbox and native-token readbacks match the deployment record. Explain when an exit affects available shares and rewards, independently of the seven-epoch claim schedule. --- pages/developers/bridging-gen.mdx | 6 +++--- pages/developers/delegating-gen.mdx | 16 ++++++++-------- pages/developers/exchange-wallet-integration.mdx | 2 +- pages/developers/staking-guide.mdx | 11 ++++++----- 4 files changed, 18 insertions(+), 17 deletions(-) diff --git a/pages/developers/bridging-gen.mdx b/pages/developers/bridging-gen.mdx index 5fe41343..0acd198d 100644 --- a/pages/developers/bridging-gen.mdx +++ b/pages/developers/bridging-gen.mdx @@ -12,7 +12,7 @@ GenLayer Chain is an Arbitrum Orbit L2. A deposit moves ERC-20 GEN on Ethereum t This guide follows a transfer through the canonical bridge from the first wallet signature to the balance change on the destination chain. - Check your deployment on [Networks](/developers/networks). For Bradbury Phase 2, verify the chain ID and genesis hash. Obtain the canonical bridge route and L1 token address from the network’s official deployment information. If you cannot verify the route, stop before approving or sending GEN. + For Bradbury Phase 2, open the [GenLayer testnet bridge on Rollbridge](https://genlayer-chain-testnet-cfn8m3xc6l-86e44e69a1216817.testnets.rollbridge.app/). Check that the route connects Ethereum Sepolia (11155111) and GenLayer Chain (4221). Verify the [Phase 2 genesis hash](/developers/networks#testnet-bradbury) and the [Sepolia GEN token](https://sepolia.etherscan.io/address/0x424242424b68330CcFb022881d25a6acC29852ea). If you cannot verify the route or token, stop before approving or sending GEN. ## Before you start @@ -33,7 +33,7 @@ Bridging touches two chains, so you need both set up: Deposits are the fast direction. Bringing GEN from Ethereum onto the GenLayer Chain follows the standard rollup deposit flow: -1. **Connect to the canonical bridge** for your deployment with the wallet that holds your L1 GEN. Verify the parent network in your wallet. +1. **Connect your wallet** to the [Bradbury Phase 2 bridge](https://genlayer-chain-testnet-cfn8m3xc6l-86e44e69a1216817.testnets.rollbridge.app/) and select Ethereum Sepolia as the source. Use the wallet that holds your Sepolia GEN. 2. **Select the deposit direction** (L1 → GenLayer Chain) and the amount of GEN. 3. **Approve and deposit the GEN.** Check the spender and amount in the L1 token approval. Submit the native-token deposit through the chain’s ERC-20 Inbox. 4. **Verify the L2 credit.** When the sequencer includes the deposit, check the recipient’s native GEN balance. A native GEN deposit uses a direct Inbox credit. Contract calls and messages can use retryable tickets. @@ -84,7 +84,7 @@ Because a transfer spans two chains, you follow it on both: | Expecting a withdrawal to arrive as soon as the L2 receipt appears | Track the message until its assertion is confirmed and the Outbox claim succeeds. | | Forgetting the L1 finalization step | A withdrawal is not complete until the L1 claim/finalize transaction succeeds. If your network's bridge doesn't auto-finalize, you must return and complete it. | | No L1 gas to finalize | Keep some L1 gas token available to pay for the withdrawal's finalization transaction. | -| Using an address from another network | Verify the bridge and token against the deployment’s official information and the chain identity on [Networks](/developers/networks). | +| Using an address from another network | Match the route and Sepolia GEN token to the Bradbury links above. Verify the destination genesis hash on [Networks](/developers/networks#testnet-bradbury). | | Confusing GenLayer finality with L2→L1 settlement | Follow the appeal window for an Intelligent Contract result and the Outbox message status for a bridge withdrawal. | --- diff --git a/pages/developers/delegating-gen.mdx b/pages/developers/delegating-gen.mdx index eda3e291..ad5823ee 100644 --- a/pages/developers/delegating-gen.mdx +++ b/pages/developers/delegating-gen.mdx @@ -126,27 +126,27 @@ See [Reward Distribution](/understand-genlayer-protocol/core-concepts/optimistic Unstaking is a two-phase process because of the unbonding period. -**Phase 1 — Exit (start unbonding).** You specify how many **shares** to withdraw. Those shares stop earning immediately, and the corresponding GEN enters a **7-epoch** lock. +**Phase 1 — Exit (start unbonding).** Specify how many **shares** to withdraw. The request removes them from your available balance and starts the seven-epoch wait. Active stake still earns its normal rewards for the exit epoch. Rewards on the withdrawn stake stop when validator priming processes the withdrawal and removes that stake from the active record. ```bash # Withdraw a number of shares from a validator you delegate to genlayer staking delegator-exit --validator 0xVALIDATOR_ADDRESS --shares SHARES ``` -**Phase 2 — Claim (after unbonding).** Once 7 full epochs have passed since your exit, claim the GEN back to your address: +**Phase 2 — Claim (after unbonding).** Count seven epochs from the exit request. Once the withdrawal has matured and been priced, claim the GEN back to your address: ```bash genlayer staking delegator-claim --validator 0xVALIDATOR_ADDRESS ``` ``` -Epoch 5: delegator-exit → unbonding starts, shares stop earning -Epochs 6–11: locked period (cannot claim yet) -Epoch 12: delegator-claim available +Epoch 5: request exit (active stake still earns epoch 5 rewards) +Epochs 6–11: withdrawal remains locked +Epoch 12: earliest claim for the priced withdrawal ``` - Plan around the 7-epoch wait — that's roughly 7 days on the network. Exited GEN earns nothing during unbonding, so only exit what you actually intend to withdraw. Track eligibility with `genlayer staking epoch-info`. + Track the current epoch with `genlayer staking epoch-info`. A partial exit leaves your remaining active shares earning rewards. @@ -162,12 +162,12 @@ For the concept-level walkthrough of exits and cooldowns, see [Unstaking in GenL There is **no "redelegate" operation** on GenLayer. Moving your stake from one validator to another is not atomic — it is a full unstake from the old validator followed by a fresh delegation to the new one, with the unbonding period in between. Concretely: 1. **Exit** your shares from your current validator: `genlayer staking delegator-exit --validator 0xOLD --shares SHARES`. -2. **Wait** the full **7-epoch** unbonding period (~7 days on the network). Your GEN is locked and earning nothing during this time. +2. **Wait** seven epochs from the exit request before claiming. The old delegation keeps its exit-epoch rewards. 3. **Claim** the released GEN back to your wallet: `genlayer staking delegator-claim --validator 0xOLD`. 4. **Delegate** the claimed GEN to the new validator: `genlayer staking delegator-join --validator 0xNEW --amount ...`. Remember this new delegation then takes **2 epochs** to activate. - **Switching is not instant and not free of downtime.** Between exiting the old validator and your new delegation activating, your GEN spends the unbonding period unstaked (no rewards) and then 2 more epochs pending activation. If you value continuity, consider building a new position with fresh GEN rather than moving an existing one — or diversifying across validators from the start so you rarely need to move stake at all. + The withdrawn stake stops earning with the old validator when priming removes it from the active record. It starts earning with the new validator once the new delegation activates. --- diff --git a/pages/developers/exchange-wallet-integration.mdx b/pages/developers/exchange-wallet-integration.mdx index a0e4a6c9..1c2b99cf 100644 --- a/pages/developers/exchange-wallet-integration.mdx +++ b/pages/developers/exchange-wallet-integration.mdx @@ -101,7 +101,7 @@ Choose the crediting threshold for each operation and record which signal the in - [ ] Pull chain IDs, RPC (HTTP + WS), currency, and explorer URLs from the [Networks](/developers/networks) page for **each** environment you support. - [ ] Verify the Bradbury Phase 2 genesis hash and AddressManager alongside the chain ID. -- [ ] Confirm the **L1 GEN representation and bridge route** from the network's canonical setup/bridge info — never hardcode a token or bridge address from a third-party source. +- [ ] Verify the L1 token and canonical bridge for each deployment. For Bradbury Phase 2, use the [bridge and Sepolia GEN links](/developers/bridging-gen). - [ ] Track native GEN via `eth_getBalance` and native transfers (not ERC-20 logs) on the GenLayer Chain. - [ ] Specify whether each credit requires sequencer inclusion, a confirmed assertion or a finalized Intelligent Contract result. - [ ] Check the supported `eth_*` methods and test full-block decoding against a block containing a Nitro system transaction. diff --git a/pages/developers/staking-guide.mdx b/pages/developers/staking-guide.mdx index ded8a8a6..a3cabc25 100644 --- a/pages/developers/staking-guide.mdx +++ b/pages/developers/staking-guide.mdx @@ -94,7 +94,8 @@ validatorWallet.validatorExit(sharesToExit); **Important Notes:** -- Exited tokens stop earning rewards immediately +- 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 @@ -200,16 +201,16 @@ 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 +- 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 **Unbonding Timeline:** ``` -Epoch 5: delegatorExit() called +Epoch 5: delegatorExit() called (active stake still earns epoch 5 rewards) Epochs 6-11: Locked period -Epoch 12: delegatorClaim() available +Epoch 12: earliest delegatorClaim() ``` ### Claiming Withdrawn Funds as a Delegator