SSV Keys CLI

CLI to work with the ETH keystore file and extract the latest validator cluster snapshot to build the payload:

1. Parse the private key using the keystore password
2. Use the private key to get shares for operators
3. Build the payload for the transaction

Option 1: Running an Executable (Recommended route)

If you want to run a compiled version (easier option than the CLI)

1. Go to the releases section: https://github.com/ssvlabs/ssv-keys/releases
2. Select the latest release for the specific version of the CLI: vX.Y.Z-v1 - for the first version of the contract, vX.Y.Z-v2 - for second etc. Example: v0.0.1-v1 or v0.0.1-v2.
3. Download the native executable for your operating system:
   • ssv-keys-lin - for Ubuntu Linux
   • ssv-keys-mac - for macOS
   • ssv-keys.exe - for Windows
4. Open the terminal and change the directory to where you downloaded the executable. For instance, on macOS you can:

   cd ~/Downloads

5. (Mac and Linux) Make sure that the executable has permissions to run by running:

   chmod 777 ./ssv-keys-mac

6. Now you can run it:

   ./ssv-keys-mac

7. If your operating system prevents you from running the executable, you can open it from the file manager (Finder in case of macOS), right-click on it, and click the Open menu. Once open click the Open or allow button when you are asked to do so. After this, go back to the console and try to run it again.

Option 2: Running from the CLI

Installation

This installation requires Node.js on your machine. You can download it here.

Once you have installed Node.js, follow instructions:

git clone https://github.com/ssvlabs/ssv-keys.git
cd ssv-keys
npm install -g pnpm@latest-10
pnpm install
pnpm run cli --help

Help

Help on available actions:

pnpm run cli --help

Help on a specific action:

pnpm run cli <action> --help

Example

To run, you will use the "shares" command

Input parameters:

• keystore (ks) = The path to either a validator keystore file or a folder that contains multiple validator keystore files. If a folder is provided, it will split in bulk all the keystore files within it according to the additional arguments provided
• password (ps) = The keystore file encryption password, if a folder was provided the password will be used for all keystore files in the folder
• operator-ids (oids) = Comma-separated list of operator IDs. The amount must be 3f+1 compatible
• operator-keys (oks) = Comma-separated list of operator keys (same sequence as operator ids). The amount must be 3f+1 compatible
• output-folder (of) = Target folder path to output the key shares file
• owner-address (oa) = The cluster owner address (in the SSV contract)
• owner-nonce (on) = The validator registration nonce of the account (owner address) within the SSV contract (increments after each validator registration), obtained using the ssv-scanner tool

# single file
pnpm run cli shares --keystore=keystore.json --password=test --operator-ids=1,2,3,4 --operator-keys=LS..,LS..,LS..,LS.. --output-folder=./ --owner-address=... --owner-nonce=..

# folder with multiple keystore files
pnpm run cli shares --keystore=./keystore-files --password=test --operator-ids=1,2,3,4 --operator-keys=LS..,LS..,LS..,LS.. --output-folder=./ --owner-address=... --owner-nonce=..

Output: Name will start with keyshares-timestamp.json

Option 3: Integration in your projects

Node Project

To run an example of a Node.js project containing all the code snippets to build the share and transaction payload, simply follow these instructions!

cd examples/console
pnpm install

To run a JavaScript example:

# example 1
pnpm run start:basic:js
# example 2
pnpm run start:complex:js

To run a TypeScript example:

pnpm run start:ts

Open the developer console to see how it works in a browser environment.

Development

Run the CLI as a TypeScript executable:

pnpm run dev:cli ...

Run the CLI as a JavaScript compiled executable:

pnpm run cli ...

Lint

pnpm run lint

Building

pnpm run build

License

The ssv-api is licensed under the GNU General Public License v3.0, also included in our repository in the LICENSE file.