Architecture

Tidecoin Core is a Bitcoin Core v30-derived node with Tidecoin-specific consensus, wallet, proof-of-work, and post-quantum cryptography extensions. Most subsystems keep the Bitcoin Core shape; the project changes the cryptographic and consensus surfaces that Tidecoin needs to be post-quantum.

This page is a contributor map. It is not the consensus specification; use Protocol for normative rules.

Main Subsystems

Area	Main paths	Responsibility
Kernel and chain parameters	`src/kernel/`, `src/chainparams*`	Consensus parameters, network constants, deployment heights, genesis data
Validation	`src/validation.cpp`, `src/validationinterface.*`	Block, transaction, mempool, chainstate, and UTXO validation flow
Script	`src/script/`, `src/addresstype.cpp`	Script execution, script flags, descriptors, destination encoding
PQ cryptography	`src/pq/`	Falcon, ML-DSA, scheme registry, PQHD, ML-KEM-related code
AuxPoW	`src/auxpow.*`, mining and validation paths	Merged-mining header/proof handling and chain ID checks
Wallet	`src/wallet/`	Descriptor wallets, PQHD seed storage, signing, backup, wallet RPC
RPC, REST, ZMQ	`src/rpc/`, `src/wallet/rpc/`, `src/zmq/`	Node and wallet control APIs
P2P	`src/net*`, `src/net_processing.cpp`	Peer connections, message handling, relay, transport
Tests	`src/test/`, `test/functional/`, `src/test/fuzz/`	Unit, functional, and fuzz coverage

Validation Flow

The normal transaction and block flow is:


P2P/RPC input
  -> transaction or block parsing
  -> contextual validation
  -> script verification
  -> PQ signature verification where scripts require it
  -> mempool acceptance or block connection
  -> UTXO set update

For PQ signatures, the important script path is:


EvalScript()
  -> EvalChecksig()
  -> CheckPostQuantumSignature()
  -> VerifyPostQuantumSignature()
  -> CPubKey::Verify()
  -> pq::VerifyPrefixed()

Scheme selection comes from the prefix byte on the serialized PQ public key, not from wallet policy.

AuxPoW Flow

Post-AuxPoW blocks carry proof data that links a Tidecoin block candidate to a scrypt parent proof of work. Validation checks the parent proof, the commitment to the Tidecoin block hash, chain ID separation, and the local Tidecoin block rules.

AuxPoW activation also gates script and signature behavior, so mining changes and post-AuxPoW cryptographic features must be reviewed together.

Wallet Flow

Wallet code is not consensus-critical, but it creates consensus objects. PQHD wallet behavior should therefore be tested against protocol rules:


PQHD seed
  -> hardened derivation path
  -> scheme-specific keypair
  -> scheme-prefixed public key
  -> descriptor/address/script
  -> transaction signing

Descriptors and PSBT metadata can describe origins. They are not replacements for seed material.

Contributor Rule

When changing a subsystem, identify whether the change is:

consensus-critical;
wallet-policy-only;
relay-policy-only;
RPC/interface-only;
test-only;
documentation-only.

Consensus and cryptography changes require the broadest tests and review. Do not make them as incidental cleanup inside a larger patch.

See also: Repo Map, Testing, Protocol, Scheme Registry.