Warning

The SDK is a work in progress and is currently under audits. Breaking changes may occur in SDK updates as well as backward compatibility is not guaranteed. Use with caution.

Symbiotic Relay Smart Contracts

Overview

Symbiotic Relay is a peer-to-peer side-network designed to collect and aggregate signatures from validators, maintain validator sets on the settlement contract.

To achieve that, Symbiotic provides a set of predefined smart contracts, in general, representing the following modules:

• VotingPowerProvider - provides the basic data regarding operators, vaults and their voting power, it allows constructing various onboarding schemes such as:

  • OperatorsWhitelist - only whitelisted operators can register

  • OperatorsBlacklist - blacklisted operators are unregistered and are forbidden to return back

  • OperatorsJail - operators can be jailed for some amount of time and register back after that

  • SharedVaults - shared (with other networks) vaults (like the ones with NetworkRestakeDelegator) can be added

  • OperatorVaults - vaults that are attached to a single operator can be added

  • MultiToken - possible to add new supported tokens on the go

  • OpNetVaultAutoDeploy - enable auto-creation of the configured by you vault on each operator registration

  • VotingPowerCalculators - there are several stake-to-votingPower conversion mechanisms you can use separately or combine:

    • EqualStakeVPCalc - voting power is equal to stake
    • NormalizedTokenDecimalsVPCalc - all tokens' decimals are normalized to 18
    • PricedTokensChainlinkVPCalc - voting power is calculated using Chainlink price feeds
    • WeightedTokensVPCalc - voting power is affected by configured weights for tokens
    • WeightedVaultsVPCalc - voting power is affected by configured weights for vaults

  • Also, there are ready bindings for slashing and rewards

• KeyRegistry - verifies and manages operators' keys; currently, these key types are supported:

  • BlsBn254 (signature verification)
  • EcdsaSecp256k1 (signature verification)

• ValSetDriver - is used by the off-chain part of the Symbiotic Relay for validator set deriving and maintenance

• Settlement - requires a compressed validator set (header) to be committed each epoch, but allows verifying signatures made by the validator set; currently, it supports the following verification mechanics:

  • SimpleVerifier - requires the whole validator set to be inputted on the verification, but in a compressed and efficient way, so that it is the best choice to use up to around 125 validators
  • ZKVerifier - uses ZK verification made with gnark, allowing larger validator sets with an almost constant verification gas cost

Examples

Can be found here.

Usage

Dependencies

• Git (installation)
• Foundry (installation)

Prerequisites

Clone the repository

git clone --recurse-submodules https://github.com/symbioticfi/relay-contracts.git

Deploy Your Relay

The deployment tooling can be found at script/ folder. It consists of RelayDeploy.sol Foundry script template relay-deploy.sh bash script (the Relay smart contracts use external libraries for their implementations, so that it's not currently possible to use solely Foundry script for multi-chain deployment).

• RelayDeploy.sol - abstract base that wires common Symbiotic core helpers and exposes the four deployment hooks: KeyRegistry, VotingPowerProvider, Settlement, and ValVetDriver
• relay-deploy.sh - orchestrates per-contract multi-chain deployments (uses Python inside to parse toml file)

The script deploys Relay modules under OZ's TransparentUpgradeableProxy using CreateX (it provides better control for production deployments and more simplified approaches for development).

Dependencies

• Python (installation)

Deployment

1. Implement your MyRelayDeploy.sol (see example) - this Foundry script should include the deployment configuration of your Relay modules

   • you need to implement all virtual functions of RelayDeploy.sol
   • in constructor, need to input the path of the toml file
   • you are provided with additional helpers such as getCore(), getKeyRegistry(), getVotingPowerProvider(), etc. (see full list in RelayDeploy.sol)

2. Implement your my-relay-deploy.toml (see example) - this configuration file should include RPC URLs that will be needed for the deployment, and which modules should be deployed on which chains

   • do not replace [1234567890] placeholder with endpoint_url = ""
   • the contracts are deployed in such order:
     1. KeyRegistry
     2. VotingPowerProvider
     3. Settlement
     4. ValSetDriver

3. Execute the deployment script, e.g.:

   ./script/relay-deploy.sh ./script/examples/MyRelayDeploy.sol ./script/examples/my-relay-deploy.toml --broadcast --ledger

   Basic form is ./script/relay-deploy.sh <FoundryScript> <TomlConfig> <Any Foundry Flags>

At the end, your toml file will contain the addresses of the deployed Relay modules.

Build, Test, and Format

forge build
forge test
forge fmt

Configure environment

Create .env based on the template:

ETH_RPC_URL=
ETHERSCAN_API_KEY=

Security

Security audits can be found here.