Handbook for Operators

Context

This document outlines the steps for operators to integrate with Symbiotic using a middleware contract as an example. We'll walk through registering as an operator and connecting to our example network via middleware. The middleware contract acts as a bridge between Symbiotic core and the network chain, handling operator registration and stake management in a standardized way.

The Symbiotic ecosystem comprises two main components: on-chain Symbiotic core contracts and a network middleware contract. Here's how they interact:

• Symbiotic core contracts manage fundamental operations such as stake accounting, slashing, and delegations.
• Operators register in the OperatorRegistry and opt into vaults and networks to participate.
• Vault managers allocate stakes to operators in supported networks using various delegation models.
• The network middleware contract acts as a bridge between Symbiotic core and the network chain:
  • It retrieves the operator set with stakes from Symbiotic core contracts.
  • The middleware selects operators, specifies their keys, and determines which vaults to use for stake information.
  • The middleware contract also handles slashing by coordinating between the network and Symbiotic core when operators need to be penalized

For more information on how networks function within Symbiotic, please consult our networks-specific documentation.

Integration Guide

🌟 Introduction

Symbiotic is a shared security protocol that serves as a thin coordination layer, empowering network builders to control and adapt their own (re)staking implementation in a permissionless manner. It provides flexible (re)staking infrastructure for networks, operators, and stakers.

Our ecosystem allows anyone to build their ideal staking/restaking model using:

• Ready-to-go open-source components
• Custom modules compatible with Symbiotic Core

note

Symbiotic Core standardizes crucial elements of (re)staking such as stake accounting, slashing, and delegations.

This guide will walk you through how a network operates within the Symbiotic ecosystem and outline the integration requirements. We’ll use our test network (SelfRegisterSqrtTaskMiddleware), deployed on devnet, as an example.

Network Overview

The SelfRegisterSqrtTaskMiddleware is a simple example network that demonstrates the core functionality of Symbiotic's middleware layer. It implements a basic task where operators must calculate and submit square roots of given numbers. This network serves as a reference implementation and testing ground for operators to understand how network middleware contracts function within the Symbiotic ecosystem.

Key features of the SelfRegisterSqrtTaskMiddleware include:

• Self-registration capability for operators
• Basic task distribution system
• Simple validation of operator submissions
• Integration with Symbiotic's core staking and slashing mechanisms

Actions in Symbiotic Core

To become an operator in Symbiotic, you must register in the OperatorRegistry. This is the first step in joining any network. To become a validator, you need to take two additional steps: opt in to the network and opt in to the relevant vaults where the network has connections and stake. Once these steps are completed, vault owners can allocate stake to operators, but only up to the network’s predetermined stake limit.

info

We suggest using operator-specific vaults or LRT vaults for your operator for convenient stake delegation.

Through Etherscan

1. Register in the OperatorRegistry contract using the registerOperator() function. Verify your registration by calling isEntity(operator).
2. Opt in to the example SelfRegisterSqrtTaskMiddleware network via this contract:
   • optIn(0x18586B8cb86b59EF3F44BC915Ef92C83B6BAfd75)
   • verify opt-in by calling isOptedIn(operator, vault/network) using the contract above

Through CLI

1. Install the CLI, see options
2. Register operator in Symbiotic

python symb.py --chain holesky register-operator --private-key YOUR_OPERATOR_PRIVATE_KEY

3. Opt in to the example SelfRegisterSqrtTaskMiddleware network

python symb.py --chain holesky opt-in-network NETWORK_ADDRESS --private-key YOUR_OPERATOR_PRIVATE_KEY

4. (Optional) Opt in to the vault

python symb.py --chain holesky opt-in-vault VAULT_ADDRESS --private-key YOUR_OPERATOR_PRIVATE_KEY

note

For this section, you’ll need an Ethereum EOA (Externally Owned Account) or a smart contract. If using an EOA, simply connect any wallet to Holešky Etherscan and call the required functions.

Actions in SelfRegisterSqrtTaskMiddleware

The network middleware contract is a crucial component in the Symbiotic ecosystem, serving as the interface between Symbiotic core contracts and the network.

For Operators

1. Clone the middleware repository

git clone https://github.com/symbioticfi/middleware-sdk.git

2. Navigate to the worker directory

cd middleware-sdk/src/examples/sqrt-task-network/worker/

3. Install dependencies

pip install -r requirements.txt

4. Register the operator in middleware

python worker.py register --validator-private-key YOUR_VALIDATOR_PRIVATE_KEY \
    --operator-private-key YOUR_OPERATOR_PRIVATE_KEY \
    --vault-address YOUR_VAULT_ADDRESS

note

Replace YOUR_VALIDATOR_PRIVATE_KEY and YOUR_OPERATOR_PRIVATE_KEY with your actual private keys. These keys can be the same. The vault address can be zero address or it must be an operator-specific vault address. See details in Creating Own Vaults for Operator-Specific Delegations

5. Build worker docker image

docker build -t sqrt-worker .

6. Run worker docker image

docker run -e VALIDATOR_PRIVATE_KEY=your_private_key -e sqrt-worker

For Curators

For curators managing vaults in the SelfRegisterSqrtTaskMiddleware network, there are two main approaches:

1. Operator-Specific Vaults: These can be registered permissionlessly and are recommended for testing. Deploy your own vault following the vault deployment guide below.

2. Shared Vaults: These require registration by the network owner. If you're using a common shared vault, please contact the team through our community channels to have your vault registered.

note

To test slashing mechanisms, you'll need to ensure proper stake allocation limits are set for both the network and operator.

• Register vaults in middleware
• Allocate stake to the operator and the network
• Register operator in middleware
• Create a task for operator to submit
• Submit the task

  python worker.py --validator-private-key YOUR_VALIDATOR_PRIVATE_KEY --task-id TASK_ID

Creating Own Vaults for Operator-Specific Delegations

Operators have the flexibility to create their own vaults with customized configurations, which is particularly interesting for operators that seek to exclusively receive delegations or put their own funds at stake. This approach offers several advantages:

• Control: Operators maintain full control over stake allocation and delegation strategies.
• Customization: Vaults can be tailored to specific network requirements and operator strategies, including e.g. institutional compliance constraints.
• Efficiency: By using only their own validators, operators can streamline operations and potentially increase returns.
• Brand Building: Custom vaults allow operators to create unique offerings, differentiating themselves in the market.
• Risk Mitigation: By using their own validators exclusively, operators can eliminate the risk of potential bad actors or underperforming nodes from other operators.

When creating their own vault, operators can configure parameters such as delegation models, slashing mechanisms, and stake limits to best suit their operational needs and risk management strategies. This approach ensures that the vault is free from the risks associated with other operators, providing a more secure and controlled environment, especially useful for institutional stakers. For details on creating and configuring your own vault with custom parameters like delegation models, slashing mechanisms and stake limits, please see our vault deployment guide.

info

📢 For more information about vaults and how to set them up, please refer to our vaults-specific documentation.

info

Creating your own vault is not a necessary step for integrating with our example network.

Operator Onboarding Checklist

Briefly, let’s describe how the operator’s connection works.

Suppose the operator wants to work on network X using stake from vault Y.

The actions are as follows:

• Register operator with OperatorRegistry, check by:

  python3 symb.py --chain holesky isop OPERATOR_ADDRESS

• Opt-in operator to vault Y using VaultOptInService, check by:

  python3 symb.py --chain holesky check-opt-in-vault OPERATOR_ADDRESS VAULT_ADDRESS

• Opt-in operator to X network using NetworkOptInService, check by:

  python3 symb.py --chain holesky check-opt-in-network OPERATOR_ADDRESS NETWORK_ADDRESS

• Register operator with X Middleware contract (if X Middleware requires local registration), check transaction status in etherscan. If transaction is successful, operator is registered.

• Have vault Y manager allocate stake to operator (assistance required here), check by:

  python3 symb.py --chain holesky op-vault-net-stake OPERATOR_ADDRESS VAULT_ADDRESS NETWORK_ADDRESS

• Start interacting with the X Middleware contract

info

Our CLI can be used to interact with the Symbiotic protocol.

info

Operators can sign up for the mailing list/community here