Skip to main content

stVault integration overview

stVaults are Lido staking building blocks that allows the creating of custom staking solutions still accessing unmatched stETH liquidity. The stVaults User Guide provides instructions for managing and integrating Staking Vaults (stVaults). This guide covers various interaction levels, from direct contract calls to using CLI tools and web interfaces, depending on requirements and preferred methods of fine-grained control.

For a deeper technical dive, you can check out the stVaults Technical Design and Architecture.

Architecture Overview​

integration-overview

stVaults consist of the following components:

  • stVaults Web UI: A web interface interacting directly with the Dashboard contract and other stVaults-related contracts, providing a user-friendly experience for managing vaults and monitoring metrics.
  • CLI (Command Line Interface): A command-line tool interacting directly with the Dashboard contract and other stVaults-related contracts offering advanced management capabilities (deposits, generating proofs, per-vault oracle reports, etc.). (GitHub Repository, Documentation)
  • Dashboard contract: A management contract deployed together with the StakingVault contract, and is assigned as the owner of the StakingVault contract by default. It provides granular management capabilities and introduces roles and permissions, allowing different actions to be managed by distinct roles. It also provides utility functions for minting/burning, performing deposits, collecting node operator fees.
  • StakingVault Contract: The core primitive contract representing the staking vault. Advanced use cases might include direct interaction with the StakingVault contract, which requires transferring ownership from the Dashboard contract.
  • Predeposit Guarantee (PDG): The contract that mitigates deposit frontrunning vulnerabilities described in LIP-5. It uses a mechanism distinct from the Deposit Security Module adopted by Lido Core. It allows stVault's owner and Node Operators to deposit validators with the vault's funds in trustless manner.
  • Off-chain monitoring tools (can be used by the Node Operator):
    • Ethereum Validators Monitoring (EVM): Consensus layer validators monitoring bot, that fetches Lido or Custom Users Node Operators keys from Execution layer and checks their performance in Consensus layer by: balance delta, attestations, proposes, sync committee participation.
    • Ethereum Head Watcher: Bot which watches Ethereum head block and handle validator-related "events" and sends notifications through Alertmanager to Discord channel.

Integration and interacting layers​

Command-line interface​

URL: GitHub Repository, Documentation

Goal: Manage stVaults via CLI for automation and advanced operations (deposits, generating/submitting proofs, per-vault oracle reports, etc.).

Steps:

  1. Clone the GitHub repository and configure it according to the CLI User Guide.
  2. Deploy, configure vaults, assign roles, and manage staking operations.
  3. Utilize commands for advanced maintenance.
  4. Check-up the vault state via data provided by CLI.

Use case examples:

  • Institutional integrator requiring automated and scriptable staking management.
  • Node Operator using the CLI to initiate staking operations and monitor staking performance, as well as predeposit, prove and top-up deposit validators via PDG.
  • Protocols integrating with stVaults and run in the integration on testnet.

Web UI​

info

The Web UI covers nearly all routine stVault tasks for Lido V3 testnet on Hoodi. For advanced or low-level features that haven’t yet been exposed in the interface, use the CLI.

URL: https://vaults-hoodi-lidov3.testnet.fi

Goal: Provide an easy-to-use interface for managing and monitoring stVaults via the Vault UI.

Steps:

  1. Access the Vault Web UI and connect the wallet.
  2. Create a vault and set up roles and permissions.
  3. Supply/withdraw ETH, perform Beacon Chain deposits/withdrawals, mint/burn stETH.
  4. View vault and validators metrics and configure settings.

Use case example:

  • Individual and institutional stakers using the UI to perform operations, exploring vault performance, economy, fees, and efficiency.
  • Prospecting vault owners examining node operator performance and vault efficiency before creating their own staking vault.
  • Anyone using the UI as an educational and analytical tool for understanding staking vault metrics.

Dashboard contract​

URL: GitHub Repository

Goal: Provide a feature-rich straightforward UX layer for staking vault and VaultHub and additional accounting for Node Operator fee.

Steps:

  1. Call VaultFactory to create a StakingVault contract and a Dashboard contract assigned as an owner of the Vault contract.
  2. Define roles and permissions on the StakingVault creating, or later via the Dashboard contract.
  3. Interact with the Dashboard contract for high-level operations.
  4. Use role-specific methods via the Dashboard contract to interact with the StakingVault contract.

Use case example:

  • Granular permissions for staking vault operations and Node Operator fee claiming.
  • Structured product integrating stVaults for staking operations with granular control.

Staking Vault contract​

URL: GitHub Repository

Goal: Directly manage a StakingVault contract by transferring its ownership from the Dashboard contract to reduce operations gas costs (advanced integrations).

If vault ownership is changed to interact with the vault directly, it’s no longer possible to use other Lido stVaults infrastructure mechanisms to manage the vault. In this case, direct interaction with Lido core protocol via the Vault Hub contract is required.

Steps:

  1. Call VaultFactory to create a StakingVault contract and a Dashboard contract.
  2. Transfer ownership from the Dashboard contract to the desired address.
  3. Use smart contract calls to configure, supply, withdraw, and manage other operations.
  4. Monitor contract status directly via blockchain explorers or custom tools.

Use case example:

  • Institutional users with a dedicated infrastructure for contract interaction who require maximum control over staking operations.
  • Structured product integrating StakingVault directly to reduce operations gas costs and use own infrastructure.

Predeposit Guarantee (PDG)​

URL: Technical details; GitHub Repository, PDG user guide

Goal: Prevent deposit frontrunning enabled by vulnerabilities described in LIP-5. PDG secures the vault owner’s ether depositing to the validator from front-running by the node operator or third parties. One of the key advantages is a separating finances of the vault owner and the node operator.

How to use:

  1. Create and configure a vault through any convenient interface (contracts, CLI, or UI).
  2. Predeposit guarantee contract enables three main use cases:
    1. Full-cycle proof of validators through PDG to enable non-custodial depositing mechanism, using the guarantee ether as a collateral (read more).
    2. PDG shortcut that allows to skip the predepositing steps and deposit directly to validator without using of PDG, later on associating the validator with the vault by proving it through PDG. Applicable in unconditional trust between the node operator and the vault owner (read more).
    3. Adding existing validator to Vault from external staking infrastructure as an advanced integration use-case.

Off-chain monitoring tools​

Ethereum Validators Monitoring (EVM)​

Where: GitHub Repository

Goal: Off-chain track the status and performance of Ethereum validators used in stVaults. It helps detect inactivity, monitor effectiveness, and identify anomalies in validator operations.

How to use:

  • Clone the repository from GitHub.
  • Install dependencies and set up the environment.
  • Run the monitoring tool to get validator status.
  • Integrate the output with alerting or dashboards.

Ethereum Head Watcher​

Where: GitHub Repository

Goal: Off-chain monitor Ethereum chain head updates to detect delays, stalls, or reorgs. It is used to ensure timely block processing and head finality, which are critical for the stability of services like stVaults.

How to use:

  • Clone the repository from GitHub.
  • Install dependencies and configure environment variables.
  • Run the watcher to observe head progression.
  • Connect it to alerting or monitoring systems if needed.