# karpathy/cryptos architecture

> Architecture diagram of the GitHub repository karpathy/cryptos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/karpathy/cryptos
- Repository: https://github.com/karpathy/cryptos

## Overview

##### Main Components

a) Core Cryptographic Components:
- SHA-256 Hash Function
- RIPEMD160 Hash Function
- Elliptic Curve Operations
- ECDSA Digital Signatures

b) Bitcoin Protocol Components:
- Key Management System
- Transaction Processing
- Block Processing
- Network Communication

**[SHA-256] --- [RIPEMD160] --- [Elliptic Curves]**
- /
- /
- [ECDSA Implementation]

**[Keys Management] --- [Transaction Processing] --- [Block Processing]**

- v                    v                         v
- [Address Gen]        [Tx Validation]         [Block Validation]

**[Simple Node Implementation]**

- v
**[Bitcoin Protocol Handler]**

##### Important Elements to Highlight

- How data flows from cryptographic primitives up to higher-level functions
- How network communication interfaces with other components

- Blue: Cryptographic primitives (sha256.py, ripemd160.py, curves.py)
- Green: Bitcoin-specific components (transaction.py, block.py)
- Yellow: Network components (network.py)
- Purple: Key management (keys.py, ecdsa.py)

##### Component Relationships

How components interact:
**[User Interface (getnewaddress.py)]**
- ↓
**[Keys Management] → [Address Generation]**
- ↓
**[Transaction Processing] ← [ECDSA Signing/Verification]**
- ↓
**[Block Processing] ← [Proof of Work Validation]**
- ↓
**[Network Layer] ← [Protocol Messages]**

##### Testing Layer

A separate section showing test coverage:
**[Unit Tests]**
- ↓
**[test_block.py] [test_ecdsa.py] [test_hash.py]**
**[test_keys.py] [test_network.py] [test_tx.py]**

##### Implementation Notes

Annotations for:
- Pure Python implementation
- Educational focus
- Performance considerations
- Security limitations

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef crypto fill:#b3e0ff,stroke:#333
    classDef bitcoin fill:#90EE90,stroke:#333
    classDef network fill:#ffeb99,stroke:#333
    classDef keys fill:#DDA0DD,stroke:#333
    classDef test fill:#FFB6C1,stroke:#333
    classDef interface fill:#F0F8FF,stroke:#333

    %% Cryptographic Primitives Layer
    subgraph Cryptographic_Layer
        SHA["SHA-256"]:::crypto
        RIPE["RIPEMD160"]:::crypto
        EC["Elliptic Curves"]:::crypto
        ECDSA["ECDSA Implementation"]:::crypto
        
        SHA --> ECDSA
        RIPE --> ECDSA
        EC --> ECDSA
    end

    %% Bitcoin Core Components Layer
    subgraph Bitcoin_Core_Layer
        KM["Keys Management"]:::keys
        TP["Transaction Processing"]:::bitcoin
        BP["Block Processing"]:::bitcoin
        AG["Address Generation"]:::keys
        TV["Transaction Validation"]:::bitcoin
        BV["Block Validation"]:::bitcoin
        
        KM --> AG
        KM --> TP
        TP --> TV
        BP --> BV
    end

    %% Network Layer
    subgraph Network_Layer
        NI["Simple Node Implementation"]:::network
        PH["Bitcoin Protocol Handler"]:::network
        
        NI --> PH
    end

    %% Testing Layer
    subgraph Testing_Layer
        UT["Unit Tests"]:::test
        TB["test_block.py"]:::test
        TE["test_ecdsa.py"]:::test
        TH["test_hash.py"]:::test
        TK["test_keys.py"]:::test
        TN["test_network.py"]:::test
        TT["test_tx.py"]:::test
        
        UT --> TB & TE & TH & TK & TN & TT
    end

    %% Interface Layer
    UI["User Interface (getnewaddress.py)"]:::interface

    %% Relationships between layers
    ECDSA --> KM
    KM --> TP
    TP --> BP
    BP --> NI
    UI --> KM

    %% Click events for component mapping
    click SHA "https://github.com/karpathy/cryptos/blob/main/cryptos/sha256.py"
    click RIPE "https://github.com/karpathy/cryptos/blob/main/cryptos/ripemd160.py"
    click EC "https://github.com/karpathy/cryptos/blob/main/cryptos/curves.py"
    click ECDSA "https://github.com/karpathy/cryptos/blob/main/cryptos/ecdsa.py"
    click KM "https://github.com/karpathy/cryptos/blob/main/cryptos/keys.py"
    click TP "https://github.com/karpathy/cryptos/blob/main/cryptos/transaction.py"
    click BP "https://github.com/karpathy/cryptos/blob/main/cryptos/block.py"
    click NI "https://github.com/karpathy/cryptos/blob/main/cryptos/network.py"
    click UI "https://github.com/karpathy/cryptos/blob/main/getnewaddress.py"
    click TB "https://github.com/karpathy/cryptos/blob/main/tests/test_block.py"
    click TE "https://github.com/karpathy/cryptos/blob/main/tests/test_ecdsa.py"
    click TH "https://github.com/karpathy/cryptos/blob/main/tests/test_hash.py"
    click TK "https://github.com/karpathy/cryptos/blob/main/tests/test_keys.py"
    click TN "https://github.com/karpathy/cryptos/blob/main/tests/test_network.py"
    click TT "https://github.com/karpathy/cryptos/blob/main/tests/test_tx.py"

    %% Legend
    subgraph Legend
        L1["Cryptographic Components"]:::crypto
        L2["Bitcoin Components"]:::bitcoin
        L3["Network Components"]:::network
        L4["Key Management"]:::keys
        L5["Testing Components"]:::test
        L6["Interface Components"]:::interface
    end
```
