# Nexus Network Design Document ## Purpose The purpose of this doc is to give a high-level overview of the system architecture and workings of different components. This acts as a guide for developers/enthusiasts to deep dive into the protocol design. This will also help other open-source contributors to understand how Nexus Network is tackling the native yield problem in a non-custodial decentralized manner. The document answers the following questions: 1. What changes are needed in rollup architecture? 2. How can we generate yield by staking using DVT? 3. How can we manage Node Operators? ## Rollups: ### What changes are needed in rollup architecture? For any rollup to enable native yield from eth by staking, they'll need to change their bridge contract where eth ends up while bridging. This is to ensure that the flow of ETH can happen from the Rollup Bridge contract to the Ethereum Deposit contract. Nexus Network onboards the rollup by following the below steps:

Rollup Registration

Onboarding on a new rollup involves a three-step process - 1. **Changes in the rollup bridge contract** - Rollup makes a few changes in the bridge contract that enable the transfer of ETH locked in the rollup to the validator deposit contract. The rollup also enables a few functions - * *depositValidator()* - The function is called to transfer ETH to a validator that is being activated for the rollup. Only Nexus Network contracts can call this function * *redeemRewards() -* This function is used by the rollup admin to claim the rewards earned by validators activated by the rollups ```solidity address constant DepositContract = address public constant DAO = address public NEXUS_NETWORK = uint256 constant VALIDATOR_DEPOSIT = 32 ether Rewards public stakingReturns function depositValidator(INexusInterface.Validator[] calldata _validators,uint256 stakingLimit,uint256 validatorCount) onlyNexus function redeemRewards() onlyDAO ``` 2. **Whitelist rollup address:** The whitelisting process ensures that a rollup registers with Nexus Network only using an admin address decided by the rollup team. This also creates a one-to-one mapping between rollup and rollup admin address. The whitelisting is done by the Nexus Network team ```solidity function whitelistRollup(string calldata name, address rollupAddress) onlyOwner ``` 3. **Register rollup:** Once the rollup bridge contract is set up and the rollup admin address is whitelisted, the admin address needs to call a *registerRollup()* function to start talking to the Nexus Network contracts. Once the rollup makes the transaction, a mapping for the rollup is created and stored with the Nexus Network. The mapping contains all the necessary information about the rollup including the address of the bridge contract, cluster to which ETH is staked, staking limit, etc ```solidity struct Rollup{ address bridgeContract; unit16 stakingLimit; uint32 operatorCluster; } mapping(address=>Rollup) public rollups; mapping(uint32=>uint32[]) public operatorClusters; function registerRollup(address bridgeContract,uint32 operatorCluster,uint256 nexusFee,uint16 stakingLimit) external ``` ### How can we generate yield by staking using DVT? To generate yields from the bridged assets, one needs to stake the ETH with the validators. The process should be secure and decentralized so that the bridged assets are safe. To ensure this, Nexus Network uses [SSV](https://ssv.network/) DVT and DKG solution to ensure the keys are securely distributed and uptime is maintained. This also ensures that the key is never at a single place at any point in time. Nexus Network follows the below architecture to achieve the same: #### 1. Validator Creation and submission
Once a rollup has registered with Nexus Network, it sets a staking limit determining the maximum amount of ETH from the rollup that can get staked. Nexus Network runs an off-chain bot that examines the amount of ETH in the rollup bridge contract. It triggers a key creation event to the Nexus Network contracts if there are 32 ETH or more available to be staked based on the limit defined by the rollup. The following steps are involved in the validator creation flow once the key generation is triggered - 1. Nexus Network has a monitoring system that tracks the performance of validator clusters and accordingly allocates the incoming ETH to a cluster. Nexus contracts generate a validator key creation event and share it with the selected node operator cluster 2. Once the cluster reads the key creation event, it performs a Decentralised Key Generation (DKG) ceremony to generate a private key in a distributed manner 3. The key shares generated are sent to the Nexus contracts. Nexus contracts send the keyshares to the SSV network for activation after which they are distributed among the node operators who are a part of the cluster 4. The public key of the validator generated during the DKG event is shared with the Nexus Network contracts which calls the rollup to activate the validator by transferring 32 ETH to the validator 5. Once the ETH is transferred, the validator starts performing staking operations with the support of the node operators in the cluster #### 2. Reward Distribution
Rollup has multiple options for rewards. Currently, the bridge contract is set as the withdrawal address and it receives all the staking rewards. Nexus Network will run an off-chain bot that will periodically update the rewards in the bridge contract which can be claimed by the DAO contract whenever they want. The staking rewards are divided into two parts - * Rollup DAO gets 90% of the staking rewards. * Nexus Network gets 10% of the staking rewards as revenue. Nexus Network will cover the node operator fee, SSV network fee, and operational cost from this and the rest will be profit for Nexus Network #### 3. Validator Exits
Validator exits can be triggered on Nexus Network in two ways - 1. Voluntary exits: These are exits triggered by the rollup DAO to reduce the amount of ETH staked through Nexus Network 2. Involuntary exits: Involuntary validator exits are triggered by Nexus off-chain bots that continuously monitor the bridge contract address. This happens if the maximum staking limit for the rollup is triggered because of changes in the amount of ETH bridged to the rollup In both of the above cases, once the withdrawals are triggered, the Nexus contracts determine the number of validators to exit and use the node operator scoring mechanism to determine which validators must be exited. The details are then transferred to the node operators to exit the validator. Once the validator exit is confirmed by the node operators, the off-chain bots notify the Nexus contracts about the validators, and the subgraph is updated accordingly. Nexus Network runs an off-chain bot that checks for the receipt of funds from validator exits. Once the validator exit is complete and funds are received in the bridge contract from the consensus chain, the off-chain bot updates the details in the Nexus contracts. ### How can we manage Node Operators? Node operators perform two critical tasks for Nexus Network - 1. They participate in the DKG ceremony to generate keyshares for the validators in a decentralized way 2. They help in running validators **Operator Registration** * Any node operator registered with the SSV network can register on Nexus using its Operator ID, DKG IP address and name * Currently, only whitelisted operators can participate with Nexus Network. Nexus Network will work towards making the operator set more decentralised over time **Operator key generation**
Untitled
* Operators participate in the DKG ceremony for validator keyshares creation * Nexus Network submits the keyshares to the SSV network which distributes them to the operators **Operator performance** * Nexus Network team will create a node operator performance dashboard to publicly track the performance of participating operators * Each node operator will get an operator score that determines the number of keyshares allocated to the node operator ### Monitoring and Alerting Nexus Network will place the right monitoring and alerting checks in place to ensure continuous monitoring with public transparency The components crucial for the product are: 1. **Contracts:** All the events that are emitted should be caught and stored in a well-structured way. For this, Nexus Network is using an indexer and graph to analyze the events. Resources to be used are [The graph](https://thegraph.com/en/), [Subsquid](https://subsquid.io/), [Zettablock](https://www.zettablock.com/) Nexus Network will also set up scripts that will monitor all the transactions and raise an alert whenever they encounter a malicious or an out-of-bounds event. The guiding rules for setting the limits to be monitored will be figured out over time with the launch of testnet 2. **Off-chain bots:** Initially the bot operation will be centralized and over time Nexus Network will look for more decentralized solutions. At the start, proper alerting channels like Telegram, slack, and email notifications will be set up. As the technology matures and becomes more stable, Nexus Network will run the bots through zk-proofs or an optimistic system to make it more decentralized with easy metrics exporting and dashboarding features. 3. **Node Operator/ Validator:** Node operators are the backbone of any staking provider. Nexus Network will ensure that proper dashboards and alerting mechanisms are in place to handle any slashing events or catch them in the early stages to prevent them altogether --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://web3navigators.gitbook.io/product-docs/design-architecture/nexus-network-design-document.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.