# Canary Meta Network Proposal

### Introduction:

The Canary Network is designed as a meta-network built on top of Symbiotic to enable faster and more efficient network development. This approach allows new networks to seamlessly integrate into Canary without having to implement the full range of Symbiotic features themselves. This document will explain how the Canary Network operates within the Symbiotic ecosystem, highlighting its key functionalities, including vaults, slashing mechanisms, subnetworks, and governance.

### Vault Contracts and Flexible Deposit Options

Canary Network implements vault contracts that accept a single ERC-20 token as collateral. When users deposit into a vault, they can choose from three predetermined withdrawal notice periods: 7 days, 30 days, or 90 days. Once a withdrawal is requested, users must wait for the specified notice period to retrieve their collateral. Importantly, rewards are distributed separately from the deposit and withdrawal process.

Each Canary vault is managed by a single operator (for now). The admin or operator can easily deposit funds into Symbiotic using the depositIntoSymbiotic function, which specifies the amount to be deposited. This process can be automated for vaults as long as the DC_Collateral contract is deployed on the Symbiotic side. The same process applies for withdrawals.

We assume that Canary will be the curator for the `NetworkRestakeDelegator` and will create its own symbiotic vaults, canary is built to be modular and hence the system design uses the underlying token as the main "ID" to connect Canary vaults with symbiotic vaults. This means that the only source of truth throughout the system is the underlying token address.

Sample Code for Deposits:

function depositIntoSymbiotic(uint256 amount) external {
     SymbioticDefaultCollateral symbioticVault_ = symbioticVault;
    IERC20 underlying_ = underlying;
    if (underlying_.balanceOf(address(this)) < amount) {
      revert InsufficientBalance();
    }
    if (address(symbioticVault_) == address(0)) {
      revert SymbioticVaultNotInitialised();
    }
    if (symbioticVault_.asset() != address(underlying_)) {
      revert WrongVault();
    }

    uint256 oldBalance = symbioticVault_.balanceOf(address(this));

    underlying_.safeApprove(address(symbioticVault_), amount);
    symbioticVault_.deposit(address(this), amount);

    assert(symbioticVault_.balanceOf(address(this)) == oldBalance + amount);
}

function requestWithdrawal(uint256 amount, uint256 noticePeriod) external {
    SymbioticDefaultCollateral symbioticVault_ = symbioticVault;
    if (address(symbioticVault_) == address(0)) {
      revert SymbioticVaultNotInitialised();
    }
    if (symbioticVault_.balanceOf(address(this)) < amount) {
      revert InsufficientBalance();
    }

    IERC20 underlying_ = underlying;
    uint256 oldUnderlyingBalance = underlying_.balanceOf(address(this));

    // Approve symbioticVault to spend the vault's shares
    symbioticVault_.safeApprove(address(symbioticVault_), amount);

    symbioticVault_.requestWithdraw(address(this), amount);

}

function claimWithdrawal(uint256 withdrawalId) external {
    // ......
}

In this way, Canary simplifies the management of collateral, making it easier for operators to handle deposits and withdrawals while maintaining flexibility for users with different time preferences.

### Middleware for Subnetworks and Slashing Management

Canary’s middleware architecture is designed to manage multiple subnetworks within the Canary Meta Network. Each subnetwork can define its own slashing rules by selecting from pre-determined templates. This simplifies network development, as developers do not need to implement custom slashing logic from scratch.

Canary handles the slashing process centrally. When certain slashing conditions are met (e.g., governance voting or a guardian veto), Canary issues slashing commands accordingly. This ensures consistency across subnetworks while still offering flexibility in how slashing is enforced.

Sample Code for Slashing:

function slashValidator(address validator, uint256 amount) external onlyAdmin {
    if (isSlashingConditionMet()) {
        slasher.slash(
            bytes32(bytes20(validator)),
            validator,
            amount,
            block.timestamp,
            new bytes(0)
        );
    }
}

This setup ensures that all subnetworks within Canary follow consistent slashing protocols. Canary’s middleware takes care of registering each subnetwork with Symbiotic and issuing the relevant slashing commands, streamlining network operations.

### Stake Management and Operator Control

Canary’s middleware allows operators to manage staking within Symbiotic vaults. Stake can be assigned using the setOperatorNetworkShares function within Symbiotic’s NetworkRestakeDelegator. This mechanism allows each subnetwork to have its own dedicated stake such that it can be slashed according to its own rules instead of the entire operator stake getting slashed.

Each Canary vault integrates with a corresponding Symbiotic vault, where all the stake is delegated to a single operator. The operator can run multiple subnetworks simultaneously, managing the stakes for each subnetwork individually. In the event that an operator for a subnetwork is slashed, only the stake associated with the misbehaving subnetwork will be affected, protecting the other subnetworks.

Sample Code for Stake Delegation:

function allocateStake(address operator, uint256 amount, uint32 domain) external {
    restakeDelegator.setOperatorNetworkShares(
        bytes32(bytes20(getNetwork(domain))),
        operator,
        amount
    );
}

This design allows for better isolation between subnetworks, ensuring that slashing one subnetwork does not affect others under the same operator.

### Governance and Dispute Resolution

Consider a simple scenario where the operator runs only one network and a dispute arises. Canary checks the configuration of the network’s app to determine if it is set to governance voting. If it is, Canary triggers a governance vote. Once the dispute is verified and the vote is completed, Canary’s contracts are called with the slashing amount. At this point, the underlying INSTANT_SLASHER is triggered to perform the slash.

By default, Symbiotic sends slashed tokens to a burner address. However, Canary allows flexibility here — rather than burning tokens, the slashed funds can be moved to a designated address where the project’s governance can decide how to use the tokens.

Sample Code for Governance Voting:

function resolveDispute(address validator, uint256 slashingAmount) external {
    if (isGovernanceVoteApproved(validator)) {
        slashValidator(validator, slashingAmount); // Slash the validator if governance approves
    }
}

function sendToGovernancePool(address token, uint256 amount) external {
    governancePool.receiveTokens(token, amount); // Send slashed tokens to governance-controlled pool
}

This flexible slashing mechanism allows each project to decide how to handle slashed tokens, providing greater autonomy to subnetworks within Canary.

### Slashing Templates

The slashing process begins with the creation of a dispute. For a dispute to move forward, it first needs to be validated. This validation can be performed in several ways, depending on how the protocol is configured:

* Smart Contract Verification: The protocol can rely on automated on-chain verification, where the dispute is validated by checking certain actions or states directly on the blockchain.
* Veto Verification: A trusted entity, such as the foundation or another designated party, can issue a veto to confirm that the dispute is valid. This introduces an off-chain human or organizational check into the process.
* Escrow or Staking Mechanism: The user initiating the dispute may be required to stake assets. If their dispute is found to be incorrect or invalid, they risk losing these assets. This ensures that users are incentivized to submit valid disputes.

Once the protocol determines that the dispute is valid through one of these methods, the dispute moves to the next stage—slashing. At this point, the Canary Meta Network offers several slashing options that developers can configure based on the network’s needs:

* Veto Slashing: A trusted entity, such as a foundation or guardian, can immediately execute the slashing through a veto mechanism.
* Governance Slashing: The network can trigger a decentralized vote, where participants decide whether slashing should be applied and how severe it should be.
* Guardian Slashing: A guardian, often represented by a multisig or a group of trusted actors, can collectively decide whether slashing is necessary.

After one of these methods (veto, governance, or guardian slashing) is finalized, the slashing decision is executed. This process invokes the instant slasher on the Symbiotic side, which handles the actual slashing of the staked funds. This design abstracts away the complexity of slashing, allowing the protocol to rely on a predetermined system that ensures disputes are handled fairly and efficiently.

By offering these configurable slashing options, Canary simplifies the slashing process for new networks while maintaining flexibility and security, allowing each network to choose the slashing method that best fits its governance model.

   function slash(
        address vault,
        uint32 domain,
        address validator,
        uint256 amount,
        uint48 timestamp
    ) external onlyOwner onlyAuthorized(vault) {
        bytes32 network = bytes32(bytes20(getNetwork(domain)));
        ISlasher(IVault(vault).slasher()).slash(
            network,
            validator,
            amount,
            timestamp,
            new bytes(0)
        );
    }

This slashing mechanism provides a decentralized and multi-step approach to enforcing network rules. It allows different actors (smart contracts, governance, veto powers) to participate in validating and resolving disputes while ensuring fairness and transparency. The severity of slashing is voted upon, ensuring the community’s consensus on handling malicious behavior.

Slashing in canary is multichain by default, this means a message will be sent via a messaging protocol to other chains to slash if the network is deployed to be multichain.

## Conclusion

Canary Meta Network offers a streamlined, modular system for building and managing networks on top of Symbiotic. By providing ready-to-use features like vaults, middleware, and slashing templates, Canary allows developers to focus on building their networks rather than worrying about the underlying infrastructure.

With flexible governance, dynamic stake delegation, and efficient slashing mechanisms, Canary ensures that networks can be created and operated securely, while still offering flexibility and autonomy to each subnetwork. This makes Canary a powerful tool for developers looking to integrate into the Symbiotic ecosystem quickly and efficiently.