Documentation TODOs and PQC Implementation Status

This document consolidates key TODOs identified across Shekyl documentation and outlines the current state and next steps for Post-Quantum Cryptography (PQC) implementation.

---

1) Key TODOs from Existing Documentation

1.1 GENESIS_TRANSPARENCY.md (formerly referenced as GENESIS_STRATEGY.md)

Item	Description
Emission Economics (TODO)	Original Shekyl MONEY_SUPPLY (2^32 in atomic units with 12 decimals) yields ~0.004 coins. Needs redesign before mainnet: reduce decimals (e.g. 8), choose different supply, or redesign emission curve. Currently using upstream default supply for testnet.
Snapshot / UTXO	Locate and extract original Shekyl UTXO set; implement snapshot restoration logic (Phase 2); mainnet launch after full testing.
PQC transaction format	Post-genesis blocks use a reboot-only hybrid PQ spend/ownership format with dedicated authorization fields — defined in POST_QUANTUM_CRYPTOGRAPHY.md; v3 tx format, core validation, and wallet construction are implemented.

1.2 DESIGN_CONCEPTS.md

Item	Description
Provisional parameters	tx_baseline (50) and FINAL_SUBSIDY_PER_MINUTE (300,000,000) are provisionally locked after 8-scenario simulation sweep (rust/shekyl-economics-sim); final confirmation from testnet.
Simulation scenarios	All eight scenarios implemented and run in rust/shekyl-economics-sim/; results in docs/economics_sim_results.json.
Test coverage	Design doc calls for unit/property/integration tests for reward curve, burn formula, staker distribution, overflow boundaries, pre/post-fork sync.

1.3 COMPILING_DEBUGGING_TESTING.md

Item	Description
To be done (and merged)	References external upstream PRs: multihost parallel compilation (#7160), faster core_tests with caching (#5821), precompiled headers (#7216), unity builds (#7217). Shekyl may adopt or reimplement as needed.

1.4 LEVIN_PROTOCOL.md

Item	Description
Wire data inventory	"This document does not currently list all data being sent by the Shekyl protocol, that portion is a work-in-progress." Completing this helps anonymity and DPI analysis.

1.5 ANONYMITY_NETWORKS.md

Item	Description
Future mitigations	Random offset for peer timed sync on anonymity networks; peers that receive tx over anonymity network delay broadcast to public peers by randomized amount; careful disconnect/reconnect strategy to avoid linking.
I2P/Tor stream reuse	Document notes that rotating circuits / disconnecting occasionally should be done carefully — implementation work remains.

1.6 RELEASE_CHECKLIST.md

Item	Description
Full checklist	Security audit, code audit, Ledger/Trezor integration, fork height and announcements, wallet/exchange/pool notifications, release tagging, testnet fork and testing, reproducible builds, CLI/GUI release, announcements. All items are unchecked; use Shekyl-specific resources and project website/channels.

1.7 SEEDS_SETUP.md

Item	Description
Current gaps	Public DNS seed list empty; fallback IP seed lists are placeholders; some docs/config still use legacy naming; seed operations under-documented for end users.
Runtime seed add	Adding new seed nodes/peers at runtime via daemon command is not currently documented/implemented.

1.8 CONTRIBUTING.md / README.i18n.md

Item	Description
Shekyl-specific	CONTRIBUTING and i18n docs have been updated to reference Shekyl maintainers, project channels, and binary names (e.g. shekyl-cli).

1.9 Other docs (PORTABLE_STORAGE, INSTALLATION_GUIDE, PUBLIC_NARRATIVE_FAQ)

• PORTABLE_STORAGE.md: No TODOs; reference doc.
• INSTALLATION_GUIDE.md: Shekyl-native; no critical TODOs.
• PUBLIC_NARRATIVE_FAQ.md: Narrative/positioning; no technical TODOs.

1.10 Economics and PoW modularization status

Item	Description
Economics chain-state wiring	tx_volume_avg is now computed from recent chain history and passed into miner template construction, tx pool block-reward estimation, and miner reward validation. circulating_supply is sourced from already_generated_coins; stake_ratio is now computed from chain-state scanning of locked txout_to_staked_key outputs.
Modular PoW schema	PoW hashing routes through a schema interface and registry (IPowSchema, RandomX schema). Shekyl uses RandomX from genesis (HF1); CryptoNight variants are not supported.
Follow-up TODO	Add configuration-driven PoW activation policy and expand test coverage for schema-selection parity against legacy get_block_longhash behavior.

1.11 Boost Migration Status

Completed migrations:

• C++ standard bumped from C++14 to C++17 (CMAKE_CXX_STANDARD 17) in both main CMakeLists.txt and macOS cross-compilation toolchain (contrib/depends/toolchain.cmake.in).
• boost::optional → std::optional across ~93 files (~486 use sites). Added Boost.Serialization adapter for std::optional in cryptonote_boost_serialization.h. Replaced BOOST_STATIC_ASSERT/boost::is_base_of with C++17 static_assert/std::is_base_of.
• boost::variant → std::variant (complete). Rewrote serialization/variant.h to use if constexpr recursion and std::visit (eliminated Boost.MPL dependency). Changed all 5 variant typedefs (txin_v, txout_target_v, tx_extra_field, transfer_view::block, Trezor rsig_v). Added local Boost.Serialization shim for std::variant in cryptonote_boost_serialization.h. Mechanical replacements across ~40 files in src/ and tests/ (~100+ sites). Replaced boost::mpl::bool_ with std::bool_constant in archive headers.
• boost::algorithm::string → tools::string_util (trim, to_lower, iequals, join).
• boost::format → snprintf / stream output / string concat in util.cpp, message_store.cpp, gen_ssl_cert.cpp, gen_multisig.cpp, wallet2.cpp, wallet_rpc_server.cpp, wallet_args.cpp.
• boost::regex → std::regex in wallet_manager.cpp. (simplewallet.cpp has been deleted.)
• boost::mutex / boost::lock_guard / boost::unique_lock / boost::condition_variable → std::mutex / std::lock_guard / std::unique_lock / std::condition_variable in util.h, util.cpp, threadpool.h, threadpool.cpp, rpc_payment.h, rpc_payment.cpp.
• boost::filesystem → std::filesystem in blockchain_export.cpp, blockchain_import.cpp, cn_deserialize.cpp, util.cpp, bootstrap_file.h/.cpp, blocksdat_file.h/.cpp, wallet_manager.cpp, wallet_rpc_server.cpp, core_rpc_server.cpp, wallet_args.cpp.
• boost::chrono/boost::this_thread → std::chrono/std::this_thread in windows_service.cpp (daemonizer). [File subsequently deleted wholesale with src/daemonizer/ in V3.1 — see CHANGELOG.md.]
• Upstream Monero PRs #9628 (ASIO io_service → io_context), #6690 (serialization), #9544 (daemonizer) confirmed already absorbed. [V3.1 deleted the daemonizer subsystem entirely; the #9544 changes are preserved in git history only.]
• Boost minimum version bumped from 1.62 to 1.74 (BOOST_MIN_VER in CMakeLists.txt). contrib/depends Boost upgraded from 1.69.0 to 1.74.0 with C++17 flags. CI containers updated to Ubuntu 22.04 minimum (Debian 11 and Ubuntu 20.04 dropped).

Phase 1 complete: Daemon RPC migrated to Rust/Axum (see docs/DAEMON_RPC_RUST.md):

• shekyl-daemon-rpc Rust crate replaces epee::http_server_impl_base for daemon RPC transport.
• core_rpc_ffi.h/.cpp provides a C dispatch facade over the existing core_rpc_server handlers.
• All 90 endpoints (33 JSON REST, 9 binary, 48 JSON-RPC) are routed through Axum.
• JSON REST accepts both GET and POST; binary endpoints return 400 on parse failure (matching epee).
• Enabled by default; use --no-rust-rpc to fall back to legacy epee HTTP.
• Validated on live testnet: 23 pass, 2 expected diffs, 2 binary skips (see docs/DAEMON_RPC_RUST.md).
• Validation harness at tests/rpc_comparison/compare_rpc.sh; test data in shekyl-dev/data/rpc_comparison/.
• Remaining for cutover: wallet sync test (binary endpoints with real payloads), standard port binding.

Deferred hard areas (tagged TODO(shekyl-v4) in source):

Area	Files	Rationale for deferral
ASIO / epee networking	abstract_tcp_server2.h, levin_protocol_handler_async.h	P2P networking layer; RPC already migrated to Axum
Multi-index containers	net_peerlist.h	Composite indices (by address, time, id) have no direct std equivalent
Spirit parser	http_auth.cpp	Heavyweight compile dep; small grammar, but needs manual rewrite
Multiprecision	difficulty.h, int-util.cpp	Consensus-critical 128-bit arithmetic; evaluate __uint128_t
Filesystem (net_ssl)	net_ssl.cpp	epee SSL layer with permissions API coupling
boost::format (simplewallet)	simplewallet.cpp	Deleted -- simplewallet has been replaced by shekyl-cli (Rust)
boost::split (token_compress)	util.cpp (vercmp, word_wrap)	token_compress_on has no direct std equivalent
boost::regex (network parsers)	http_base.cpp, http_client.h, wallet_rpc_server.cpp	Parse untrusted network input; edge-case semantics must be verified
boost::posix_time / date_time	connection_context.h, block_queue.h, net_node.h	Types cross P2P protocol boundaries; must migrate as a coordinated unit
boost::thread (attributes)	threadpool.h	boost::thread::attributes (stack size) has no std equivalent

---

2) What Is Documented for PQC

2.1 Project rules (.cursor/rules/privacy-security.mdc)

• Priority: Quantum resistance is priority #1; classical security #2; privacy #3.
• Standards: Prefer NIST PQC finalized standards: ML-DSA, ML-KEM, SLH-DSA.
• Transition: Prefer hybrid constructions (e.g. Ed25519 + ML-DSA) during transition.
• Requirements: No new crypto without quantum security evaluation; constant-time/side-channel resistance; no key material in logs or error messages.

2.2 Genesis strategy (docs/GENESIS_TRANSPARENCY.md)

• The rebooted chain is planned to use a single PQ-enabled transaction format from launch.
• Legacy transaction coexistence is no longer a requirement on the rebooted runtime.

2.3 Code: rust/shekyl-crypto-pq

• Purpose: Post-quantum primitives for Shekyl (ML-DSA, ML-KEM, hybrid signatures).
• Design:
  • Signatures: Hybrid Ed25519 + ML-DSA-65; both must verify.
  • KEM: Hybrid X25519 + ML-KEM-768 ships at genesis for per-output PQC key derivation.
• Types: HybridPublicKey, HybridSecretKey, HybridSignature; HybridKemPublicKey, HybridKemSecretKey, HybridCiphertext, SharedSecret.
• Status: Hybrid signature support is implemented with canonical serialization helpers and tests. KEM ships at genesis for per-output PQC key derivation. Deterministic KEM encapsulation from tx_key_secret is implemented (derive_kem_seed). Proof pipeline helpers (rederive_combined_ss, derive_proof_secrets, derive_output_key, recover_recipient_spend_pubkey, decrypt_amount, compute_output_key_image) are implemented with full test coverage. KAT vectors at docs/test_vectors/KEM_DERIVE_V1_KAT.json.
• Integration: Signature operations are exposed via shekyl-ffi. Proof helper FFI exports (shekyl_generate_tx_proof_outbound/inbound, shekyl_verify_tx_proof_outbound/inbound, shekyl_generate_reserve_proof, shekyl_verify_reserve_proof, shekyl_derive_proof_secrets) are wired and the C++ wallet2 proof functions (get_tx_proof, check_tx_proof, get_reserve_proof, check_reserve_proof) delegate to the Rust FFI. Monero-era DH proof functions (crypto::generate_tx_proof, crypto::check_tx_proof) and helpers (check_tx_key_helper, is_out_to_acc) have been deleted.

2.4 Gaps in PQC documentation

• Dedicated PQC design doc now exists: docs/POST_QUANTUM_CRYPTOGRAPHY.md.
• Remaining work: keep the PQC spec aligned with implementation as code lands.
• Exact measured encoded sizes and a publishable vector are now documented (docs/POST_QUANTUM_CRYPTOGRAPHY.md, docs/PQC_TEST_VECTOR_001.json).
• Negative/malformed test vectors (PQC_TEST_VECTOR_002–004) now cover tampered ownership, wrong scheme_id, and oversized blob rejection.
• Operator-facing rollout notes now exist (docs/V3_ROLLOUT.md).
• Wallet scanning vs hybrid authorization coexistence is now documented in docs/POST_QUANTUM_CRYPTOGRAPHY.md.
• Hybrid signature vector verification is now covered in Rust unit tests (documented_vector_verifies).
• FCMP++ / stealth addresses: hybrid PQ spend protection works alongside FCMP++ membership proofs. The FCMP++ 4-scalar leaf H(pqc_pk) binds per-output PQC ownership to the UTXO in-circuit.
• v3 boundary: anonymous per-input PQ ownership enforcement is solved at genesis via FCMP++ 4-scalar leaf: H(pqc_pk) proven in-circuit, binding per-output PQC ownership to the UTXO.
• FCMP++ documentation:
  • FCMP++ design document: created -- see docs/FCMP_PLUS_PLUS.md
  • Per-output PQC key derivation: documented in POST_QUANTUM_CRYPTOGRAPHY.md and FCMP_PLUS_PLUS.md
  • Curve tree operations: covered in FCMP_PLUS_PLUS.md (dedicated CURVE_TREE_OPERATIONS.md not needed)
  • Bech32m address format specification

---

3) PQC Next Steps (Recommended)

Phase 1: Hybrid signatures

Completed:

• dependencies selected and wired
• HybridEd25519MlDsa keygen/sign/verify implemented
• canonical serialization for HybridPublicKey and HybridSignature implemented
• unit tests added for success/failure and malformed serialization paths

Remaining:

• extend vector set with additional malformed/negative vectors Done — three negative vectors added:
  • PQC_TEST_VECTOR_002_tampered_ownership.json (corrupted Ed25519 public key byte)
  • PQC_TEST_VECTOR_003_wrong_scheme_id.json (scheme_id 0x01 → 0x02)
  • PQC_TEST_VECTOR_004_oversized_blob.json (ML-DSA length field inflated beyond blob)
  • Integration tests in rust/shekyl-crypto-pq/tests/negative_vectors.rs
• KEM test vectors (ships at genesis with per-output PQC key derivation)

Phase 2: KEM (HybridX25519MlKem)

Ships at genesis for per-output PQC key derivation:

• Unclamped Montgomery DH + ML-KEM-768 hybrid KEM for per-output PQC keypair derivation (X25519 public key derived from Ed25519 view key; not RFC 7748; see POST_QUANTUM_CRYPTOGRAPHY.md §X25519 Binding to View Key, §DH Semantics)
• Deterministic encapsulation from tx_key_secret via derive_kem_seed (HKDF-SHA-512, salt "shekyl-output-kem-v1", info = SHA3-256 recipient fingerprint || index)
• ML-KEM ciphertexts stored in tx_extra tag 0x06
• Combined shared secret via HKDF-SHA-512(ikm = X25519_ss || ML-KEM_ss, salt = "shekyl-kem-v1", info = "")
• Proof helpers: rederive_combined_ss, derive_proof_secrets, derive_output_key, recover_recipient_spend_pubkey, decrypt_amount, compute_output_key_image
• fips203 pinned to =0.4.3 (exact) with KAT tripwire (KEM_DERIVE_V1_KAT.json)
• Full specification in docs/POST_QUANTUM_CRYPTOGRAPHY.md under "Per-Output PQC Key Derivation"

Phase 3: FFI and C++ integration

Completed:

• shekyl-ffi now exposes hybrid keygen/sign/verify
• explicit Rust-owned buffer release helper exists
• ABI expectations are documented in docs/POST_QUANTUM_CRYPTOGRAPHY.md

Completed:

• C++ transaction serialization for the reboot-only v3 format (pqc_auth in transaction)
• hybrid layer bound to spend/ownership via PqcAuthentication and signed payload
• Rust verify called from core validation (verify_transaction_pqc_auth)
• Rust sign called from wallet transaction construction when hf_version >= HF_VERSION_SHEKYL_NG
• reboot-chain transaction version rules enforced (max_tx_version, version gates)
• create_claim_transaction (stake reward claims) wired with PQC hybrid signing
• all v3 transaction paths audited: staking and unstaking go through construct_tx_with_tx_key (already wired); claim tx now has its own PQC block
• multisig wallets restricted to v2 (PQC secret cleared); documented as intentional
• PQC verification enforced in mempool and block validation for all non-coinbase v3 txs

Remaining:

• expand wallet RPC docs with claim-flow details
• document multisig PQC limitations in operator guidance

Phase 3b: Wallet testnet readiness

Completed:

• hardfork schedule rebooted: all HF_VERSION_* = 1, single-entry hardfork tables
• raw numeric HF gates replaced with named HF_VERSION_* constants throughout consensus, transaction construction, and core validation code
• staked outputs excluded from is_transfer_unlocked, balance, and coin selection
• create_unstake_transaction rewired to spend actual staked UTXOs via create_transactions_from
• check_stake_claim_input now looks up real amount/tier from blockchain DB
• new daemon RPC estimate_claim_reward computes per-output reward server-side
• wallet estimate_claimable_reward wired to daemon RPC (replaces hardcoded stub)
• CLI: balance shows staked amount; new staking_info command; daemon guards on stake/unstake/claim_rewards
• wallet RPC: unstake returns tx_hash_list; stake accepts account_index; new get_staked_balance endpoint

Phase 4: Documentation and audit

1. PQC design doc

   • Canonical spec exists in docs/POST_QUANTUM_CRYPTOGRAPHY.md.
   • Keep it aligned with the hybrid spend/ownership model as code lands.

2. Privacy

   • FCMP++ provides full-chain anonymity; pqc_auth provides quantum-resistant authorization.
   • Ensure no key material in logs; constant-time and side-channel notes.
   • Per-output PQC keys via hybrid KEM prevent transaction linkability.

3. Test vectors

   • Publish test vectors for hybrid sign/verify and KEM for interop and future audits.

4. Security review

   • Schedule review of PQC integration (crypto + integration points) before mainnet.

5. FCMP++ integration (major next step)

   • FCMP++ FFI bridge (prove/verify round-trip)
   • Curve tree DB operations (grow/trim/root/path)
   • FCMP++ fuzz targets (6 harnesses, 10M iterations each)
   • Per-output PQC key derivation end-to-end testing
   • Bech32m address encoding/decoding
   • FCMP++ design document: created -- see docs/FCMP_PLUS_PLUS.md

---

4) Summary Table

Area	Key TODOs	PQC-related
Genesis / emission	Emission economics redesign; snapshot/UTXO; v3 tx format	v3 depends on PQC
Design / economics	Params provisionally locked; 8-scenario simulation complete (shekyl-economics-sim); test coverage expanding	—
Build / test	Adopt or reimplement upstream build/test improvements	—
Levin / wire	Complete list of data on wire	—
Anonymity	Timestamp offset; broadcast delay; circuit rotation	—
Release	Full checklist; Shekyl-specific seeds, wallets, exchanges	—
Seeds	Populate DNS/IP seeds; runtime seed add; Shekyl naming	—
Economics / PoW	Finish config-driven proof activation and staker-claim transaction grammar	Stake-ratio chain-state tracking implemented; modular PoW scaffolding implemented
Boost migration	C++17 bump complete; boost::optional fully migrated (~93 files); boost::variant fully migrated (~40 files); boost::filesystem migrated in wallet/RPC/utility layers; boost::format removed from wallet2/wallet_rpc/wallet_args; Boost minimum bumped to 1.74; CI updated to Ubuntu 22.04+; daemon RPC HTTP server migrated from epee to Rust/Axum (Phase 1); remaining hard areas deferred with TODO(shekyl-v4) (see §1.11)	Majority of codebase now uses std::optional, std::variant, std::filesystem; daemon RPC on Axum
PQC	v3 complete; 4 published vectors (1 positive, 3 negative); V4 roadmap updated; KEM ships at genesis; FCMP++ integration is major next step; external audit remains	Core of this document

---

5) References

• Project rules: .cursor/rules/privacy-security.mdc
• Genesis: docs/GENESIS_TRANSPARENCY.md
• Design: docs/DESIGN_CONCEPTS.md
• Rust PQC crate: rust/shekyl-crypto-pq/ (signature.rs, kem.rs, error.rs)
• FFI: rust/shekyl-ffi/src/lib.rs (hybrid keygen/sign/verify exported)
• Backward compatibility: .cursor/rules/backward-compatibility.mdc (pre-fork blocks remain valid under original consensus)