AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

code-maturity-assessor

Systematic code maturity assessment using Trail of Bits' 9-category framework. Analyzes codebase for arithmetic safety, auditing practices, access controls, complexity, decentralization, documentation, MEV risks, low-level code, and testing, then produces a scorecard with evidence-based ratings and a priority-ordered roadmap. Use when assessing or scoring the maturity of a smart contract or blockchain codebase, producing a maturity scorecard or evaluation, or judging how mature, well-tested, or well-documented such a project is against a rubric.

Original source
trailofbits
License
CC-BY-SA-4.0
Pinned revision
2be6433b39e009cd2b6fd3be1895f6b1faa5af9a

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read trailofbits--code-maturity-assessor at revision 2be6433b39e009cd2b6fd3be1895f6b1faa5af9a, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 4

resources/ASSESSMENT_CRITERIA.md

The 9 Categories

1. ARITHMETIC

Focus: Overflow protection, precision handling, formula specification, edge case testing

I'll analyze:

  • Overflow protection mechanisms (Solidity 0.8, SafeMath, checked_, saturating_)
  • Unchecked arithmetic blocks and documentation
  • Division/rounding operations
  • Arithmetic in critical functions (balances, rewards, fees)
  • Test coverage for arithmetic edge cases
  • Arithmetic specification documents

WEAK if:

  • No overflow protection without justification
  • Unchecked arithmetic not documented
  • No arithmetic specification OR spec doesn't match code
  • No testing strategy for arithmetic
  • Critical edge cases not tested

MODERATE requires:

  • All weak criteria resolved
  • Unchecked arithmetic minimal, justified, documented
  • Overflow/underflow risks documented and tested
  • Explicit rounding for precision loss
  • Automated testing (fuzzing/formal methods)
  • Stateless arithmetic functions
  • Bounded parameters with explained ranges

SATISFACTORY requires:

  • All moderate criteria met
  • Precision loss analyzed vs ground-truth
  • All trapping operations identified
  • Arithmetic spec matches code one-to-one
  • Automated testing covers all operations in CI

2. AUDITING

Focus: Events, monitoring systems, incident response

I'll analyze:

  • Event definitions and emission patterns
  • Events for critical operations (transfers, access changes, parameter updates)
  • Event naming consistency
  • Critical functions without events

I'll ask you:

  • Off-chain monitoring infrastructure?
  • Monitoring plan documented?
  • Incident response plan exists and tested?

WEAK if:

  • No event strategy
  • Events missing for critical updates
  • No consistent event guidelines
  • Same events reused for different purposes

MODERATE requires:

  • All weak criteria resolved
  • Events for all critical functions
  • Off-chain monitoring logs events
  • Monitoring plan documented
  • Event documentation (purpose, usage, assumptions)
  • Log review process documented
  • Incident response plan exists

SATISFACTORY requires:

  • All moderate criteria met
  • Monitoring triggers alerts on unexpected behavior
  • Defined roles for incident detection
  • Incident response plan regularly tested

3. AUTHENTICATION / ACCESS CONTROLS

Focus: Privilege management, role separation, access patterns

I'll analyze:

  • Access control modifiers/functions
  • Role definitions and separation
  • Admin/owner patterns
  • Privileged function implementations
  • Test coverage for access controls

I'll ask you:

  • Who are privileged actors? (EOA, multisig, DAO?)
  • Documentation of roles and privileges?
  • Key compromise scenarios?

WEAK if:

  • Access controls unclear or inconsistent
  • Single address controls system without safeguards
  • Missing access controls on privileged functions
  • No role differentiation
  • All privileges on one address

MODERATE requires:

  • All weak criteria resolved
  • All privileged functions have access control
  • Least privilege principle followed
  • Non-overlapping role privileges
  • Clear actor/privilege documentation
  • Tests cover all privileges
  • Roles can be revoked
  • Two-step processes for EOA operations

SATISFACTORY requires:

  • All moderate criteria met
  • All actors well documented
  • Implementation matches specification
  • Privileged actors not EOAs
  • Key leakage doesn't compromise system
  • Tested against known attack vectors

4. COMPLEXITY MANAGEMENT

Focus: Code clarity, function scope, avoiding unnecessary complexity

I'll analyze:

  • Function length and nesting depth
  • Cyclomatic complexity
  • Code duplication
  • Inheritance hierarchies
  • Naming conventions
  • Function clarity

I'll ask you:

  • Complex parts documented?
  • Naming convention documented?
  • Complexity measurements?

WEAK if:

  • Unnecessary complexity hinders review
  • Functions overuse nested operations
  • Functions have unclear scope
  • Unnecessary code duplication
  • Complex inheritance tree

MODERATE requires:

  • All weak criteria resolved
  • Complex parts identified, minimized
  • High complexity (≥11) justified
  • Critical functions well-scoped
  • Minimal, justified redundancy
  • Clear inputs with validation
  • Documented naming convention
  • Types not misused

SATISFACTORY requires:

  • All moderate criteria met
  • Minimal unnecessary complexity
  • Necessary complexity documented
  • Clear function purposes
  • Straightforward to test
  • No redundant behavior

5. DECENTRALIZATION

Focus: Centralization risks, upgrade control, user opt-out

I'll analyze:

  • Upgrade mechanisms (proxies, governance)
  • Owner/admin control scope
  • Timelock/multisig patterns
  • User opt-out mechanisms

I'll ask you:

  • Upgrade mechanism and control?
  • User opt-out/exit paths?
  • Centralization risk documentation?

WEAK if:

  • Centralization points not visible to users
  • Critical functions upgradable by single entity without opt-out
  • Single entity controls user funds
  • All decisions by single entity
  • Parameters changeable anytime by single entity
  • Centralized permission required

MODERATE requires:

  • All weak criteria resolved
  • Centralization risks identified, justified, documented
  • User opt-out/exit path documented
  • Upgradeability only for non-critical features
  • Privileged actors can't unilaterally move/trap funds
  • All privileges documented

SATISFACTORY requires:

  • All moderate criteria met
  • Clear decentralization path justified
  • On-chain voting risks addressed OR no centralization
  • Deployment risks documented
  • External interaction risks documented
  • Critical parameters immutable OR users can exit

6. DOCUMENTATION

Focus: Specifications, architecture, user stories, inline comments

I'll analyze:

  • README, specification, architecture docs
  • Inline code comments (NatSpec, rustdoc, etc.)
  • User stories
  • Glossaries
  • Documentation completeness and accuracy

I'll ask you:

  • User stories documented?
  • Architecture diagrams exist?
  • Glossary for domain terms?

WEAK if:

  • Minimal or incomplete/outdated documentation
  • Only high-level description
  • Code comments don't match docs
  • Not publicly available (for public codebases)
  • Unexplained artificial terms

MODERATE requires:

  • All weak criteria resolved
  • Clear, unambiguous writing
  • Glossary for business terms
  • Architecture diagrams
  • User stories included
  • Core/critical components identified
  • Docs sufficient to understand behavior
  • All critical functions/blocks documented
  • Known risks/limitations documented

SATISFACTORY requires:

  • All moderate criteria met
  • User stories cover all operations
  • Detailed behavior descriptions
  • Implementation matches spec (deviations justified)
  • Invariants clearly defined
  • Consistent naming conventions
  • Documentation for end-users AND developers

7. TRANSACTION ORDERING RISKS

Focus: MEV, front-running, sandwich attacks

I'll analyze:

  • MEV-vulnerable patterns (AMM swaps, arbitrage, large trades)
  • Front-running protections
  • Slippage/deadline checks
  • Oracle implementations

I'll ask you:

  • Transaction ordering risks identified/documented?
  • Known MEV opportunities?
  • Mitigation strategies?
  • Testing for ordering attacks?

WEAK if:

  • Ordering risks not identified/documented
  • Protocols/assets at risk from unexpected ordering
  • Relies on unjustified MEV prevention constraints
  • Unproven assumptions about MEV extractors

MODERATE requires:

  • All weak criteria resolved
  • User operation ordering risks limited, justified, documented
  • MEV mitigations in place (delays, slippage checks)
  • Testing emphasizes ordering risks
  • Tamper-resistant oracles used

SATISFACTORY requires:

  • All moderate criteria met
  • All ordering risks documented and justified
  • Known risks highlighted in docs/tests, visible to users
  • Documentation centralizes MEV opportunities
  • Privileged operation ordering risks limited, justified
  • Tests highlight ordering risks

8. LOW-LEVEL MANIPULATION

Focus: Assembly, unsafe code, low-level operations

I'll analyze:

  • Assembly blocks
  • Unsafe code sections
  • Low-level calls
  • Bitwise operations
  • Justification and documentation

I'll ask you:

  • Why use assembly/unsafe here?
  • High-level reference implementation?
  • How is this tested?

WEAK if:

  • Unjustified low-level manipulations
  • Assembly/low-level not justified, could be high-level

MODERATE requires:

  • All weak criteria resolved
  • Assembly use limited and justified
  • Inline comments for each operation
  • No re-implementation of established libraries without justification
  • High-level reference for complex assembly

SATISFACTORY requires:

  • All moderate criteria met
  • Thorough documentation/justification/testing
  • Validated with automated testing vs reference
  • Differential fuzzing compares implementations
  • Compiler optimization risks identified

9. TESTING AND VERIFICATION

Focus: Coverage, testing techniques, CI/CD

I'll analyze:

  • Test file count and organization
  • Test coverage reports
  • CI/CD configuration
  • Advanced testing (fuzzing, formal verification)
  • Test quality and isolation

I'll ask you:

  • Test coverage percentage?
  • Do all tests pass?
  • Testing techniques used?
  • Easy to run tests?

WEAK if:

  • Limited testing, only happy paths
  • Common use cases not tested
  • Tests fail
  • Can't run tests "out of the box"

MODERATE requires:

  • All weak criteria resolved
  • Most functions/use cases tested
  • All tests pass
  • Coverage reports available
  • Automated testing for critical components
  • Tests in CI/CD
  • Integration tests (if applicable)
  • Test code follows best practices

SATISFACTORY requires:

  • All moderate criteria met
  • 100% reachable branch/statement coverage
  • End-to-end testing covers all entry points
  • Isolated test cases (no dependencies)
  • Mutation testing used