From d0e161c9db4e672272e3324b6b38170f167fdc55 Mon Sep 17 00:00:00 2001 From: Edgars Date: Fri, 3 Jul 2026 11:48:05 +0100 Subject: [PATCH] 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