Skip to content

Commit 61e8781

Browse files
ai-chen2050ai-chen2050
committed
docs: add test instruction documents
1 parent 7e49280 commit 61e8781

File tree

5 files changed

+957
-1
lines changed

5 files changed

+957
-1
lines changed

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ make build-validator
8080
### Running the Muti-Node
8181

8282
```bash
83-
chmod +x start.sh stop.sh
83+
chmod +x ./scripts/start.sh ./scripts/stop.sh
8484
```
8585

8686
- Usage examples:

‎contracts/.hardhat.config.js‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,10 @@ require("@nomicfoundation/hardhat-toolbox");
33
/** @type import('hardhat/config').HardhatUserConfig */
44
module.exports = {
55
solidity: "0.8.20",
6+
networks: {
7+
local: {
8+
url: "http://localhost:8545",
9+
accounts: ["**your private key**"],
10+
},
11+
},
612
};

‎tests/Checkpoints.md‎

Lines changed: 291 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,291 @@
1+
# Hetu Checkpoint Test Cases Documentation
2+
3+
## Overview
4+
5+
This document outlines test cases for the Hetu Checkpoint system, focusing on the Dispatcher and Validator components. These test cases are designed to verify the functionality, reliability, and security of the checkpoint mechanism.
6+
7+
## Prerequisites
8+
9+
Before running the tests, ensure you have the following:
10+
11+
1. Clone the repository:
12+
```
13+
git clone https://github.com/hetuproject/checkpoint.git
14+
```
15+
16+
2. Set up the required environment:
17+
- PostgreSQL database
18+
- Ethereum development network (local or testnet)
19+
- Hetu chain node (CometBFT node)
20+
21+
22+
3. Configure the test environment:
23+
- Update `dis_config.json` and `val_config.json` with appropriate test values
24+
- Deploy necessary contracts (CKPTValStaking and Staking Token)
25+
26+
## Dispatcher Test Cases
27+
28+
### 1. Initialization and Configuration
29+
30+
| Test ID | Test Name | Description | Expected Result |
31+
|---------|-----------|-------------|----------------|
32+
| DISP-001 | Basic Initialization | Start dispatcher with valid configuration | Dispatcher starts successfully and logs initialization |
33+
| DISP-002 | Database Connection | Verify database connection on startup | Connection established, tables created if not exist |
34+
| DISP-003 | Configuration Validation | Start with invalid configuration parameters | Clear error messages, graceful failure |
35+
| DISP-004 | Ethereum Connection | Verify connection to Ethereum RPC | Connection established, chain ID verified |
36+
| DISP-005 | Contract Connection | Verify connection to CKPTValStaking contract | Contract instance created successfully |
37+
38+
### 2. Validator Management
39+
40+
| Test ID | Test Name | Description | Expected Result |
41+
|---------|-----------|-------------|----------------|
42+
| DISP-101 | Validator Registration | Process incoming validator registration | Registration stored in database |
43+
| DISP-102 | Validator List Query | Query active validators from the chain | Correct validator set retrieved |
44+
| DISP-103 | Validator Connection | Handle validator TCP connections | Connections accepted and tracked |
45+
| DISP-104 | Validator Disconnection | Handle validator disconnection | Connection closed properly, state updated |
46+
| DISP-105 | Multiple Validators | Test with multiple validators connected | All connections maintained correctly |
47+
48+
### 3. Checkpoint Generation
49+
50+
| Test ID | Test Name | Description | Expected Result |
51+
|---------|-----------|-------------|----------------|
52+
| DISP-201 | Epoch Detection | Detect new epochs from blockchain | New epochs identified correctly |
53+
| DISP-202 | Checkpoint Creation | Create checkpoint for new epoch | Checkpoint created with correct data |
54+
| DISP-203 | Request Distribution | Distribute checkpoint requests to validators | Requests sent to all active validators |
55+
| DISP-204 | Timeout Handling | Handle validator response timeout | Timeout correctly identified and logged |
56+
| DISP-205 | Request Persistence | Store checkpoint requests in database | Requests stored correctly with status |
57+
58+
### 4. Signature Aggregation
59+
60+
| Test ID | Test Name | Description | Expected Result |
61+
|---------|-----------|-------------|----------------|
62+
| DISP-301 | Response Collection | Collect responses from validators | All valid responses collected |
63+
| DISP-302 | Signature Verification | Verify individual BLS signatures | Valid signatures accepted, invalid rejected |
64+
| DISP-303 | Threshold Verification | Check if enough validators responded | Threshold check works correctly |
65+
| DISP-304 | BLS Aggregation | Aggregate BLS signatures | Signatures aggregated correctly |
66+
| DISP-305 | Power Calculation | Calculate total voting power | Power calculated correctly based on validators |
67+
| DISP-306 | Bitmap Generation | Generate bitmap of participating validators | Bitmap correctly represents participants |
68+
69+
### 5. Checkpoint Reporting
70+
71+
| Test ID | Test Name | Description | Expected Result |
72+
|---------|-----------|-------------|----------------|
73+
| DISP-401 | Ethereum Transaction | Submit checkpoint to Ethereum | Transaction submitted successfully |
74+
| DISP-402 | Transaction Confirmation | Wait for transaction confirmation | Transaction confirmed, receipt stored |
75+
| DISP-403 | Retry Mechanism | Handle submission failure with retry | Retry works with backoff strategy |
76+
| DISP-404 | Gas Price Adjustment | Adjust gas price for transaction | Gas price adjusted according to network conditions |
77+
| DISP-405 | Report Persistence | Store reporting status in database | Reporting status stored correctly |
78+
79+
### 6. Reward Distribution
80+
81+
| Test ID | Test Name | Description | Expected Result |
82+
|---------|-----------|-------------|----------------|
83+
| DISP-501 | Distribution Triggering | Trigger distribution after interval | Distribution triggered after configured epochs |
84+
| DISP-502 | Contract Interaction | Call distributeCheckpointRewards | Function called with correct parameters |
85+
| DISP-503 | Distribution Status | Track distribution status | Status correctly tracked in database |
86+
| DISP-504 | Multiple Epoch Distribution | Distribute rewards for multiple epochs | All epochs processed correctly |
87+
| DISP-505 | Error Handling | Handle distribution errors | Errors logged, retries implemented |
88+
89+
### 7. API and Integration
90+
91+
| Test ID | Test Name | Description | Expected Result |
92+
|---------|-----------|-------------|----------------|
93+
| DISP-601 | HTTP API Availability | Check HTTP API endpoints | All endpoints accessible |
94+
| DISP-602 | Status Endpoint | Query status information | Correct status information returned |
95+
| DISP-603 | Metrics Collection | Collect performance metrics | Metrics collected and available |
96+
| DISP-604 | Chain Integration | Verify integration with Hetu chain | Chain data correctly processed |
97+
| DISP-605 | CometBFT Integration | Verify integration with CometBFT | Block data correctly retrieved |
98+
99+
## Validator Test Cases
100+
101+
### 1. Initialization and Configuration
102+
103+
| Test ID | Test Name | Description | Expected Result |
104+
|---------|-----------|-------------|----------------|
105+
| VAL-001 | Basic Initialization | Start validator with valid configuration | Validator starts successfully and logs initialization |
106+
| VAL-002 | Database Connection | Verify database connection on startup | Connection established, tables created if not exist |
107+
| VAL-003 | Configuration Validation | Start with invalid configuration parameters | Clear error messages, graceful failure |
108+
| VAL-004 | Dispatcher Connection | Connect to dispatcher TCP service | Connection established successfully |
109+
| VAL-005 | Key Loading | Load validator keys | Keys loaded correctly from storage |
110+
111+
### 2. Registration and Staking
112+
113+
| Test ID | Test Name | Description | Expected Result |
114+
|---------|-----------|-------------|----------------|
115+
| VAL-101 | Role Verification | Verify validator has required roles | Role verification works correctly |
116+
| VAL-102 | Validator Registration | Register as validator in the contract | Registration transaction successful |
117+
| VAL-103 | Token Approval | Approve tokens for staking | Approval transaction successful |
118+
| VAL-104 | Staking Process | Stake tokens in the contract | Staking transaction successful |
119+
| VAL-105 | Info Update | Update validator information | Update transaction successful |
120+
121+
### 3. Checkpoint Signing
122+
123+
| Test ID | Test Name | Description | Expected Result |
124+
|---------|-----------|-------------|----------------|
125+
| VAL-201 | Request Reception | Receive checkpoint request from dispatcher | Request received and parsed correctly |
126+
| VAL-202 | Checkpoint Validation | Validate checkpoint data | Validation logic works correctly |
127+
| VAL-203 | BLS Signature Generation | Generate BLS signature for checkpoint | Signature generated correctly |
128+
| VAL-204 | Response Sending | Send response to dispatcher | Response sent successfully |
129+
| VAL-205 | Request Persistence | Store request and response in database | Data stored correctly with status |
130+
131+
### 4. BLS Key Management
132+
133+
| Test ID | Test Name | Description | Expected Result |
134+
|---------|-----------|-------------|----------------|
135+
| VAL-301 | Key Generation | Generate new BLS key pair | Key pair generated with correct format |
136+
| VAL-302 | Key Storage | Store BLS keys securely | Keys stored with proper encryption |
137+
| VAL-303 | Key Recovery | Recover keys from storage | Keys recovered correctly |
138+
| VAL-304 | Key Rotation | Rotate BLS keys | Key rotation process works correctly |
139+
| VAL-305 | Key Registration | Register new BLS public key | Registration transaction successful |
140+
141+
### 5. Reward Management
142+
143+
| Test ID | Test Name | Description | Expected Result |
144+
|---------|-----------|-------------|----------------|
145+
| VAL-401 | Reward Calculation | Calculate expected rewards | Calculation matches contract implementation |
146+
| VAL-402 | Reward Claiming | Claim rewards from contract | Claim transaction successful |
147+
| VAL-403 | Reward Tracking | Track claimed rewards | Rewards tracked correctly in database |
148+
| VAL-404 | Unstaking Process | Initiate and complete unstaking | Unstaking process works correctly |
149+
| VAL-405 | Balance Verification | Verify token balances after operations | Balances match expected values |
150+
151+
### 6. Error Handling and Recovery
152+
153+
| Test ID | Test Name | Description | Expected Result |
154+
|---------|-----------|-------------|----------------|
155+
| VAL-501 | Connection Loss | Handle dispatcher connection loss | Reconnection attempts made |
156+
| VAL-502 | Invalid Request | Handle invalid checkpoint request | Error logged, no signature generated |
157+
| VAL-503 | Transaction Failure | Handle Ethereum transaction failure | Proper error handling and retry |
158+
| VAL-504 | Database Error | Handle database connection issues | Graceful degradation, recovery attempts |
159+
| VAL-505 | Restart Recovery | Recover state after restart | State correctly recovered from database |
160+
161+
### 7. Security Tests
162+
163+
| Test ID | Test Name | Description | Expected Result |
164+
|---------|-----------|-------------|----------------|
165+
| VAL-601 | Authentication | Verify dispatcher authentication | Only authorized dispatchers accepted |
166+
| VAL-602 | Request Verification | Verify request integrity | Tampered requests rejected |
167+
| VAL-603 | Double Signing Prevention | Prevent signing same checkpoint twice | Duplicate signing prevented |
168+
| VAL-604 | Key Protection | Protect private keys from exposure | Keys never exposed in logs or responses |
169+
| VAL-605 | Data Validation | Validate all incoming data | Invalid data rejected with appropriate errors |
170+
171+
## Integration Test Cases
172+
173+
### 1. End-to-End Checkpoint Flow
174+
175+
| Test ID | Test Name | Description | Expected Result |
176+
|---------|-----------|-------------|----------------|
177+
| INT-001 | Complete Checkpoint Cycle | Run through entire checkpoint cycle | Checkpoint submitted to Ethereum successfully |
178+
| INT-002 | Multiple Validators | Test with multiple validators | Signatures correctly aggregated from all validators |
179+
| INT-003 | Validator Subset | Test with subset of validators responding | Threshold mechanism works correctly |
180+
| INT-004 | Sequential Epochs | Process multiple sequential epochs | All epochs processed correctly in order |
181+
| INT-005 | Parallel Requests | Handle multiple checkpoint requests in parallel | All requests processed correctly |
182+
183+
### 2. Performance and Stress Tests
184+
185+
| Test ID | Test Name | Description | Expected Result |
186+
|---------|-----------|-------------|----------------|
187+
| PERF-001 | High Validator Count | Test with high number of validators | System scales correctly |
188+
| PERF-002 | Rapid Epoch Changes | Process rapidly changing epochs | All epochs processed without missing any |
189+
| PERF-003 | Network Latency | Test with simulated network latency | System handles latency gracefully |
190+
| PERF-004 | Resource Constraints | Test under limited CPU/memory | System degrades gracefully |
191+
| PERF-005 | Long-Running Test | Run system for extended period | Stability maintained over time |
192+
193+
## Test Environment Setup
194+
195+
### Local Development Environment
196+
197+
```bash
198+
# Start PostgreSQL
199+
docker run -d --name postgres-checkpoint -e POSTGRES_PASSWORD=hetu -p 5432:5432 postgres
200+
201+
# Create required databases
202+
psql -h localhost -U postgres -c "CREATE DATABASE bls_db3;"
203+
psql -h localhost -U postgres -c "CREATE DATABASE validator_db;"
204+
205+
# Start local Ethereum node
206+
npx hardhat node
207+
208+
# Deploy contracts
209+
cd contracts
210+
npx hardhat run scripts/deploy.js --network localhost
211+
212+
# Start Dispatcher
213+
cd cmd/dispatcher
214+
go run main.go
215+
216+
# Start Validator
217+
cd cmd/validator
218+
go run main.go
219+
```
220+
221+
### Test Configuration Examples
222+
223+
**Dispatcher Configuration (dis_config.json):**
224+
```json
225+
{
226+
"DBhost": "localhost",
227+
"DBport": 5432,
228+
"DBuser": "postgres",
229+
"DBpassword": "hetu",
230+
"DBname": "bls_db3",
231+
"Httpport": 8080,
232+
"Tcpport": 8081,
233+
"EnableReport": true,
234+
"ChainGRpcURL": "localhost:9090",
235+
"CometBFTSvr": "localhost:26657",
236+
"ChainID": "hetu_560002-1",
237+
"EthRpcURL": "http://localhost:8545",
238+
"EthChainID": 31337,
239+
"ValidatorStakingAddress": "0x5FbDB2315678afecb367f032d93F642f64180aa3",
240+
"RewardDistrInterval": 3
241+
}
242+
```
243+
244+
**Validator Configuration (val_config.json):**
245+
```json
246+
{
247+
"DBhost": "localhost",
248+
"DBport": 5432,
249+
"DBuser": "postgres",
250+
"DBpassword": "hetu",
251+
"DBname": "validator_db",
252+
"dispatchertcp": "localhost:8081",
253+
"ListenAddr": "localhost",
254+
"port": 0,
255+
"ChainRpcURL": "http://localhost:8545",
256+
"StakingTokenAddress": "0xe7f6c60d813a17e2fa16869371351d8c800c7fc1",
257+
"ValidatorStakingAddress": "0x5FbDB2315678afecb367f032d93F642f64180aa3",
258+
"DispatcherURL": "http://localhost:8080",
259+
"ChainGRpcURL": "localhost:9090",
260+
"CometBFTSvr": "localhost:26657",
261+
"ChainID": "hetu_560002-1"
262+
}
263+
```
264+
265+
## Test Execution Guidelines
266+
267+
1. **Unit Tests**: Run individual component tests
268+
```
269+
go test ./... -v
270+
```
271+
272+
2. **Integration Tests**: Run through complete checkpoint flow
273+
```
274+
go test ./tests/integration -v
275+
```
276+
277+
3. **Performance Tests**: Measure system performance under load
278+
```
279+
go test ./tests/performance -v -benchtime=10s
280+
```
281+
282+
4. **Manual Tests**: Follow test cases in this document with the provided test environment
283+
284+
## Test Reporting
285+
286+
For each test, document:
287+
1. Test case ID
288+
2. Test date and environment
289+
3. Test result (Pass/Fail)
290+
4. Observations and issues encountered
291+
5. Performance metrics (if applicable)

0 commit comments

Comments
 (0)