From d0c64c8ad692d84c3aa9418443c329dcb8f3e9a3 Mon Sep 17 00:00:00 2001 From: Snider Date: Fri, 13 Mar 2026 13:38:01 +0000 Subject: [PATCH] docs: add CLAUDE.md project instructions Co-Authored-By: Virgil --- CLAUDE.md | 76 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 62 insertions(+), 14 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 85346ac..8a6cb68 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,40 +1,88 @@ # CLAUDE.md -Go implementation of the Lethean blockchain protocol with CGo crypto bridge. +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +Go implementation of the Lethean blockchain protocol (CryptoNote/Zano-fork) with a CGo crypto bridge. Module: `forge.lthn.ai/core/go-blockchain` +Licence: EUPL-1.2 (every source file carries the copyright header) ## Build ```bash -# First time: build the crypto C++ library (requires cmake, g++, libssl-dev, libboost-dev) +# First time: build the C++ crypto library (requires cmake, g++/clang, libssl-dev, libboost-dev) cmake -S crypto -B crypto/build -DCMAKE_BUILD_TYPE=Release cmake --build crypto/build --parallel -# Then: run tests +# Run tests (race detector required before commit) go test -race ./... go vet ./... ``` +Pure Go packages (`config/`, `types/`, `wire/`, `difficulty/`) build without a C toolchain. Packages that use CGo (`crypto/`, `consensus/`, `chain/`, `wallet/`, `mining/`) require `libcryptonote.a` from the cmake step. + ## Commands ```bash -go test ./... # run all tests -go test -race ./... # race detector (required before commit) -go test -v -run Name ./... # single test -go vet ./... # vet check -cmake --build crypto/build --parallel # rebuild C++ after bridge.cpp changes +go test ./... # all tests +go test -race ./... # race detector (required before commit) +go test -v -run TestName ./pkg/ # single test +go test -v -run "TestName/subtest" ./pkg/ # single subtest +go vet ./... # vet check +go mod tidy # must produce no changes before commit +cmake --build crypto/build --parallel # rebuild after bridge.cpp changes +go test -tags integration ./... # integration tests (need C++ testnet daemon) ``` ## Standards -- UK English -- `go test -race ./...` and `go vet ./...` must pass before commit +- UK English throughout (colour, serialise, behaviour — in identifiers, comments, docs) +- `go test -race ./...`, `go vet ./...`, and `go mod tidy` must all pass before commit - Conventional commits: `type(scope): description` -- Co-Author: `Co-Authored-By: Charon ` +- Co-Author trailer: `Co-Authored-By: Charon ` +- Error strings: `package: description` format (e.g. `types: invalid hex for hash`) +- Error wrapping: `fmt.Errorf("package: description: %w", err)` +- Import order: stdlib, then `golang.org/x`, then `forge.lthn.ai`, blank lines between groups +- No emojis in code or comments + +## Test Conventions + +- Tests use `_Good`, `_Bad`, `_Ugly` suffix pattern (happy path / expected errors / edge cases) +- Table-driven subtests with `t.Run()` are the norm +- Use stdlib `testing` package directly (`t.Error`, `t.Errorf`, `t.Fatal`) — testify is a dependency but tests in core packages use stdlib assertions +- Integration tests are build-tagged (`//go:build integration`) and need a C++ testnet daemon on `localhost:46941` + +## Architecture + +``` +consensus ← standalone validation (pure functions, no storage dependency) + ↓ + chain ← persistent storage (go-store/SQLite), RPC + P2P sync + ↓ +p2p / rpc / wallet ← network and wallet layer + ↓ + wire ← consensus-critical binary serialisation + ↓ +types / config ← leaf packages (stdlib only, no internal deps) + ↓ + crypto ← CGo boundary (libcryptonote.a + librandomx.a) +``` + +**Key design decisions:** +- `consensus/` is pure — takes types + config + height, returns errors. No dependency on `chain/` or storage. +- `wire/` stores extra, attachment, and proof fields as opaque raw bytes for bit-identical round-tripping without implementing all variant types. +- `crypto/` follows ADR-001: Go shell + C++ crypto library. 29-function C API in `bridge.h`, only `uint8_t*` pointers cross the boundary. Upstream C++ from Zano commit `fa1608cf` in `crypto/upstream/`. +- On-chain curve points are stored premultiplied by cofactor inverse (1/8). `PointMul8`/`PointDiv8` convert between representations. +- Transaction wire format differs between versions: v0/v1 is `version, vin, vout, extra, [signatures]`; v2+ is `version, vin, extra, vout, [hardfork_id], [attachment, signatures, proofs]`. +- Block hash includes a varint length prefix: `Keccak256(varint(len) || block_hashing_blob)`. +- Two P2P varint formats exist: CryptoNote LEB128 (`wire/`) and portable storage 2-bit size mark (`go-p2p/node/levin/`). + +**Binary:** `cmd/core-chain/` — cobra CLI via `forge.lthn.ai/core/cli`. Subcommands: `chain sync` (P2P block sync) and `chain explorer` (TUI dashboard). + +**Local replace directives:** `go.mod` uses local `replace` for sibling `forge.lthn.ai/core/*` modules. ## Docs -- `docs/architecture.md` -- package structure, key types, design decisions, ADR-001 -- `docs/development.md` -- prerequisites, test patterns, coding standards -- `docs/history.md` -- completed phases with commit hashes, known limitations +- `docs/architecture.md` — package structure, key types, wire format details +- `docs/development.md` — prerequisites, test patterns, coding standards, coverage +- `docs/history.md` — completed phases with commit hashes, known limitations