# @casimir/ethereum

Solidity contracts for decentralized staking on Ethereum

## 📝 Overview

State of the art [Ethereum staking provider platforms](https://ethereum.org/en/staking/#how-to-stake-your-eth) (solo staking, staking-as-a-service, Lido, RocketPool) either require a user to deposit a complete balance (32 ETH) or deposit funds to [inherently centralized liquid staking derivative](https://notes.ethereum.org/@djrtwo/risks-of-lsd) (LSD) protocols. In the latter, users might trust a 3rd party to select node operators (risking operator centralization), handle validator signing keys (risking ransom attacks), and manage stake balances (risking stuck or lost ETH). Alternatively, the Casimir manager lets stakers deposit any amount of ETH directly to high-performing Ethereum validators while taking an approach that minimizes counterparty risk for users and improves the decentralization of Ethereum staking:

- Validators duties are performed by openly registered (and collateralized) operators running distributed validator technology (DVT)
- Keys are trustlessly managed using zero-coordination distributed key generation (DKG)
- Automated actions (like compounding stake or handling a slash) are carried out by a decentralized oracle network (DON)

Casimir's first open staking manager uses the SSV DVT network, the RockX DKG CLI, and the Chainlink DON to provide trustless staking to all users. Additionally, Casimir will provide a contract factory for users to deploy their own staking managers using any compatible DVT, DKG, or DON implementation.

Casimir is working to solve some of the key issues facing Ethereum staking today, with the goal of:
1. Node Operator Independence: Leveraging DVT brings in multiple operators, minimizing and mitigating the risk of malicious actors. It also allows smaller and independent validators to participate as Ethereum Validating Node Operators.
2. Open Node Selection and Evaluation: Decentralized Node monitoring as well as an inuitive UI that allow users to see validator performance will help create a more mericratic Ethereum Node Operator selection.
3. Staked Ethereum Governance Participation: Unlike LSD holders, Casimir stakers hold and receive rewards in L1 ETH, allowing them to participate in governance and signal their support of core changes.
4. Reduction in Counterparty Risk: A tradeable derviative of someone's staked ETH introduces an inate risk to the users original stake. Failure of the third party or market conditions affecting the LSD could result in partial or total loss of the user's staked ETH. A non-custodial solution can help reduce this counterparty risk.

### Architecture

Casimir distributes user deposits to Ethereum validators operated by SSV. Validator keys are shared with zero-coordination distributed key generation. Chainlink nodes report from the Beacon chain and SSV to sync rewards, manage slashing, and automate validator creation and exiting.

graph LR

    subgraph Contracts
        B(Manager Contract)
        C(Beacon Deposit Contract)
        D(SSV Contract)
        G(PoR Contract)
        H(Functions Contract)
        I(Automation Contract)
    end

    A((User)) --> B

    B --> C
    B --> D

    C --> E1(Ethereum Validator 1)
    C --> E2(Ethereum Validator 2)

    subgraph Validator 1
        E1 --> F11(SSV Operator 1)
        E1 --> F12(SSV Operator 2)
        E1 --> F13(SSV Operator 3)
        E1 --> F14(SSV Operator 4)
    end
    
    subgraph Validator 2
        E2 --> F21(SSV Operator 5)
        E2 --> F22(SSV Operator 6)
        E2 --> F23(SSV Operator 7)
        E2 --> F24(SSV Operator 8)
    end

    G <--> I
    H <--> I
    I <--> B
    
    subgraph Chainlink
        J1(Chainlink Node 1)
        J2(Chainlink Node 2)
        J3(Chainlink Node 3)
        J4(Chainlink Node 4)
    end

    J1 --> G
    J2 --> G
    J3 --> G
    J4 --> G
    
    J1 --> H
    J2 --> H
    J3 --> H
    J4 --> H

    J1 --> I
    J2 --> I
    J3 --> I
    J4 --> I

### Contracts

Casimir deploys two internal contracts and interfaces with suite of vendor contracts from the Consensus Specs, Chainlink, OpenZeppelin, SSV, and Uniswap. All contract source code is located in the [./src](./src) directory. A Hardhat environment for development and deployment is configured in the [hardhat.config.ts](./hardhat.config.ts) file. The following contract scripts can be executed from the **monorepo root** directory:

- `npm run dev:ethereum` - Run a local Ethereum network and deploy contracts
- `npm run test:ethereum` - Run tests for the Ethereum contracts
- `npm run clean --workspace @casimir/ethereum` - Clean the Ethereum build directory
- `npm run build --workspace @casimir/ethereum` - Compile the Ethereum contracts

**Internal Contracts:**

Core internal contracts and interfaces are located in the [src](./src) directory.

| Contract | Description | Docs |
| --- | --- | --- |
| [CasimirManager](./src/CasimirManager.sol) | Manages stake distribution | [docs/index.md#casimirmanager](./docs/index.md#casimirmanager) |
| [CasimirAutomation](./src/CasimirAutomation.sol) | Automates event handling | [docs/index.md#casimirautomation](./docs/index.md#casimirautomation) |

**Vendor Contracts:**

Vendor contracts and interfaces are located in the [src/vendor](./src/vendor) directory.

| Contract | Description | Docs |
| --- | --- | --- |
| [DepositContract](./src/vendor/interfaces/IDepositContract.sol) | Accepts Beacon deposits | Todo |
| [Functions](./src/vendor/Functions.sol) | Provides a library for Chainlink functions | Todo |
| [FunctionsBillingRegistry](./src/vendor/interfaces/FunctionsBillingRegistryInterface.sol) | Manages Chainlink function billing | Todo |
| [FunctionsClient](./src/vendor/FunctionsClient.sol) | Executes Chainlink function requests | Todo |
| [FunctionsOracle](./src/vendor/interfaces/FunctionsOracleInterface.sol) | Handles Chainlink function requests | Todo |
| [KeeperRegistry](./src/vendor/interfaces/IKeeperRegistry.sol) | Manages Chainlink upkeeps | Todo |
| [SSVNetwork](./src/vendor/interfaces/ISSVNetwork.sol) | Connects distributed validators | Todo |
| [SSVToken](./src/vendor/interfaces/ISSVToken.sol) | Serves as operator utility token | Todo |
| [WETH](./src/vendor/interfaces/IWETH.sol) | Wraps ETH for swapping | Todo |

**Mock Contracts:**

Mock (development-only) contracts and interfaces are located in the [src/mock](./src/mock) directory.

### Distributed Key Generation

Casimir trustlessly distributes validator key shares to operators using the [rockx-dkg-cli](https://github.com/RockX-SG/rockx-dkg-cli). The DKG server is called via [Automated Chainlink Functions](https://docs.chain.link/chainlink-functions/tutorials/automate-functions/) to generate, reshare, and exit validators.

### Oracles

The contract loosely depends on two decentralized oracles. The first oracle provides a PoR feed aggregating the total of all Casimir validator balances on the Beacon chain. The second oracle automates checking balance changes, responds with relevant validator actions, and updates the contract only when necessary conditions are met (see [Chainlink PoR](https://docs.chain.link/data-feeds/proof-of-reserve) and [Chainlink Automation](https://docs.chain.link/chainlink-automation/introduction)). External requests are made using trust-minimized compute infrastructure (see [Chainlink Functions](https://docs.chain.link/chainlink-functions)).

### Research

Ongoing research includes two key areas:

1. Account Abstraction: Casimir leverages Account Abstraction to improve the user experience by automating validator contract creation as well as automating reward tracking and compounding stake, among other things. Additional research and development will seek to further the capabilities of Account Abstraction to improve the ease of withdrawals from Ethereum staking contracts in conjunction with ongoing EIPs designed to improve this process.

2. Distributed Key Generation: Initially deployed to create a distributed validator group, DKG will be further developed to help create and manage the staking smart contract for an improved self custody experience.

## 👥 Users

Users can deposit any amount of ETH to the manager contract. Their deposits are staked to validators run by SSV operators (see [Operators](./README.md#operators)). Rewards are auto-compounded into stake and users can withdraw their principal plus any earned proportion of new stake (or a partial amount of their choice) at any time.

### User Fees

The contract charges a small user fee for each deposit (and some amount TBD in reward distribution) to fund the contract's operations. The fee is a percentage of the amount deposited by a user or reward distibution.

**User Fee Calculation:**

1. $feePercent = fees_{LINK} + fees_{SSV}$

2. $ethAmount = depositAmount\times{\frac{100}{100 + feePercent}}$

3. $feeAmount = depositAmount - ethAmount$

*Where:*

- $fees_{LINK}$ is the LINK fee percentage, which is [**`getLINKFee()`**](./docs/index.md#getlinkfee) in the contract.
- $fees_{SSV}$ is the SSV fee percentage, which is [**`getSSVFee()`**](./docs/index.md#getssvfee) in the contract.
- $feePercent$ is the total fee percentage, which is the sum of the LINK and SSV fees.
- $depositAmount$ is the amount of ETH deposited.
- $ethAmount$ is the amount of ETH to be distributed into the contract.
- $feeAmount$ is the amount of ETH to be swapped for LINK and SSV to operate the contract.

### User Stake

The manager contract adjusts a user's stake based on the change in the total reward-to-stake distribution sum since their last interaction with the contract. Each time new rewards are distributed (after either a heartbeat interval or a threshold change is detected in the oracle), the distribution sum is updated and the new rewards are staked in an auto-compounding fashion.

**User Stake Calculation:**

1. Whenever a user deposits or updates their stake, their initial stake and the current distribution sum are recorded.
2. When rewards are distributed, the distribution sum is updated to include the new reward-to-stake ratio.
3. $userStake =userStake_0\times{\frac{distributionSum}{userDistributionSum_0}}$ calculates a user's current compounded stake at any time.

*Where:*

- $userStake$ is the calculated current stake of the user, including compounded rewards. This is [**`users[userAddress].stake`**](./docs/index.md#user) in the contract.
- $userStake_0$ is the initial stake of the user at the time of their last deposit or stake update. This is also [**`users[userAddress].stake`**](./docs/index.md#user) in the contract, but it is accessed before settling the user's current stake.
- $distributionSum$ is the current cumulative sum of reward-to-stake ratios in the contract. This is [**`distributionSum`**](./docs/index.md#distributionsum) in the contract.
- $userDistributionSum_0$ is the cumulative sum of reward-to-stake ratios at the time the user made their last deposit or update to their stake. This is [**`users[userAddress].distributionSum0`**](./docs/index.md#user) in the contract.

### User Withdrawals

Users can initiate a withdrawal of any amount of their stake at any time. **Full exits and withdrawal liquidity are still a WIP.** In the meantime, valid user withdrawals up to the to total current `readyDeposits` will be fulfilled by the contract. Note, more notes are coming soon on withdrawal liquidity, alongside an additional contract.

## 👷 Operators

Each Casimir validator is run by four selected operators holding key share to perform duties with threshold signatures on SSV. Registration is open to any SSV operator (see [Operator Registration](./README.md#operatorregistration). Operators are selected by an algorithm that ensures high-performance but emphasizes decentralization (see [Operator Selection](./README.md#operatorselection)) as user's deposit stake and new validators are required.

### Operator Registration

Operators can join the contract registry with a small deposit of ETH for slashing collateral (see [Operator Collateral](./README.md#operatorcollateral)) and a lightweight SSV node config add-on (see [Operator Config](./README.md#operatorconfig)).

### Operator Selection

Operators are chosen to run validators based on metrics fetched and derived directly from the SSV network. These metrics are mainly performance, market share, and fees.

Operators are selected from our approved list. Operators who have registered, onboarded and deposited the minimal colateral are evaluted for approval at a regular frequency. Currently we evaluate operators on 24 and 30 day performance, operator fee rate and number of validators already staked with them. The exact funtion for selecting the operators is still TBD, but our goal will be to select a diverse group of high performing operators to optimize for both user rewards and preventing centralization of stake on only a few operators.

Operator performance is reported by (Chainlink) monitoring SSV exporter attestations. If an operator's performance is poor for an extended period of time, and their slashing collateral is below a threshold, Casimir removes the operator from existing operator groups by resharing or exiting. The latter is only required in the case that a validator has already undergone more than two reshares to avoid leaving the full key recoverable outside of the currently selected operators.

### Operator Collateral

Todo add notes.

### Operator Config

Operators will need to follow the [node onboarding process from RockX](https://github.com/RockX-SG/rockx-dkg-cli/blob/main/docs/dkg_node_installation_instructions.md) to participate in DKG make their node available to new validator selections. Todo add details.

## 👾Future Roadmap

Phase I: Initial Small Staker / Independent Distributed Validator deployment early Q3 2023. This will be a secure but simplified version of the broader vision designed to fully test basic functionality, build relaibility, and develop an early set of users.

Phase II: Full automated DKG ceremony. Further Account Abstraction Tooling. Validator onboarding Automation. Composable smart contract platform.

Phase III: Further Validator Tooling including MEV and blockbuilding to improve rewards and lower gas fees for users.

### Composability

Working towards:
Develop a decentralized accounting layer between depositors and validators (operators), automated and outside of deploying contract codes. Removes the need for trusted parties to manage key actions and allows others to deploy code via a "factory". Centralized LSDs/Exchanges do their own reporting and balance monitoring. This approach can help minimize attack vectors and vulnerability of a DAO.

DKG ceremony: fully automated - significantly reduces risk because it requires multiple operator keys. (to do: reshares, regens, exits)

Desired: EIP with smart contract validator exit functionality

This open source "factory" approach can allow anyone to bootstrap their own validator group, set fees, managed or otherise with minimal trust.