Starknet Staking v2

Validator software written in Go for Starknet staking v2 as specified in SNIP 28

ℹ️ This README offers a basic overview of the Validator tool. For detailed instructions—such as running with Docker, configuring external signing, or setting up a metrics server—please refer to the official documentation.

Requirements

• A connection to a Starknet node or RPC endpoint with support for the JSON-RPC 0.8.0 API specification. For reliability reasons we recommend stakers to host their own nodes. See Juno and Pathfinder.
• An account with enough funds to pay for the attestation transactions.

Installation

The tool can be either built from source or pulled from docker. Aditionally we offer pre-compiles, check our release page.

Building from source

Requires having the latest GO compiler version. Once installed run:

make validator

This will compile the project and place the binary in ./build/validator.

Validator configuration and execution

To run the validator it needs certain data specified such as the Starknet node to connect to and the operational address of the staker. This data can be provided through several ways, in order of (decreasing) priority:

1. Command line flags,
2. Environment vars and
3. Configuration file.

With a configuration file

The validator can be run with:

./build/validator --config <path_to_config_file>

The config file is .json which specifies two main fields provider and signer. For the provider, it requires an http and websocket endpoints to a starknet node that supports rpc version 0.8.1 or higher. Those endpoints are used to listen information from the network.

For the signer, you need to specify the operational address and a signing method. The signing method can be either internal to the tool or asked externally, based on if you provide a private key or an external url:

1. By provding a private key the program will sign the transactions internally.
2. By providing an external url to program from which the validator will ask for signatures, see exactly how here.
3. If both are provided, the validator will use the remote signer over the internal one.

A full configuration file looks like this:

{
  "provider": {
      "http": "http://localhost:6060/v0_8",
      "ws": "ws://localhost:6061/v0_8"
  },
  "signer": {
      "url": "http://localhost:8080",
      "operationalAddress": "0x123",
      "privateKey": "0x456"
  }
}

Note that because both url and privateKey fields are set in the previous example the tool will prioritize remote signing through the url than internally signing with the privateKey. Be sure to be explicit on your configuration file and leave just one of them.

With Environment Variables

Alternatively, similarly as described as the previous section, the validator can be configured using environment vars. The following example using a .env file with the following content:

export PROVIDER_HTTP_URL="http://localhost:6060/v0_8"
export PROVIDER_WS_URL="ws://localhost:6061/v0_8"

export SIGNER_EXTERNAL_URL="http://localhost:8080"
export SIGNER_OPERATIONAL_ADDRESS="0x123"
export SIGNER_PRIVATE_KEY="0x456"

Source the enviroment vars and run the validator:

source path/to/env

./build/validator

With flags

Finally, as a third alternative, you can specify the necessary validation configuration through flags as well:

./build/validator \
    --provider-http "http://localhost:6060/v0_8" \
    --provider-ws "ws://localhost:6061/v0_8" \
    --signer-url "http://localhost:8080" \
    --signer-op-address "0x123" \
    --signer-priv-key "0x456"

Mixed configuration approach

Using a combination of both approaches is also valid. Values set by flags will override values set by enviroment flags and values set by enviroment flags will override values set in a configuration file.

PROVIDER_HTTP_URL="http://localhost:6060/v0_8" ./build/validator \
    --config <path_to_config_file> \
    --provider-ws "ws://localhost:6061/v0_8" \
    --signer-url "http//localhost:8080" \
    --signer-op-address "0x123" \
    --private-key "0x456"

Additional configurations

In addition to the configuration described above, the tool allows for other non-essential customization. You can see all available options by using the --help flag:

1. Using specific staking and attestation contract addresses through the --staking-contract-address and --attest-contract-address flags respectively. If no values are provided, sensible defaults are provided based on the network id (only Mainnet and Sepolia).

2. --max-tries allows you to set how many attempts the tool does to get attestation information. It can be set to any positive number or to infinite if you want the tool to never stop execution. It's set to infinite by default.

3. --balance-threshold represents the balance amount you want your signer account to be above of. Checks are performed after every attestation window ends and if the balance is below the specified amount a warning is emitted. Defaults to 100 STRK.

4. --log-level set's the tool logging level. Defaults to info.

5. --braavos-account changes the transaction version format from 0x3 to 1<<128 + 0x3 required by Braavos accounts.

Other features

We offer advance features such as external signing and monitoring via prometheus.

For further general details of the tool you can reference the official documentation.

Contact us

We are the team behind the Juno client. Please don't hesitate to contact us if you have questions or feedback:

• Telegram
• Discord
• X(Formerly Twitter)

License

Starknet Staking v2 is open-source software licensed under the Apache-2.0 License.