Files
corona/Makefile
T
zeekay 261ad9d290 pulsar: lattice threshold kernel with key-era lifecycle + Pulsar-SHA3 + Nebula binding
Forked from github.com/luxfi/corona @ d09b2c2. Pulsar inherits the
2-round signing math byte-equal but adds blockchain-grade key
lifecycle and a SHA3-based domain-separated hash profile for
permissionless validator-set rotation.

Inherits from upstream Corona (byte-equal):
  - Sign1/Sign2/Combine 2-round signing math
  - Lattice ring R_q = Z_q[X]/(X^256+1), q = 0x1000000004A01
  - Module-LWE / Module-SIS hardness
  - NTT, Discrete-Gaussian Ziggurat, MAC layer

Replaces from upstream:
  - Broken Feldman-style DKG (pseudoinverse-recoverable). Replaced
    with: (a) one-time foundation MPC ceremony / trusted-dealer
    Bootstrap; (b) Pedersen DKG over R_q (research, dkg2/) hiding
    under MLWE on B / binding under MSIS on [A | B].
  - Trusted-dealer-per-epoch lifecycle (wrong shape for permissionless
    rotation). Replaced with Verifiable Secret Resharing (VSR) every
    epoch under the persistent group public key.

Key-era lifecycle (KeyEraID / Generation / RollbackFrom):
  - KeyEraID bumps only at Reanchor (rare governance event)
  - Generation bumps every Refresh / Reshare under the same GroupKey
  - RollbackFrom records prior generation reverted from (0 = forward)
  - Activation cert (QUASAR-PULSAR-ACTIVATE-v1) gates new generations
    under the unchanged GroupKey

Pulsar-SHA3 hash profile (NIST FIPS 202 / SP 800-185):
  - Hc:        cSHAKE256("PULSAR-HC-v1", transcript) → challenge
  - Hu:        cSHAKE256("PULSAR-HU-v1", transcript) → XOF stream
  - TranscriptHash: TupleHash256("PULSAR-TRANSCRIPT-v1", parts...)
  - PRF:       KMAC256(key, msg, "PULSAR-PRF-v1")
  - MAC:       KMAC256(key, msg, "PULSAR-MAC-v1")
  - Pairwise:  KMAC256(kex, encode(...), "PULSAR-PAIRWISE-v1")
  - Default suite is Pulsar-SHA3; Pulsar-BLAKE3 retained as optional
    non-normative fast profile. HashSuiteID is bound into transcripts.
  - Implementation at pulsar/hash/ with HashSuite interface.
  - All KATs regenerated under SHA3 profile; vectors in
    luxcpp/crypto/pulsar/test/kat/.

Nebula root binding (TranscriptInputs + ActivationMessage canonical
bytes, all bound under TupleHash256):
    chain_id, network_id, group_id,
    key_era_id, old_generation, new_generation,
    old_epoch_id, new_epoch_id,
    old_set_hash, new_set_hash,
    threshold_old, threshold_new,
    group_public_key_hash,
    nebula_root,
    hash_suite_id,
    implementation_version,
    variant.

Packages:
  primitives/   Shamir over R_q, Lagrange, hash helpers
  sign/         2-round sign math (byte-equal upstream)
  threshold/    GroupKey, KeyShare, Signer types
  reshare/      VSR kernel — Refresh (HJKY97 zero-poly), Reshare
                (Desmedt-Jajodia), commit (Pedersen R_q), complaint,
                transcript, pairwise KEX, activation cert
  hash/         HashSuite interface; PulsarSHA3 (default), PulsarBLAKE3
  dkg2/         Pedersen DKG over R_q (research, reference only)
  keyera/       Lifecycle wrapper: Bootstrap → Reshare → Reanchor
  papers/       LP-073-pulsar paper (sections + bibliography)
  cmd/*_oracle/ KAT generators (Go ↔ C++ byte-equal validation)

DESIGN.md is the single source of truth:
  - The Pulsar metaphor (rotating beam over persistent body)
  - Vocabulary stack per LP-105: Nebula / Photon / Lumen / Beam /
    Pulsar / Pulse / Prism / Horizon / Quasar
  - Pulsar ≠ Lumen (PQ stream is separate, planned)
  - Pulsar / Lens / LSS three-layer architecture
  - Bootstrap Dealer vs Signature Coordinator
  - No-slashing failure ladder (timeout → retry → rollback → reanchor)
  - MVP VSR vs Robust VSR phasing
  - Borrowed-brand terms ("X-Wing" used casually) replaced with
    "hybrid KEM" / "Hybrid Lumen Handshake"; X-Wing cited only as
    the IETF combiner primitive name where exact reference matters.

Tests: full suite green
  hash 5+/5+, keyera 5/5, reshare 45+/45+, threshold, sign, dkg,
  dkg2, primitives, networking, utils, corona_oracle_v2 KAT —
  all pass.

Honest claim: the crypto primitives are not new (HJKY97,
Desmedt-Jajodia97, Wong-Wang-Wing02, Corona, Hermine, Threshold
Raccoon all exist). The novel contribution is the systems
composition: a permissionless-consensus deployment architecture that
turns static two-round PQ threshold signatures into a dynamic,
leaderless, validator-rotation-tolerant finality layer.

Companion docs: papers/lp-073-pulsar/ (academic paper); LP-073 +
LP-103 + LP-105 in github.com/luxfi/lps; threshold/protocols/lss/
lss_pulsar.go (LSS adapter wrapping this kernel).
2026-03-03 12:00:00 -08:00

216 lines
5.6 KiB
Makefile

# Corona - Post-Quantum Threshold Signature Scheme
# Makefile for building, testing, and managing the project
.PHONY: all build test clean fmt lint vet coverage bench run help install-tools
# Go parameters
GOCMD=go
GOBUILD=$(GOCMD) build
GOCLEAN=$(GOCMD) clean
GOTEST=$(GOCMD) test
GOGET=$(GOCMD) get
GOMOD=$(GOCMD) mod
GOFMT=gofmt
GOVET=$(GOCMD) vet
GOLINT=golangci-lint
# Binary name
BINARY_NAME=corona
BINARY_PATH=./bin/$(BINARY_NAME)
# Test parameters
TEST_TIMEOUT=30s
BENCH_TIME=10s
COVERAGE_OUT=coverage.out
COVERAGE_HTML=coverage.html
# Build flags
LDFLAGS=-ldflags "-s -w"
BUILD_FLAGS=-v
# Default target
all: test build
## help: Display this help message
help:
@echo "Corona - Post-Quantum Threshold Signature Scheme"
@echo ""
@echo "Usage: make [target]"
@echo ""
@echo "Targets:"
@grep -E '^## ' Makefile | sed 's/## / /'
## build: Build the binary
build:
@echo "Building $(BINARY_NAME)..."
@mkdir -p bin
$(GOBUILD) $(BUILD_FLAGS) $(LDFLAGS) -o $(BINARY_PATH) .
@echo "Build complete: $(BINARY_PATH)"
## test: Run all tests
test:
@echo "Running tests..."
$(GOTEST) -v -timeout $(TEST_TIMEOUT) ./...
## test-short: Run short tests only
test-short:
@echo "Running short tests..."
$(GOTEST) -v -short -timeout $(TEST_TIMEOUT) ./...
## test-race: Run tests with race detector
test-race:
@echo "Running tests with race detector..."
$(GOTEST) -v -race -timeout $(TEST_TIMEOUT) ./...
## coverage: Generate test coverage report
coverage:
@echo "Generating coverage report..."
$(GOTEST) -v -coverprofile=$(COVERAGE_OUT) -covermode=atomic ./...
$(GOCMD) tool cover -html=$(COVERAGE_OUT) -o $(COVERAGE_HTML)
@echo "Coverage report generated: $(COVERAGE_HTML)"
@echo "Coverage summary:"
@$(GOCMD) tool cover -func=$(COVERAGE_OUT) | grep total | awk '{print "Total coverage: " $$3}'
## bench: Run benchmarks
bench:
@echo "Running benchmarks..."
$(GOTEST) -bench=. -benchtime=$(BENCH_TIME) -benchmem ./...
## bench-cpu: Run benchmarks with CPU profiling
bench-cpu:
@echo "Running benchmarks with CPU profiling..."
$(GOTEST) -bench=. -benchtime=$(BENCH_TIME) -benchmem -cpuprofile=cpu.prof ./...
@echo "CPU profile saved to cpu.prof"
@echo "View with: go tool pprof cpu.prof"
## bench-mem: Run benchmarks with memory profiling
bench-mem:
@echo "Running benchmarks with memory profiling..."
$(GOTEST) -bench=. -benchtime=$(BENCH_TIME) -benchmem -memprofile=mem.prof ./...
@echo "Memory profile saved to mem.prof"
@echo "View with: go tool pprof mem.prof"
## fmt: Format Go code
fmt:
@echo "Formatting code..."
$(GOFMT) -w -s .
@echo "Code formatting complete"
## lint: Run linter
lint:
@echo "Running linter..."
@if command -v golangci-lint >/dev/null 2>&1; then \
$(GOLINT) run ./...; \
else \
echo "golangci-lint not installed. Run 'make install-tools' to install it."; \
exit 1; \
fi
## vet: Run go vet
vet:
@echo "Running go vet..."
$(GOVET) ./...
## mod: Download and tidy Go modules
mod:
@echo "Downloading dependencies..."
$(GOMOD) download
@echo "Tidying modules..."
$(GOMOD) tidy
@echo "Verifying modules..."
$(GOMOD) verify
## clean: Clean build artifacts
clean:
@echo "Cleaning build artifacts..."
$(GOCLEAN)
@rm -rf bin/
@rm -f $(COVERAGE_OUT) $(COVERAGE_HTML)
@rm -f *.prof
@rm -f *.test
@echo "Clean complete"
## install: Install the binary to GOPATH/bin
install: build
@echo "Installing $(BINARY_NAME) to $(GOPATH)/bin..."
@cp $(BINARY_PATH) $(GOPATH)/bin/
@echo "Installation complete"
## install-tools: Install development tools
install-tools:
@echo "Installing development tools..."
@echo "Installing golangci-lint..."
@go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
@echo "Installing goimports..."
@go install golang.org/x/tools/cmd/goimports@latest
@echo "Installing staticcheck..."
@go install honnef.co/go/tools/cmd/staticcheck@latest
@echo "Tools installation complete"
## run: Run the application with default parameters
run: build
@echo "Running $(BINARY_NAME)..."
$(BINARY_PATH)
## run-local: Run local simulation
run-local: build
@echo "Running local simulation..."
$(BINARY_PATH) l 0 0
## run-party: Run as party (requires party ID, IP, and port)
run-party: build
@if [ -z "$(PARTY_ID)" ] || [ -z "$(IP)" ] || [ -z "$(PORT)" ]; then \
echo "Usage: make run-party PARTY_ID=1 IP=127.0.0.1 PORT=8000"; \
exit 1; \
fi
@echo "Running as party $(PARTY_ID) on $(IP):$(PORT)..."
$(BINARY_PATH) $(PARTY_ID) $(IP) $(PORT)
## docker-build: Build Docker image
docker-build:
@echo "Building Docker image..."
docker build -t corona:latest .
## docker-run: Run Docker container
docker-run: docker-build
@echo "Running Docker container..."
docker run --rm -it corona:latest
## ci: Run CI pipeline locally (format, vet, lint, test, build)
ci: fmt vet lint test-race coverage build
@echo "CI pipeline complete"
## check: Quick check (format, vet, test)
check: fmt vet test-short
@echo "Quick check complete"
## update: Update dependencies to latest versions
update:
@echo "Updating dependencies..."
$(GOGET) -u ./...
$(GOMOD) tidy
@echo "Dependencies updated"
## version: Display Go version and module info
version:
@echo "Go version:"
@$(GOCMD) version
@echo ""
@echo "Module info:"
@$(GOCMD) list -m all | head -5
## stats: Display code statistics
stats:
@echo "Code statistics:"
@echo " Lines of code:"
@find . -name "*.go" -not -path "./vendor/*" | xargs wc -l | tail -1
@echo " Number of Go files:"
@find . -name "*.go" -not -path "./vendor/*" | wc -l
@echo " Number of test files:"
@find . -name "*_test.go" -not -path "./vendor/*" | wc -l
# Create necessary directories
init:
@mkdir -p bin
.DEFAULT_GOAL := help