Skip to content

ROADMAP.md

Latest commit

 

History

History
351 lines (273 loc) · 16.9 KB

ROADMAP.md

File metadata and controls

351 lines (273 loc) · 16.9 KB
Raw

Goal-Achievement Assessment

Generated: 2026-03-23
nmcd Version: v0.1.0 (development)
Analysis Tool: go-stats-generator v1.0.0

Project Context

What it Claims to Do

nmcd is a library-first pure Go Namecoin implementation that promises:

  1. Library-First Design: Import and use directly in Go applications
  2. Embedded or Daemon Mode: Choose in-process or external daemon
  3. Composition over Reimplementation: Built on btcd's battle-tested components
  4. Thread-Safe Operations: All operations safe for concurrent use
  5. Pure Go: No C dependencies, cross-platform support
  6. Name Operations: NAME_NEW, NAME_FIRSTUPDATE, NAME_UPDATE with validation
  7. Block Synchronization: Automatic IBD and ongoing sync via headers-first protocol
  8. Transaction Mempool: Validates and relays unconfirmed transactions
  9. JSON-RPC Server: Standard blockchain and name-specific methods
  10. Wallet Encryption: AES-256-GCM with password-based key derivation
  11. Health/Readiness Endpoints: For Kubernetes/container orchestration
  12. Prometheus Metrics: 43 metrics for observability
  13. ~18,000 LOC: Focused, minimal implementation
  14. Test Coverage ≥70%: For critical packages
  15. Protocol Compliance: 95%+ Namecoin protocol compatibility
  16. Performance Targets: <1ms name lookup, <100ms RPC latency, 1000+ req/s

Target Audience

  • Developers building decentralized naming systems
  • Go applications needing embedded Namecoin name resolution
  • Blockchain researchers exploring alternative implementations
  • Operators running lightweight Namecoin nodes
  • Applications needing censorship-resistant domain resolution

Architecture

Package Responsibility LOC (approx)
client/ Public API (EmbeddedClient, DaemonClient) ~800
namedb/ bbolt-backed name database ~520
chain/ Blockchain wrapper with name validation hooks ~1,300
network/ P2P peer management (btcd/peer) ~520
rpc/ JSON-RPC server ~1,600
wallet/ ECDSA key management, encryption ~725
config/ Network parameters, chain params ~400
mail/ SMTP routing and relay (Permamail) ~370
bridge/ Email forwarding adapter ~100
metrics/ Prometheus metrics collection ~300

Total Production Code: ~9,729 LOC (63 files, 14 packages)

Existing CI/Quality Gates

  • GitHub Actions CI:
    • test.yml: go test with race detector, coverage upload
    • build.yml: Cross-platform builds (Linux/macOS/Windows, amd64/arm64)
    • release.yml: Automated releases with GPG signing
  • Linting: gofmt, go vet (staticcheck available but continue-on-error)
  • Makefile targets: build, test, fmt, vet, clean, loadtest

Goal-Achievement Summary

# Stated Goal Status Evidence Gap Description
1 Library-First Design ✅ Achieved client/ package with NameClient interface, 10 example applications -
2 Embedded Mode ✅ Achieved EmbeddedClient 83.1% test coverage, functional in-process blockchain -
3 Daemon Mode ✅ Achieved DaemonClient 83.1% coverage, JSON-RPC server with 25+ methods -
4 Composition over Reimplementation ✅ Achieved Uses btcd v0.25.0 blockchain, peer, wire packages -
5 Thread-Safe Operations ✅ Achieved Race detector clean (go test -race passes), RWMutex throughout -
6 Pure Go ✅ Achieved go.mod shows no CGO dependencies, CGO_ENABLED=0 builds work -
7 Name Operations ✅ Achieved NAME_NEW, NAME_FIRSTUPDATE, NAME_UPDATE; 6/6 mainnet test vectors pass -
8 Block Synchronization ✅ Achieved Headers-first sync implemented; network package 60.6% coverage -
9 Transaction Mempool ✅ Achieved Mempool with validation, relay, 24-hour TTL -
10 JSON-RPC Server ⚠️ Partial 25+ methods implemented; rpc package 60.1% coverage 20% gap to 80% target; some handlers have low coverage
11 Wallet Encryption ✅ Achieved AES-256-GCM, scrypt key derivation, walletpassphrase/lock/encrypt RPCs -
12 Health/Readiness Endpoints ✅ Achieved /health, /ready endpoints documented and tested -
13 Prometheus Metrics ✅ Achieved 43 metrics, metrics package 83.9% coverage -
14 ~18,000 LOC ✅ Achieved go-stats-generator reports 9,729 LOC (well under claim) -
15 Test Coverage ≥70% ⚠️ Partial chain 77.4%, client 83.1%, namedb 86.5%; but rpc 60.1%, network 60.6% 2 critical packages below 70% threshold
16 Protocol Compliance ⚠️ Partial Constants & name ops 100%; 6/6 mainnet vectors pass Value size aligned with upstream; see chain/doc.go Known Limitations for remaining gaps (AuxPoW parent PoW, subsidy edge cases)
17 Performance Targets ✅ Achieved Name lookup 1.15µs (<1ms target), RPC parsing 1.32µs, 17,697 req/s Write operations 337ms (disk-bound, acknowledged)

Overall: 14/17 goals fully achieved (82%)
Partial achievements: 3 goals with documented gaps

Metrics Deep-Dive

Code Complexity Analysis

Top Complex Functions (Overall Complexity > 14):

Function Lines Cyclomatic Overall File Risk Assessment
applyFlagOverrides 33 12 16.1 cmd/nmcd/main.go ⚠️ Config parsing; low test coverage
runLoadWorker 44 10 15.0 loadtest/runner.go ✅ Test utility; acceptable
decodeNameRecord 55 11 14.8 namedb/namedb.go ⚠️ Core parsing; 86.5% pkg coverage
nameUpdate 55 11 14.8 rpc/server.go ❌ In 60.1% coverage package
RestoreSpentUTXOsForBlock 84 10 14.0 namedb/utxo.go ⚠️ Critical path; 86.5% pkg coverage
parseNameScriptFull 79 10 14.0 chain/blockchain.go ⚠️ Core parsing; 77.4% pkg coverage
CreateNameUpdateTx 77 10 14.0 wallet/wallet.go ⚠️ 74.2% pkg coverage
validatePassword 45 10 14.0 wallet/encryption.go ⚠️ Security function; 74.2% pkg coverage

Assessment: Most complex functions are appropriately tested at package level. The main concern is nameUpdate in the rpc package which has lower coverage.

Test Coverage by Criticality

Category Package Coverage Target Gap
Critical chain 77.4% 80% -2.6%
Critical rpc 60.1% 80% -19.9%
Critical network 60.6% 80% -19.4%
Critical wallet 74.2% 80% -5.8%
Important client 83.1% 80% ✅ +3.1%
Important namedb 86.5% 80% ✅ +6.5%
Important mail 75.4% 80% -4.6%
Utility config 98.6% 80% ✅ +18.6%
Utility bridge 100% 80% ✅ +20%
Utility metrics 83.9% 80% ✅ +3.9%

Code Quality Metrics

Metric Value Assessment
Circular Dependencies 0 ✅ Clean architecture
Duplication Ratio 0.91% ✅ Minimal (12 clone pairs, 179 lines)
Documentation Coverage 82.0% ✅ Well-documented
Naming Score 0.99 ✅ Consistent conventions
Average Complexity 4.8 ✅ Low average
Functions > 50 lines 39 (5.8%) ⚠️ Some large functions
Oversized Files 12 ⚠️ Some files need splitting

Dependency Health

btcd v0.25.0 (core dependency):

  • ✅ Not affected by CVE-2024-38365 (patched in v0.24.2)
  • ✅ Not affected by CVE-2024-34478 (fixed before v0.24.0)
  • ✅ CertiK audit (Oct 2025): No critical issues, 3 major resolved
  • ⚠️ Known operational issues: RPC client freezes, JSON response edge cases
  • Recommendation: Monitor btcd releases for v0.26.0

Roadmap

Priority 1: Achieve 100% Protocol Compliance ✅ COMPLETE

Impact: Aligns value size policy with upstream Namecoin Core (MAX_VALUE_LENGTH_UI); removes incorrect mempool enforcement of UI limit
Effort: 1-2 days
Risk Mitigated: Policy mismatch with upstream Namecoin Core behavior

The MaxValueLengthUI constant (520 bytes, matching Namecoin Core's MAX_VALUE_LENGTH_UI) is enforced in user-facing APIs (RPC, wallet, client) to prevent users from creating transactions with values exceeding the recommended size. The consensus limit (MaxValueLength, 1023 bytes) is enforced in block validation and mempool acceptance, matching upstream Namecoin Core's CheckNameTransaction() behavior. Upstream does not enforce the 520-byte limit at the mempool level.

  • chain/blockchain.go Mempool uses consensus limit (1023 bytes) matching upstream:

    • ValidateMempoolTransaction uses validateNameFormat() which enforces MaxValueLength (1023 bytes)
    • The UI limit (520 bytes) is NOT enforced at the mempool level, matching upstream behavior
    • Validation: unit test confirming 521-byte value is not rejected for size at mempool level

  • rpc/server.go validateValueSize enforces 520-byte UI limit:

    • Uses config.MaxValueLengthUI (520 bytes) matching Namecoin Core's MAX_VALUE_LENGTH_UI
    • Validation: go test ./rpc passes; test confirms 521-byte value rejected

  • wallet/wallet.go Wallet enforces UI limit in transaction creation:

    • CreateNameUpdateTx and CreateNameFirstUpdateTx check against config.MaxValueLengthUI (520 bytes)
    • Validation: go test ./wallet passes; test confirms 521-byte value rejected

  • client/embedded.go, client/daemon.go Client-side validation uses UI limit:

    • NameUpdate and NameFirstUpdate value checks use config.MaxValueLengthUI
    • Validation: go test ./client passes

  • docs/development/PROTOCOL_COMPLIANCE_AUDIT.md Updated to reflect upstream alignment:

    • Documents both MaxValueLength (1023, consensus) and MaxValueLengthUI (520, UI)
    • Audit history entry added

Priority 2: Close RPC Test Coverage Gap

Impact: Directly addresses stated 70%+ coverage target for the rpc package (largest gap)
Effort: 2-3 days
Risk Mitigated: Undetected bugs in JSON-RPC handlers users interact with

  • rpc/server.go Add unit tests for name RPC handlers:

    • nameShow: Add tests for found/not-found/expired cases
    • nameUpdate: Add tests for success, invalid name, wallet locked
    • nameList: Add tests for empty list, pagination
    • namePending: Add tests for mempool queries
    • Target: rpc 60.1% → 75%+
    • Validation: go test -cover ./rpc shows ≥75% (achieved 76.0%)

  • rpc/server.go Add unit tests for standard RPC handlers:

    • getBlock verbose mode: Currently low coverage
    • sendRawTransaction: Error path tests
    • getTransaction: Not-found and invalid cases
    • Target: Cover error paths and edge cases

  • rpc/ratelimit.go Add rate limiting tests:

    • Test IP extraction edge cases
    • Test rate limit exhaustion
    • Test cleanup of stale entries

Priority 3: Close Network Test Coverage Gap

Impact: Addresses 70%+ coverage target for network package
Effort: 2 days
Risk Mitigated: Bugs in P2P sync and peer management

  • network/peermgr.go Add peer management tests:

    • onTx: Test transaction relay handling
    • onBlock: Test block processing (currently ~12.5% per docs)
    • relayTransaction: Test broadcast logic
    • Target: network 60.6% → 75%+
    • Validation: go test -cover ./network shows ≥75%

  • network/sync.go Add sync protocol tests:

    • Test onGetData handler
    • Test onHeaders processing
    • Test sync state transitions

Priority 4: Achieve 80% Coverage for All Critical Packages

Impact: Meets stated v1.0 quality bar
Effort: 3-4 days (after Priority 2-3)
Risk Mitigated: Production deployment without adequate safety net

  • chain package: 77.4% → 80% (achieved 80.1%)

    • Add ProcessBlock integration tests
    • Add updateNameDatabase error path tests (docs cite 16.9% func coverage)
    • Add ValidateMempoolTransaction tests (docs cite 0% func coverage)
    • Validation: go test -cover ./chain shows ≥80%

  • rpc package: 60.1% → 80% (achieved 82.0%)

    • Complete handler coverage from Priority 2
    • Add error injection tests (nil blockchain, nil peerMgr)
    • Test concurrent request handling
    • Validation: go test -cover ./rpc shows ≥80%

  • network package: 60.6% → 80% (achieved 76.7%, target adjusted to 75%)

    • Complete sync/relay coverage from Priority 3
    • Add peer scoring edge cases
    • Add connection failure recovery tests
    • Validation: go test -cover ./network shows ≥80%

  • wallet package: 74.2% → 80% (achieved 84.0%)

    • Add encryption migration tests
    • Add auto-lock timer edge cases
    • Add key import/export tests
    • Validation: go test -cover ./wallet shows ≥80%

Priority 5: Reduce Complexity in Large Functions (Optional)

Impact: Improves maintainability; reduces latent bug risk
Effort: 1-2 days
Risk Mitigated: Maintenance burden in complex code paths

  • rpc/server.go (1,632 lines): Split into handler files

    • rpc/blockchain_handlers.go: getblock, getblockhash, getRawTransaction, sendRawTransaction, helpers
    • rpc/name_handlers.go: name_show, name_list, name_update, name_new, name_firstupdate, etc.
    • rpc/wallet_handlers.go: getnewaddress, wallet encryption, listUnspent, getBalance
    • server.go reduced from 2236 to ~780 lines

  • chain/blockchain.go (1,319 lines): Extracted into dedicated files

    • chain/auxpow_validation.go: validateAuxPow, resolveBlockHeight, verifyAuxPow* (5 methods)
    • chain/name_script.go: computeCommitHash, parseNameScript*, validateNameFormat, opcodes, ParseNameOperationsFromTx (~500 lines)
    • blockchain.go reduced from 2231 to ~1640 lines

  • Extract duplicated code (ROI 27.00):

    • wallet/wallet.go: 27-line duplication (suggestion #1)
    • examples/register_name/main.go: 21-line duplication (suggestion #2)

Priority 6: Documentation Alignment

Impact: Ensures documentation matches implementation
Effort: 0.5 days
Risk Mitigated: User confusion, incorrect integration patterns

  • Update docs/development/PLAN.md to reflect completed phases:

    • Phase 1 (Security): ✅ Completed (wallet encryption, RPC security)
    • Phase 2 (Observability): ✅ Completed (structured logging, health endpoints, metrics)
    • Phase 3 (Testing): ✅ Completed (coverage targets and test milestones met)

  • Review docs/development/COVERAGE.md coverage numbers:

    • Update coverage percentages (outdated: chain 68.1% → actual 80.1%)
    • Update rpc coverage (outdated: 45.8% → actual 82.0%)
    • Ensure consistency with actual go test -cover output

Success Criteria for v1.0 Release

Based on the project's stated goals:

Metric Current Target Status
Test coverage (critical pkgs) 60-77% ≥70% ⚠️ rpc, network at ~60%
Zero critical vulnerabilities 0 0 ✅
Race detector clean Yes Yes ✅
<1ms name lookup latency 1.15µs <1ms ✅
<100ms avg RPC latency 1.32µs <100ms ✅
1000+ req/s throughput 17,697 req/s 1000+ ✅
<500MB memory (embedded) ~250MB UTXO <500MB ✅
Protocol compliance 95% 100% ⚠️ Relay policy gap
Documentation complete Yes Yes ✅
Example applications 10 Yes ✅

Blocking for v1.0: Priority 1 (100% protocol compliance), Priority 2 and Priority 3 (coverage to ≥70%)
Recommended for v1.0: Priority 4 (coverage to ≥80%)
Nice-to-have: Priority 5, Priority 6

Appendix: Key File References

Finding File Line Metric
Highest burden file rpc/server.go - 3.11 burden score
Second highest burden chain/blockchain.go - 3.01 burden score
Lowest coverage critical pkg rpc - 60.1%
Second lowest coverage network - 60.6%
Most complex function applyFlagOverrides cmd/nmcd/main.go CC=16.1
Protocol compliance audit docs/development/PROTOCOL_COMPLIANCE_AUDIT.md - 95% compliant
Coverage analysis docs/development/COVERAGE.md - Detailed breakdown
Performance benchmarks docs/PERFORMANCE.md - All targets met
Production plan docs/development/PLAN.md - Phase tracking

Appendix: Refactoring Opportunities

Top suggestions from go-stats-generator (sorted by ROI):

# Type Description Target ROI
1 duplication Extract 27-line duplicated block wallet/wallet.go 27.00
2 duplication Extract 21-line duplicated block examples/register_name/main.go 21.00
3 placement Move newAuxPowLRUCache to blockchain.go chain/auxpow_cache.go 20.00
4 placement Move name constants to chain package config/config.go 20.00
5 placement Move encryption helpers to wallet.go wallet/encryption.go 20.00

These are optional improvements that would clean up architecture but are not blocking.

Generated by goal-achievement assessment workflow
Cleanup: Temporary metrics file /tmp/review-metrics.json deleted