Symbiotic Operators Guide

Overview

This guide explains how operators can integrate with Byzantine's Symbiotic vaults. Operators are entities running infrastructure for decentralized networks within the Symbiotic ecosystem.

Prerequisites

• An Ethereum account (EOA) or smart contract (e.g multisig) that will act as the operator

• Understanding of the following Symbiotic contracts:

  • OperatorRegistry

  • NetworkOptInService

  • VaultOptInService

Contract	Holesky Address	Mainnet Address
OperatorRegistry	0x6F75a4ffF97326A00e52662d82EA4FdE86a2C548	0xAd817a6Bc954F678451A71363f04150FDD81Af9F
NetworkOptInService	0x58973d16FFA900D11fC22e5e2B6840d9f7e13401	0x7133415b33B438843D581013f98A08704316633c
VaultOptInService	0x95CC0a052ae33941877c9619835A233D21D57351	0xb361894bC06cbBA7Ea8098BF0e32EB1906A5F891

Integration Flow

Integration Steps

Installation

Byzantine SDK

System Requirements

• Node.js (v14 or higher)

• npm or yarn

• TypeScript (optional but recommended)

Installation Steps

1. Install the SDK

npm install @byzantine/operator-sdk

1. Create Environment File Create a .env file in your project root:

RPC_URL=https://holesky.infura.io/v3/your_api_key_here

# Choose ONE of the following authentication methods:
MNEMONIC=your_wallet_mnemonic
# OR
PRIVATE_KEY=your_wallet_private_key_without_0x_prefix

DEFAULT_CHAIN_ID=17000  # 17000 for Holesky testnet, 1 for Ethereum Mainnet, 560048 for Hoodi Testnet

1. Basic Setup

import { ByzOperatorClient } from "@byzantine/operator-sdk";
import { ethers } from "ethers";
import * as dotenv from "dotenv";

dotenv.config();

const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
const wallet = ethers.Wallet.fromPhrase(process.env.MNEMONIC).connect(provider);
// OR const wallet = new ethers.Wallet(process.env.PRIVATE_KEY).connect(provider);

const client = new ByzOperatorClient({
  chainId: 17000, // 17000 for Holesky, 1 for Mainnet, 560048 for Hoodi
  provider: provider,
  signer: wallet,
});

Symbiotic CLI

System Requirements

• Git

• Python ≥ 3.8x

• pip (Python package manager)

Installation Steps

1. Clone the Repository

git clone https://github.com/symbioticfi/cli.git
cd cli

1. Install Dependencies

pip3 install -r requirements.txt

1. Verify Installation

python3 symb.py --help

Using the CLI

CLI Command Structure

python3 symb.py <general-options> <command> <args> <options>

Where:

• <general-options>: General options like chain selection

  • --chain <CHAIN_ID>: Choose chain (holesky | sepolia)

  • --provider <HTTPS_PROVIDER>: Custom RPC URL

• <command>: The method to call

• <args>: Input values for the command

• <options>: Additional options like --ledger or --private-key

The CLI can be used with either a private key or a Ledger device:

Using Private Key

Add --private-key YOUR_PRIVATE_KEY to any command:

python3 symb.py register-operator --private-key YOUR_PRIVATE_KEY

Using Ledger

Add --ledger to any command:

python3 symb.py register-operator --ledger

Optional: Specify a Ledger address with --ledger-address:

python3 symb.py register-operator --ledger --ledger-address YOUR_LEDGER_ADDRESS

Ledger Setup Requirements

• Ledger Live installed

• Blind Signing enabled on your Ledger device for the Ethereum app

• Ethereum app open and device unlocked before transactions

1. Registration

First, operators must register themselves in the Symbiotic ecosystem:

// Call on OperatorRegistry contract
function registerOperator() external;

Byzantine SDK

import { ByzOperatorClient } from "@byzantine/operator-sdk";
import { ethers } from "ethers";
import * as dotenv from "dotenv";

dotenv.config();

// Initialize provider and wallet
const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
const wallet = ethers.Wallet.fromPhrase(process.env.MNEMONIC).connect(provider);
// OR const wallet = new ethers.Wallet(process.env.PRIVATE_KEY).connect(provider);

// Initialize client
const client = new ByzOperatorClient({
  chainId: 17000, // 17000 for Holesky, 1 for Mainnet, 560048 for Hoodi
  provider: provider,
  signer: wallet,
});

// Register as operator
const tx = await client.registerOperator();
const receipt = await tx.wait();

Symbiotic CLI

# Register as an operator
python3 symb.py register-operator --private-key YOUR_PRIVATE_KEY
# or using Ledger
python3 symb.py register-operator --ledger

2. Network Opt-In

Operators must opt into specific networks they want to validate:

// Call on NetworkOptInService contract
function optIn(address network) external;

Byzantine SDK

// Opt into network
const tx = await client.optInNetwork(NETWORK_ADDRESS);
const receipt = await tx.wait();

// Check if opted in
const isOptedIn = await client.isOptedInNetwork(
  operatorAddress,
  networkAddress
);

Symbiotic CLI

# Opt-in to a network
python3 symb.py opt-in-network NETWORK_ADDRESS --private-key YOUR_PRIVATE_KEY

# Get signature for opt-in (for delegated opt-ins)
python3 symb.py opt-in-network-signature NETWORK_ADDRESS DURATION

# Check if already opted in
python3 symb.py check-opt-in-network OPERATOR_ADDRESS NETWORK_ADDRESS

3. Vault Opt-In

Operators must opt into vaults they want to receive stake from:

// Call on VaultOptInService contract
function optIn(address vault) external;

Byzantine SDK

// Opt into vault
const tx = await client.optInVault(VAULT_ADDRESS);
const receipt = await tx.wait();

// Check if opted in
const isOptedIn = await client.isOptedInVault(operatorAddress, vaultAddress);

Symbiotic CLI

# Opt-in to a vault
python3 symb.py opt-in-vault VAULT_ADDRESS --private-key YOUR_PRIVATE_KEY

# Get signature for opt-in (for delegated opt-ins)
python3 symb.py opt-in-vault-signature VAULT_ADDRESS DURATION

# Check if already opted in
python3 symb.py check-opt-in-vault OPERATOR_ADDRESS VAULT_ADDRESS

4. Stake Allocation (done by Vault's curator)

After opting in, the vault's OPERATOR_NETWORK_LIMIT_SET_ROLE can allocate stake to the operator through the vault's Delegator module:

// Call on FullRestakeDelegator contract
function setOperatorNetworkLimit(bytes32 subnetwork, address operator, uint256 limit) external;
// Call on NetworkRestakeDelegator contract
function setOperatorNetworkShares(bytes32 subnetwork, address operator, uint256 shares) external;
// Automatically delegate 100% of vault's stake at initialization for:
//    - OperatorSpecificDelegator
//    - OperatorNetworkSpecificDelegator

5. Network Activation (done by the NetworkMiddleware contract)

For a stake to become fully active and start earning rewards, the Network administrators perform due diligence on the Vault and decide whether to opt in. Once the Network opts in, the Vault’s stake becomes subject to slashing and stakers, curators, and operators begin earning rewards.

// Call on BaseDelegator contract
function setMaxNetworkLimit(uint96 identifier, uint256 amount) external;

6. Run the node

Now that you’ve fully opted in to every entity (networks and vaults), and once you’ve received delegation from the vault curator to specific networks, you’re actually ready to run nodes for these networks and start earning rewards.

Each network has its own requirements and setup process. That means you’ll need to follow their official documentation to properly run the node and make sure everything is correctly configured.

To make things easier, we’ve compiled a table on the next page listing each supported network and their respective operator documentation:

👉 Click here to access the full list of network node setup guides

Important Notes

1. Activation Timing:

   • Operator to Network Opt-In: The operator becomes eligible for the network immediately after completing the network opt-in process. The Symbiotic network doesn't have to opt-in to the operator: a network's operator set is permissionless.

   • Operator to Vault Opt-In: The operator becomes eligible for the vault only after the vault's curator (OPERATOR_NETWORK_LIMIT_SET_ROLE holder) explicitly delegates stake to the operator (see stake allocation).

   The operator's stake becomes active and subject to slashing only after the Network opts-in to the vault.

2. Slashing: Slashing is handled by the vault's Slasher module and can occur in two ways:

   • Instant slashing

   • Veto-enabled slashing (with resolver capability)

3. Metadata: Operators can attach additional credentials and metadata to their entity through the MetadataService.

4. You can view a detailed breakdown, including diagrams, of how each entity (Operator, Network, Curator) fits into the opt-in flow based on the type of Delegator. 👉 See the full opt-in flow in the Symbiotic Operators Guide

Restaking operator best practises

Operators should monitor:

• Networks they've opted into

• Associated vaults and restaked collateral

• Historical logs of slashings

• All interactions with the Symbiotic ecosystem