Introduction

A Curator is responsible for managing a Vault and its delegation strategy, distributing users' stake across different L1s while balancing risk and rewards. They play a crucial role in determining how pooled stake is allocated and managed.

Contracts handled by the Curator

Suzaku Vaults

Pool Collateral deposited by stakers to secure Avalanche-based L1s. They convert deposited Collateral into ERC20-like Vault shares representing each user's stake. A Vault serves for the Curator to setup at deployment the deposit and withdrawal rules, Vault epochs that influence withdrawal times, and for the Curator to actively manage where stake is delegated by operators and Avalanche L1s through the Delegator contract.

The VaultTokenized.sol contract implements several key features: it uses checkpointing libraries (such as Checkpoints.Trace256) to maintain historical records of active stake and share balances; integrates ERC20 functionality through standard functions such as balanceOf and totalSupply to represent Vault shares; enforces role-based access control for managing deposit whitelists and limits; handles epoch durations while tracking deposits and withdrawals to synchronize with reward cycles; and provides interoperability through functions such as setDelegator to configure associated Delegator and Slasher contracts.

Delegator Contract

The Delegator contract serves as a crucial component in managing and distributing pooled stake from Vaults across multiple L1 networks and operators. Its primary purpose is to determine how Vault Collateral is allocated to validators by calculating effective stake per operator, ensuring optimal distribution of resources.

The contract implementation consists of two main components: BaseDelegator.sol and L1RestakeDelegator.sol. The base contract provides core functionality that is extended by specific implementations. It employs a checkpointing mechanism to maintain historical records of operator shares, L1 limits, and total delegated stake. The contract implements key functions such as setL1Limit and setOperatorL1Shares to manage delegation parameters, while computing effective stake based on current Vault active stake, L1 limits, and operator share ratios. Integration with opt-in services (such as OperatorVaultOptInService) and registries ensures proper verification of operators and L1s available. Security is maintained through role-based permissions.

Permissionless contracts Curator contract interacts with

Vault Factory

This contract is responsible for deploying new Vaults and managing their lifecycle. It ensures that only approved implementations are used and maintains a registry of all Vault entities.

Delegator Factory

Implementations are whitelisted here. A new implementation contract—with, for example, new slashing logic or shares distribution logic—must be whitelisted in the official Delegator Factory before being used.

Operator-Vault Optin service

Actively used when a Vault registers to determine which operators it wants to work with. This service facilitates the permissionless opt-in of operators by Vaults.

Operator and L1 registries

• Operator Registry: A permissionless registry that records and manages eligible operator (validator) registrations.
• L1 Registry: A registry where Avalanche-based L1 networks opt in to be secured. It ensures that L1s meet the protocol requirements and can interact with Vaults and operators.

Third-Party Contracts (Entities, DAOs, etc) the Curator contracts interact with

L1 Middleware

Deployed for each Suzaku secured Avalanche-based L1 network, the L1 Middleware enforces staking rules, manages the whitelisting of Vaults and operators, and coordinates interactions with the underlying Avalanche Validator Manager (BalancerValidatorManager).

Vault Manager

This contract manages the registration of Vaults on the L1, sets maximum stake limits, and ensures Vaults comply with the network's operational parameters.

Integration Flow

A high-level checklist for integrating a new Vault into Suzaku:

1. Create & configure Your Vault
   • Deploy it with your chosen parameters:
     • Collateral: The ERC-20 token stakers deposit (must match L1 Collateral classes you plan to delegate to)
     • epoch duration: Time period (in seconds) for stake/withdrawal cycles
     • deposit limits: Optional cap on total stake
     • deposit whitelist: Optional restriction on who can deposit
     • admin roles: Addresses with permission to modify Vault settings
   • Attach a Delegator contract (via L1RestakeDelegator) that handles how your Vault's stake is allocated across operators and L1s.
2. Onboard L1s
   • Each L1 registers itself on Suzaku (via L1Registry) and optionally sets limits (such as the max stake for your Vault).
   • As Vault manager, you also configure how much stake you'll send to each L1 by calling setL1Limit(...).
3. Onboard operators
   • Operators must register on Suzaku, then opt in to your Vault and to each L1 they want to validate.
   • You allocate shares/limits per operator for the L1, setOperatorL1Shares(l1, collateralClassId, operator, shares).
4. Deposit stake
   • Stakers deposit Collateral in the Vault.
   • The Vault tracks epoch-based deposits/withdrawals and automatically routes stake to the L1s/operators you've configured.