Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 110 additions & 0 deletions .claude-flow/metrics/system-metrics.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
[
{
"timestamp": 1755890431041,
"memoryTotal": 549755813888,
"memoryUsed": 511922192384,
"memoryFree": 37833621504,
"memoryUsagePercent": 93.11810433864594,
"memoryEfficiency": 6.881895661354065,
"cpuCount": 32,
"cpuLoad": 0.1175994873046875,
"platform": "darwin",
"uptime": 75174
},
{
"timestamp": 1755890461042,
"memoryTotal": 549755813888,
"memoryUsed": 512978010112,
"memoryFree": 36777803776,
"memoryUsagePercent": 93.31015646457672,
"memoryEfficiency": 6.689843535423279,
"cpuCount": 32,
"cpuLoad": 0.1191864013671875,
"platform": "darwin",
"uptime": 75204
},
{
"timestamp": 1755890491043,
"memoryTotal": 549755813888,
"memoryUsed": 508581625856,
"memoryFree": 41174188032,
"memoryUsagePercent": 92.51045882701874,
"memoryEfficiency": 7.489541172981262,
"cpuCount": 32,
"cpuLoad": 0.11566162109375,
"platform": "darwin",
"uptime": 75234
},
{
"timestamp": 1755890521044,
"memoryTotal": 549755813888,
"memoryUsed": 510043963392,
"memoryFree": 39711850496,
"memoryUsagePercent": 92.77645647525787,
"memoryEfficiency": 7.2235435247421265,
"cpuCount": 32,
"cpuLoad": 0.114990234375,
"platform": "darwin",
"uptime": 75264
},
{
"timestamp": 1755890551046,
"memoryTotal": 549755813888,
"memoryUsed": 511729025024,
"memoryFree": 38026788864,
"memoryUsagePercent": 93.08296740055084,
"memoryEfficiency": 6.917032599449158,
"cpuCount": 32,
"cpuLoad": 0.1104278564453125,
"platform": "darwin",
"uptime": 75294
},
{
"timestamp": 1755890581046,
"memoryTotal": 549755813888,
"memoryUsed": 510072913920,
"memoryFree": 39682899968,
"memoryUsagePercent": 92.78172254562378,
"memoryEfficiency": 7.218277454376221,
"cpuCount": 32,
"cpuLoad": 0.1017913818359375,
"platform": "darwin",
"uptime": 75324
},
{
"timestamp": 1755890611047,
"memoryTotal": 549755813888,
"memoryUsed": 509791354880,
"memoryFree": 39964459008,
"memoryUsagePercent": 92.73050725460052,
"memoryEfficiency": 7.269492745399475,
"cpuCount": 32,
"cpuLoad": 0.0872344970703125,
"platform": "darwin",
"uptime": 75354
},
{
"timestamp": 1755890641048,
"memoryTotal": 549755813888,
"memoryUsed": 509953163264,
"memoryFree": 39802650624,
"memoryUsagePercent": 92.75994002819061,
"memoryEfficiency": 7.240059971809387,
"cpuCount": 32,
"cpuLoad": 0.0832061767578125,
"platform": "darwin",
"uptime": 75384
},
{
"timestamp": 1755890671049,
"memoryTotal": 549755813888,
"memoryUsed": 509911793664,
"memoryFree": 39844020224,
"memoryUsagePercent": 92.75241494178772,
"memoryEfficiency": 7.24758505821228,
"cpuCount": 32,
"cpuLoad": 0.074127197265625,
"platform": "darwin",
"uptime": 75414
}
]
144 changes: 144 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Chainweb-node is the implementation of Kadena's Chainweb consensus protocol - a braided, parallelized Proof of Work blockchain architecture. The project is written in Haskell and uses Cabal as the build system.

## Build Commands

### Building the project
```bash
# Update cabal package index (do this occasionally)
cabal update

# Build all components
cabal build all

# Build specific components
cabal build chainweb # Main library
cabal build chainweb-node # Node executable
cabal build cwtools # Command-line tools
```

### Running tests
```bash
# Run all tests
cabal test chainweb-tests

# Run tests with specific patterns
cabal run chainweb-tests -- --hide-successes -p '!/chainweb216Test/'

# Run a single test module
cabal test chainweb-tests --test-options="-p 'Chainweb.Test.BlockHeaderDB'"
```

### Common development tasks
```bash
# Run the chainweb node
cabal run chainweb-node

# Get help and configuration options
cabal run chainweb-node -- --help
cabal run chainweb-node -- --print-config > config.yaml

# Build with optimizations
cabal build -O2 chainweb-node

# Clean build artifacts
cabal clean
```

## Architecture Overview

### Core Module Structure

The codebase is organized into several key areas:

- **src/Chainweb/**: Core blockchain implementation
- `BlockHeader/`: Block header management and genesis blocks
- `BlockHeaderDB/`: Block header database operations
- `CutDB/`: Cut (blockchain state) management
- `Mempool/`: Transaction mempool implementation
- `Miner/`: Mining-related functionality
- `Pact/`: Smart contract (Pact) integration
- `SPV/`: Simple Payment Verification proofs
- `Payload/`: Block payload management
- `RestAPI/`: REST API endpoints
- `VerifierPlugin/`: Pluggable verification systems (e.g., Hyperlane)

- **src/P2P/**: Peer-to-peer networking layer
- Bootstrap nodes configuration
- Peer discovery and communication

- **node/**: Chainweb-node executable
- Main entry point is `node/src/ChainwebNode.hs`

- **cwtools/**: Command-line utilities for debugging and maintenance

- **test/**: Test suites
- `unit/`: Unit tests
- `pact/`: Pact smart contract tests
- `multinode/`: Multi-node integration tests

### Key Architectural Concepts

1. **Chainweb Protocol**: Multiple parallel chains (20 chains in mainnet) that reference each other's block headers, creating a braided structure

2. **Cut**: The current state across all chains - essentially a snapshot of the latest block header on each chain

3. **Pact Integration**: Each chain runs its own Pact interpreter for smart contract execution

4. **P2P Network**: Nodes communicate via a custom P2P protocol for block propagation and synchronization

5. **Mining API**: Provides endpoints for external miners to get work and submit solutions

## Working with the Codebase

### Language Extensions
The project uses many GHC language extensions. Common ones include:
- OverloadedStrings
- LambdaCase
- TypeApplications
- ScopedTypeVariables
- FlexibleContexts

### External Dependencies
Key external dependencies managed via Cabal:
- pact (smart contract language)
- rocksdb-haskell (database backend)
- servant (REST API framework)
- yet-another-logger (logging)

Custom forks are specified in `cabal.project` as source-repository-packages.

### Database Backends
- RocksDB for block headers and payloads
- SQLite for Pact state

### Testing Approach
- Unit tests use HUnit and QuickCheck
- Integration tests use custom multi-node test framework
- Test data files in `test/pact/` and `test/golden/`
- CI runs tests on multiple GHC versions (9.6, 9.8, 9.10)

## Network Configuration

### Networks
- **mainnet01**: Production network
- **testnet04**: Test network
- **development**: Local development network

### Bootstrap Nodes
Hardcoded in `src/P2P/BootstrapNodes.hs`
- Mainnet: us-[e|w][1-3].chainweb.com, jp[1-3].chainweb.com, fr[1-3].chainweb.com
- Testnet: us[1-2].testnet.chainweb.com, eu[1-2].testnet.chainweb.com, ap[1-2].testnet.chainweb.com

## Important Files

- `cabal.project`: Cabal configuration with dependency overrides
- `chainweb.cabal`: Main library package definition
- `node/chainweb-node.cabal`: Node executable package
- `.github/workflows/`: CI/CD workflows
- `src/Chainweb/Version.hs`: Network version definitions
18 changes: 9 additions & 9 deletions flake.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 3 additions & 1 deletion src/Chainweb/BlockHeaderDB/RestAPI/Server.hs
Original file line number Diff line number Diff line change
Expand Up @@ -428,5 +428,7 @@ blockStreamHandler db withPayloads = Tagged $ \req resp -> do
}

f :: HeaderUpdate -> ServerEvent
f hu = ServerEvent (Just $ fromByteString "BlockHeader") Nothing
f hu = ServerEvent (Just $ fromByteString eventType) Nothing
[ fromLazyByteString . encode $ toJSON hu ]
where
eventType = if withPayloads then "Block" else "BlockHeader"
Loading