Skip to main content

Configuration

The Starknet Staking v2 validator can be configured using several methods, with the following order of precedence:

  1. Command line parameters
  2. Environment variables
  3. Configuration file
Protocol Context

For detailed information about validator roles, address types, and security practices in Starknet's staking protocol, see the official Starknet staking documentation.

Command Line Parameters​

The validator can be configured directly on the command line, e.g:

docker run nethermind/starknet-staking-v2 \
    --provider-http "http://localhost:6060/rpc/v0_10" \
    --provider-ws "ws://localhost:6061/ws/v0_10" \
    --signer-op-address "0x123" \
    --signer-url "http://localhost:8080"
tip

Command line parameters override environment variables and configuration file.

Environment Variables​

The validator can be configured through environment variables using specific variable names:

PROVIDER_HTTP_URL="http://localhost:6060/v0_10" \
PROVIDER_WS_URL="ws://localhost:6061/v0_10" \
SIGNER_OPERATIONAL_ADDRESS="0x123" \
SIGNER_PRIVATE_KEY="0x456" \
./build/validator

Using a .env File​

Create a .env file with your configuration:

.env
PROVIDER_HTTP_URL="http://localhost:6060/v0_10"
PROVIDER_WS_URL="ws://localhost:6061/v0_10"

SIGNER_OPERATIONAL_ADDRESS="0x123"
SIGNER_EXTERNAL_URL="http://localhost:8080"

Then source the environment variables and run the validator:

source .env
./build/validator

Docker with Environment Variables​

When using Docker, set environment variables using the -e option:

docker run \
  -e PROVIDER_HTTP_URL="http://host.docker.internal:6060/v0_10" \
  -e PROVIDER_WS_URL="ws://host.docker.internal:6061/v0_10" \
  -e SIGNER_OPERATIONAL_ADDRESS="0x123" \
  -e SIGNER_EXTERNAL_URL="http://host.docker.internal:8080" \
  nethermind/starknet-staking-v2

Or use an environment file:

docker run --env-file .env nethermind/starknet-staking-v2
tip

Environment variables rank second in configuration precedence. Command line parameters override environment variables.

Configuration File​

The validator can be configured using a JSON file:

Sample JSON File​

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

To run the validator with a configuration file, use the --config option:

# Standalone binary
./build/validator --config config.json

# Docker container
docker run \
  -v /path/to/config.json:/app/config/config.json \
  nethermind/starknet-staking-v2 --config /app/config/config.json
Signing Method Required

You must provide exactly one signing method: either privateKey for internal signing or url for external signing. If both are provided, the validator won't start.

Mixed Configuration​

You can combine multiple configuration methods. Values set by command line flags will override environment variables, and environment variables will override configuration file settings.

PROVIDER_HTTP_URL="http://localhost:6060/v0_10" ./build/validator \
    --config config.json \
    --provider-ws "ws://localhost:6061/v0_10" \
    --signer-url "http://localhost:8080" \
    --log-level debug

Signing Methods​

The validator supports two signing approaches:

Internal Signing​

  • Provide your private key directly to the validator
  • The validator signs transactions internally
  • ⚠️ Security Note: Only use this in secure environments

External Signing​

  • Provide a URL to an external signing service
  • The validator requests signatures from the external service
  • ✅ Recommended: For mainnet and cloud deployments
One Signing Method

Only one of privateKey and url can be set. Since the configuration sources are merged field by field, this also applies across sources: e.g. a url in the configuration file together with a --signer-priv-key flag is an error as well.

Auto-Claim Rewards​

Optionally, the validator can automatically claim the staking rewards once they reach a threshold. It is configured through the reward section of the configuration file, the REWARD_* environment variables or the --reward-* flags:

{
  "reward": {
    "address": "0x789",
    "privateKey": "0xabc",
    "claimThreshold": 100
  }
}

See Auto-Claim Rewards for how it works and all of its options.

What's Next?​