253 lines
8.3 KiB
Markdown
253 lines
8.3 KiB
Markdown
---
|
|
name: guidelines-advisor
|
|
description: Smart contract development advisor based on Trail of Bits' best practices. Analyzes codebase to generate documentation/specifications, review architecture, check upgradeability patterns, assess implementation quality, identify pitfalls, review dependencies, and evaluate testing. Provides actionable recommendations.
|
|
---
|
|
|
|
# Guidelines Advisor
|
|
|
|
## Purpose
|
|
|
|
Systematically analyzes the codebase and provides guidance based on Trail of Bits' development guidelines:
|
|
|
|
1. **Generate documentation and specifications** (plain English descriptions, architectural diagrams, code documentation)
|
|
2. **Optimize on-chain/off-chain architecture** (only if applicable)
|
|
3. **Review upgradeability patterns** (if your project has upgrades)
|
|
4. **Check delegatecall/proxy implementations** (if present)
|
|
5. **Assess implementation quality** (functions, inheritance, events)
|
|
6. **Identify common pitfalls**
|
|
7. **Review dependencies**
|
|
8. **Evaluate test suite and suggest improvements**
|
|
|
|
**Framework**: Building Secure Contracts - Development Guidelines
|
|
|
|
---
|
|
|
|
## How This Works
|
|
|
|
### Phase 1: Discovery & Context
|
|
Explores the codebase to understand:
|
|
- Project structure and platform
|
|
- Contract/module files and their purposes
|
|
- Existing documentation
|
|
- Architecture patterns (proxies, upgrades, etc.)
|
|
- Testing setup
|
|
- Dependencies
|
|
|
|
### Phase 2: Documentation Generation
|
|
Helps create:
|
|
- Plain English system description
|
|
- Architectural diagrams (using Slither printers for Solidity)
|
|
- Code documentation recommendations (NatSpec for Solidity)
|
|
|
|
### Phase 3: Architecture Analysis
|
|
Analyzes:
|
|
- On-chain vs off-chain component distribution (if applicable)
|
|
- Upgradeability approach (if applicable)
|
|
- Delegatecall proxy patterns (if present)
|
|
|
|
### Phase 4: Implementation Review
|
|
Assesses:
|
|
- Function composition and clarity
|
|
- Inheritance structure
|
|
- Event logging practices
|
|
- Common pitfalls presence
|
|
- Dependencies quality
|
|
- Testing coverage and techniques
|
|
|
|
### Phase 5: Recommendations
|
|
Provides:
|
|
- Prioritized improvement suggestions
|
|
- Best practice guidance
|
|
- Actionable next steps
|
|
|
|
---
|
|
|
|
## Assessment Areas
|
|
|
|
I analyze 11 comprehensive areas covering all aspects of smart contract development. For detailed criteria, best practices, and specific checks, see [ASSESSMENT_AREAS.md](resources/ASSESSMENT_AREAS.md).
|
|
|
|
### Quick Reference:
|
|
|
|
1. **Documentation & Specifications**
|
|
- Plain English system descriptions
|
|
- Architectural diagrams
|
|
- NatSpec completeness (Solidity)
|
|
- Documentation gaps identification
|
|
|
|
2. **On-Chain vs Off-Chain Computation**
|
|
- Complexity analysis
|
|
- Gas optimization opportunities
|
|
- Verification vs computation patterns
|
|
|
|
3. **Upgradeability**
|
|
- Migration vs upgradeability trade-offs
|
|
- Data separation patterns
|
|
- Upgrade procedure documentation
|
|
|
|
4. **Delegatecall Proxy Pattern**
|
|
- Storage layout consistency
|
|
- Initialization patterns
|
|
- Function shadowing risks
|
|
- Slither upgradeability checks
|
|
|
|
5. **Function Composition**
|
|
- Function size and clarity
|
|
- Logical grouping
|
|
- Modularity assessment
|
|
|
|
6. **Inheritance**
|
|
- Hierarchy depth/width
|
|
- Diamond problem risks
|
|
- Inheritance visualization
|
|
|
|
7. **Events**
|
|
- Critical operation coverage
|
|
- Event naming consistency
|
|
- Indexed parameters
|
|
|
|
8. **Common Pitfalls**
|
|
- Reentrancy patterns
|
|
- Integer overflow/underflow
|
|
- Access control issues
|
|
- Platform-specific vulnerabilities
|
|
|
|
9. **Dependencies**
|
|
- Library quality assessment
|
|
- Version management
|
|
- Dependency manager usage
|
|
- Copied code detection
|
|
|
|
10. **Testing & Verification**
|
|
- Coverage analysis
|
|
- Fuzzing techniques
|
|
- Formal verification
|
|
- CI/CD integration
|
|
|
|
11. **Platform-Specific Guidance**
|
|
- Solidity version recommendations
|
|
- Compiler warning checks
|
|
- Inline assembly warnings
|
|
- Platform-specific tools
|
|
|
|
For complete details on each area including what I'll check, analyze, and recommend, see [ASSESSMENT_AREAS.md](resources/ASSESSMENT_AREAS.md).
|
|
|
|
---
|
|
|
|
## Example Output
|
|
|
|
When the analysis is complete, you'll receive comprehensive guidance covering:
|
|
|
|
- System documentation with plain English descriptions
|
|
- Architectural diagrams and documentation gaps
|
|
- Architecture analysis (on-chain/off-chain, upgradeability, proxies)
|
|
- Implementation review (functions, inheritance, events, pitfalls)
|
|
- Dependencies and testing evaluation
|
|
- Prioritized recommendations (CRITICAL, HIGH, MEDIUM, LOW)
|
|
- Overall assessment and path to production
|
|
|
|
For a complete example analysis report, see [EXAMPLE_REPORT.md](resources/EXAMPLE_REPORT.md).
|
|
|
|
---
|
|
|
|
## Deliverables
|
|
|
|
I provide four comprehensive deliverable categories:
|
|
|
|
### 1. System Documentation
|
|
- Plain English descriptions
|
|
- Architectural diagrams
|
|
- Documentation gaps analysis
|
|
|
|
### 2. Architecture Analysis
|
|
- On-chain/off-chain assessment
|
|
- Upgradeability review
|
|
- Proxy pattern security review
|
|
|
|
### 3. Implementation Review
|
|
- Function composition analysis
|
|
- Inheritance assessment
|
|
- Events coverage
|
|
- Pitfall identification
|
|
- Dependencies evaluation
|
|
- Testing analysis
|
|
|
|
### 4. Prioritized Recommendations
|
|
- CRITICAL (address immediately)
|
|
- HIGH (address before deployment)
|
|
- MEDIUM (address for production quality)
|
|
- LOW (nice to have)
|
|
|
|
For detailed templates and examples of each deliverable, see [DELIVERABLES.md](resources/DELIVERABLES.md).
|
|
|
|
---
|
|
|
|
## Assessment Process
|
|
|
|
When invoked, I will:
|
|
|
|
1. **Explore the codebase**
|
|
- Identify all contract/module files
|
|
- Find existing documentation
|
|
- Locate test files
|
|
- Check for proxies/upgrades
|
|
- Identify dependencies
|
|
|
|
2. **Generate documentation**
|
|
- Create plain English system description
|
|
- Generate architectural diagrams (if tools available)
|
|
- Identify documentation gaps
|
|
|
|
3. **Analyze architecture**
|
|
- Assess on-chain/off-chain distribution (if applicable)
|
|
- Review upgradeability approach (if applicable)
|
|
- Audit proxy patterns (if present)
|
|
|
|
4. **Review implementation**
|
|
- Analyze functions, inheritance, events
|
|
- Check for common pitfalls
|
|
- Assess dependencies
|
|
- Evaluate testing
|
|
|
|
5. **Provide recommendations**
|
|
- Present findings with file references
|
|
- Ask clarifying questions about design decisions
|
|
- Suggest prioritized improvements
|
|
- Offer actionable next steps
|
|
|
|
---
|
|
|
|
## Rationalizations (Do Not Skip)
|
|
|
|
| Rationalization | Why It's Wrong | Required Action |
|
|
|-----------------|----------------|-----------------|
|
|
| "System is simple, description covers everything" | Plain English descriptions miss security-critical details | Complete all 5 phases: documentation, architecture, implementation, dependencies, recommendations |
|
|
| "No upgrades detected, skip upgradeability section" | Upgradeability can be implicit (ownable patterns, delegatecall) | Search for proxy patterns, delegatecall, storage collisions before declaring N/A |
|
|
| "Not applicable" without verification | Premature scope reduction misses vulnerabilities | Verify with explicit codebase search before skipping any guideline section |
|
|
| "Architecture is straightforward, no analysis needed" | Obvious architectures have subtle trust boundaries | Analyze on-chain/off-chain distribution, access control flow, external dependencies |
|
|
| "Common pitfalls don't apply to this codebase" | Every codebase has common pitfalls | Systematically check all guideline pitfalls with grep/code search |
|
|
| "Tests exist, testing guideline is satisfied" | Test existence ≠ test quality | Check coverage, property-based tests, integration tests, failure cases |
|
|
| "I can provide generic best practices" | Generic advice isn't actionable | Provide project-specific findings with file:line references |
|
|
| "User knows what to improve from findings" | Findings without prioritization = no action plan | Generate prioritized improvement roadmap with specific next steps |
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- I'll only analyze relevant sections (won't hallucinate about upgrades if not present)
|
|
- I'll adapt to your platform (Solidity, Rust, Cairo, etc.)
|
|
- I'll use available tools (Slither, etc.) but work without them if unavailable
|
|
- I'll provide file references and line numbers for all findings
|
|
- I'll ask questions about design decisions I can't infer from code
|
|
|
|
---
|
|
|
|
## Ready to Begin
|
|
|
|
**What I'll need**:
|
|
- Access to your codebase
|
|
- Context about your project goals
|
|
- Any existing documentation or specifications
|
|
- Information about deployment plans
|
|
|
|
Let's analyze your codebase and improve it using Trail of Bits' best practices!
|