QuantumCoin (Q) is a quantum-resistant blockchain that implements NIST post-quantum cryptography (PQC) algorithms for digital signatures and node-to-node key establishment. This repository (quantum-coin-go) is the Go implementation of the QuantumCoin node client, forked from go-ethereum.
Requires a Go toolchain compatible with the version declared in go.mod.
Build the node binary:
go build -o ./build ./...Check the documentation portal for information on running the blockchain node client.
To spin up a local development network populated with coins and prefilled wallets, see the QuantumCoin Devnet readme. Download the devnet package for your platform and just run connectvalidator.ps1 (Windows) or connectvalidator.sh (macOS/Ubuntu).
To interact with the QuantumCoin blockchain from JavaScript:
- quantumcoin.js — the recommended library for most applications. It provides an API closely compatible with ethers.js, so you can connect to nodes, query balances, send transactions, and work with smart contracts in the familiar ethers.js style.
- quantum-coin-js-sdk (npm) — use this if you only need lower-level functionality, such as wallet creation, transaction signing, and direct relay/RPC interaction. See the Quantum Coin SDK documentation for details and examples.
QuantumCoin uses a custom Proof-of-Stake (PoS) consensus engine with stake-weighted, multi-round Byzantine Fault Tolerant (BFT) consensus for immediate deterministic finality. Each block progresses through four message phases -- PROPOSAL, ACK_PROPOSAL, PRECOMMIT, COMMIT -- with a 67% (2/3) weighted deposit threshold for phase transitions. The protocol tolerates up to 1/3 Byzantine validators and guarantees safety unconditionally; liveness is guaranteed under partial synchrony assumptions (bounded message delay after GST), consistent with the FLP impossibility result.
| Document | Description |
|---|---|
| Consensus Protocol | Step-by-step protocol specification: phases, vote types, round escalation, fault model, FLP assumptions, and glossary. |
| TLA+ Specification | Formal TLA+ model of the protocol: Byzantine behaviors modeled, safety/liveness properties verified, fairness encoding, and model configurations. |
| TLA+ Verification Report | TLC model checking results: exhaustive state-space exploration for Safe (25%), Boundary (33%), and Unsafe (34%) Byzantine configurations with counterexample analysis. |
The consensus code lives under ./consensus/proofofstake.
| Component | PQC Algorithm | NIST Standard | Classical Algorithm | Hybrid |
|---|---|---|---|---|
| Signatures | ML-DSA-44/87, SLH-DSA-SHAKE-256f/s | FIPS 204, FIPS 205 | ed25519 | Yes |
| Key Establishment | ML-KEM-768 | FIPS 203 | X25519 | Yes |
All PQC-signature operations use hybrid constructions combining post-quantum and classical algorithms, ensuring security against both quantum and classical attackers.
QuantumCoin uses hybrid constructions (PQC + classical) so the system remains secure against both classical attackers and quantum-capable adversaries. Hybrid mode also provides a hedge if any single primitive is weakened. See: NIST PQC FAQs.
Algorithms used (NIST standard names):
- Signatures: ML-DSA (Module-Lattice Digital Signature Algorithm; standardized from Dilithium; FIPS 204), SLH-DSA (Stateless Hash-Based Digital Signature Algorithm; standardized from SPHINCS+; FIPS 205), plus ed25519 in a hybrid combiner.
- Key Establishment: ML-KEM (Module-Lattice Key Encapsulation Mechanism; standardized from Kyber; FIPS 203) in hybrid with X25519.
QuantumCoin implements multiple hybrid signature modes. At a high level, a hybrid signature is built from:
- PQC signature (e.g., ML-DSA and/or SLH-DSA), plus
- ed25519 (classical),
combined so that verification must succeed for all component signatures required by that mode. This means an attacker must break both the post-quantum and classical algorithms to forge a signature.
Two families of hybrid signatures exist in the codebase:
- Dilithium + Ed25519 + SPHINCS+ (legacy naming in code:
DILITHIUM_ED25519_SPHINCS_*) - ML-DSA + Ed25519 + SLH-DSA (FIPS-aligned naming in code:
MLDSA_ED25519_SLHDSA_*)
QuantumCoin supports a compact vs full approach:
- Compact mode: Signs with Ed25519 + ML-DSA only, for smaller on-chain size (default for most operations). The SLH-DSA public key is still embedded in the compact signature, so the hash-based component can be verified retroactively if a full signature is later produced for the same key pair.
- Full mode (break-glass): Signs with all three components (Ed25519 + ML-DSA + SLH-DSA) for defense-in-depth. Hash-based signatures like SLH-DSA provide security based on the well-understood properties of hash functions, offering an additional layer of protection even if lattice-based assumptions are compromised.
The post-quantum cryptography code lives under ./crypto. QuantumCoin uses a fork of Cloudflare's CIRCL library for PQC/hybrid primitives (see dependency github.com/quantumcoinproject/circl in go.mod).
- Transactions are signed with one of the hybrid PQC signature schemes. The gas price of the transaction varies based on the scheme to compensate for larger signature and public key sizes.
- Node keys use post-quantum cryptography to provide blockchain node identifiers via signed packets.
- Validator consensus messages use the same hybrid post-quantum signature approach. Messages are typically signed in compact mode, while the proposal message of every 4,096th block is signed in full mode (adding the extra PQC component) to maintain smaller average block sizes.
The hybrid schemes exposed at the protocol level include:
| Algorithm ID | Code Constant | Components | Mode | Notes |
|---|---|---|---|---|
| 1 | DILITHIUM_ED25519_SPHINCS_COMPACT_ID |
Ed25519 + Dilithium + SPHINCS+ | Compact | Legacy (pre-SigAlgSwitchBlock) |
| 2 | DILITHIUM_ED25519_SPHINCS_FULL_ID |
Ed25519 + Dilithium + SPHINCS+ | Full | Legacy (pre-SigAlgSwitchBlock) |
| 3 | MLDSA_ED25519_SLHDSA_COMPACT_ID |
Ed25519 + ML-DSA + SLH-DSA | Compact | FIPS-aligned (post-SigAlgSwitchBlock) |
| 4 | MLDSA_ED25519_SLHDSA_FULL_ID |
Ed25519 + ML-DSA + SLH-DSA | Full | FIPS-aligned (post-SigAlgSwitchBlock) |
| 5 | MLDSA_ED25519_SLHDSA_5_ID |
Ed25519 + ML-DSA + SLH-DSA | Full | NIST Security Level 5 for all components |
The specific ML-DSA and SLH-DSA parameter sets (e.g., ML-DSA-44 vs ML-DSA-87, SLH-DSA-SHAKE-256f vs 256s) are determined by the CIRCL library implementations imported in each scheme package (see circl/sign/hybridedmldsaslhdsa for IDs 3–4 and circl/sign/hybridedmldsaslhdsa5 for ID 5 in the quantumcoinproject/circl dependency).
To verify use of the PQC signature schemes, inspect any transaction or validator message and verify the signature fields with a standard PQC library, using the algorithm identifier to select the correct hybrid mode.
Node-to-node sessions use hybrid X25519 + ML-KEM-768 (via circl/kem/hybrid.X25519MLKEM768()) to establish a secure session between blockchain nodes in the rewritten RLPx handshake. The KEM is unconditional: every session uses this hybrid construction.
The RLPx protocol has two versions, selected at runtime by defaults.DefaultConfig.KemSwitchTime (mainnet: Aug 21, 2026 00:00:00 UTC; see defaults/config.go). Both versions use the same hybrid KEM; the V2 protocol adds encrypted headers, a fixed HKDF label encoding, and a new frame format.
- V2 cryptographic specification:
./p2p/rlpx/README.md— full protocol specification covering the handshake, key schedule, record layer, and security properties (intended for cryptographers and auditors). - KEM selection logic:
./crypto/keyestablishmentalgorithm/kem.go - Handshake V1 (legacy, client):
./p2p/rlpx/client.go - Handshake V1 (legacy, server):
./p2p/rlpx/server.go - Handshake V2 (client):
./p2p/rlpx/clientv2.go - Handshake V2 (server):
./p2p/rlpx/serverv2.go - Key derivation (HKDF):
./p2p/rlpx/secret.go - Protocol switch time:
./defaults/config.go
| What | File Path | Details |
|---|---|---|
| Hybrid signature algorithm IDs | ./crypto/crypto.go |
DILITHIUM_ED25519_SPHINCS_*, MLDSA_ED25519_SLHDSA_* |
| Signature selection/verification | ./crypto/cryptobase/cryptobase.go |
Wiring for hybrid signatures |
| KEM selection | ./crypto/keyestablishmentalgorithm/kem.go |
X25519+ML-KEM-768 |
| RLPx handshake (V2) | ./p2p/rlpx/clientv2.go, ./p2p/rlpx/serverv2.go |
Active handshake after KemSwitchTime |
| HKDF key derivation | ./p2p/rlpx/secret.go |
TLS 1.3-style key schedule |
| Protocol-level switches | ./defaults/config.go |
SigAlgSwitchBlock, KemSwitchTime |
| CIRCL hybrid signature bindings | ./crypto/* |
Imports github.com/quantumcoinproject/circl/sign/... |
This section is intended for cryptographers and auditors who need to verify that QuantumCoin uses NIST-specified post-quantum and classical signature algorithms correctly, and to perform independent per-component verification (e.g. cross-checking against PQClean, liboqs, or other reference implementations).
Underlying primitives. The hybrid signature schemes do not modify any underlying cryptographic primitive; each component (Ed25519, ML-DSA, SLH-DSA, or the legacy Dilithium/SPHINCS+ in schemes 1–2) is invoked as specified by the relevant NIST standard (FIPS 186-5, FIPS 204, FIPS 205) or draft. This aligns with NIST guidance on combining NIST-approved and post-quantum algorithms (NIST IR 8547).
Audit tooling (CIRCL). For audit, validation, and independent per-component verification of hybrid signatures, the dependency quantumcoinproject/circl provides the hybridparser package. It offers:
- ParseHybrid: verify a hybrid signature and extract per-component public keys and signatures (hex-encoded) for re-verification with external DSA implementations.
- CheckHybrid: reconstruct and verify using both the composite hybrid verifier and each component’s verifier.
The hybridparser README describes NIST alignment (FIPS 204, FIPS 205, FIPS 186-5), the HybridSignature struct (SchemeID, Message, PublicKeys, Signatures, Context, AdditionalData), and how to decode hex components and pass them to external implementations for conformance audits. Use hybridparser for audit and tooling only; production verification in this node uses the hybrid scheme APIs directly.
Obtaining data to audit in QuantumCoin:
| Target | How to obtain | Notes |
|---|---|---|
| Transaction signatures | (a) Bash curl (pass transaction hash): curl -X POST https://public.rpc.quantumcoinapi.com -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_getTransactionSignature","params":["0x5419cd6244d236c1e08bb2274122a3d10b4555c27d16977a68dc2d0b3d6d901a"],"id":1}'(b) Attach to a node and call eth.getTransactionSignature(txHash) (e.g. dp attach IPC_ENDPOINT, then eth.getTransactionSignature("0x...")). (b) Run dputil txnsig TXN_HASH with DP_RAW_URL set to a public RPC endpoint (e.g. https://public.rpc.quantumcoinapi.com). |
Returns transaction hash, public key hex, signature hex, and a hybridSignature object (SchemeID, Message, PublicKeys, Signatures, Context, AdditionalData). The Message field is the signing hash (digest) of the transaction; use it with the extracted components for per-component verification as in the hybridparser README. |
| Consensus messages | (a) Bash curl (pass block number in hex): curl -X POST https://public.rpc.quantumcoinapi.com -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"proofofstake_getBlockConsensusDataWithSignatures","params":["0x100"],"id":1}'(b) Call proofofstake.getBlockConsensusDataWithSignatures(blockNumberInHex) (e.g. from dp attach or any RPC client). |
Returns block consensus data including validator signatures for that block; these can be parsed and verified per component using the same hybridparser workflow. |
Consensus signature mode. The consensus proposal packet (packet type 0) uses the following signing rule: one in every 4,096 blocks starting from block 421,888 is signed in Full signature mode (all three components: Ed25519 + ML-DSA + SLH-DSA); all other proposal packets are signed in Compact mode (Ed25519 + ML-DSA only; SLH-DSA public key present but not signed). All other consensus packet types use Compact mode. Auditors can use getBlockConsensusDataWithSignatures and the block number to determine which mode was used for a given block’s proposal.
Example: auditing transaction signatures with dputil
Set DP_RAW_URL to the public RPC endpoint, then run dputil.exe txnsig with the transaction hash. Example transaction IDs you can use:
# Windows (cmd)
set DP_RAW_URL=https://public.rpc.quantumcoinapi.com
dputil.exe txnsig 0x5419cd6244d236c1e08bb2274122a3d10b4555c27d16977a68dc2d0b3d6d901a
dputil.exe txnsig 0x292a2405b2253989e99d4e9c7ee20975fa586a3f5d9fba90617398b93fb55734
dputil.exe txnsig 0x25cd8b25103f8d6b889afbe57d1cfd8473843c744a0a38e36a7549a75a9fd498# Windows (PowerShell)
$env:DP_RAW_URL = "https://public.rpc.quantumcoinapi.com"
.\dputil.exe txnsig 0x5419cd6244d236c1e08bb2274122a3d10b4555c27d16977a68dc2d0b3d6d901a
.\dputil.exe txnsig 0x292a2405b2253989e99d4e9c7ee20975fa586a3f5d9fba90617398b93fb55734
.\dputil.exe txnsig 0x25cd8b25103f8d6b889afbe57d1cfd8473843c744a0a38e36a7549a75a9fd498# Linux/macOS
export DP_RAW_URL=https://public.rpc.quantumcoinapi.com
./dputil txnsig 0x5419cd6244d236c1e08bb2274122a3d10b4555c27d16977a68dc2d0b3d6d901a
./dputil txnsig 0x292a2405b2253989e99d4e9c7ee20975fa586a3f5d9fba90617398b93fb55734
./dputil txnsig 0x25cd8b25103f8d6b889afbe57d1cfd8473843c744a0a38e36a7549a75a9fd498Each command prints the full transaction signature result (including hybridSignature) as JSON to the console for audit.
Using the above, auditors can obtain raw signature material (message, public keys, component signatures) and verify each component against FIPS 204, FIPS 205, and FIPS 186-5 (or the applicable pre-final drafts for schemes 1–2) with their chosen tooling.
-
32-byte addresses: Addresses are 32 bytes instead of 20 bytes in Ethereum, for increased security.
-
Rewritten RLPx protocol: The RLPx protocol has been completely rewritten and modularized to use post-quantum cryptography. The final client and server encryption keys are derived similarly to TLS 1.3 as detailed in RFC 8446. A PQC-capable KEM is used for key exchange, and the resulting key material is used as input to HMAC HKDF functions (RFC 5869). However, unlike TLS, instead of trusting a certificate, the node's identity is verified via its hybrid PQC key pair. The private key corresponds to the hybrid PQC key pair used to secure the account using digital signatures. These changes are in the
./p2p/rlpxpackage. -
New consensus engine: See Proof-of-Stake Consensus.
- Commits to fix tests are pending sanitization before merge.
- The transaction metadata contains values named
v,r, ands, which are legacy fields from Ethereum. In Ethereum, these values are used for public key recovery; however, QuantumCoin's hybrid PQC signatures use a different mechanism for identity verification.
"Quantum Coin" ("QuantumCoin") and "Quantum Coin Community" were previously known under the monikers "Doge Protocol" and "Doge Protocol Community" respectively.
Thank you for considering helping out with the source code! We welcome contributions from anyone on the internet, and are grateful for even the smallest of fixes!
If you'd like to contribute to quantum-coin-go, please fork, fix, commit and send a pull request to review and merge into the main code base. If you wish to submit more complex changes though, please check up first in our community Discord Server to ensure those changes are in line with the general philosophy of the project and/or get some early feedback which can make both your efforts much lighter as well as our review and merge procedures quicker and simpler.
Please make sure your contributions adhere to our coding guidelines:
- Code must adhere to the official Go formatting guidelines (i.e. use gofmt).
- Code must be documented according to the official Go commentary guidelines.
- Pull requests need to be based on and opened against the
mainbranch. - Commit messages should be prefixed with the package(s) they modify.
- E.g. "eth, rpc: make trace configs optional"
The quantum-coin-go library maintains the same licensing model of go-ethereum. The library (i.e. all code outside of the cmd directory) is licensed under the GNU Lesser General Public License v3.0, also included in our repository in the COPYING.LESSER file.
The binaries (i.e. all code inside of the cmd directory) are licensed under the GNU General Public License v3.0, also included in our repository in the COPYING file.