Contract architecture
Every Solidity source file, its kind, and how modules depend on each other.
BugCrawl's on-chain side is 47 Solidity source files compiled with solc 0.8.30, optimizer on (200 runs), EVM target cancun. Every module inherits ModuleBase, which checks roles against one AccessHub and pause flags against one PauseGuard. Dependencies are passed to constructors and stored as immutables, so there are no proxies, no upgrade hooks and no cycles.
Roles
DEFAULT_ADMIN | Grants roles, unpauses, edits parameters. Two-step transfer with a delay; intended to end up with AdminTimelock. |
REGISTRAR | Adds directory entries, records deployment manifests, publishes versions. |
CURATOR | Networks, providers, auditors, revocations, appeals, triage. |
VERIFIER | The off-chain service account that reports explorer results through VerificationCoordinator. |
PAUSER | Can pause one module or everything. Cannot unpause. |
| module roles | RECORD_WRITER, EVIDENCE_WRITER, REQUEST_OPERATOR, REPUTATION_WRITER: held by contracts, not people. |
Source files
access
AccessHub | deployable (core) | Single role registry for every BugCrawl module. |
AdminTimelock | deployable (separate script) | Delays privileged changes so the community can see them coming. Intended to become the AccessHub default admin once the deployment is stable. |
BugCrawlRoles | library | Canonical role identifiers. Kept in one place so modules, scripts and the web app agree. |
ModuleBase | abstract | Common plumbing for BugCrawl modules: role checks against AccessHub and pause checks against PauseGuard. |
PauseGuard | deployable (core) | Emergency pause controller. Pausers can stop one module or the whole protocol quickly; only the admin can resume, so a compromised pauser cannot flip modules back on. |
core
BugCrawlCore | deployable (core) | The "nest": an address book mapping module names to their live deployments, so clients only need one address to discover the whole system. |
ContractDirectory | deployable (core) | The catalogue ("trail index") of contracts BugCrawl tracks, across any supported EVM chain. |
ContractMetadataRegistry | deployable (core) | Public links and descriptive fields for directory entries (website, repository, docs, ...). |
ContractRelationshipRegistry | deployable (core) | Directed links between directory entries ("trails"), e.g. proxy -> implementation, module -> dependency, factory -> child. |
DeploymentRegistry | deployable (core) | Anchors the hash of each BugCrawl deployment manifest on-chain, so the JSON manifest published in the repository can be checked against what the registrar recorded. |
NetworkRegistry | deployable (core) | Networks whose contracts BugCrawl catalogues, with their explorer base URLs. |
VersionRegistry | deployable (core) | Protocol release history with strictly increasing semantic versions. |
verification
AttestationRegistry | deployable (core) | Security-review attestations signed (by transaction) by curator-approved auditors. |
VerificationAppeals | deployable (core) | Entry controllers can contest a Failed or Revoked result. A curator either upholds the appeal (which opens a fresh verification request) or rejects it with a public note. |
VerificationCoordinator | deployable (core) | The single door through which the off-chain verification service reports explorer results. One call appends the record, attaches its evidence and closes the open request. |
VerificationEvidenceStore | deployable (core) | Content digests and locations of the evidence behind each verification record (standard-JSON input, explorer response, compiler output). |
VerificationExpiryManager | deployable (core) | Decides whether a positive verification is still "fresh". Upgradeable proxies can change implementation after a check, so results age out and must be re-checked. |
VerificationRecordStore | deployable (core) | Append-only history of source-verification results per directory entry. |
VerificationRequestManager | deployable (core) | Queue asking the verification service to (re)check a directory entry against its explorer. |
VerificationRevocationManager | deployable (core) | Lets curators withdraw a positive verification with a public reason, e.g. when a proxy is upgraded to unverified code or the explorer later reports a mismatch. |
ecosystem
AuditorDirectory | deployable (core) | Security reviewers that curators have approved to publish attestations. |
BugBountyRegistry | deployable (full) | Listing of bug-bounty programmes run by projects: scope, terms and declared reward ceiling. |
BugReportRegistry | deployable (full) | Public, non-sensitive bug reports against directory entries and their triage outcome. |
ContributorRegistry | deployable (full) | Public list of addresses that work on a project ("colony members"), each with a role tag. |
ProjectRegistry | deployable (core) | Self-service projects ("colonies") that group related contracts under one owner. |
ReputationRegistry | deployable (core) | Non-transferable activity points earned by auditors and bug reporters (e.g. +severity when a reported bug is confirmed fixed). |
SecurityDisclosureRegistry | deployable (full) | Projects publish how to report vulnerabilities; researchers timestamp private reports with a commitment and reveal them after the project ships a fix. |
periphery
BugCrawlLens | deployable (core) | Read-only aggregator for the web app: one call returns an entry together with its latest source-verification result, freshness, open request and active attestation count. |
ConfigurationRegistry | deployable (core) | Typed protocol parameters (e.g. "verification.maxAge") with optional bounds that the admin sets once per key, so a later value cannot leave its sane range. |
IntegrationRegistry | deployable (core) | External services BugCrawl relies on, chiefly verification providers (e.g. a Blockscout instance). Every on-chain verification record cites a provider id from here. |
interfaces
IAccessHub | interface | Read interface for the central role registry every BugCrawl module consults. |
IAuditorDirectory | interface | Read interface for curator-approved security reviewers. |
IConfigurationRegistry | interface | Read interface for typed protocol parameters. |
IContractDirectory | interface | Read interface for the catalogue of contracts known to BugCrawl. |
IEvidenceStore | interface | Write interface for verification evidence references. |
IIntegrationRegistry | interface | Read interface for registered verification providers / integrations. |
INetworkRegistry | interface | Read interface for supported networks. |
IPauseGuard | interface | Read interface for the emergency pause controller. |
IProjectRegistry | interface | Read interface for projects that group related contracts. |
IReputationRegistry | interface | Write interface used by modules that award or deduct activity-based reputation points. |
IVerificationRecordStore | interface | Append-only history of source-verification results. |
IVerificationRequestManager | interface | Queue of reconciliation requests for directory entries. |
libraries
AddressChecks | library | Small validation helpers shared by modules that accept addresses and strings. |
BugCrawlTypes | types | Shared enums and structs used across BugCrawl modules. |
EvidenceHashLib | library | Deterministic digests for off-chain evidence so anyone can recompute and compare them. |
PaginationLib | library | Bounds arithmetic for paginated view functions so they never revert on out-of-range pages. |
VerificationStatusLib | library | State machine for source-verification statuses. |
See the live picture on the ecosystem page.