Qtcl Mcp Server

Create a new QTCL post-quantum wallet backed by a real HypΓ keypair (Schnorr-Γ over SL(3,p), 512-step random walk, SHA3-256² address). Returns private_key, public_key, address, and created_at. Store private_key securely — the server never retains it.

Sign a 32-byte message hash with a HypΓ private key using Schnorr-Γ. To sign a transaction, compute: SHA3-256(JSON.dumps({"sender": from_addr, "recipient": to_addr, "amount": amount_float, "nonce": nonce_int}, sort_keys=True)) → pass the 64-char hex as message_hex. The nonce MUST match the nonce you will use in qtcl_send_transaction. Returns the full signature dict (with canonical R/Z matrix fields) — pass the entire JSON output as the signature field to qtcl_send_transaction. CRITICAL: use the 'signature_for_tx' field from the response as the 'signature' argument to qtcl_send_transaction — do not extract sub-fields.

Check QTCL balance for any address. Returns balance in base units (qsat), UTXO count, and UTXO list. 1 QTCL = 100 qsat.

List unspent transaction outputs (UTXOs) for an address. Returns tx_hash, output_index, amount_base per coin.

Submit a signed UTXO transaction to the QTCL network. Flat fee: 1 qsat. Finality: ~18 seconds. WORKFLOW: (1) pick nonce = int(time.time()*1000) [ms epoch]. (2) build payload = JSON.dumps({sender,recipient,amount,nonce}, sort_keys=True). (3) hash = SHA3-256(payload) as 64-char hex. (4) call qtcl_sign_message(message_hex=hash, private_key=key). (5) pass the 'signature_for_tx' field from step 4 as the 'signature' arg here, with the SAME nonce used in steps 1-4. CRITICAL: nonce must be a millisecond timestamp (>1700000000000) to avoid nonce_replay rejection. Never use sequential integers.

Look up a QTCL transaction by its SHA3-256 hash. Returns full tx details, status, and block height.

Current blockchain state: height, latest block hash, mempool depth, oracle status, and system health vector.

Takes no parameters.

Retrieve a block by height (integer) or hash (hex string). Omit both for the latest block.

List recent transactions, optionally filtered by address. Returns newest first. Max 50 per call.

Live quantum coherence metrics: W-state fidelity (≥0.75 healthy), entanglement witness (NPT criterion), oracle consensus round, Mermin inequality test, and kappa=0.11 non-Markovian coherence score.

Takes no parameters.

List registered quantum oracle nodes participating in 5-oracle Byzantine consensus (3-of-5 majority).

List active P2P peers in the QTCL Kademlia DHT network.

QTCL network quantum coherence metrics and valuation signals. Note: QTCL has no public USD exchange. Returns W-state fidelity, entanglement witness, and oracle coherence as network health proxy.

Takes no parameters.

Retroactively settle all blocks whose UTXOs are missing from address_utxos. Safe to call repeatedly — idempotent. Returns counts of settled/skipped/error blocks. Use this when miner balance is lower than expected after mining blocks.

Takes no parameters.

Nuclear UTXO repair: bypasses settlement machinery and directly inserts missing UTXOs from the transactions table. Use when qtcl_retro_settle reports success but UTXOs are still missing. Commits per-UTXO for maximum isolation. Returns repaired_blocks, repaired_utxos, recomputed_wallets counts.

Takes no parameters.

Submit a fully PoW-solved and HypΓ-signed block to the chain. This is the unified miner submission path. The miner client performs PoW locally, signs the block header, then calls this with the complete payload. Required: height, block_hash, parent_hash, merkle_root, timestamp, nonce, miner_address, difficulty_bits, w_entropy_hash, hyp_signature, miner_public_key_hex. Optional: transactions (JSON array), w_state_fidelity, pq0, pq_curr, pq_last, mermin_value, mermin_violated, quantum_field_16x16x16. Returns: {status, height, block_hash, next_height, miner_reward_qtcl}.

Quantum-bound encryption via IBM QLDPC hardware (ibm_marrakesh/ibm_kingston). Two modes: quantum_bound (async=false, default): XOR-masks the encapsulated key with a hardware-derived quantum key. Runs synchronously with 8192 shots for deterministic results. Recipient MUST use qtcl_quantum_decrypt to recover the key. attestation (async=true): Leaves encapsulated key unchanged, runs hardware in background. Attaches quantum_commitment as metadata. Classical decrypt still works. Returns: Ciphertext dict with quantum_commitment, quantum_status, quantum_mode, quantum_hardened, and all standard encryption fields.

Decrypt quantum-bound or quantum-assisted ciphertext. Auto-detects mode from the ciphertext dict: quantum_bound → runs QLDPC pipeline on masked key, XOR-unmasks, decrypts attestation → tries classical first, falls back to quantum-assisted recovery classical → pure classical decrypt Returns: Plaintext (hex), plaintext_length, quantum_assisted flag, quantum_mode.

Run the full QLDPC pipeline directly on IBM quantum hardware. Encodes ciphertext bytes into a hyperbolic QLDPC code, runs on real IBM hardware (8192 shots), decodes syndromes via BP+OSD, and returns the recovered key fragment. Returns: Pipeline result with recovered_key_hex, residual, status, job_id, backend.

Create a new QTCL wallet with HYBRID post-quantum keys: Falcon-512 (NIST FIPS 206, 128-bit PQ security) + SL(3,p) (~70-bit classical). Returns full keypair dict with both Falcon and SL(3,p) components. Server does NOT retain secret keys. This is the v3 recommended wallet type — quantum-safe by default.

Sign a 32-byte message hash with HYBRID PQC (Falcon-512 + SL(3,p)). Both Falcon and SL(3,p) signatures are computed independently — verification requires BOTH to be valid. message_hex must be 64 hex chars (SHA3-256 of signing payload). private_key_json must be the full JSON output from qtcl_create_hybrid_wallet. Returns hybrid signature dict — pass verbatim as 'signature' to qtcl_send_transaction.

Return PQC module status — shows whether Falcon-512 is available, key/signature sizes, security level, and hybrid signature overhead. Use to check if the server supports full hybrid PQ signatures.

Takes no parameters.