Skip to content

Commit cf0d272

Browse files
hrishikeshiohrishikeshio
authored
Docs: add directory structure (#1018)
* docs: added docs * docs: add directory structure
1 parent 653ae58 commit cf0d272

File tree

2 files changed

+210
-8
lines changed

2 files changed

+210
-8
lines changed

‎docs/README.md

+35-8
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ Welcome to the Oracle Contracts documentation. This documentation provides compr
44

55
## Documentation Structure
66

7+
### Core Documentation
8+
- [Project Structure](project-structure.md) - Directory layout and file purposes
79
- [Architecture Overview](architecture.md) - System design and component interactions
810
- [Setup & Installation](setup-and-installation.md) - Environment setup and deployment steps
911
- [API Reference](api-reference.md) - Contract interfaces and endpoints
@@ -12,10 +14,27 @@ Welcome to the Oracle Contracts documentation. This documentation provides compr
1214
- [Contributing](contributing.md) - Development workflow and guidelines
1315

1416
### Detailed Guides
15-
- [Staking Guide](guides/staking.md)
16-
- [Voting Guide](guides/voting.md)
17-
- [Bonds Guide](guides/bonds.md)
18-
- [Delegation Guide](guides/delegation.md)
17+
- [Staking Guide](guides/staking.md) - Participate through staking
18+
- [Voting Guide](guides/voting.md) - Consensus participation
19+
- [Bonds Guide](guides/bonds.md) - Data bond management
20+
- [Delegation Guide](guides/delegation.md) - Delegate tokens to stakers
21+
22+
## Getting Started
23+
24+
1. **New to Oracle Contracts?**
25+
- Start with [Core Concepts](core-concepts.md)
26+
- Review the [Architecture Overview](architecture.md)
27+
- Follow the [Setup Guide](setup-and-installation.md)
28+
29+
2. **Want to Develop?**
30+
- Check the [Project Structure](project-structure.md)
31+
- Read the [API Reference](api-reference.md)
32+
- Follow the [Contributing Guide](contributing.md)
33+
34+
3. **Ready to Participate?**
35+
- Follow the [Staking Guide](guides/staking.md)
36+
- Learn about [Voting](guides/voting.md)
37+
- Understand [Delegation](guides/delegation.md)
1938

2039
## Quick Links
2140

@@ -26,11 +45,19 @@ Welcome to the Oracle Contracts documentation. This documentation provides compr
2645
## Getting Help
2746

2847
If you need help or have questions:
29-
1. Check the [Core Concepts](core-concepts.md) guide
30-
2. Review the [API Reference](api-reference.md)
31-
3. See the [Contributing](contributing.md) guide for development questions
32-
4. Open an issue on GitHub for bugs or feature requests
48+
1. Check the [Project Structure](project-structure.md) to find relevant files
49+
2. Review the [Core Concepts](core-concepts.md) guide
50+
3. Consult the [API Reference](api-reference.md)
51+
4. See the [Contributing Guide](contributing.md) for development questions
52+
5. Open an issue on GitHub for bugs or feature requests
3353

3454
## Contributing to Documentation
3555

3656
See our [Contributing Guide](contributing.md) for information about improving this documentation.
57+
58+
## Documentation Updates
59+
60+
This documentation is actively maintained. For the latest updates:
61+
1. Check the [Documentation Plan](documentation-plan.md) for upcoming changes
62+
2. Review the [Change Log](../CHANGELOG.md) for recent updates
63+
3. Submit improvements through pull requests

‎docs/project-structure.md

+175
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# Project Structure
2+
3+
This document provides an overview of the project's directory structure and explains the purpose of key files.
4+
5+
## Directory Structure
6+
7+
```
8+
oracle-contracts/
9+
├── contracts/ # Smart contract source files
10+
│ ├── Core/ # Core contract implementations
11+
│ │ ├── interface/ # Contract interfaces
12+
│ │ ├── parameters/ # Contract parameters
13+
│ │ └── storage/ # Storage contracts
14+
│ ├── lib/ # Utility libraries
15+
│ ├── mocks/ # Mock contracts for testing
16+
│ ├── randomNumber/ # Random number generation
17+
│ └── tokenization/ # Token-related contracts
18+
├── deploy/ # Deployment scripts
19+
├── deployed/ # Deployment addresses
20+
├── docker/ # Docker configuration
21+
├── migrations/ # Migration scripts
22+
├── scenarios/ # Test scenarios
23+
├── scripts/ # Utility scripts
24+
└── test/ # Test files
25+
```
26+
27+
## Key Files and Their Purpose
28+
29+
### Root Directory Files
30+
31+
- `hardhat.config.js` - Hardhat configuration including network settings, compiler options, and task definitions
32+
- `package.json` - Project dependencies and scripts
33+
- `.env.tpl` - Template for environment variables
34+
- `.solhint.json` - Solidity linting rules
35+
- `.prettierrc` - Code formatting rules
36+
- `codechecks.yml` - Code quality checks configuration
37+
38+
### Contract Files
39+
40+
#### Core Contracts
41+
42+
```
43+
contracts/Core/
44+
├── BlockManager.sol # Manages epoch blocks and confirmations
45+
├── BondManager.sol # Handles data bond creation and management
46+
├── CollectionManager.sol # Manages data collections and jobs
47+
├── RewardManager.sol # Distributes rewards to participants
48+
├── StakeManager.sol # Handles staking and delegation
49+
└── VoteManager.sol # Manages voting and consensus
50+
```
51+
52+
#### Interfaces
53+
54+
```
55+
contracts/Core/interface/
56+
├── IBlockManager.sol # Block management interface
57+
├── IBondManager.sol # Bond management interface
58+
├── ICollectionManager.sol # Collection management interface
59+
├── IRewardManager.sol # Reward distribution interface
60+
├── IStakeManager.sol # Stake management interface
61+
└── IVoteManager.sol # Vote management interface
62+
```
63+
64+
#### Parameters
65+
66+
```
67+
contracts/Core/parameters/
68+
├── ACL.sol # Access control settings
69+
├── Governance.sol # Governance parameters
70+
└── child/ # Individual parameter contracts
71+
├── BlockManagerParams.sol
72+
├── BondManagerParams.sol
73+
├── CollectionManagerParams.sol
74+
├── RandomNoManagerParams.sol
75+
├── RewardManagerParams.sol
76+
├── StakeManagerParams.sol
77+
└── VoteManagerParams.sol
78+
```
79+
80+
#### Storage
81+
82+
```
83+
contracts/Core/storage/
84+
├── BlockStorage.sol # Block-related storage
85+
├── BondStorage.sol # Bond-related storage
86+
├── CollectionStorage.sol # Collection-related storage
87+
├── Constants.sol # System constants
88+
├── StakeStorage.sol # Stake-related storage
89+
└── VoteStorage.sol # Vote-related storage
90+
```
91+
92+
### Libraries
93+
94+
```
95+
contracts/lib/
96+
├── MerklePosAware.sol # Merkle tree utilities
97+
├── Random.sol # Random number utilities
98+
└── Structs.sol # Common data structures
99+
```
100+
101+
### Deployment
102+
103+
```
104+
deploy/
105+
├── 001_deploy_governance.js # Governance deployment
106+
├── 002_deploy_block_manager.js # Block manager deployment
107+
├── 003_deploy_collection_manager.js # Collection manager deployment
108+
└── ... # Additional deployment scripts
109+
```
110+
111+
### Testing
112+
113+
```
114+
test/
115+
├── helpers/ # Test helper functions
116+
│ ├── constants.js # Test constants
117+
│ ├── InternalEngine.js # Test engine
118+
│ └── testSetup.js # Test setup utilities
119+
├── ACL.js # Access control tests
120+
├── BlockManager.js # Block manager tests
121+
└── ... # Additional test files
122+
```
123+
124+
## File Categories and Their Uses
125+
126+
### For Smart Contract Development
127+
- `contracts/Core/` - Main contract implementations
128+
- `contracts/Core/interface/` - Contract interfaces
129+
- `contracts/lib/` - Reusable libraries
130+
- `test/` - Contract tests
131+
132+
### For Deployment
133+
- `deploy/` - Deployment scripts
134+
- `deployed/` - Network addresses
135+
- `migrations/` - Migration scripts
136+
- `.env.tpl` - Environment configuration
137+
138+
### For Testing
139+
- `test/` - Test files
140+
- `test/helpers/` - Test utilities
141+
- `scenarios/` - Complex test scenarios
142+
143+
### For Development Tools
144+
- `scripts/` - Utility scripts
145+
- `docker/` - Container configuration
146+
- `.solhint.json` - Linting rules
147+
- `.prettierrc` - Formatting rules
148+
149+
## Common Development Workflows
150+
151+
### 1. Contract Development
152+
Key files:
153+
- `contracts/Core/` for implementations
154+
- `contracts/Core/interface/` for interfaces
155+
- `test/` for tests
156+
- `.solhint.json` for linting rules
157+
158+
### 2. Deployment Process
159+
Key files:
160+
- `deploy/` for deployment scripts
161+
- `.env` for configuration
162+
- `hardhat.config.js` for network settings
163+
- `deployed/` for addresses
164+
165+
### 3. Testing
166+
Key files:
167+
- `test/` for test files
168+
- `test/helpers/` for utilities
169+
- `scenarios/` for complex tests
170+
- `contracts/mocks/` for mock contracts
171+
172+
## Related Documentation
173+
- [Architecture Overview](architecture.md)
174+
- [Setup Guide](setup-and-installation.md)
175+
- [Contributing Guidelines](contributing.md)

0 commit comments

Comments
 (0)