Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions pages/developers/_meta.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,11 @@
{
"networks": "Networks & RPCs",
"consensus-v06-migration": "Consensus v0.6 Migration",
"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",
"error-reference": "Error & Revert Reference",
"staking-guide": "Staking Contract Guide"
}
100 changes: 100 additions & 0 deletions pages/developers/bridging-gen.mdx
Original file line number Diff line number Diff line change
@@ -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 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 guide follows a transfer through the canonical bridge from the first wallet signature to the balance change on the destination chain.

<Callout type="warning">
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.
</Callout>

## 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.

<Callout type="info">
Use the bridge for your specific GenLayer deployment. An Arbitrum One or Nova bridge address belongs to a different chain.
</Callout>

---

## Deposit: L1 → L2

Deposits are the fast direction. Bringing GEN from Ethereum onto the GenLayer Chain follows the standard rollup deposit flow:

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.

<Callout type="info">
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).
</Callout>

---

## Withdraw: L2 → L1

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.** 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.

<Callout type="warning">
**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.
</Callout>

<Callout type="info">
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.
</Callout>

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.

---

## Track a transfer

Because a transfer spans two chains, you follow it on both:

- **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.

<Callout type="info">
Keep the L2 withdrawal hash so you can find the message and claim it when its assertion is confirmed.
</Callout>

---

## Common pitfalls

| Pitfall | What to do |
|---|---|
| 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 | 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. |

---

## Related resources

<Cards>
<Card title="🌐 Networks & RPCs" href="/developers/networks" />
<Card title="🧱 GenLayer Chain (L2)" href="/developers/networks#genlayer-chain-l2" />
<Card title="🔗 Rollup Integration" href="/understand-genlayer-protocol/core-concepts/rollup-integration" />
<Card title="⏱️ Finality" href="/understand-genlayer-protocol/core-concepts/optimistic-democracy/finality" />
<Card title="💸 Value Transfers (GEN)" href="/developers/intelligent-contracts/features/value-transfers" />
</Cards>
202 changes: 202 additions & 0 deletions pages/developers/delegating-gen.mdx
Original file line number Diff line number Diff line change
@@ -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).

<Callout type="info">
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).
</Callout>

## 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.

<Callout type="warning">
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.
</Callout>

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.

---

## Step 1 — Choose a validator

Your rewards and risk both depend on the validator you back. Evaluate candidates before committing.

### Where to look

- **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
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. |

<Callout type="info">
**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.
</Callout>

<Callout type="warning">
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.
</Callout>

---

## 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.

<Callout type="info">
**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`.
</Callout>

### 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#rewards-and-risks) 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).** 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).** 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: request exit (active stake still earns epoch 5 rewards)
Epochs 6–11: withdrawal remains locked
Epoch 12: earliest claim for the priced withdrawal
```

<Callout type="warning">
Track the current epoch with `genlayer staking epoch-info`. A partial exit leaves your remaining active shares earning rewards.
</Callout>

<Callout type="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.
</Callout>

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** 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.

<Callout type="error">
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.
</Callout>

---

## 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.

<Callout type="warning">
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.
</Callout>

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

<Cards>
<Card title="🥩 Staking in GenLayer" href="/understand-genlayer-protocol/core-concepts/optimistic-democracy/staking" />
<Card title="📜 Staking Contract Guide" href="/developers/staking-guide" />
<Card title="🌱 Genesis Epoch 0" href="/developers/staking-guide#genesis-epoch-0" />
<Card title="⛓️ Unstaking" href="/understand-genlayer-protocol/core-concepts/optimistic-democracy/unstaking" />
<Card title="⚔️ Slashing" href="/understand-genlayer-protocol/core-concepts/optimistic-democracy/slashing" />
<Card title="🛠️ GenLayer CLI: Staking" href="/api-references/genlayer-cli/staking/staking" />
</Cards>
Loading
Loading