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
30 changes: 15 additions & 15 deletions UBIQUITOUS_LANGUAGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@
| **BERA** | Native gas and staking token. Validators stake BERA for consensus; block rewards are emitted as WBERA. | — |
| **WBERA** | Wrapped BERA (1:1). The Reward Vault emission token and the payout token for the Incentive Auction. | "different from BERA" — they are the same value |
| **sWBERA** | Yield-bearing token issued by `WBERAStakerVault` when a user deposits BERA or WBERA. Earns Incentive Auction yield. | — |
| **LST** | A transferable ERC-20 token representing staked BERA, issued by an LST protocol. Can be staked into an `LSTStakerVault` for Incentive Auction yield. On mainnet, only **iBERA** (Infrared) has a registered vault. | stBERA (non-transferable pool shares are not LSTs) |

Check warning on line 10 in UBIQUITOUS_LANGUAGE.md

View check run for this annotation

Mintlify / Mintlify Validation (berachain-422fce37) - vale-spellcheck

UBIQUITOUS_LANGUAGE.md#L10

Did you really mean 'LSTs'?
| **iBERA** | Infrared's liquid staking token (`0x9b67…`). Transferable ERC-20. The only LST with a registered `LSTStakerVault` on mainnet. | — |
| **stBERA** | Non-transferable pool shares issued by Berachain Staking Pools. No `transfer()`, `transferFrom()`, or `approve()`. Cannot be staked into an `LSTStakerVault`. | LST (stBERA is not liquid — it is soulbound to the depositor) |

Check warning on line 12 in UBIQUITOUS_LANGUAGE.md

View check run for this annotation

Mintlify / Mintlify Validation (berachain-422fce37) - vale-spellcheck

UBIQUITOUS_LANGUAGE.md#L12

Did you really mean 'soulbound'?
| **BGT** | Deprecated governance token from the pre-Next model. Can be redeemed 1:1 for BERA. No role in current PoL. | — |

## Actors
Expand All @@ -28,15 +28,15 @@

## Contracts

| Term | Definition | Aliases to avoid |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
| **Incentive commission** | Validator operator's share of incentive tokens: `(amount * commissionRate) / 1e4`. Max 20%, default 5%. | Validator commission (acceptable shorthand) |
| **Incentive Auction** | Settlement where a buyer pays WBERA to `BGTIncentiveFeeCollector` and receives accumulated redirected incentive tokens. | Fee collection |
| **BGTIncentiveFeeCollector** | Installed as `RewardVaultFactory.incentiveTokensCollector`. Splits auction WBERA pro-rata between `WBERAStakerVault` and registered `LSTStakerVault`s. | FeeCollector (different contract — pays BGTStaker, legacy) |
| **IncentiveCollector** | Pool-level contract that auctions operator commission incentive tokens for BERA, flowing to `StakingRewardsVault`. | Not the same as BGTIncentiveFeeCollector |
| **WBERAStakerVault** | Issues sWBERA. Receives WBERA from the Incentive Auction. | Staking Vault (acceptable in user-facing docs) |
| **LSTStakerVault** | Governance-registered vault that receives Incentive Auction WBERA (converted to LST via adapter). | Pool vault (these are not staking pool contracts) |
| **Staking Pool** | Contract where users deposit BERA via `submit()` and receive non-transferable stBERA shares. Managed by a SmartOperator. | — |
| Term | Definition | Aliases to avoid |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
| **Incentive commission** | Validator operator's share of incentive tokens: `(amount * commissionRate) / 1e4`. Max 20%, default 5%. | Validator commission (acceptable shorthand) |
| **Incentive Auction** | Settlement where a buyer pays WBERA to `IncentivesCollector` and receives accumulated redirected incentive tokens. | Fee collection |
| **IncentivesCollector** | Installed as `RewardVaultFactory.incentiveTokensCollector`. Splits auction WBERA pro-rata between `WBERAStakerVault` and registered `LSTStakerVault`s. | FeeCollector (different contract — pays BGTStaker, legacy) |
| **IncentiveCollector** | Pool-level contract that auctions operator commission incentive tokens for BERA, flowing to `StakingRewardsVault`. | Not the same as IncentivesCollector |
| **WBERAStakerVault** | Issues sWBERA. Receives WBERA from the Incentive Auction. | Staking Vault (acceptable in user-facing docs) |
| **LSTStakerVault** | Governance-registered vault that receives Incentive Auction WBERA (converted to LST via adapter). | Pool vault (these are not staking pool contracts) |
| **Staking Pool** | Contract where users deposit BERA via `submit()` and receive non-transferable stBERA shares. Managed by a SmartOperator. | — |

## Yield paths

Expand All @@ -45,33 +45,33 @@
| **Validator operator** | Base rate (0.4 WBERA/block) | BlockRewardController → operator |
| **Validator operator** | Incentive commission | RewardVault → operator |
| **Vault staker** | Allocated WBERA emissions | Distributor → RewardVault → claim |
| **sWBERA staker** | Incentive Auction WBERA | BGTIncentiveFeeCollector → WBERAStakerVault |
| **LST staker** | Incentive Auction WBERA → LST | BGTIncentiveFeeCollector → LSTAdapter → LSTStakerVault |
| **sWBERA staker** | Incentive Auction WBERA | IncentivesCollector → WBERAStakerVault |
| **LST staker** | Incentive Auction WBERA → LST | IncentivesCollector → LSTAdapter → LSTStakerVault |

Check warning on line 49 in UBIQUITOUS_LANGUAGE.md

View check run for this annotation

Mintlify / Mintlify Validation (berachain-422fce37) - vale-spellcheck

UBIQUITOUS_LANGUAGE.md#L49

Did you really mean 'LSTAdapter'?
| **Staking pool depositor** | Operator WBERA + pool incentive auction BERA | SmartOperator + IncentiveCollector → StakingRewardsVault → pool rebase |

Check warning on line 50 in UBIQUITOUS_LANGUAGE.md

View check run for this annotation

Mintlify / Mintlify Validation (berachain-422fce37) - vale-spellcheck

UBIQUITOUS_LANGUAGE.md#L50

Did you really mean 'rebase'?

## Key relationships

- **stBERA is not an LST.** Pool shares have no transfer surface. A staking pool depositor cannot stake stBERA anywhere.
- **iBERA is an LST.** Infrared issues iBERA as a transferable ERC-20. Users stake iBERA into the registered LSTStakerVault (siBERA, `0xA350…`) to earn Incentive Auction yield.
- **The core Incentive Auction does not pay staking pools.** BGTIncentiveFeeCollector sends WBERA to WBERAStakerVault and LSTStakerVaults only. Staking pools have their own IncentiveCollector — a separate auction system.
- **sWBERA and LST staker yields come from the same auction.** BGTIncentiveFeeCollector splits WBERA pro-rata by WBERA-denominated totalAssets across both vault types.
- **The core Incentive Auction does not pay staking pools.** IncentivesCollector sends WBERA to WBERAStakerVault and LSTStakerVaults only. Staking pools have their own IncentiveCollector — a separate auction system.
- **sWBERA and LST staker yields come from the same auction.** IncentivesCollector splits WBERA pro-rata by WBERA-denominated totalAssets across both vault types.

Check warning on line 57 in UBIQUITOUS_LANGUAGE.md

View check run for this annotation

Mintlify / Mintlify Validation (berachain-422fce37) - vale-spellcheck

UBIQUITOUS_LANGUAGE.md#L57

Did you really mean 'totalAssets'?

## Example dialogue

> **Dev:** "Is stBERA an LST?"

Check warning on line 61 in UBIQUITOUS_LANGUAGE.md

View check run for this annotation

Mintlify / Mintlify Validation (berachain-422fce37) - vale-spellcheck

UBIQUITOUS_LANGUAGE.md#L61

Did you really mean 'Dev'?
>
> **Domain expert:** "No. stBERA is a non-transferable pool share — it has no transfer() or approve(). iBERA from Infrared is an LST: a transferable ERC-20 backed by staked BERA."
>
> **Dev:** "So how does a staking pool depositor earn auction yield?"

Check warning on line 65 in UBIQUITOUS_LANGUAGE.md

View check run for this annotation

Mintlify / Mintlify Validation (berachain-422fce37) - vale-spellcheck

UBIQUITOUS_LANGUAGE.md#L65

Did you really mean 'Dev'?
>
> **Domain expert:** "They don't — at least not from the core Incentive Auction. Pool depositors earn from the pool's own IncentiveCollector and operator WBERA. If someone wants core auction yield, they hold sWBERA or stake an LST like iBERA into a registered LSTStakerVault."
>
> **Dev:** "What about gBERA?"

Check warning on line 69 in UBIQUITOUS_LANGUAGE.md

View check run for this annotation

Mintlify / Mintlify Validation (berachain-422fce37) - vale-spellcheck

UBIQUITOUS_LANGUAGE.md#L69

Did you really mean 'Dev'?
>
> **Domain expert:** "gBERA exists as a token but has no registered LSTStakerVault on the BGTIncentiveFeeCollector. It doesn't earn auction yield until governance registers a vault for it."
> **Domain expert:** "gBERA exists as a token but has no registered LSTStakerVault on the IncentivesCollector. It doesn't earn auction yield until governance registers a vault for it."

## Flagged ambiguities

- **"Delegator"**: No `delegate()` for BERA staking. Use **BERA staker**. `DelegationHandler` in contracts-staking-pools is Foundation capital management. `RewardVault.delegateStake()` is custodial receipt-token staking.
- **"Staking pool staker" vs "LST staker"**: Distinct roles. Never hyphenate as one group. Pool depositors hold soulbound stBERA. LST stakers hold transferable tokens like iBERA.

Check warning on line 76 in UBIQUITOUS_LANGUAGE.md

View check run for this annotation

Mintlify / Mintlify Validation (berachain-422fce37) - vale-spellcheck

UBIQUITOUS_LANGUAGE.md#L76

Did you really mean 'soulbound'?
- **"FeeCollector" vs "BGTIncentiveFeeCollector"**: Different contracts. FeeCollector pays BGTStaker (legacy). BGTIncentiveFeeCollector splits to sWBERA + LST vaults. Use "incentive tokens collector" as the generic role name.
- **"FeeCollector" vs "IncentivesCollector"**: Different contracts. FeeCollector pays BGTStaker (legacy). IncentivesCollector splits to sWBERA + LST vaults. Use "incentive tokens collector" as the generic role name.
5 changes: 0 additions & 5 deletions build/bex/deployed-contracts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
<Warning>
On January 21st, 2025, Balancer disclosed a long-standing vulnerability in their V2 Vault implementation. BEX incorporates contract logic from Balancer V2 and shares the same vulnerability. Exercise additional caution when creating new pools, particularly when including **untrusted or newly-created tokens**.

**Funds currently deposited in BEX are safe, and no action from LPs is needed.** The issue only potentially affects tokens that are not live on-chain today. Frontend warnings are displayed on BEX for potentially vulnerable tokens.

Check warning on line 11 in build/bex/deployed-contracts.mdx

View check run for this annotation

Mintlify / Mintlify Validation (berachain-422fce37) - vale-spellcheck

build/bex/deployed-contracts.mdx#L11

Did you really mean 'LPs'?

Future plans include integrating the Balancer V3 codebase, which mitigates this vulnerability and is cross-compatible with current BEX pools.

Expand All @@ -18,9 +18,4 @@

The following is a list of contract addresses for interacting with Berachain BEX.

<Tip>
A full list of contract ABIs can be found at
[github.com/berachain/doc-abis](https://github.com/berachain/doc-abis).
</Tip>

<BexContractsTable />
8 changes: 0 additions & 8 deletions build/getting-started/deployed-contracts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,17 @@ description: "Berachain core and staking-pool contract addresses by network."
---

import CoreContractsTable from "/snippets/contracts/generated/core-contracts-table.mdx";
import StakingPoolSingletonsTable from "/snippets/contracts/generated/staking-pools-singletons-table.mdx";

For **BEX** (DEX) addresses, see [BEX deployed contracts](/build/bex/deployed-contracts). For **Bend** (lending) addresses, see [Bend deployed contracts](/build/bend/deployed-contracts).

All contracts are verified at the [block explorer](https://berascan.com).

- ABI files: [berachain/abis](https://github.com/berachain/abis).
- Core protocol: [berachain/contracts](https://github.com/berachain/contracts).
- Staking pools: [berachain/contracts-staking-pools](https://github.com/berachain/contracts-staking-pools).

<Info>
All audit reports are publicly available on
[Github](https://github.com/berachain/security-audits).
</Info>

<CoreContractsTable />

## Staking pool contracts

Shared singleton addresses for staking pools are listed below. For per-pool proxies, behavior, and links to the guides repo, see [Staking pool contracts](/nodes/staking-pools/contracts).

<StakingPoolSingletonsTable />
16 changes: 8 additions & 8 deletions build/pol/lst-integration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,36 +3,36 @@
description: "Register an LSTStakerVault so your LST product earns a pro-rata share of WBERA paid through the PoL Incentive Auction."
---

Liquid Staking Token (LST) issuers can plug their staked-LST product into the Berachain Proof of Liquidity (PoL) Incentive Auction. Once an `LSTStakerVault` and its adapter are registered on `BGTIncentiveFeeCollector`, the vault automatically receives a pro-rata share of every WBERA payment auction buyers make against redirected Reward Vault incentive tokens.
Liquid Staking Token (LST) issuers can plug their staked-LST product into the Berachain Proof of Liquidity (PoL) Incentive Auction. Once an `LSTStakerVault` and its adapter are registered on `IncentivesCollector`, the vault automatically receives a pro-rata share of every WBERA payment auction buyers make against redirected Reward Vault incentive tokens.

This page is the integrator-facing guide. For the auction mechanics from the protocol side, see [Incentive Marketplace — Incentive fee settlement](/general/proof-of-liquidity/incentives#incentive-fee-settlement).

## What registration enables

When a buyer settles redirected incentive tokens through `BGTIncentiveFeeCollector`, the WBERA they pay is split **pro-rata, by WBERA-denominated total assets**, across:
When a buyer settles redirected incentive tokens through `IncentivesCollector`, the WBERA they pay is split **pro-rata, by WBERA-denominated total assets**, across:

- The shared `WBERAStakerVault` (sWBERA stakers).
- Every registered `LSTStakerVault` whose LST has an adapter that converts WBERA into the underlying LST.

A registered LST vault therefore accrues two sources of return for its stakers: the LST's own underlying yield, plus a continuous share of PoL incentive-auction WBERA proportional to its total stake value.

Check warning on line 17 in build/pol/lst-integration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (berachain-422fce37) - vale-spellcheck

build/pol/lst-integration.mdx#L17

Did you really mean 'LST's'?

Stakers of a registered LST do not need to interact with PoL directly. As long as the vault and adapter are registered, the WBERA flows in automatically on every auction settlement.

## How auction yield reaches an LST vault

1. Reward Vaults transfer redirected incentive tokens (incentives not paid as validator commission) into `BGTIncentiveFeeCollector`.
2. An auction buyer calls `claimFees(recipient, feeTokens)` and pays WBERA into the collector.
1. Reward Vaults transfer redirected incentive tokens (incentives not paid as validator commission) into `IncentivesCollector`.
2. An auction buyer calls `claim(recipient, incentiveTokens)` and pays WBERA into the collector.
3. The collector splits the paid WBERA pro-rata across the sWBERA Staking Vault and registered `LSTStakerVault`s, sized by each vault's WBERA-denominated total assets.
4. For each registered LST vault, the collector calls the vault's registered **adapter** to convert that WBERA share into the vault's underlying LST, then credits the LST to the vault through `receiveRewards`.
5. The vault's per-share value rises; its stakers earn the increment without taking any action.

The split is recomputed on every settlement, so vaults that grow attract a larger share of subsequent WBERA flows.

## Currently registered LSTs

Check warning on line 31 in build/pol/lst-integration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (berachain-422fce37) - vale-spellcheck

build/pol/lst-integration.mdx#L31

Did you really mean 'LSTs'?

The first registered LST is **iBERA** from Infrared. Its staked version, **siBERA**, accrues both the underlying iBERA yield and its pro-rata share of PoL incentive-auction WBERA via the registered LST adapter.

Additional LSTs can be registered through the steps below.

Check warning on line 35 in build/pol/lst-integration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (berachain-422fce37) - vale-spellcheck

build/pol/lst-integration.mdx#L35

Did you really mean 'LSTs'?

## Integration steps for LST issuers

Expand All @@ -51,31 +51,31 @@

The adapter is the contract that converts WBERA into your underlying LST during auction settlement. It must:

- Accept WBERA from `BGTIncentiveFeeCollector`.
- Accept WBERA from `IncentivesCollector`.
- Convert that WBERA into the LST (through your protocol's mint, swap, or wrap path).
- Hand the resulting LST to the registered `LSTStakerVault` via `receiveRewards`.

Adapter design is LST-specific. Refer to the iBERA adapter for a working pattern.

### 3. Register the vault and adapter with governance

Submit a governance proposal to call `addLstStakerVault` on `BGTIncentiveFeeCollector`, supplying:
Submit a governance proposal to call `addLstStakerVault` on `IncentivesCollector`, supplying:

- The deployed `LSTStakerVault` address.
- The deployed adapter address.

Once the registry write lands, the collector includes the new vault in every subsequent pro-rata split. The vault begins accruing WBERA-sourced LST yield on the next auction settlement.

See [Deployed contract addresses](/build/getting-started/deployed-contracts) for the live `BGTIncentiveFeeCollector` and `LSTStakerVaultFactory` addresses on each network.
See [Deployed contract addresses](/build/getting-started/deployed-contracts) for the live `IncentivesCollector` and `LSTStakerVaultFactory` addresses on each network.

## Operational notes

- **Vault total assets must be denominated comparably to WBERA.** The collector sizes each vault's share by its WBERA-denominated total assets; an adapter that misreports the underlying value will distort the split for every other registered vault.
- **No staking-pool LSTs.** Staking pool shares (stBERA) are not LSTs and cannot be registered through this path; they have their own yield mechanics. See [Staking Pools Overview](/nodes/staking-pools/overview).

Check warning on line 74 in build/pol/lst-integration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (berachain-422fce37) - vale-spellcheck

build/pol/lst-integration.mdx#L74

Did you really mean 'LSTs'?

Check warning on line 74 in build/pol/lst-integration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (berachain-422fce37) - vale-spellcheck

build/pol/lst-integration.mdx#L74

Did you really mean 'LSTs'?

## See also

- [Incentive Marketplace — Incentive fee settlement](/general/proof-of-liquidity/incentives#incentive-fee-settlement) — the auction mechanics from the protocol side.
- [\$sWBERA Token](/general/tokens/swbera) — the sister product that shares the pro-rata WBERA split.
- [Deployed contract addresses](/build/getting-started/deployed-contracts) — current `BGTIncentiveFeeCollector` and `LSTStakerVaultFactory` addresses.
- [Deployed contract addresses](/build/getting-started/deployed-contracts) — current `IncentivesCollector` and `LSTStakerVaultFactory` addresses.
- [Proof of Liquidity Overview](/general/proof-of-liquidity/overview) — the broader PoL picture.
Loading