feat: add connect-and-accept-tier, update documentation

DiRaiks · DiRaiks · commit bb9087124a5b · 2025-12-17T19:22:28.000+03:00
diff --git a/docs/cli/commands/vault-operations.md b/docs/cli/commands/vault-operations.md
@@ -53,6 +53,7 @@ Vault Operations commands manage the core functionality of Lido Staking Vaults i
 | change-tier-by-no (ct-no) \<tierId>          | vault tier change by node operator with multi-role confirmation                                                         |
 | change-tier (ct) \<tierId>                   | vault tier change with multi-role confirmation                                                                          |
 | sync-tier (st)                               | requests a sync of tier on the OperatorGrid                                                                             |
+| connect-and-accept-tier (connect-and-accept) | changes the tier of the vault and connects to VaultHub                                                                  |
 | role-grant                                   | mass-grants multiple roles to multiple accounts                                                                         |
 | role-revoke                                  | mass-revokes multiple roles from multiple accounts                                                                      |
 | create-vault                                 | creates a new StakingVault and Dashboard contracts                                                                      |
@@ -814,6 +815,51 @@ yarn start vo w st [options]
 
 **Use Case:** Synchronize vault tier configuration when changes need to be applied from the OperatorGrid system.
 
+### connect-and-accept-tier (connect-and-accept)
+
+Changes the tier of the vault and connects to VaultHub.
+
+**Usage:**
+
+```bash
+yarn start vo write connect-and-accept-tier <tier> <requestedShareLimit> [options]
+```
+
+Or using aliases:
+
+```bash
+yarn start vo w connect-and-accept <tier> <requestedShareLimit> [options]
+```
+
+**Arguments:**
+
+- `<tier>`: Tier ID to change to (numeric value)
+- `<requestedShareLimit>`: Requested new share limit for the vault (in shares, e.g., 1000.0)
+
+**Options:**
+
+- `-v, --vault <address>`: Specify vault address (optional - prompts for selection if not provided)
+- `-f, --fund`: Optional fund the vault with 1 ETH (default: false)
+
+**Process:**
+
+1. Reads current `settledGrowth` from the dashboard
+2. If `--fund` flag is NOT provided (default):
+   - Checks vault's available balance against required connect deposit
+   - If balance is insufficient, prompts for confirmation to fund with required amount
+   - Adds funding value to transaction if confirmed
+3. Displays confirmation with target tier, share limit, settled growth, and funding details
+4. Submits transaction to change tier and connect to VaultHub
+
+- Optionally funds the vault with 1 ETH if confirmed
+
+**Requirements:**
+
+- Vault must be in a state allowing connection
+- Caller must have appropriate permissions
+- Reverts if `settledGrowth` is not corrected after the vault is disconnected
+- Vault must have sufficient balance OR user confirms additional funding
+
 ### role-grant
 
 Mass-grants multiple roles to multiple accounts on the vault.
diff --git a/docs/cli/get-started/additional-helpers.md b/docs/cli/get-started/additional-helpers.md
@@ -1,5 +1,7 @@
 ---
-sidebar_position: 7
+title: Additional Helpers
+description: Useful utility commands for working with Lido Staking Vaults
+sidebar_position: 8
 ---
 
 # Additional Helpers
diff --git a/docs/cli/get-started/configuration.md b/docs/cli/get-started/configuration.md
@@ -1,11 +1,45 @@
 ---
+title: Configuration
+description: Configure your environment variables and wallet settings
 sidebar_position: 1
 ---
 
 # Configuration
 
 Before using the Lido Staking Vault CLI, you need to configure your environment variables and wallet settings. This guide covers all necessary configuration steps to get started.
 
+## Installation
+
+### Clone from Repository
+
+```bash
+git clone git@github.com:lidofinance/lido-staking-vault-cli.git
+cd lido-staking-vault-cli
+```
+
+### Choosing a Branch
+
+The repository maintains two primary branches:
+
+- **`main`** (Recommended): Stable, tested, and production-ready releases. Use this branch for reliable operation with verified features.
+- **`develop`**: Latest features and ongoing development. Choose this branch if you want access to cutting-edge functionality and are comfortable with potentially unstable features.
+
+```bash
+# For stable releases (recommended)
+git checkout main
+
+# For latest features in development
+git checkout develop
+```
+
+### Install Dependencies
+
+After cloning and selecting your branch, install dependencies:
+
+```bash
+yarn install
+```
+
 ## Environment Variables
 
 Configure your environment by creating a `.env` file in your project root:
diff --git a/docs/cli/get-started/create-vault.md b/docs/cli/get-started/create-vault.md
@@ -1,5 +1,7 @@
 ---
-sidebar_position: 2
+title: Creating a Vault
+description: Create new Lido Staking Vaults using the CLI
+sidebar_position: 3
 ---
 
 # Creating a Vault
diff --git a/docs/cli/get-started/deposits.md b/docs/cli/get-started/deposits.md
@@ -1,5 +1,7 @@
 ---
-sidebar_position: 6
+title: Validator Deposits
+description: Validator deposit operations in Lido Staking Vaults
+sidebar_position: 7
 ---
 
 # Validator Deposits
diff --git a/docs/cli/get-started/mint-burn.md b/docs/cli/get-started/mint-burn.md
@@ -1,5 +1,7 @@
 ---
-sidebar_position: 4
+title: Mint and Burn Tokens
+description: Mint and burn stETH-based tokens in Lido Staking Vaults
+sidebar_position: 5
 ---
 
 # Mint and Burn Tokens
diff --git a/docs/cli/get-started/reports.md b/docs/cli/get-started/reports.md
@@ -1,5 +1,7 @@
 ---
-sidebar_position: 5
+title: Reports
+description: Vault reporting operations for Lido Staking Vaults
+sidebar_position: 6
 ---
 
 # Reports
diff --git a/docs/cli/get-started/supply-withdrawal.md b/docs/cli/get-started/supply-withdrawal.md
@@ -1,5 +1,7 @@
 ---
-sidebar_position: 3
+title: Supply (Fund) and Withdrawal
+description: Funding and withdrawing ETH from Lido Staking Vaults
+sidebar_position: 4
 ---
 
 # Supply (Fund) and Withdrawal
diff --git a/docs/cli/get-started/wallet-connect.md b/docs/cli/get-started/wallet-connect.md
@@ -1,7 +1,7 @@
 ---
 title: WalletConnect (WC)
 description: Use WalletConnect with the CLI to sign and send transactions from your mobile/desktop wallet
-sidebar_position: 3
+sidebar_position: 2
 ---
 
 # WalletConnect Integration
diff --git a/features/utils/connection.ts b/features/utils/connection.ts
@@ -0,0 +1,24 @@
+import { Address } from 'viem';
+
+import { getVaultHubContract } from 'contracts';
+import { callReadMethodSilent, logInfo } from 'utils';
+
+export const checkIsDisconnected = async (vault: Address) => {
+  const vaultHubContract = await getVaultHubContract();
+  const connection = await callReadMethodSilent(
+    vaultHubContract,
+    'vaultConnection',
+    [vault],
+  );
+
+  const isDisconnected =
+    connection.owner === '0x0000000000000000000000000000000000000000' ||
+    connection.vaultIndex === 0n;
+
+  if (isDisconnected) {
+    logInfo('⚠️  The vault is not connected to VaultHub  ⚠️');
+    return true;
+  }
+
+  return false;
+};
diff --git a/features/utils/index.ts b/features/utils/index.ts
@@ -5,3 +5,4 @@ export * from './get-address.js';
 export * from './quarantine.js';
 export * from './settled-growth.js';
 export * from './get-boolean.js';
+export * from './connection.js';
diff --git a/features/utils/report-fresh.ts b/features/utils/report-fresh.ts
@@ -8,26 +8,7 @@ import {
   logInfo,
   PopulatedTx,
 } from 'utils';
-
-const checkIsDisconnected = async (vault: Address) => {
-  const vaultHubContract = await getVaultHubContract();
-  const connection = await callReadMethodSilent(
-    vaultHubContract,
-    'vaultConnection',
-    [vault],
-  );
-
-  const isDisconnected =
-    connection.owner === '0x0000000000000000000000000000000000000000' ||
-    connection.vaultIndex === 0n;
-
-  if (isDisconnected) {
-    logInfo('⚠️  The vault is not connected to VaultHub  ⚠️');
-    return true;
-  }
-
-  return false;
-};
+import { checkIsDisconnected } from './connection.js';
 
 export const checkIsReportFresh = async ({
   vault,
diff --git a/features/vault-operations/connect-vault.ts b/features/vault-operations/connect-vault.ts
@@ -0,0 +1,37 @@
+import { Address, formatEther } from 'viem';
+import { callReadMethodSilent, confirmOperation, logInfo } from 'utils';
+import { getStakingVaultContract, getVaultHubContract } from 'contracts';
+
+export const checkVaultAvailableBalance = async (
+  vault: Address,
+): Promise<{ isFundConfirmed: boolean }> => {
+  const vaultHub = await getVaultHubContract();
+  const connectDeposit = await callReadMethodSilent(
+    vaultHub,
+    'CONNECT_DEPOSIT',
+  );
+
+  const vaultContract = await getStakingVaultContract(vault);
+  const availableBalance = await callReadMethodSilent(
+    vaultContract,
+    'availableBalance',
+  );
+
+  if (availableBalance < connectDeposit) {
+    logInfo(
+      `⚠️  Vault available balance is less than connect deposit:
+        Available balance: ${formatEther(availableBalance)} ETH
+        Connect deposit: ${formatEther(connectDeposit)} ETH`,
+    );
+    const confirm = await confirmOperation(
+      `Do you want to fund the vault with ${formatEther(connectDeposit)} ETH?`,
+    );
+    if (!confirm) {
+      throw new Error('Vault available balance is less than connect deposit');
+    }
+
+    return { isFundConfirmed: true };
+  }
+
+  return { isFundConfirmed: false };
+};
diff --git a/features/vault-operations/dashboard-by-vault.ts b/features/vault-operations/dashboard-by-vault.ts
@@ -8,19 +8,40 @@ import {
   getVaultHubContract,
 } from 'contracts';
 import { getPublicClient } from 'providers';
-import { callReadMethodSilent, enterContractAddress } from 'utils';
+import {
+  callReadMethodSilent,
+  confirmOperation,
+  enterContractAddress,
+} from 'utils';
+import { checkIsDisconnected } from 'features';
 
 import { chooseVault } from './vaults-by-role.js';
 
 export const getDashboardByVault = async (vault: Address) => {
-  const vaultHub = await getVaultHubContract();
-  const vaultConnection = await callReadMethodSilent(
-    vaultHub,
-    'vaultConnection',
-    [vault],
-  );
+  const isDisconnected = await checkIsDisconnected(vault);
+  let vaultOwner: Address;
+
+  if (isDisconnected) {
+    const confirm = await confirmOperation(
+      'Vault is not connected to VaultHub. Do you want to continue executing the command?',
+    );
+    if (!confirm) {
+      throw new Error('Vault is not connected to VaultHub');
+    }
+
+    const vaultContract = await getStakingVaultContract(vault);
+    vaultOwner = await callReadMethodSilent(vaultContract, 'owner');
+  } else {
+    const vaultHub = await getVaultHubContract();
+    const vaultConnection = await callReadMethodSilent(
+      vaultHub,
+      'vaultConnection',
+      [vault],
+    );
+
+    vaultOwner = vaultConnection.owner;
+  }
 
-  const vaultOwner = vaultConnection.owner;
   const dashboard = await getDashboardContract(vaultOwner);
 
   const publicClient = await getPublicClient();
diff --git a/features/vault-operations/index.ts b/features/vault-operations/index.ts
@@ -6,3 +6,4 @@ export * from './vault-overview.js';
 export * from './vault-roles.js';
 export * from './create-vault.js';
 export * from './roles.js';
+export * from './connect-vault.js';
diff --git a/programs/use-cases/vault-operations/write.ts b/programs/use-cases/vault-operations/write.ts
@@ -1,4 +1,4 @@
-import { type Address, formatEther } from 'viem';
+import { type Address, formatEther, parseEther } from 'viem';
 import { Option } from 'commander';
 
 import {
@@ -27,6 +27,7 @@ import {
   logRolesOperations,
   askRoleOperationInfo,
   callWriteMethodsWithReportFresh,
+  checkVaultAvailableBalance,
 } from 'features';
 import { getAccount } from 'providers';
 import { getOperatorGridContract } from 'contracts';
@@ -677,3 +678,57 @@ vaultOperationsWrite
       });
     },
   );
+
+vaultOperationsWrite
+  .command('connect-and-accept-tier')
+  .alias('connect-and-accept')
+  .description('changes the tier of the vault and connects to VaultHub')
+  .argument('<tier>', 'tier to change to', stringToBigInt)
+  .argument(
+    '<requestedShareLimit>',
+    'requested new share limit for the vault (in shares)',
+    etherToWei,
+  )
+  .option('-f, --fund', 'optional fund the vault with 1 ETH', false)
+  .option('-v, --vault <string>', 'vault address', stringToAddress)
+
+  .addHelpText(
+    'after',
+    `Reverts if settledGrowth is not corrected after the vault is disconnected`,
+  )
+  .action(
+    async (
+      tier: bigint,
+      requestedShareLimit: bigint,
+      { fund, vault }: { fund: boolean; vault: Address },
+    ) => {
+      const { contract } = await chooseVaultAndGetDashboard({
+        vault,
+      });
+      const currentSettledGrowth = await callReadMethodSilent(
+        contract,
+        'settledGrowth',
+      );
+
+      const confirm = await confirmOperation(
+        `Are you sure you want to change the tier of the vault ${vault} to ${tier} and connect to VaultHub?
+        Requested share limit: ${formatEther(requestedShareLimit)}
+        Current settled growth: ${formatEther(currentSettledGrowth)}
+        Fund with 1 ETH: ${fund}`,
+      );
+      if (!confirm) return;
+
+      let value: bigint | undefined;
+      if (!fund) {
+        const { isFundConfirmed } = await checkVaultAvailableBalance(vault);
+        if (isFundConfirmed) value = parseEther('1');
+      }
+
+      await callWriteMethodWithReceipt({
+        contract,
+        methodName: 'connectAndAcceptTier',
+        payload: [tier, requestedShareLimit],
+        value,
+      });
+    },
+  );
diff --git a/utils/consolidation/confirms.ts b/utils/consolidation/confirms.ts
diff --git a/utils/consolidation/logs.ts b/utils/consolidation/logs.ts
diff --git a/utils/consolidation/types.ts b/utils/consolidation/types.ts
diff --git a/utils/consolidation/validator-info.ts b/utils/consolidation/validator-info.ts
