|
1 | | -## Foundry |
| 1 | +# Lumino Contracts |
2 | 2 |
|
3 | | -**Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.** |
| 3 | +A blockchain-based staking and reward system for a decentralized network, built using the Foundry framework. |
4 | 4 |
|
5 | | -Foundry consists of: |
| 5 | +## Overview |
6 | 6 |
|
7 | | -- **Forge**: Ethereum testing framework (like Truffle, Hardhat and DappTools). |
8 | | -- **Cast**: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data. |
9 | | -- **Anvil**: Local Ethereum node, akin to Ganache, Hardhat Network. |
10 | | -- **Chisel**: Fast, utilitarian, and verbose solidity REPL. |
| 7 | +The Lumino Staking System is designed to manage staker participation, token staking, and state transitions in a decentralized network. Key features include: |
11 | 8 |
|
12 | | -## Documentation |
| 9 | +- Epoch-based system with state transitions |
| 10 | +- Staking mechanism for network participation |
| 11 | +- Unstaking process with lock periods |
| 12 | +- 2-phase Commit-Reveal for Jobs Verification and assignment |
| 13 | +- Token Incentives for stakers to act honestly |
| 14 | +- Role-based access control |
13 | 15 |
|
14 | | -https://book.getfoundry.sh/ |
| 16 | +## Lumino Protocol: Detailed Component and Flow Documentation |
15 | 17 |
|
16 | | -## Usage |
| 18 | +### Table of Contents |
17 | 19 |
|
18 | | -### Build |
| 20 | +- [Components](#components) |
| 21 | + - [StakeManager](#stakemanager) |
| 22 | + - [VoteManager](#votemanager) |
| 23 | + - [JobsManager](#jobsmanager) |
| 24 | + - [BlockManager](#blockmanager) |
| 25 | + - [StateManager](#statemanager) |
| 26 | + - [ACL (Access Control List)](#acl-access-control-list) |
| 27 | +- [System Flows](#2-system-flows) |
| 28 | + - [Staking Flow](#21-staking-flow) |
| 29 | + - [Job Creation and Execution Flow](#22-job-creation-and-execution-flow) |
| 30 | + - [Commit-Reveal Flow](#23-commit-reveal-flow) |
| 31 | + - [Block Proposal and Confirmation Flow](#24-block-proposal-and-confirmation-flow) |
| 32 | + - [Reward Distribution Flow](#25-reward-distribution-flow) |
| 33 | +- [Interactions Between Components](/INTERACTIONS.md) |
19 | 34 |
|
20 | | -```shell |
21 | | -$ forge build |
22 | | -``` |
| 35 | +## Components |
23 | 36 |
|
24 | | -### Test |
| 37 | +### StakeManager |
25 | 38 |
|
26 | | -```shell |
27 | | -$ forge test |
28 | | -``` |
| 39 | +The StakeManager is responsible for handling all staking-related operations in the Lumino Protocol. |
29 | 40 |
|
30 | | -### Format |
| 41 | +Key Functions: |
| 42 | +- `stake(uint32 _epoch, uint256 _amount, string memory _machineSpecInJSON)`: Allows users to stake tokens and become a staker in the system. |
| 43 | +- `unstake(uint32 _stakerId, uint256 _amount)`: Initiates the unstaking process for a staker. |
| 44 | +- `withdraw(uint32 _stakerId)`: Allows stakers to withdraw their unstaked tokens after the lock period. |
31 | 45 |
|
32 | | -```shell |
33 | | -$ forge fmt |
34 | | -``` |
| 46 | +State Variables: |
| 47 | +- `numStakers`: Total number of stakers in the system. |
| 48 | +- `stakers`: Mapping of staker IDs to Staker structs containing staker information. |
| 49 | +- `locks`: Mapping of staker addresses to Lock structs for unstaking information. |
35 | 50 |
|
36 | | -### Gas Snapshots |
| 51 | +### VoteManager |
37 | 52 |
|
38 | | -```shell |
39 | | -$ forge snapshot |
40 | | -``` |
| 53 | +The VoteManager handles the commit-reveal scheme for job result submission and verification. |
41 | 54 |
|
42 | | -### Anvil |
| 55 | +Key Functions: |
| 56 | +- `commit(uint32 epoch, bytes32 commitment)`: Allows stakers to commit their job results without revealing them. |
| 57 | +- `reveal(uint32 epoch, Structs.JobVerifier[] memory results, bytes memory signature)`: Allows stakers to reveal their previously committed results. |
43 | 58 |
|
44 | | -```shell |
45 | | -$ anvil |
46 | | -``` |
| 59 | +State Variables: |
| 60 | +- `commitments`: Mapping of staker IDs to Commitment structs containing commitment information. |
| 61 | +- `assignedJob`: Mapping of epoch and staker ID to assigned jobs and their results. |
| 62 | +- `salt`: A value used in the commit-reveal process to prevent result manipulation. |
47 | 63 |
|
48 | | -### Deploy |
| 64 | +### JobsManager |
49 | 65 |
|
50 | | -```shell |
51 | | -$ forge script script/Counter.s.sol:CounterScript --rpc-url <your_rpc_url> --private-key <your_private_key> |
52 | | -``` |
| 66 | +The JobsManager is responsible for creating, assigning, and managing the lifecycle of jobs in the system. |
53 | 67 |
|
54 | | -### Cast |
| 68 | +Key Functions: |
| 69 | +- `createJob(string memory _jobDetailsInJSON)`: Creates a new job in the system. |
| 70 | +- `updateJobStatus(uint256 _jobId, Status _newStatus)`: Updates the status of a job. |
| 71 | +- `getJobsForStaker(bytes32 _seed, uint32 _stakerId)`: Assigns jobs to a staker based on a seed. |
55 | 72 |
|
56 | | -```shell |
57 | | -$ cast <subcommand> |
58 | | -``` |
| 73 | +State Variables: |
| 74 | +- `jobs`: Mapping of job IDs to Job structs containing job information. |
| 75 | +- `jobStatus`: Mapping of job IDs to their current status. |
| 76 | +- `activeJobIds`: Array of currently active job IDs. |
| 77 | +- `jobIdCounter`: Counter for generating unique job IDs. |
59 | 78 |
|
60 | | -### Help |
| 79 | +### BlockManager |
61 | 80 |
|
62 | | -```shell |
63 | | -$ forge --help |
64 | | -$ anvil --help |
65 | | -$ cast --help |
66 | | -``` |
| 81 | +The BlockManager handles the proposal and confirmation of blocks, which represent the state transitions in the system. |
| 82 | + |
| 83 | +Key Functions: |
| 84 | +- `propose(uint32 epoch, uint256[] memory _jobIds)`: Allows stakers to propose a new block. |
| 85 | +- `confirmBlock(uint32 epoch)`: Confirms a proposed block for the given epoch. |
| 86 | + |
| 87 | +State Variables: |
| 88 | +- `proposedBlocks`: Mapping of epochs and block IDs to proposed Block structs. |
| 89 | +- `blocks`: Mapping of epochs to confirmed Block structs. |
| 90 | +- `sortedProposedBlockIds`: Mapping of epochs to arrays of proposed block IDs. |
| 91 | +- `numProposedBlocks`: Total number of proposed blocks in the current epoch. |
| 92 | + |
| 93 | +### StateManager |
| 94 | + |
| 95 | +The StateManager is responsible for managing the system's state and epoch transitions. |
| 96 | + |
| 97 | +Key Functions: |
| 98 | +- `getEpoch()`: Returns the current epoch number. |
| 99 | +- `getState(uint8 buffer)`: Returns the current state of the system (Commit, Reveal, Propose, or Buffer). |
| 100 | + |
| 101 | +Constants: |
| 102 | +- `EPOCH_LENGTH`: The duration of each epoch in seconds. |
| 103 | +- `NUM_STATES`: The number of states in each epoch. |
| 104 | + |
| 105 | +### ACL (Access Control List) |
| 106 | + |
| 107 | +The ACL contract manages roles and permissions within the system. |
| 108 | + |
| 109 | +Key Function: |
| 110 | +- `initialize(address initialAdmin)`: Sets up the initial admin role. |
| 111 | + |
| 112 | +## System Flows |
| 113 | + |
| 114 | +### Staking Flow |
| 115 | + |
| 116 | +1. User calls `stake()` on StakeManager with the desired amount and epoch. |
| 117 | +2. StakeManager checks if the user is a new staker or existing one. |
| 118 | +3. For new stakers, a new Staker struct is created and added to the `stakers` mapping. |
| 119 | +4. For existing stakers, their stake amount is updated. |
| 120 | +5. The staked amount is transferred from the user to the contract. |
| 121 | + |
| 122 | +### Creation and Execution Flow |
| 123 | + |
| 124 | +1. A user calls `createJob()` on JobsManager with job details. |
| 125 | +2. JobsManager creates a new Job struct and adds it to the `jobs` mapping. |
| 126 | +3. The job ID is added to `activeJobIds`. |
| 127 | +4. During the Commit state, stakers are assigned jobs using `getJobsForStaker()`. |
| 128 | +5. Stakers execute the assigned jobs off-chain. |
| 129 | + |
| 130 | +### Commit-Reveal Flow |
| 131 | + |
| 132 | +1. In the Commit state, stakers call `commit()` on VoteManager with a hash of their job results. |
| 133 | +2. VoteManager stores the commitment in the `commitments` mapping. |
| 134 | +3. In the Reveal state, stakers call `reveal()` on VoteManager with their actual results and a signature. |
| 135 | +4. VoteManager verifies the revealed results against the commitment and processes the results. |
| 136 | + |
| 137 | +### Block Proposal and Confirmation Flow |
| 138 | + |
| 139 | +1. In the Propose state, eligible stakers call `propose()` on BlockManager with job IDs for the epoch. |
| 140 | +2. BlockManager creates a new Block struct and adds it to `proposedBlocks`. |
| 141 | +3. At the start of the next epoch, `confirmBlock()` is called. |
| 142 | +4. BlockManager selects the winning block proposal and confirms it, updating the `blocks` mapping. |
| 143 | + |
| 144 | +### Reward Distribution Flow |
| 145 | + |
| 146 | +1. After block confirmation, the system calculates rewards based on correct job execution and block proposals. |
| 147 | +2. Rewards are added to the `stakerReward` field in the Staker struct. |
| 148 | +3. Stakers can claim their rewards when withdrawing their stake. |
| 149 | + |
| 150 | +## Interactions Between Components |
| 151 | + |
| 152 | +- StakeManager <-> VoteManager: VoteManager checks staker eligibility with StakeManager during commit and reveal. |
| 153 | +- StakeManager <-> BlockManager: BlockManager verifies staker eligibility for block proposals with StakeManager. |
| 154 | +- JobsManager <-> VoteManager: VoteManager retrieves active jobs from JobsManager for result processing. |
| 155 | +- BlockManager <-> VoteManager: BlockManager uses VoteManager to verify revealed results during block confirmation. |
| 156 | +- All Components <-> StateManager: All components use StateManager to check current epoch and state. |
| 157 | +- All Components <-> ACL: All components use ACL to verify permissions for sensitive operations. |
| 158 | + |
| 159 | +More on interactions can be found in [`Interactions`](/INTERACTIONS.md) |
0 commit comments