Skip to content

PROJECT_STRUCTURE.md

Latest commit

 

History

History
207 lines (174 loc) · 12.2 KB

PROJECT_STRUCTURE.md

File metadata and controls

207 lines (174 loc) · 12.2 KB

Project Structure

A map of the repository: directory layout, package responsibilities, and where each concern lives. For how these pieces interact at runtime see ARCHITECTURE.md.

Repository layout

web3_decoder_2/
├── README.md                     # Project overview + links to these docs
├── docs/                         # This documentation set
├── settings.gradle               # Gradle multi-project definition (root + :web3-decoder)
├── gradle/
│   ├── libs.versions.toml        # Version catalog (Gradle-init leftover; see notes)
│   └── wrapper/                  # Gradle 8.8 wrapper
├── gradlew / gradlew.bat         # Gradle wrapper launchers
└── web3-decoder/                 # The extension module
    ├── build.gradle              # Dependencies, fat-jar packaging, test config
    └── src/
        ├── main/
        │   ├── java/com/nccgroup/web3decoder/
        │   │   ├── Web3DecoderExtension.java        # BurpExtension entry point
        │   │   ├── Web3EditorTabProvider.java       # Editor factory
        │   │   ├── Web3RequestEditor.java           # "Web3 Request" tab
        │   │   ├── Web3ResponseEditor.java          # "Web3 Response" tab
        │   │   ├── Web3RequestContextDecoder.java   # Headless decode orchestration
        │   │   ├── RequestContextStore.java         # Request→response context bridge
        │   │   ├── abi/                             # ABI resolution (chain-scoped chain)
        │   │   ├── annotation/                      # HTTP-handler history-row annotator
        │   │   ├── decoder/                         # Decode/encode core
        │   │   ├── detection/                      # Passive ABI detection (scan check, pool)
        │   │   ├── proxies/                         # Proxy detection
        │   │   ├── persistence/                     # Config + caches
        │   │   ├── ui/                              # Swing panels (Web3 suite tab)
        │   │   │   └── editor/                      # Custom JSON editor component
        │   └── resources/
        │       ├── chains.json                      # Default chain registry
        │       └── builtin-abis/multicall3.json     # Bundled Multicall3 ABI
        └── test/
            ├── java/com/nccgroup/web3_decoder/...   # JUnit 5 tests
            └── resources/                           # Sample ABIs + fixtures

The Gradle group is com.nccgroup.web3-decoder; runtime Java packages are under com.nccgroup.web3decoder (production) and com.nccgroup.web3_decoder (tests).

Package responsibilities

graph LR
    ROOT["web3decoder<br/>(entry + editors + orchestration)"]
    ABI["web3decoder.abi<br/>(ABI resolution)"]
    DEC["web3decoder.decoder<br/>(encode/decode core)"]
    DET["web3decoder.detection<br/>(passive ABI detection + pool)"]
    PROX["web3decoder.proxies<br/>(proxy detection)"]
    PERS["web3decoder.persistence<br/>(config + caches)"]
    UI["web3decoder.ui<br/>(suite-tab Swing panels)"]

    ROOT --> DEC
    ROOT --> ABI
    ROOT --> DET
    ROOT --> PROX
    ROOT --> PERS
    UI --> DEC
    UI --> ABI
    UI --> DET
    UI --> PROX
    UI --> PERS
    DEC --> ABI
    DEC --> DET
    DEC --> PROX
    ABI --> PERS
    DET --> PERS
Loading

com.nccgroup.web3decoder (root)

File Responsibility
Web3DecoderExtension BurpExtension entry point; registers editors + suite tab.
Web3EditorTabProvider Creates per-context request/response editor instances.
Web3RequestEditor Renders decoded calldata; re-encodes edited args on send.
Web3ResponseEditor Decodes JSON-RPC result; enriches multicall return data.
Web3RequestContextDecoder Headless decode of all eth_call items; populates the context store; resolves chain id.
RequestContextStore Static map bridging request decode → response decode, keyed by request + item.

com.nccgroup.web3decoder.decoder

File Responsibility
Web3DataDecoder Per-call orchestration: proxy → ABI source → decode, with detected-pool and 4byte fallbacks. Tolerates a null AbiProvider for chain-agnostic decode.
ABIInputDecoder web3j-backed engine: selector hashing, type mapping, input/output decode, encode. Has a CLI main().
MulticallRecursiveDecoder Detects/decodes the six Multicall3 aggregate variants recursively.

com.nccgroup.web3decoder.abi

File Responsibility
IAbiProvider Single-method interface: getAbi(address).
AbiProvider Composite: cache → builtin → explorer, with caching of explorer hits + lastAbiSource.
CachedAbiProvider Reads from the persistent CachedAbis store.
BuiltinAbiProvider Serves bundled ABIs (Multicall3 at its canonical address).
EtherscanAbiProvider Etherscan v2 multichain fetch with legacy /api fallback + support cache.
FourByteSignatureProvider 4byte selector lookup + synthetic-ABI generation.

com.nccgroup.web3decoder.detection

File Responsibility
AbiDetectionScanCheck Burp PassiveScanCheck registered as PER_REQUEST. Runs the pipeline on every audited response and raises a Solidity-ABI-detected audit issue per response that introduces a new ABI.
AbiDetectionPipeline Stateless facade: body → tokens → boundaries → normalize → validate → deduplicated list of DetectedAbi.
AbiTokenScanner Fixed-needle search over the body. Returns ascending byte offsets of candidate ABI internals.
AbiBoundaryExtractor String-aware, depth-tracking walk to the outermost enclosing [{...}] array of each hit. Computes the body's inString bitmap once and reuses it across all hits.
AbiNormalizer Jackson lenient parse with minified !0/!1 → true/false preprocessing, re-serialised as sorted-keys canonical JSON.
AbiValidator Type-vocabulary check, content fingerprint (SHA-256 of canonical JSON), and selector list extracted via AbiSelectorBuilder.
AbiSelectorBuilder Shared canonical-signature + 4-byte selector logic. Extracted from ABIInputDecoder so both decoder and validator reuse one implementation.
DetectedAbi Immutable value object: fingerprint, canonical JSON, selectors. Equality and hash are fingerprint-only.
DetectedAbiStore Project-scoped persistence over Burp PersistedObject (extensionData → detected_ABIs). Maintains an in-memory selector→fingerprint index, FIFO eviction at capacity, and exposes saveIfNew / findBySelector / snapshot / remove.

com.nccgroup.web3decoder.proxies

File Responsibility
IProxyDetector Single-method interface: getImplementationAddress(address).
ProxyDetector Composite + shared cache; runs each detector in order.
ERC1967ProxyDetector Reads the EIP-1967 implementation storage slot.
ZeppelinOSProxyDetector Reads the legacy ZeppelinOS/OpenZeppelin slot.

com.nccgroup.web3decoder.persistence

File Responsibility
ExtensionConfig Chain registry + API keys (Preferences), deprecated-chain migration, key resolution.
ChainInfo Jackson POJO: chainId, name, explorer, explorerAPIKey.
CachedAbis ABI cache over Burp PersistedObject, keyed chainId_address.

com.nccgroup.web3decoder.annotation

File Responsibility
Web3HistoryAnnotator HttpHandler that annotates Burp's Proxy/HTTP history rows with the decoded Web3 function name (synchronously, before the handler returns). Also threads the shared DetectedAbiStore into the context decoder.
AnnotationNoteBuilder Builds the actual annotation string from a decoded request (multicall-aware).

com.nccgroup.web3decoder.ui

File Responsibility
MainChainsPanel 2×2 dashboard. The bottom-left slot is a JSplitPane of "Cached ABIs" + "Detected ABIs" when a detected pool is wired.
ChainsListPanel Chain CRUD table, per-chain + shared Etherscan API key management.
CachedAbisListPanel Cached-ABI list; add manually or fetch from explorer; remove.
DetectedAbisListPanel Detected-ABI list (fingerprint, function count, first-seen URL); open in editor; remove.
AbiEditorPanel View/edit/save a cached ABI (setAbi) or view a detected ABI read-only with a context header (setDetectedAbi).
CalldataCodecPanel Standalone decode/re-encode tool with optional RPC + proxy + multicall.

com.nccgroup.web3decoder.ui.editor

File Responsibility
Web3JsonEditor Public reusable Swing JSON editor component; assembles gutter, text pane, and search bar. Used by both HTTP message tabs and the Calldata Codec.
JsonStyleScanner Pure-logic scanner; produces a list of StyleSpan (token ranges + StyleKind) from raw JSON text.
JsonSearchEngine Pure-logic search; finds all match ranges for a query string within the editor text.
JsonValidator Pure-logic validator; checks JSON well-formedness and reports the first error offset.
BracketMatcher Pure-logic matcher; locates the paired bracket for a given caret position; also defines StyleKind, StyleSpan, and Range value types.
EditorTheme Swing support; defines color constants (background, tokens, highlights) for the editor.
LineNumberGutter Swing support; JComponent painted alongside the text pane to show line numbers.
SearchBar Swing support; toolbar panel wiring together the search field, match navigation, and result count label.

Resources

Resource Purpose
resources/chains.json Default chain registry (chainId → {name, explorer}); merged with user Preferences at load. All entries target the unified Etherscan v2 host api.etherscan.io.
resources/builtin-abis/multicall3.json Canonical Multicall3 ABI served by BuiltinAbiProvider for 0xca11bde0…ca11 on every chain.

Tests

JUnit 5 + Mockito, under src/test/java/com/nccgroup/web3_decoder/:

Test Covers
decoder/ABIInputDecoderTest Core type encode/decode (scalars, arrays, tuples).
decoder/ABIInputDecoderRealTransactionsTest Decode against captured real-world calldata fixtures.
decoder/NestedStructOutputDecodeTest Nested struct/tuple output decoding.
decoder/MulticallRecursiveDecoderTest Multicall variant detection + recursive decode.
decoder/Web3DataDecoderTest Per-call strategy incl. proxy/detected/4byte fallbacks (mocked).
abi/FourByteSignatureProviderTest Selector lookup + synthetic ABI generation.
detection/AbiTokenScannerTest / AbiBoundaryExtractorTest / AbiNormalizerTest / AbiValidatorTest Per-stage unit tests for the passive detection pipeline.
detection/AbiSelectorBuilderTest Canonical signature / selector calculation.
detection/AbiDetectionPipelineTest Facade integration test, including a real-bundle excerpt fixture.
detection/DetectedAbiStoreTest Persistence + selector index + FIFO eviction + restart-reload semantics.
detection/AbiDetectionScanCheckTest Scan check happy path, dedup contract, audit-issue detail format.
RequestContextStoreTest Context store keying/retrieval semantics.

Fixtures live in src/test/resources/ (sample contract ABIs, decoder edge cases, captured real-transaction cases, and a trimmed minified-bundle excerpt for ABI detection at abi-detection/hive-auth-svelte-excerpt.js).

Notes & loose ends

  • gradle/libs.versions.toml is a gradle init leftover (declares guava and a junit-jupiter alias) and is not referenced by build.gradle, which pins versions directly. Treat the catalog as vestigial.
  • Main-Class is ABIInputDecoder — the packaged jar doubles as a small CLI for decoding/encoding from an ABI file (see TECH_STACK.md).
  • Jackson and BouncyCastle are not declared directly; they arrive transitively through org.web3j:core.