core/go-blockchain
8
0
Fork 0
Code Issues 5 Pull requests Projects Releases Packages Wiki Activity Actions 2
Page: Development Phases
Pages
Architecture Chain Parameters Crypto Primitives Data Structures Development Phases Hardfork Schedule Home P2P Protocol RPC Reference
1 Development Phases
Claude edited this page 2026-02-20 15:12:17 +00:00
Table of Contents

Development Phases

The go-blockchain package is being developed in 9 phases, from foundational types through to a fully operational node. Each phase builds on the previous and has clear deliverables and test criteria.

Phase 0: Config + Types

Status: Active

Delivers:

  • config/ package: ChainConfig struct with all chain parameters, Mainnet and Testnet pre-defined instances
  • config/ hardfork schedule: HardFork struct, MainnetForks and TestnetForks slices, VersionAtHeight() lookup
  • types/ package: Fundamental types (Hash, PublicKey, SecretKey, KeyImage, Signature as [32]byte / [64]byte aliases)
  • types/ address: AccountPublicAddress struct, base58 encode/decode with Keccak-256 checksum, prefix validation
  • types/ block and transaction structs: BlockHeader, Block, TransactionPrefix, Transaction, input/output variant types
  • wire/ varint: CryptoNote varint encoding (7-bit, MSB continuation)
  • difficulty/ initial: LWMA difficulty calculation stub with test vectors
  • Wiki pages populated

Dependencies: None (stdlib only).

Test criteria:

  • go test ./... passes with race detector
  • go vet ./... clean
  • Address encode/decode round-trips match C++ output
  • Config constants match currency_config.h.in + default.cmake exactly
  • Varint encoding matches CryptoNote reference vectors

Phase 1: Wire Format + Serialisation

Delivers:

  • wire/ package: Consensus-critical binary serialisation for all block and transaction types
  • Serialisation must be bit-identical to C++ output for the same input
  • Variant type serialisation (tagged unions for inputs, outputs, signatures, extras)
  • Block hash computation (header hash + miner tx hash + Merkle root)
  • Transaction hash computation (prefix hash)

Dependencies: Phase 0 (types, config).

Test criteria:

  • Serialise/deserialise actual mainnet block hex blobs and verify round-trip
  • Serialise/deserialise actual mainnet transaction hex blobs
  • Computed block and transaction hashes match C++ node output
  • Tree hash for Merkle root matches reference vectors

Phase 2: CGo Crypto Bridge

Delivers:

  • Build system for libcryptonote from cleaned C++ source
  • crypto/ package with CGo wrappers:
    • Hash functions: cn_fast_hash (Keccak-256), tree_hash
    • Key derivation: generate_key_derivation, derive_public_key, derive_secret_key
    • Stealth addresses: one-time key generation and detection
    • Key images: generate_key_image
    • Ring signature verification: classic CryptoNote (check_ring_signature)
  • Build tags: //go:build cgo for real crypto, stubs without
  • Memory-safe wrappers (no C pointers leak to Go heap)

Dependencies: Phase 0 (types).

Test criteria:

  • Key derivation output matches C++ for known test vectors
  • Key image generation matches C++ for known keypairs
  • Ring signature verification accepts valid sigs, rejects invalid
  • No memory leaks under -race and CGo sanitiser

Phase 3: RPC Client

Delivers:

  • rpc/ package: JSON-RPC 2.0 client for daemon and wallet APIs
  • Daemon client: getinfo, getheight, getblocktemplate, submitblock, gettransactions, getblockheaderbyheight, getblockheaderbyhash
  • Wallet client: getbalance, getaddress, transfer
  • Binary endpoint support for fast sync (getblocks.bin)
  • Integration with the core CLI: core chain status, core chain info

Dependencies: Phase 0 (types, config), Phase 1 (wire, for binary endpoints).

Test criteria:

  • Successful RPC calls against a running C++ testnet node
  • Correct deserialisation of all response types
  • Error handling for connection failures and invalid responses

Phase 4: Difficulty + Consensus Rules

Delivers:

  • difficulty/ package: Full LWMA difficulty algorithm for both PoW and PoS
  • consensus/ package:
    • Block reward calculation (fixed 1 LTHN)
    • Fee policy (0.01 LTHN default, fee burn)
    • Block validation rules per hardfork version
    • Timestamp validation (median check, future limit)
    • Transaction validation rules (input/output counts, version checks, decoy set size)

Dependencies: Phase 0 (config, types), Phase 1 (wire), Phase 2 (crypto for hash verification).

Test criteria:

  • Difficulty calculation matches C++ output for first 1,000 mainnet blocks
  • Block reward returns correct value at all hardfork boundaries
  • Timestamp validation accepts/rejects correctly against median window
  • Fee policy matches C++ node behaviour

Phase 5: P2P Protocol

Delivers:

  • p2p/ package: Levin binary protocol implementation
    • 33-byte header encoding/decoding
    • Epee portable storage serialisation for payloads
    • COMMAND_HANDSHAKE (1001): connection establishment with network ID and sync data
    • COMMAND_TIMED_SYNC (1002): periodic state exchange
    • COMMAND_PING (1003): connectivity verification
    • NOTIFY_NEW_BLOCK (2001): block propagation
    • NOTIFY_OR_INVOKE_NEW_TRANSACTIONS (2002): transaction propagation
    • NOTIFY_REQUEST_GET_OBJECTS (2003) + NOTIFY_RESPONSE_GET_OBJECTS (2004): object fetch
    • NOTIFY_REQUEST_CHAIN (2006) + NOTIFY_RESPONSE_CHAIN_ENTRY (2007): chain sync
  • Peer list management (white list, grey list, 70% preference)
  • IP blocking after 10 failures (24-hour block)
  • Connection lifecycle management (timeouts, idle kill)

Dependencies: Phase 0 (config, types), Phase 1 (wire).

Test criteria:

  • Successful handshake with a C++ node
  • Receive and parse new block notifications
  • Chain sync downloads at least 100 blocks from a C++ peer
  • Peer list grows via handshake exchanges
  • Invalid handshakes (wrong network ID) are rejected

Phase 6: Blockchain Storage

Delivers:

  • chain/ package: Persistent blockchain database
    • Block and transaction storage (LMDB or Pebble backend, behind interface)
    • Output index: global output index mapping
    • Key image tracking: spent/unspent state
    • Chain state: current height, top block hash, cumulative difficulty
    • Chain reorganisation: detect and switch to a heavier chain
    • Checkpoint system for fast initial sync
    • Alternative block tracking (max CURRENCY_ALT_BLOCK_MAX_COUNT = 43,200)

Dependencies: Phase 0-2 (types, wire, crypto), Phase 4 (consensus for validation).

Test criteria:

  • Store and retrieve 10,000 blocks without data loss
  • Key image double-spend detection works correctly
  • Chain reorg correctly switches to a heavier fork
  • Database survives crash recovery (write-ahead log)

Phase 7: Wallet

Delivers:

  • wallet/ package:
    • Account key generation: seed phrase (mnemonic) to spend key + view key derivation
    • Output scanning: using view key to detect owned outputs in blocks
    • Balance calculation: sum of unspent, owned outputs
    • Transaction construction:
      • Input selection (age-based, amount-based)
      • Decoy ring construction (random output selection via RPC)
      • Output generation (stealth addresses)
      • Fee calculation
      • Signing via CGo crypto bridge (NLSAG for v1, ZC_sig/CLSAG for v2+)
    • Wallet file encryption (ChaCha8)
    • Payment ID handling (standard and integrated addresses)
    • Auditable wallet support

Dependencies: Phase 0-2 (types, wire, crypto), Phase 3 (RPC for output selection), Phase 4 (consensus for fee policy).

Test criteria:

  • Seed phrase generates identical keys to C++ wallet
  • Output scanning detects all owned outputs in test blocks
  • Constructed transactions are accepted by a C++ node
  • Wallet file encrypts and decrypts correctly

Phase 8: Full Node

Delivers:

  • Complete integration: P2P + chain storage + RPC server + mempool + wallet
  • CLI commands:
    • core chain serve -- Run a full node (P2P + RPC)
    • core chain mine -- PoW mining
    • core chain stake -- PoS staking
    • core wallet create -- Create new wallet
    • core wallet balance -- Show balance
    • core wallet transfer -- Send funds
    • core wallet stake -- Delegate stake
  • Mempool management:
    • Transaction validation before acceptance
    • Expiration handling (CURRENCY_MEMPOOL_TX_LIVETIME = 4 days)
    • Fee-based prioritisation
  • Block template construction (for both PoW and PoS)
  • Full chain sync from genesis against C++ network
  • Checkpoint verification

Dependencies: All prior phases.

Test criteria:

  • Go node syncs fully with the C++ testnet
  • Go node mines a valid PoW block accepted by C++ peers
  • Go node stakes a valid PoS block accepted by C++ peers
  • Go wallet sends a transaction accepted by C++ nodes
  • Go node serves RPC requests compatible with existing tooling

Phase Dependency Graph

Phase 0: Config + Types
    |
    +--- Phase 1: Wire Format
    |       |
    |       +--- Phase 3: RPC Client
    |       |       |
    |       +--- Phase 5: P2P Protocol
    |       |
    +--- Phase 2: CGo Crypto Bridge
            |
            +--- Phase 4: Difficulty + Consensus
            |       |
            |       +--- Phase 6: Blockchain Storage
            |
            +--- Phase 7: Wallet
                    |
                    +--- Phase 8: Full Node (integrates all)