Add stVaults contract docs #781

TheDZhon · 2026-01-16T14:06:32Z

Summary

Comprehensive Lido V3 and stVaults documentation update:

New contract docs: VaultHub, StakingVault, Dashboard, LazyOracle, PredepositGuarantee, OperatorGrid, VaultFactory, Accounting
Enhanced guides: Rewrote protocol-levers.md and steth-superuser-functions.md with concrete addresses and role holders
Added struct definitions and fixed accuracy issues (Burner address, implementation vs proxy labels)

Test cases

npm run build
Verify Etherscan links and internal doc links
Confirm struct definitions match source code

Copilot

Pull request overview

This PR adds comprehensive contract reference documentation for the stVaults system and integrates these references into existing documentation. The changes provide detailed API documentation for 9 stVaults contracts with method signatures, descriptions, and cross-references.

Changes:

Added 9 new contract documentation files covering VaultHub, StakingVault, PredepositGuarantee, OperatorGrid, LazyOracle, Dashboard, factories, beacon, and consolidation helper contracts
Updated sidebar navigation to include all new contract pages in the contracts section
Added cross-reference links from stVaults technical docs and whitepaper to the new contract reference pages

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
sidebars.js	Adds 9 new contract reference pages to the contracts section navigation
docs/contracts/vault-hub.md	Main VaultHub contract reference with comprehensive API documentation
docs/contracts/staking-vault.md	StakingVault primitive contract reference with full method listings
docs/contracts/predeposit-guarantee.md	PredepositGuarantee (PDG) contract reference including deposit flow diagrams
docs/contracts/operator-grid.md	OperatorGrid registry contract reference with tier and group management APIs
docs/contracts/lazy-oracle.md	LazyOracle adapter contract reference with reporting and quarantine mechanisms
docs/contracts/dashboard.md	Dashboard management contract reference with role-based operations
docs/contracts/staking-vault-factory.md	VaultFactory deployment contract reference
docs/contracts/staking-vault-beacon.md	UpgradeableBeacon proxy pattern reference
docs/contracts/validator-consolidation-requests.md	Consolidation helper contract reference for EIP-7251 support
run-on-lido/stvaults/tech-documentation/tech-design.md	Adds link to contract reference from technical design doc
run-on-lido/stvaults/tech-documentation/integration-overview.md	Adds link to contract reference and formatting fix for bullet list
run-on-lido/stvaults/index.md	Adds contract reference link to stVaults documentation center
docs/lido-v3-whitepaper.mdx	Adds contract reference link to whitepaper related documentation section

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/contracts/staking-vault.md

docs/contracts/dashboard.md

docs/contracts/lazy-oracle.md

docs/contracts/operator-grid.md

docs/contracts/predeposit-guarantee.md

docs/contracts/staking-vault-factory.md

TheDZhon

👀

docs/contracts/accounting-oracle.md

docs/contracts/lazy-oracle.md

docs/contracts/predeposit-guarantee.md

docs/contracts/staking-vault-beacon.md

docs/contracts/staking-vault-factory.md

docs/contracts/vault-hub.md

docs/guides/oracle-spec/accounting-oracle.md

docs/guides/protocol-levers.md

docs/guides/verify-lido-v2-upgrade-manual.md

docs/token-guides/steth-superuser-functions.md

- Add new Accounting contract documentation with structs and methods - Add roles/permissions and PDGPolicy enum docs to Dashboard - Add VaultConnection, VaultRecord, Report structs to VaultHub - Add staged balance explanation and Deposit struct to StakingVault - Fix requestValidatorExit method signature in VaultHub Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Add report freshness documentation to LazyOracle - Add key concepts (groups, tiers, default tier, jailing) to OperatorGrid - Add BLS verification context and structs to PredepositGuarantee - Add factory chaining and connect deposit docs to VaultFactory - Clarify EIP-7002 for ejectValidators in StakingVault - Add node operator fee accounting to Dashboard - Add ownership and ossification context to StakingVaultBeacon Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

These contracts are implementation addresses, not singleton proxies. Individual instances are deployed by VaultFactory as proxies/beacon proxies. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 44 out of 44 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/contracts/burner.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

failingtwice · 2026-01-23T07:49:55Z

docs/contracts/accounting.md

+The method performs these operations in order:
+1. Internalizes bad debt from stVaults
+2. Updates consensus layer state on Lido
+3. Collects EL rewards and processes withdrawals
+4. Finalizes withdrawal queue requests
+5. Commits shares to burn
+6. Distributes protocol fees to modules and treasury
+7. Emits token rebase event
+8. Notifies rebase observers


If we want to list the operations in the order they are executed in the contract, this is the correct order.

Performs sanity checks

Updates consensus layer state on Lido

Internalizes bad debt

Commits shares to burn

Finalizes withdrawal queue requests

Distributes protocol fees to modules and treasury

Notifies rebase observers

Emits token rebase event

https://github.com/lidofinance/core/blob/d5d92266b5bb305044c5dcf3e407463f776a4def/contracts/0.8.9/Accounting.sol#L329

failingtwice · 2026-01-23T07:58:38Z

docs/contracts/accounting.md

+```mermaid
+graph LR;
+  AO[AccountingOracle]--handleOracleReport-->A[Accounting];
+  A--collectRewardsAndProcessWithdrawals-->L[Lido];
+  A--finalize-->WQ[WithdrawalQueue];
+  A--internalizeBadDebt-->VH[VaultHub];
+  A--reportModuleRewards-->SR[StakingRouter];
+  A--sanityChecks-->SC[OracleReportSanityChecker];
+```


The method names are incorrect, e.g. Accounting calls VaultHub.decreaseInternalizedBadDebt(), and StakingRouter.reportRewardsMinted().

We can update the diagram to use correct method name OR we can leave these names but without camelCase so as they are not confused with actual method names, e.g. A -> report module rewards -> SR

failingtwice · 2026-01-23T08:00:22Z

docs/contracts/accounting.md

+  A--sanityChecks-->SC[OracleReportSanityChecker];
+```
+
+## Structs


Missing struct PreReportState

failingtwice · 2026-01-23T08:01:46Z

docs/contracts/accounting.md

+
+Simulates an oracle report without applying changes. Returns calculated state changes that would result from the report. Used by oracle daemons to compute the simulated share rate before submitting.
+
+## Methods


Constructor missing

failingtwice · 2026-01-23T08:06:47Z

docs/contracts/dashboard.md

+### wrap(uint256 _stETHAmount)
+
+```solidity
+function wrap(uint256 _stETHAmount) external returns (uint256)
+```
+
+Wraps stETH into wstETH.
+
+### unwrap(uint256 _wstETHAmount)
+
+```solidity
+function unwrap(uint256 _wstETHAmount) external returns (uint256)
+```
+
+Unwraps wstETH into stETH.


These methods don't exist

failingtwice · 2026-01-26T07:57:26Z

docs/contracts/staking-vault-factory.md

+
+## Factory flows
+
+VaultFactory exposes two creation flows, reflected in the NatSpec:


Might be worth mentioning that the factory acts as temporary admin during the deploy.

failingtwice · 2026-01-26T08:13:37Z

docs/contracts/staking-vault.md

+function ossify() external onlyOwner
+```
+
+Pins the implementation for this vault (no upgrades).


Suggested change

Pins the implementation for this vault (no upgrades).

Pins the implementation for this vault (no upgrades). After ossification, the vault cannot reconnect to VaultHub.

failingtwice · 2026-01-26T08:14:26Z

docs/contracts/staking-vault.md

+
+Returns whether deposits are paused.
+
+## Methods


I think it's important to document receive function

failingtwice · 2026-01-26T08:47:37Z

docs/contracts/vault-hub.md

+VaultHub validates that a vault was deployed by the current VaultFactory (or a
+previous factory in the chain) before allowing connection.
+
+## Structs


failingtwice · 2026-01-26T08:49:23Z

docs/contracts/vault-hub.md

+
+VaultHub is driven by reports from `LazyOracle` and vault actions routed via the `Dashboard` or direct calls.
+
+## How it works


Pause intent not documented

Add stVaults contract docs

e27e6cb

TheDZhon requested a review from a team as a code owner January 16, 2026 14:06

tamtamchik requested a review from Copilot January 16, 2026 14:59

Copilot started reviewing on behalf of tamtamchik January 16, 2026 14:59 View session

Copilot AI reviewed Jan 16, 2026

View reviewed changes

Update docs for Lido V3 accounting

8af0c5e

TheDZhon requested a review from a team as a code owner January 16, 2026 16:06

TheDZhon commented Jan 16, 2026

View reviewed changes

TheDZhon and others added 11 commits January 16, 2026 19:43

Resolve review feedback and refresh guides

767ec11

Remove eth_call references in oracle docs

1dc4381

Enhance stVaults docs with NatSpec context

eb24a32

Adjust proxy admin notes and layout

f559d67

Clarify proxy admin ownership

756f212

Link Accounting docs in core references

cf1f396

Reaffirm proxy admin ownership

ec14805

Fix upgradeable contract list and stETH superuser details

7ed9575

Clarify Dashboard and StakingVault as implementation contracts

c7507b7

These contracts are implementation addresses, not singleton proxies. Individual instances are deployed by VaultFactory as proxies/beacon proxies. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

tamtamchik requested a review from Copilot January 21, 2026 14:28

Copilot started reviewing on behalf of tamtamchik January 21, 2026 14:29 View session

Copilot AI reviewed Jan 21, 2026

View reviewed changes

docs/contracts/burner.md Outdated Show resolved Hide resolved

Update docs/contracts/burner.md

0f5c075

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

failingtwice reviewed Jan 26, 2026

View reviewed changes


		Simulates an oracle report without applying changes. Returns calculated state changes that would result from the report. Used by oracle daemons to compute the simulated share rate before submitting.

		## Methods


		## Factory flows

		VaultFactory exposes two creation flows, reflected in the NatSpec:

	Pins the implementation for this vault (no upgrades).
	Pins the implementation for this vault (no upgrades). After ossification, the vault cannot reconnect to VaultHub.


		VaultHub is driven by reports from `LazyOracle` and vault actions routed via the `Dashboard` or direct calls.

		## How it works

Add stVaults contract docs #781

Are you sure you want to change the base?

Add stVaults contract docs #781

Uh oh!

Conversation

TheDZhon commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test cases

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

TheDZhon left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

TheDZhon commented Jan 16, 2026 •

edited

Loading