# wevm/ox architecture

> Architecture diagram of the GitHub repository wevm/ox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wevm/ox
- Repository: https://github.com/wevm/ox

## Overview

##### Main System Components
- Core Library Modules – Represent the bulk of the functionality within the src/core folder. This includes modules for:
– Ethereum data structures such as ABIs (Abi, AbiConstructor, AbiEvent, etc.)
– Cryptographic utilities (Secp256k1, P256, Bls, etc.)
– Transaction envelopes (various EIP-specific envelopes)
– Polymorphic utilities like Hex, Bytes, JSON-RPC, RLP, and more.
- Specialized Modules – Include additional directories and implementations such as:
– ERC modules: Separate subdirectories like src/erc4337 and src/erc6492 that build on the core primitives.
– Trusted setups: Located under src/trusted-setups for cryptographic parameters and protocols.
- Smart Contracts Integration – The contracts directory holds Solidity smart contracts and related scripts. This area forms the bridge with Ethereum on-chain logic.
- Examples and Documentation – The examples folder (e.g., webauthn-p256) demonstrates how to use Ox in realistic scenarios. Also, the site and scripts/docgen directories are used for generating and hosting documentation.
- Testing & Internal Utilities – Multiple _test directories within src/core, src/erc4337, src/erc6492, and additional tests in the root test folder illustrate the project’s emphasis on robust testing.

##### Relationships and Interactions
- The Core Library is the backbone and is used by all the specialized modules and examples.
- The ERC modules (ERC4337, ERC6492) are layered on top of the core primitives to provide additional functionalities related to Ethereum proposals.
- The Contracts segment interacts with the on-chain world and the TypeScript API (e.g., deployment scripts in the contracts/scripts folder).
- Testing components (found in src/core/_test, test, and vectors) should be represented as parallel blocks ensuring robustness; they “drive” the development of the main modules.

##### Treat Architectural Patterns and Design Principles
- Modularity – Each major feature (e.g., ABIs, Cryptography, Transactions) is encapsulated in its own module.
- Unopinionated & Stateless APIs – Show that functions (such as interface constructors, signing, and serialization) remain pure and stateless.
- The Functional Core (src/core)
- Extended functionality (ERC modules and Trusted setups)
- External interactions (Provider and contracts)
- Developer tooling and documentation (scripts, site)
- Testing/Validation – Include a testing block that interacts with nearly every module to affirm functionality.

##### Representing Technologies and Frameworks
- That the code is written in TypeScript, with Foundry-related configuration (contracts/foundry.toml, forge-std in contracts/lib) for Solidity contracts.
- The actions and GitHub workflows indicate continuous integration practices; you might include a “CI/CD” cloud component if desired.
- Documentation generation via scripts/docgen and site pages can be shown as a separate “Docs & Tooling” unit.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Ox Ethereum Standard Library (TypeScript)"]:::library

    subgraph "Core Modules"
        B["ABI Utilities"]:::core
        subgraph "Crypto Utilities"
            C1["Secp256k1"]:::core
            C2["P256"]:::core
            C3["Bls"]:::core
        end
        subgraph "Transaction Envelopes"
            D["TransactionEnvelope"]:::core
            D1["TransactionEnvelopeEip1559"]:::core
            D2["TransactionEnvelopeEip2930"]:::core
            D3["TransactionEnvelopeEip4844"]:::core
            D4["TransactionEnvelopeEip7702"]:::core
            D5["TransactionEnvelopeLegacy"]:::core
        end
        E["Provider (Web3 Interface)"]:::core
    end

    subgraph "Specialized Modules"
        F["ERC4337 Module"]:::special
        G["ERC6492 Module"]:::special
        H["Trusted Setups Module"]:::special
    end

    I["Smart Contracts"]:::external
    J["Documentation & Tooling"]:::docs
    K["Examples"]:::docs
    L["Testing Suites"]:::testing
    M["CI/CD"]:::cicd

    %% Relationships from the Library
    A -->|"uses"| B
    A -->|"uses"| E
    A -->|"extends"| F
    A -->|"interacts"| I
    A -->|"docs"| J
    A -->|"examples"| K
    A -->|"tests"| L
    A -->|"ci"| M

    %% Internal Core Relationships and Dependencies
    B -->|"foundation"| F
    B -->|"foundation"| G
    B -->|"foundation"| H
    D -->|"sendsEnvelope"| E
    E -->|"interactsWith"| I

    %% Testing associations from key modules
    B -->|"testedBy"| L
    E -->|"testedBy"| L
    F -->|"testedBy"| L
    I -->|"testedBy"| L

    %% Click Events
    click B "https://github.com/wevm/ox/tree/main/src/core"
    click C1 "https://github.com/wevm/ox/blob/main/src/core/Secp256k1.ts"
    click C2 "https://github.com/wevm/ox/blob/main/src/core/P256.ts"
    click C3 "https://github.com/wevm/ox/blob/main/src/core/Bls.ts"
    click D "https://github.com/wevm/ox/blob/main/src/core/TransactionEnvelope.ts"
    click D1 "https://github.com/wevm/ox/blob/main/src/core/TransactionEnvelopeEip1559.ts"
    click D2 "https://github.com/wevm/ox/blob/main/src/core/TransactionEnvelopeEip2930.ts"
    click D3 "https://github.com/wevm/ox/blob/main/src/core/TransactionEnvelopeEip4844.ts"
    click D4 "https://github.com/wevm/ox/blob/main/src/core/TransactionEnvelopeEip7702.ts"
    click D5 "https://github.com/wevm/ox/blob/main/src/core/TransactionEnvelopeLegacy.ts"
    click E "https://github.com/wevm/ox/blob/main/src/core/Provider.ts"
    click F "https://github.com/wevm/ox/tree/main/src/erc4337"
    click G "https://github.com/wevm/ox/tree/main/src/erc6492"
    click H "https://github.com/wevm/ox/tree/main/src/trusted-setups"
    click I "https://github.com/wevm/ox/tree/main/contracts"
    click J "https://github.com/wevm/ox/tree/main/site/"
    click K "https://github.com/wevm/ox/tree/main/examples/webauthn-p256"
    click L "https://github.com/wevm/ox/tree/main/test"

    %% Styles
    classDef library fill:#E6E6FA,stroke:#000,stroke-width:2px;
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef special fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef external fill:#FFDAB9,stroke:#000,stroke-width:2px;
    classDef docs fill:#FFEB99,stroke:#000,stroke-width:2px;
    classDef testing fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef cicd fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
