34128d8e98
Update go.mod module line, all require/replace directives, and every .go import path from forge.lthn.ai/core/go-blockchain to dappco.re/go/core/blockchain. Add replace directives to bridge dappco.re paths to existing forge.lthn.ai registry during migration. Update CLAUDE.md, README, and docs to reflect the new module path. Co-Authored-By: Virgil <virgil@lethean.io>
88 lines
4.4 KiB
Markdown
88 lines
4.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
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: `dappco.re/go/core/blockchain`
|
|
Licence: EUPL-1.2 (every source file carries the copyright header)
|
|
|
|
## Build
|
|
|
|
```bash
|
|
# 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
|
|
|
|
# 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 ./... # 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 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 trailer: `Co-Authored-By: Charon <charon@lethean.io>`
|
|
- 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 `dappco.re`, 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 `dappco.re/go/core/cli`. Subcommands: `chain sync` (P2P block sync) and `chain explorer` (TUI dashboard).
|
|
|
|
**Local replace directives:** `go.mod` uses `replace` to map `dappco.re/go/core/*` paths to `forge.lthn.ai/core/*` modules during migration.
|
|
|
|
## Docs
|
|
|
|
- `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
|