docs: add Yield Boost protocol docs and assertions social card by kyzooghost · Pull Request #1350 · Consensys/doc.linea

kyzooghost · 2026-02-10T00:35:14Z

Summary

Yield Boost protocol documentation – Adds documentation for the Linea Yield Boost staking system, covering ETH fund flow, architecture, roles, and fund flow scenarios (docs/protocol/yield-boost.mdx).
Assertions social card – Adds social card image metadata to write-and-deploy-assertions.mdx.

Note

Low Risk
Documentation-only change with no impact to runtime code paths or security-critical logic.

Overview
Adds a new docs/protocol/yield-boost.mdx page documenting the intended Yield Boost design, including L1/L2 ETH flow diagrams, yield reporting mechanics, and role/permission boundaries for staking, unstaking, reporting, and ossification.

The doc also enumerates end-to-end fund-movement scenarios (routine staking/replenishment, permissionless fallback actions, LST withdrawal as last resort, and vault ossification) plus a quick reference table for reviewers/operators.

^{Written by Cursor Bugbot for commit b39be2b. This will update automatically on new commits. Configure here.}

Document ETH fund flow, architecture, roles, and fund flow scenarios for the Linea Yield Boost staking system. Co-authored-by: Cursor <[email protected]>

Co-authored-by: Cursor <[email protected]>

vercel · 2026-02-10T00:35:19Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
doc-linea	Ready	Preview, Comment	Feb 12, 2026 9:56am

Co-authored-by: Cursor <[email protected]>

docs/protocol/yield-boost.mdx

allywhiting · 2026-02-10T15:49:57Z

docs/protocol/yield-boost.mdx

+Yield Boost is not yet live. This documentation describes the intended design.
+:::
+
+# Yield Boost - ETH fund flow


Let's move this H1 above the caution callout, so:

H1

Caution

H2 "Overview"

allywhiting · 2026-02-10T18:48:51Z

docs/protocol/yield-boost.mdx

+
+## Overview
+
+The Linea Yield Boost system stakes LineaRollup funds on Ethereum L1 via Lido V3 stVaults to generate beacon chain rewards, which are reported to L2 for distribution. This document maps **where ETH flows** and **which roles control each movement**.


Let's get some more non-technical description here before getting into the technical intricacies.

Maybe this first sentence in Overview could instead be moved down to "High-level architecture", and replaced with simpler description for overview.

docs/protocol/yield-boost.mdx

allywhiting · 2026-02-10T18:54:54Z

General question -- is there an action item here for readers? Any thing they need to do on their end, or is this exclusively informational

Co-authored-by: allywhiting <[email protected]>

kyzooghost · 2026-02-11T11:37:09Z

General question -- is there an action item here for readers? Any thing they need to do on their end, or is this exclusively informational

Exclusively informational

Co-authored-by: Cursor <[email protected]>

- Simplify Overview with user-focused description - Add Bridge deposits intro and Key entities bullet list - Clarify LST withdrawal and ossification descriptions Co-authored-by: Cursor <[email protected]>

Co-authored-by: Cursor <[email protected]>

- Add numbered summary of all 6 fund flow scenarios - Move reserve replenishment before yield reporting to follow flow order - Replace 'freezes' with 'locks' in ossification description Co-authored-by: Cursor <[email protected]>

docs/protocol/yield-boost.mdx

arthur-remy · 2026-02-10T16:59:10Z

docs/protocol/yield-boost.mdx

+    LR -->|excess ETH| YM
+    YM -->|fund| DB
+    DB -->|fund| SV
+    NO -.->|discretion over beacon chain deposits| SV


"discretion over beacon chain deposits" - the wording is subject to interpretation and can make it sounds like it is custodial.
I would rather suggest saying "decide when to trigger the deposit".

Also I suggest to add a small note below the diagram indicate that while the NO "decides" when to stake it is part of an automated process with logic agreed beforehand with the node operator. We should also mention the recommended approach is for the NO to greedily stake funds newly deposited funds in the vault (except withdrawals).

arthur-remy · 2026-02-10T17:00:00Z

docs/protocol/yield-boost.mdx

+
+    class NO admin
+    class User permissionless
+```


Can we include a short description of the roles of each contracts in the diagram?

have added a Key Entities section near the top

arthur-remy · 2026-02-10T17:04:33Z

docs/protocol/yield-boost.mdx

+    SV[StakingVault]
+    NO([Node Operator])
+    BC{{Beacon Chain}}
+


The diagram implicitly indicates that the staking/unstaking is triggered by users' ETH deposit / withdrawal on the bridge. Can we make it clearer what are the atomic actions and who triggers them?

Following sequence diagram makes it clearer but it is important in my opinion that we don't give a wrong impression in this first diagram for users who might not read the document completely.

arthur-remy · 2026-02-10T17:09:02Z

docs/protocol/yield-boost.mdx

+    DB -->|stETH borrow liability| Lido[Lido]
+    DB -->|protocol fees| Lido
+    DB -->|node operator fees| FeeRecipient([Node Op Fee Recipient])
+    YM -.->|reportNativeYield| LR[LineaRollup]


Can we add one more step here explaining what happens when this is triggered and how the accrued yield is computed?
Without context, it could sound like the Automation service defines how much yield should be distributed, but this is not the case.

arthur-remy · 2026-02-10T17:09:37Z

docs/protocol/yield-boost.mdx

+
+    class L2MS,L2YD l2
+    class FeeRecipient admin
+```


Can we add a description in english of each steps as the diagram might be hard to follow for someone without context on the feature

arthur-remy · 2026-02-10T17:10:15Z

docs/protocol/yield-boost.mdx

+
+| Role | Held By | ETH Movement Authorized |
+|------|---------|------------------------|
+| `YIELD_PROVIDER_STAKING_ROLE` | Automation Service | LineaRollup → YieldManager → StakingVault |


Can we explain in plain english and functional terms what are the ETH Movement Authorized?

arthur-remy · 2026-02-10T17:14:41Z

docs/protocol/yield-boost.mdx

+        Note over DB: Skip settlement<br/>carry forward obligations
+    end
+
+    YM-->>LR: reportNativeYield()<br/>(net surplus after obligations)


Can we make it explicit where we fetch the information about how much yield has been generated?

arthur-remy · 2026-02-10T17:16:50Z

docs/protocol/yield-boost.mdx

+    L2MS->>L2YD: distribute yield
+```
+
+No L1 ETH moves for the yield report itself - obligation payments (solid arrows) are the only L1 ETH transfers. The `MessageSent` event is synthetic: it relays the net surplus to L2 for distribution without bridging ETH.


It would be worth it to explicitly call out why we don't need to bridge funds, while the system remains fully collateralized.

Co-authored-by: allywhiting <[email protected]>

Co-authored-by: Cursor <[email protected]>

Soften "discretion over beacon chain deposits" to "decides when to trigger deposits" and add note explaining the automated nature of the process and the recommended greedy-staking approach.

Rewrite all entries for a non-technical audience: remove jargon (withdrawal credentials, LST minting, obligation settlement), explain each role in plain language, and add a Beacon Chain entry.

Co-authored-by: Cursor <[email protected]>

Replace contract-path notation and function names with plain-language descriptions of what each role can do. Correct ossification roles to note Lido-required fee settlement instead of direct ETH withdrawal.

Make explicit that totalValue comes from the Lido Oracle Committee daily updates and that yield is the diff against a stored checkpoint.

Add note clarifying that L1 staking rewards grow collateral beyond the existing L2 supply, so L2 can safely mint the difference without moving ETH across the bridge.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

docs/network/how-to/write-and-deploy-assertions.mdx

- Promote Key entities to a heading - Fix YieldManager casing, clarify totalValue and Lido Oracle role - Add obligation settlement skip logic to yield reporting steps - Minor wording tweaks throughout Co-authored-by: Cursor <[email protected]>

Co-authored-by: Cursor <[email protected]>

…able - Replace verbose collateralization paragraph with concise blockquotes - Use "Automation Service" consistently in quick reference table - Clarify LST withdrawal trigger Co-authored-by: Cursor <[email protected]>

Co-authored-by: Cursor <[email protected]>

…ectly Co-authored-by: Cursor <[email protected]>

kyzooghost and others added 2 commits February 10, 2026 11:34

docs: add Yield Boost protocol documentation

2bf2cde

Document ETH fund flow, architecture, roles, and fund flow scenarios for the Linea Yield Boost staking system. Co-authored-by: Cursor <[email protected]>

docs: add social card image for write-and-deploy-assertions

05333af

Co-authored-by: Cursor <[email protected]>

vercel bot deployed to Preview February 10, 2026 00:35 View deployment

docs: add caution that Yield Boost is not yet live

cd353f7

Co-authored-by: Cursor <[email protected]>

vercel bot deployed to Preview February 10, 2026 09:28 View deployment

allywhiting reviewed Feb 10, 2026

View reviewed changes

docs/protocol/yield-boost.mdx Show resolved Hide resolved

Update docs/protocol/yield-boost.mdx

0fd9534

Co-authored-by: allywhiting <[email protected]>

vercel bot deployed to Preview February 11, 2026 11:37 View deployment

kyzooghost and others added 4 commits February 11, 2026 22:41

docs: move Yield Boost heading above caution callout

bc1d11e

Co-authored-by: Cursor <[email protected]>

docs: improve Yield Boost overview and add key entities section

4ae09fd

- Simplify Overview with user-focused description - Add Bridge deposits intro and Key entities bullet list - Clarify LST withdrawal and ossification descriptions Co-authored-by: Cursor <[email protected]>

docs: use LineaRollup consistently in Yield Boost doc

13c7f94

Co-authored-by: Cursor <[email protected]>

docs: add intro for Yield Boost fund flow scenarios section

2a78f69

Co-authored-by: Cursor <[email protected]>

vercel bot deployed to Preview February 11, 2026 11:58 View deployment

docs: reorder Yield Boost scenarios and add summary list

e95377e

- Add numbered summary of all 6 fund flow scenarios - Move reserve replenishment before yield reporting to follow flow order - Replace 'freezes' with 'locks' in ossification description Co-authored-by: Cursor <[email protected]>

vercel bot deployed to Preview February 11, 2026 12:06 View deployment

allywhiting reviewed Feb 11, 2026

View reviewed changes

docs/protocol/yield-boost.mdx Outdated Show resolved Hide resolved

arthur-remy reviewed Feb 11, 2026

View reviewed changes

Update docs/protocol/yield-boost.mdx

528677f

Co-authored-by: allywhiting <[email protected]>

vercel bot deployed to Preview February 12, 2026 06:55 View deployment

kyzooghost and others added 6 commits February 12, 2026 18:27

docs: add missing entities to yield-boost Key entities section

30e55af

Co-authored-by: Cursor <[email protected]>

docs: clarify Node Operator role in Yield Boost deposit diagram

cb2fb62

Soften "discretion over beacon chain deposits" to "decides when to trigger deposits" and add note explaining the automated nature of the process and the recommended greedy-staking approach.

docs: simplify Key entities descriptions and add Beacon Chain

b0b9283

Rewrite all entries for a non-technical audience: remove jargon (withdrawal credentials, LST minting, obligation settlement), explain each role in plain language, and add a Beacon Chain entry.

docs: update L1 ETH flow diagram in yield-boost

b5678c7

Co-authored-by: Cursor <[email protected]>

docs: expand yield reporting section with step-by-step explanation

d01abe9

Co-authored-by: Cursor <[email protected]>

docs: rewrite roles table in plain English

cb88252

Replace contract-path notation and function names with plain-language descriptions of what each role can do. Correct ossification roles to note Lido-required fee settlement instead of direct ETH withdrawal.

kyzooghost added 2 commits February 12, 2026 19:08

docs: show yield computation source in reporting sequence diagram

93ac51a

Make explicit that totalValue comes from the Lido Oracle Committee daily updates and that yield is the diff against a stored checkpoint.

docs: explain why yield distribution needs no ETH bridging

82a7dd1

Add note clarifying that L1 staking rewards grow collateral beyond the existing L2 supply, so L2 can safely mint the difference without moving ETH across the bridge.

vercel bot deployed to Preview February 12, 2026 08:11 View deployment

cursor bot reviewed Feb 12, 2026

View reviewed changes

docs/network/how-to/write-and-deploy-assertions.mdx Outdated Show resolved Hide resolved

kyzooghost and others added 6 commits February 12, 2026 20:12

docs: remove redundant yield reporting blockquote

300df81

Co-authored-by: Cursor <[email protected]>

docs: clarify role descriptions in permissions table

48e3417

Co-authored-by: Cursor <[email protected]>

docs: reword fund flow scenario summaries for clarity

664bb36

Co-authored-by: Cursor <[email protected]>

docs: remove manual social card images from metadata

c5ff0d9

Co-authored-by: Cursor <[email protected]>

vercel bot deployed to Preview February 12, 2026 09:28 View deployment

vercel bot deployed to Preview February 12, 2026 09:29 View deployment

docs: clarify that yield is made available on L2, not distributed dir…

b39be2b

…ectly Co-authored-by: Cursor <[email protected]>

vercel bot deployed to Preview February 12, 2026 09:56 View deployment


		## Overview

		The Linea Yield Boost system stakes LineaRollup funds on Ethereum L1 via Lido V3 stVaults to generate beacon chain rewards, which are reported to L2 for distribution. This document maps where ETH flows and which roles control each movement.

Conversation

kyzooghost commented Feb 10, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

vercel bot commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

allywhiting commented Feb 10, 2026

Uh oh!

kyzooghost commented Feb 11, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kyzooghost commented Feb 10, 2026 •

edited by cursor bot

Loading

vercel bot commented Feb 10, 2026 •

edited

Loading