Cursor rule

1# Solidity Development Guidelines for Asset Tokenization Kit
2 
3## General Principles
4 
5- **Think first, code second**: Minimize the number of lines changed and consider ripple effects across the codebase.
6- **Prefer simplicity**: Fewer moving parts → fewer bugs and lower audit overhead.
7 
8## Assembly Usage
9 
10| Rule | Rationale |
11|------|-----------|
12| Use assembly only when essential. | Keeps code readable and auditable. |
13| Assembly is mandatory for low-level external calls. | Gives full control over call parameters & return data, and saves gas. |
14| Precede every assembly block with: • A brief justification (1-2 lines). • Equivalent Solidity pseudocode. | Documents intent for reviewers. |
15| Mark assembly blocks memory-safe when the Solidity docs' criteria are met. | Enables compiler optimizations. |
16 
17## Gas Optimization
18 
19- Keep a dedicated **Gas Optimization** section in the PR description; justify any measurable gas deltas.
20- Prefer `calldata` over `memory`.
21- Limit storage (`sstore`, `sload`) operations; cache in memory wherever possible.
22- Use forge snapshot and benchmarks:
23```bash
24  forge snapshot                # Create gas snapshot
25  forge test --gas-report       # Gas report for tests
26  forge test --match-test bench # Run benchmarks
27```
28- Large regressions must be explained.
29 
30## Handling "Stack Too Deep"
31 
32- **Struct hack (tests only)**: Bundle local variables into a temporary struct declared above the test.
33- **Scoped blocks**: Wrap code in `{ ... }` to drop unused vars from the stack.
34- **Internal helper functions**: Encapsulate logic to shorten call frames.
35- **Refactor / delete unnecessary variables before other tricks**.
36 
37## Security Checklist
38 
39- Review every change with an adversarial mindset.
40- Favor the simplest design that meets requirements.
41- After coding, ask: "What new attack surface did I introduce?"
42- Reject any change that raises security risk without strong justification.
43- Follow SMART protocol security patterns for ERC-3643 compliance.
44 
45## Error Handling Style
46 
47Always use custom errors with the revert pattern instead of require statements:
48 
49```solidity
50// ❌ Don't use require with string messages
51require(amount > 0, "Amount must be positive");
52require(to != address(0), "Cannot transfer to zero address");
53 
54// ✅ Do use custom errors with if/revert pattern
55error AmountMustBePositive();
56error CannotTransferToZeroAddress();
57 
58if (amount == 0) revert AmountMustBePositive();
59if (to == address(0)) revert CannotTransferToZeroAddress();
60```
61 
62**Benefits of custom errors**:
63- More gas efficient than require strings
64- Better error identification in tests and debugging
65- Cleaner, more professional code
66- Consistent with modern Solidity best practices
67 
68## Testing Guidelines
69 
70### Core Testing Principles
71 
72**Every feature or change MUST have comprehensive tests before creating a PR**. This is non-negotiable for maintaining code quality and preventing regressions.
73 
74### When to Write Tests
75 
76- **New Features**: Write tests that demonstrate the complete flow and all edge cases
77- **Bug Fixes**: Add tests that reproduce the bug and verify the fix
78- **Refactoring**: Ensure existing tests still pass; add new ones if behavior changes
79- **Gas Optimizations**: Include benchmark tests showing before/after comparisons
80 
81### Types of Required Tests
82 
83**Unit Tests**:
84- Write clear unit tests that demonstrate the general flow of your feature/change
85- Test both happy paths and failure cases
86- Include edge cases and boundary conditions
87- Test revert conditions with specific error messages
88 
89**Fuzz Tests**:
90- **Fuzz tests are highly encouraged** for all new functionality
91- Use Foundry's built-in fuzzing capabilities
92- Apply random arguments to thoroughly test your implementation
93 
94Example fuzz test pattern:
95```solidity
96function testFuzz_myFeature(uint256 amount, address user) public {
97    // Bound inputs to reasonable ranges
98    amount = bound(amount, 1, type(uint128).max);
99    vm.assume(user != address(0));
100    
101    // Test your feature with random inputs
102    myContract.myFeature(amount, user);
103    
104    // Assert expected outcomes
105    assertEq(myContract.balanceOf(user), amount);
106}
107```
108 
109### Testing Checklist Before PR
110 
111Before opening any PR, ensure:
112- [ ] All new functions have unit tests
113- [ ] Critical paths have fuzz tests with random inputs
114- [ ] Edge cases and revert scenarios are tested
115- [ ] Gas benchmarks are included for optimizations
116- [ ] All tests pass: `forge test`
117- [ ] No test coverage regression: `forge coverage`
118 
119## Verification Workflow
120 
121```bash
122forge build                    # compile
123forge test                     # full test suite
124forge snapshot                 # gas snapshot
125forge test --match-test bench  # run benchmarks
126forge test --gas-report        # gas usage report
127forge coverage                 # code coverage
128```
129 
130## Asset Tokenization Kit Specific Guidelines
131 
132### Contract Structure
133- Follow the SMART protocol patterns for all asset implementations
134- Use the established factory pattern (`ATKBondFactory`, `ATKEquityFactory`, etc.)
135- Implement proper ERC-3643 compliance for all tokenized assets
136- Utilize the extension system (`SMARTBurnable`, `SMARTCapped`, etc.) for modularity
137 
138### Testing Assets
139When testing tokenized assets:
140- Test compliance features (identity registry, claim topics)
141- Test factory deployment patterns
142- Test proxy upgradeability
143- Test all extensions used by the asset
144- Include integration tests with the compliance system
145 
146### Common Patterns
147- Use `AccessControl` for role-based permissions
148- Implement `Pausable` for emergency stops
149- Follow ERC-3643 for identity and compliance
150- Use proxy patterns for upgradeability
151 
152### Available Tools
153 
154The Asset Tokenization Kit includes:
155- Foundry for contract compilation and testing
156- OpenZeppelin contracts for base implementations
157- SMART protocol contracts for compliance
158- Hardhat for additional tooling support
159 
160### Project Structure
161 
162- `contracts/`: Smart contract source files
163  - `assets/`: Asset factories and implementations
164  - `smart/`: SMART protocol base contracts and extensions
165  - `system/`: Compliance and registry contracts
166  - `test/`: Test contracts and utilities
167- `test/`: Foundry tests
168- `scripts/`: Deployment and utility scripts
169 
170## Critical Reminders
171 
172### DO NOT
173 
174- Use require() statements - always use custom errors
175- Create contracts without comprehensive tests
176- Make gas-intensive changes without benchmarks
177- Skip security considerations for any change
178- Use inline strings for errors
179 
180### ALWAYS
181 
182- Follow SMART protocol patterns
183- Test all compliance features
184- Measure gas impact of changes
185- Consider upgradeability implications
186- Use established factory patterns
187- Document assembly blocks
188- Run full test suite before PR
189 
190## Continuous Learning
191 
192- Consult SMART protocol documentation
193- Review OpenZeppelin best practices
194- Study ERC-3643 compliance requirements
195- Learn from audited tokenization projects
196 
197Apply these rules rigorously when working with Solidity files in the Asset Tokenization Kit.