Skip to main content

Basic stVault with optional liquidity

Intro​

This guide is aimed to help Node Operators, Builders, Protocols, Liquidity Providers create and operate an stVault with optional liquidity.

Product value proposition​

Competitive offering to native staking — users stake with the same Node Operator and get optional liquidity through stETH.

The vault strategy​

ETH is deposited to validators and generate staking rewards, stETH is minted on demand by the Vault Owner.

Environments​

Testnet​

Mainnet​

info

Coming this autumn

Steps​

Create an stVault​

Creating an stVault is permissionless. There are two main ways to do it:

  1. Two-step process (recommended): initiated by the Node Operator and completed by the Vault Owner.
  2. One-step process (for experienced Vault Owners / Stakers): create the stVault and supply 1 ETH in a single transaction.

Parameters needed to create an stVault:​

  1. Node Operator address — a unique, immutable identifier of the Node Operator within stVaults, used in protocol logic such as calculating per-operator stETH minting terms and limits. It designates the Node Operator that provides validation services for the stVault and also manages ETH deposits from the stVault balance to validators, as well as handling validator exits when required.
  2. Node Operator Manager address. One of the two administrative roles in an stVault. From the Node Operator perspective, this role manages permissions and can update key vault parameters. Multiple addresses are supported.
  3. Vault Owner address. One of the two administrative roles in an stVault. From the Vault Owner (Staker) perspective, this role manages permissions and can update key vault parameters. Multiple addresses are supported.
  4. Node Operator Fee. The share of gross staking rewards that the Node Operator charges for providing validation services. Expressed as a percentage [0% .. 100.00%].
  5. Confirmation Lifetime. The key parameter of the multi-role confirmation mechanism. This mechanism is used to update certain stVault parameters by requiring consensus between the two stVault representatives: the Vault Owner and the Node Operator Manager. Measured in hours [24h .. 720h (30 days)].

This approach enables a Node Operator to create an stVault without providing their own ETH. It is recommended because it prevents ETH commingling and streamlines the experience for Stakers and Vault Owners.

1.1. Node Operator creates an stVault that is not yet connected to Lido Core.​

Creating stVault is permissionless operations, but in this 2-steps process it is usually performed by the Node Operator.

by Command-line Interface
yarn start vo w create-vault create-without-connecting --defaultAdmin <VaultOwnerAddress> --nodeOperator <NodeOperarorAddress> --nodeOperatorManager <NodeOperarorManagerAddress> --confirmExpiry <TimeInSeconds> --nodeOperatorFeeRate <NodeOperatorFeeInBasisPoints> 1

Note down the addresses of the created Vault and Dashboard contracts — these are the key contracts of your newly created stVault.

using Etherscan UI
  1. Open Etherscan and navigate to the VaultFactory contract by its address (available in the stVaults contract addresses list, see #Environments).
  2. Go to the Contract tab → Write Contract.
  3. Click Connect to Web3 and connect your wallet in the dialog window.
  4. Find the method createVaultWithDashboardWithoutConnectingToVaultHub in the list, fill out the fields, and click Write.
    • You can leave _payableAmount (ether) = 0 and _roleAssignments = [].
  5. Sign the transaction in your wallet.
  6. Click View your transaction and wait for it to be executed.
  7. Open the Logs tab, scroll to the DashboardCreated event, and note down the addresses of the created Vault and Dashboard contracts — these are the key contracts of your newly created stVault.
1.2. When an stVault is created, the Node Operator may optionally propose a tier with more favorable stETH minting terms than the Default tier.​

To perform this step, the Node Operator of the newly created vault must already have individual tiers assigned. Otherwise, the stVault will remain limited to the Default tier option (tierID = 0).

Parameters needed for this step:

  • VaultAddress: the address of the Vault contract.
  • TierID: the ID of the tier to which the stVault will be connected.
  • RequestedShareLimit: the requested absolute stETH minting limit for the stVault, expressed in shares. This value cannot exceed the tier’s stETH limit.
by Command-line Interface
   yarn start contracts operator-grid w ct <VaultAddress> <TierID> <RequestedShareLimit>
using Etherscan UI
  1. Open Etherscan and navigate to the Operator Grid contract by its address (available in the stVaults contract addresses list, see #Environments).
  2. Since this contract is a proxy, complete the verification steps once (if not done before):
    • Go to Contract → Code.
    • Click More options.
    • Select Is this a proxy?.
    • Click Verify in the dialog.
    • Return to the contract details page.
  3. Open the Contract tab → Write as Proxy.
  4. Click Connect to Web3 and connect your wallet in the dialog window.
  5. Find the changeTier method in the list, fill out the fields, and click Write.
  6. Sign the transaction in your wallet.
  7. Click View your transaction and wait for it to be executed.
1.3. After that, the Vault Owner, in one transaction, accepts the stETH minting parameters and fees (by accepting the tier), supplies 1 ETH as collateral for connection to Lido Core, and initiates the connection to Lido Core.​

This is a permissioned operation. By default, this permission belongs to the Vault Owner, who can delegate it to other addresses (multiple supported, including the Vault Owner’s own address). Read more about roles.

Parameters and addresses needed for this step:

  • VaultAddress: the address of the Vault contract.
  • TierID: the ID of the tier to which the stVault will be connected.
  • RequestedShareLimit: the requested absolute stETH minting limit for the stVault, expressed in shares. This value cannot exceed the tier’s stETH limit.
  • payableAmount: the amount of ETH to supply in the same transaction; minimum is 1 ETH.
using stVaults Web UI

Will be supported later this Autumn

by Command-line Interface
yarn start contracts dashboard w connect-and-accept-tier -f <DashboardAddress> <TierID> <RequestedShareLimit>
using Etherscan UI
  1. Open Etherscan and navigate to the Dashboard contract by its address (provided in the results of stVault creation, see step 1.1).
  2. Since this contract is a proxy, complete the verification steps once (if not done before):
    • Go to Contract → Code.
    • Click More options.
    • Select Is this a proxy?.
    • Click Verify in the dialog.
    • Return to the contract details page.
  3. Open the Contract tab → Write as Proxy.
  4. Click Connect to Web3 and connect your wallet in the dialog window.
  5. Find the connectAndAcceptTier method in the list, fill out the fields, and click Write.
    • fill out the payableAmount field with '1' to supply 1 ETH in the same transaction.
  6. Sign the transaction in your wallet.
  7. Click View your transaction and wait for it to be executed.

2. One-step process (for experienced Vault Owners / Stakers)​

In this approach, the Vault Owner creates an stVault that automatically connects to Lido Core, enabling stETH minting. This requires supplying 1 ETH, which will be locked as collateral for the connection to Lido Core. All completed in a single transaction, so despite it is a permissionless operation, it is usually performed by the Vault Owner of the future stVault.

using stVaults Web UI
  1. Open the stVaults mainpage (see #Environments)
  2. Connect wallet on the "My Vaults" page.
  3. Click "Create vault".
  4. Fill out the form and click "Continue".
  5. Sign transaction in the wallet.
by Command-line Interface
yarn start vo w create-vault create --defaultAdmin <VaultOwnerAddress> --nodeOperator <NodeOperarorAddress> --nodeOperatorManager <NodeOperarorManagerAddress> --confirmExpiry <TimeInSeconds> --nodeOperatorFeeRate <NodeOperatorFeeInBasisPoints> 1
using Etherscan UI
  1. Open Etherscan and navigate to the VaultFactory contract by its address (available in the stVaults contract addresses list, see #Environments).
  2. Go to the Contract tab → Write Contract.
  3. Click Connect to Web3 and connect your wallet in the dialog window.
  4. Find the method createVaultWithDashboard in the list, fill out the fields, and click Write.
    • _payableAmount (ether) must be at least 1 ETH.
    • You can leave _roleAssignments = [].
  5. Sign the transaction in your wallet.
  6. Click View your transaction and wait for it to be executed.
  7. Open the Logs tab, scroll to the DashboardCreated event, and note down the addresses of the created Vault and Dashboard contracts — these are the key contracts of your newly created stVault.

Adjust stETH minting parameters​

By default, a newly created stVault is connected to the Default tier with a Reserve Ratio of 50%. If the Node Operator has passed identification and been granted individual tiers, the stVault can be moved from the Default tier to one of the Node Operator’s tiers to access better stETH minting conditions.

When using vault creation method #1 ("Two-step process"), the Node Operator and Vault Owner can set up the stVault with the desired stETH minting parameters from the start. Otherwise, the tier can be changed afterwards.

Tier changes are performed via a multi-role confirmation mechanism, where the Node Operator and Vault Owner act as contracting parties. One party proposes the change, and the other party accepts it. Technically, both requests are made through the same method: changeTier(tierId, requestedShareLimit).

Both parties must submit the request with identical parameters within the confirmation lifetime of 24 hours for the change to take effect.

Addresses perform this operation must have the following roles (Read more about roles):

  • From the Vault Owner: Vault Owner (Admin DEFAULT_ADMIN_ROLE, or delegated VAULT_CONFIGURATION_ROLE].
  • From the Node Operator: Node Operator (registered in theOperatorGrid contract).

Parameters and addresses needed for this step (for CLI and Smart contracts):

  • VaultAddress: the address of the Vault contract.
  • TierID: the ID of the tier to which the stVault will be connected.
  • RequestedShareLimit: the requested absolute stETH minting limit for the stVault, expressed in shares. This value cannot exceed the tier’s stETH limit.
using stVaults Web UI
  1. On behalf of the first contracting party, open 'Settings > Tiers', and click the tier selector:

Settings &gt; Tiers

  1. Select the desired tier from the list:

Selecting Tier

  1. Review how the stVault metrics will change after moving to the new tier, then submit your request/proposal.

Review settings

  1. On behalf of the another contracting party open 'Settings > Tiers'.

Open proposal

  1. Open the request details, review the projected changes to the stVault metrics, and submit approval.

Review settings

by Command-line Interface

On behalf of the Vault Owner (details and examples):

yarn start vo w change-tier -v <vaultAddress> -r <requestedShareLimit> <tierId>

On behalf of the Node Operator (details and examples)::

yarn start vo w change-tier-by-no -v <vaultAddress> -r <requestedShareLimit> <tierId>
using Etherscan UI

The Node Operator and Vault Owner use same-named metods in different contracts to perform this change.

Node Operator:

  1. Open Etherscan and navigate to the Operator Grid contract by its address (available in the stVaults contract addresses list, see #Environments).
  2. Since this contract is a proxy, complete the verification steps once (if not done before):
    • Go to Contract → Code.
    • Click More options.
    • Select Is this a proxy?.
    • Click Verify in the dialog.
    • Return to the contract details page.
  3. Open the Contract tab → Write as Proxy.
  4. Click Connect to Web3 and connect your wallet in the dialog window.
  5. Find the changeTier method in the list, fill out the fields, and click Write.
  6. Sign the transaction in your wallet.
  7. Click View your transaction and wait for it to be executed.

Vault Owner:

  1. Open Etherscan and navigate to the Dashboard contract by its address (provided in the results of stVault creation, see step 1.1).
  2. Since this contract is a proxy, complete the verification steps once (if not done before):
    • Go to Contract → Code.
    • Click More options.
    • Select Is this a proxy?.
    • Click Verify in the dialog.
    • Return to the contract details page.
  3. Open the Contract tab → Write as Proxy.
  4. Click Connect to Web3 and connect your wallet in the dialog window.
  5. Find the changeTier method in the list, fill out the fields, and click Write.
  6. Sign the transaction in your wallet.
  7. Click View your transaction and wait for it to be executed.

Supply and withdraw ETH​

Supply and Withdraw ETH are permissioned operations. By default, these permissions belong to the Vault Owner, who can delegate them to other addresses (multiple are supported, including the Vault Owner’s own address). Read more about roles.

using stVaults Web UI

Supply / Withdraw section: Supply and Withdraw When supplying, you can mint all amount of available stETH immediately by selecting the checkbox. When withdrawing, you can specify a destination address for the withdrawal. You can also choose which token to supply or withdraw: ETH or wETH.

by Command-line Interface

Supply (fund) ((details and examples)):

yarn start vo w fund <amount>

Withdraw (details and examples):

yarn start vo w withdraw <amount>
using Etherscan UI
  1. Open Etherscan and navigate to the Dashboard contract by its address (provided in the results of stVault creation, see step 1.1).
  2. Since this contract is a proxy, complete the verification steps once (if not done before):
    • Go to Contract → Code.
    • Click More options.
    • Select Is this a proxy?.
    • Click Verify in the dialog.
    • Return to the contract details page.
  3. Open the Contract tab → Write as Proxy.
  4. Click Connect to Web3 and connect your wallet in the dialog window.
  5. Find the required method in the list, fill out the fields, and click Write:
    • fund to supply (fund) ETH into the stVault;
    • withdraw to withdraw ETH from the stVault balance.
  6. Sign the transaction in your wallet.
  7. Click View your transaction and wait for it to be executed.
info

Withdrawable ETH is defined by:

  • stVault Balance - ETH that is not staked on validators.
  • Total lock — collateral reserved for stETH liability, the mandatory 1 ETH minimal reserve for connecting the stVault to Lido Core, and protocol and Node Operator fee obligations.

Read more about stVaults metrics

Mint and repay stETH​

When ETH is supplied to an stVault, the Vault Owner can mint stETH on demand. Unlike Lido Core, stVaults allow stETH minting only within the defined stETH minting capacity.

Mint and Repay stETH are permissioned operations. By default, these permissions belong to the Vault Owner, who can delegate them to other addresses (multiple supported, including the Vault Owner’s own address). Read more about roles.

using stVaults Web UI

Mint / Repay section: Mint and Repay When minting stETH, you can specify an address to receive it. You can also choose which token to mint or repay: stETH or wstETH.

by Command-line Interface

Mint (details and examples):

  • Mint Shares yarn start vo w mint <amount>
  • Mint stETH tokens (rebasing): yarn start vo w mint-steth <amount>
  • Mint wrapped stETH tokens (non-rebasing): yarn start vo w mint-wsteth <amount>

Repay (burn) (details and examples):

  • Repay (burn) vault shares: yarn start vo w burn <amount>
  • Repay (burn) stETH tokens: yarn start vo w burn-steth <amount>
  • Repay (burn) wrapped stETH tokens: yarn start vo w burn-wsteth <amount>
using Etherscan UI
  1. Open Etherscan and navigate to the Dashboard contract by its address (provided in the results of stVault creation, see step 1.1).
  2. Since this contract is a proxy, complete the verification steps once (if not done before):
    • Go to Contract → Code.
    • Click More options.
    • Select Is this a proxy?.
    • Click Verify in the dialog.
    • Return to the contract details page.
  3. Open the Contract tab → Write as Proxy.
  4. Click Connect to Web3 and connect your wallet in the dialog window.
  5. Find the required method in the list, fill out the fields, and click Write:
    • mintShares to mint shares;
    • mintStETH to mint stETH token (rebasable);
    • mintWstETH to mint the wrapped token wstETH (not rebasable);
    • burnShares to repay (burn) shares;
    • burnStETH to repay (burn) stETH token;
    • burnWstETH to repay (burn) the wrapped token wstETH;
  6. Sign the transaction in your wallet.
  7. Click View your transaction and wait for it to be executed.

To repay (burn) shares and stETH, you must first grant approval to the contract. Go to the token contract and execute the approve() method for the amount you want to set as allowance. Only after the approval is confirmed you can proceed with the repay (burn) operation. Please find the contracts' addresses on the Contracts page in accordance with your environment.

info

After stETH is repaid, the corresponding ETH is unlocked once the upcoming Oracle report confirms the repaid amount.

Deposit ETH to validators​

Supplying ETH to the stVault increases its balance. The Node Operator can then deposit ETH from this balance into validators.

The Predeposit Guarantee (PDG) contract, as part of the stVaults platform, helps prevent deposit frontrunning caused by the vulnerabilities described in LIP-5. PDG secures the Vault Owner’s ETH deposits to validators from being front-run by the Node Operator.

One of the key benefits of using PDG is the avoidance of commingling: it keeps the finances of the Vault Owner and the Node Operator strictly separated.

PDG enables three main use cases:

  • Full-cycle proof of validators. Enables a non-custodial deposit mechanism by using guarantee ETH as collateral. Follow the main guide.
  • PDG shortcut. Allows skipping the pre-deposit steps and depositing directly to a validator without using PDG initially. The validator can later be associated with the vault by proving it through PDG. This path is applicable when there is unconditional trust between the Node Operator and the Vault Owner. Follow the shortcut guide.
  • Adding existing validators. Lets you connect an existing validator from external staking infrastructure to an stVault as an advanced integration use case.

Read more: Technical details; GitHub Repository.

Monitor stVault health and rebalance​

The key stVault metrics that the Vault Owner should monitor and control are:

  • Utilization ratio -- the share of the stETH minting capacity currently used by the Vault Owner. Learn more
  • Health Factor -- a metric that reflects the economic state of the vault. It shows how the stETH liability is collateralized by the Total Value. A Health Factor of 100% corresponds to the Forced Rebalance Threshold, meaning that if the Health Factor falls below 100%, the stVault becomes subject to forced rebalancing. Learn more

The Health Factor metric may decrease as a result of validator underperformance, penalties, or a slashing event.

If this happens, there are three main options available:

  • Supply ETH to increase Total Value.
  • Repay stETH to reduce stETH liability.
  • Rebalance ETH (optionally combined with a supply in a single transaction).

Rebalancing involves transferring available ETH from the stVault balance to Lido Core, receiving stETH at a 1:1 ratio, and repaying it back to the stVault. This reduces stETH Liability and thereby increases the Health Factor.

Rebalancing is performed in one transacion.

The amount of ETH required for rebalancing to bring the Utilization Ratio to 100% depends on the current Health Factor and Reserve Ratio. It can be pre-calculated manually using the formula, or via the built-in methods.

by Formula

ETH for rebalance = stETH Liability - (1 - Reserve Ratio * Total Value ) / Reserve Ratio

by Command-line Interface

Will be supported later on testnet-3

using Etherscan UI
  1. Open Etherscan and navigate to the VaultHub contract by its address (available in the stVaults contract addresses list, see #Environments).
  2. Since this contract is a proxy, complete the verification steps once (if not done before):
    • Go to Contract → Code.
    • Click More options.
    • Select Is this a proxy?.
    • Click Verify in the dialog.
    • Return to the contract details page.
  3. Open the Contract tab → Read as Proxy.
  4. Click Connect to Web3 and connect your wallet in the dialog window.
  5. Find the method healthShortfallShares in the list, fill out the input with the vault contract address, and click Query.
  6. Receive the result right under the submit button.