Fakenet and mining runbook

Nockchain Operations

Upstream-script-backed triage for fakenet nodes, miners, empty routing tables, no peers, wrong block commitments, behind-tip gossip suppression, wallet checks, and PMA/state-jam provenance.

Operations API Diagnostics Runbook

Build

33ba97b1e206

Scripts

Scenarios

Release

build-33ba97b1e206

Upstream Script Sources

fakenet-node

scripts/run_nockchain_node_fakenet.sh

nockchain --fakenet --bind-public-grpc-addr 127.0.0.1:5555 --bind /ip4/127.0.0.1/udp/3006/quic-v1

Start the local fakenet hub/node with public local gRPC and a fixed UDP/QUIC bind address.

fakenet-miner

scripts/run_nockchain_miner_fakenet.sh

nockchain --mine --fakenet --mining-pkh ${MINING_PKH} --peer /ip4/127.0.0.1/udp/3006/quic-v1 --no-default-peers

Mine against the local fakenet node by explicitly peering to the hub and disabling default peers.

mainnet-node

scripts/run_nockchain_node.sh

nockchain

Start a non-mining Nockchain node from the current environment and persisted state.

mainnet-miner

scripts/run_nockchain_miner.sh

nockchain --mining-pkh ${MINING_PKH} --mine --num-threads $num_threads

Start a miner with logical CPU count minus two threads, bounded to at least one mining thread.

Priority Triage

wrong-block-commitment

Wrong block commitment

A wrong commitment usually means the miner, wallet, or test expectation is looking at a different fakenet tip or state artifact than the node.

symptom

wrong block commitment

upstreamSignal

The latest Nockchain build is centered on behind-tip behavior; block commitments should only be compared after sync and state-artifact provenance are known.

relatedCrates

nockchain, nockchain-types, nockvm/rust/nockvm

empty-routing-table

Routing table is empty

The node has not discovered usable peers for the target network. On fakenet, verify the hub/miner peer multiaddrs and WSL UDP/QUIC reachability before treating mining output as evidence.

symptom

routing table is empty

upstreamSignal

Fakenet scripts pin the hub bind address to /ip4/127.0.0.1/udp/3006/quic-v1 and the miner peers to that address with --no-default-peers.

relatedCrates

nockchain, nockchain-libp2p-io, nockapp-grpc

no-connected-peers

No connected peers

Mining against zero connected peers can produce stale tip context and misleading commitment checks.

symptom

No connected peers

upstreamSignal

The current fakenet miner script disables default peers, so the explicit fakenet hub peer must be reachable.

relatedCrates

nockchain, nockchain-libp2p-io

behind-tip-gossip-suppression

Behind-tip gossip suppression

A node that is behind tip can intentionally suppress outgoing gossip while catching up; quiet gossip is not by itself proof that mining or networking is broken.

symptom

node is syncing or appears quiet while behind tip

upstreamSignal

libp2p: suppress all outgoing gossip while catching up (behind tip)

relatedCrates

nockchain, nockchain-libp2p-io

Operator Checklist

Confirm the node is caught up before mining or interpreting block commitments.

Confirm fakenet node and miner use matching data dirs, bootstrap peer, bind address, and wallet endpoint mode.

Verify peer multiaddrs plus UDP/QUIC ports are reachable from the laptop and WSL network namespace.

Capture peer count, height, block commitment, wallet address, endpoint, and Nockchain build in the same evidence receipt.

Record state-jam/checkpoint source URL, hash, height/event boundary, and Nockchain build before trusting bootstrap state.

Keep raw PMA slabs, event logs, checkpoints, state jams, keys, seed phrases, and wallet exports out of git and receipts.

State Artifact Safety

posture

PMA is durable local kernel-state storage, not a disposable cache or safe raw third-party bootstrap artifact.

doNotStore

raw PMA slabs, event logs, checkpoints, state jams, wallet exports, seed phrases, private keys

metadataToTrack

source URL or Drive folder id, filename, size, hash, checkpoint height or event boundary, network, Nockchain build or commit, producer identity if known

Additional Scenarios

grpc-unreachable

Local fakenet gRPC unreachable

The local evidence commands cannot reach the fakenet gRPC endpoint. Start the fakenet node, verify port 5555, then regenerate evidence.

symptom

ECONNREFUSED or endpoint not reachable

upstreamSignal

scripts/run_nockchain_node_fakenet.sh binds public local gRPC at 127.0.0.1:5555.

relatedCrates

nockapp-grpc, nockchain

wallet-balance-unknown

Wallet balance unknown

Wallet and miner evidence must name the address, endpoint mode, and sync context before balance or reward expectations can be trusted.

symptom

balance check failed or wallet address context is missing

upstreamSignal

Wallet commands are operator-facing; Nocksperimental should preserve wallet address and endpoint provenance instead of treating balance as a naked number.

relatedCrates

nockchain-wallet, nockchain-api

state-jam-provenance

State-jam provenance required

State artifacts are durable runtime/chain state. Treat them as metadata-only external inputs and never store raw PMA slabs, event logs, checkpoints, state jams, wallet exports, seed phrases, or private keys.

symptom

bootstrap state, checkpoint, PMA, or state jam was imported or considered

upstreamSignal

PMA/state-jam safety policy is recorded in the Nockchain upstream intelligence and state-jam registry.

relatedCrates

nockvm/rust/nockvm, nockchain, noun-serde

Evidence Links

localDiagnostics

https://nocksperimental.com/api/fakenet/diagnostics

fakenetRunbook

https://nocksperimental.com/api/fakenet/runbook.sh

stateJams

https://nocksperimental.com/api/nockchain/state-jams

rustAtlas

https://nocksperimental.com/api/nockchain/rust-atlas

release

https://github.com/nockchain/nockchain/releases/tag/build-33ba97b1e206dd89b15c61b72b7802caf2136c18