ssv-keys
Version:
CLI Tool for splitting a validator key into a predefined threshold of shares via Shamir-Secret-Sharing (SSS), and encrypt them with a set of operator keys.
162 lines (115 loc) • 5.33 kB
Markdown
# 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:
```bash
cd ~/Downloads
```
5. (Mac and Linux) Make sure that the executable has permissions to run by running:
```bash
chmod 777 ./ssv-keys-mac
```
6. Now you can run it:
```bash
./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](https://nodejs.org/en/download/).
Once you have installed Node.js, follow instructions:
```bash
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:
```bash
pnpm run cli --help
```
Help on a specific action:
```bash
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
```bash
# 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!
```bash
cd examples/console
pnpm install
```
To run a JavaScript example:
```bash
# example 1
pnpm run start:basic:js
# example 2
pnpm run start:complex:js
```
To run a TypeScript example:
```bash
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:
```bash
pnpm run dev:cli ...
```
### Run the CLI as a JavaScript compiled executable:
```bash
pnpm run cli ...
```
### Lint
```bash
pnpm run lint
```
### Building
```bash
pnpm run build
```
## License
The ssv-api is licensed under the
[GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.en.html),
also included in our repository in the `LICENSE` file.