Symbiotic Operator Integration Guide for Byzantine Vaults
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:
Contract
Holesky Address
Mainnet Address
OperatorRegistry
NetworkOptInService
VaultOptInService
Integration Flow
Integration Steps
Installation
System Requirements
Node.js (v14 or higher)
npm or yarn
TypeScript (optional but recommended)
Installation Steps
Install the SDK
npm install @byzantine/operator-sdk
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
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,
});
System Requirements
Git
Python ≥ 3.8x
pip (Python package manager)
Installation Steps
Clone the Repository
git clone https://github.com/symbioticfi/cli.git
cd cli
Install Dependencies
pip3 install -r requirements.txt
Verify Installation
python3 symb.py --help
Using the CLI
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:
<options>: Additional options like --ledger or --private-key
1. Registration
First, operators must register themselves in the Symbiotic ecosystem:
// Call on OperatorRegistry contract
function registerOperator() external;
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();
# 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;
// 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
);
# 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;
// 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);
# 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;
Important Notes
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.
The operator's stake becomes active and subject to slashing only after the Network opts-in to the vault.
Slashing: Slashing is handled by the vault's Slasher module and can occur in two ways:
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
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 ).
(with resolver )
Metadata: Operators can attach additional credentials and metadata to their entity through the .