fukuii

Operate Fukuii's checkpoint-based rapid sync for ETC/Mordor nodes — point a fresh node at a trusted checkpoint archive (local file or HTTP URL) so it imports a known pivot and starts SNAP sync immediately instead of waiting on peer consensus, and produce checkpoint archives for others. Use when bootstrapping an ETC/Mordor node fast, running a checkpoint source for a fleet, or debugging why checkpoint import didn't engage. ETH/Sepolia nodes do NOT use checkpoint-sync — they sync via Consensus Layer / Engine API instead. Config changes require a restart — an irreversible/disruptive action under the guarded-write protocol.

Stand up a Consensus Layer (CL) client (Prysm / Lighthouse / Teku) alongside Fukuii for an ETH/Sepolia node so the CL can drive Execution Layer block import via the Engine API. Use when bringing up a post-Merge ETH/Sepolia node, connecting or replacing the CL, or when the operator asks "why won't my Sepolia node sync" / "do I need a beacon client". Covers the EL+CL pairing rationale, JWT secret sharing, CL connection flags, startup order, and the 401 liveness check. ETH/Sepolia only — ETC/Mordor has no CL. For the EL-side Engine API config keys see fukuii-engine-api-setup; for handshake/auth faults see fukuii-engine-api-debug.

Triage and manage Fukuii's disk usage — understand the datadir layout, measure RocksDB growth, free space safely, and size storage for the supported chains. Use when disk is filling up, the node warns about space, you're planning capacity, or sync is slow due to I/O. Measurement is read-only; any deletion/relocation of the database is an irreversible action under the guarded-write protocol.

Troubleshoot a broken or stalled Engine API channel between a Consensus Layer client and Fukuii on ETH/Sepolia — JWT 401 auth failures, forkchoiceUpdated timeouts, newPayload INVALID, EL-reports-SYNCING, exchangeCapabilities version mismatches — and decide whether the fault is in the EL (Fukuii) or the CL. Use when the CL logs Engine API errors, payloads are rejected, attestation duties are withheld, or sync won't advance with a connected CL. ETH/Sepolia only; ETC/Mordor has no Engine API. For first-time CL bring-up see fukuii-cl-setup; for EL config keys see fukuii-engine-api-setup.

Configure Fukuii's Engine API authrpc endpoint so a Consensus Layer (CL) client can drive ETH/Sepolia block import — generate the shared JWT secret, enable the authrpc server, and verify the CL handshake. ETH/Sepolia only; ETC/Mordor does not use the Engine API. Use when setting up a new ETH/Sepolia node, connecting or replacing the CL, or troubleshooting eth_syncing not advancing when peers are healthy. Config changes require a restart — irreversible/disruptive under the guarded-write protocol.

Bring up a brand-new Fukuii node end to end — pick the network, generate the node key, set the datadir and config, start the node, and confirm it discovers peers and begins syncing. Use when bootstrapping a fresh node, onboarding a new host, or setting up ETC/Mordor/Sepolia for the first time. For ETH/Sepolia nodes a Consensus Layer client must also be running and connected to the Engine API before the EL will sync. Generating keys and starting the node are security-sensitive/irreversible actions under the guarded-write protocol.

Configure Fukuii logging and triage problems through logs — set the log level at runtime without a restart, switch JSON output, find the log files, and map common error patterns (peer drops, RocksDB, OOM, sync stalls) to causes. Use when investigating any node issue via logs, when asked to raise/lower verbosity, or to enable structured logging. Reading logs is read-only; changing the live log level is a reversible write under the guarded-write protocol.

Safely edit a Fukuii node's HOCON configuration and choose an operating mode — network selection, datadir, RPC apis/ports, sync mode (SNAP vs fast), mining, and resource settings — with a back-up-then-restart discipline. Use when asked to change config, enable an RPC namespace, switch sync strategy, set the datadir, or pick an operating profile. Editing config and restarting is an irreversible/disruptive action under the guarded-write protocol.

Inspect and manage a Fukuii node's peer connections — list peers, add/remove peers, mark trusted peers, tune max-peers, and configure static/bootstrap nodes. Use when peer count is low, the node is isolated, you need to pin a specific peer, connect to a private/consortium set, or troubleshoot P2P connectivity. Listing is read-only; add/remove/trust/maxPeers are reversible writes under the guarded-write protocol.

Produce a PoS-specific health verdict for an ETH/Sepolia Fukuii node — the CL↔EL Engine API liveness check, EL sync state, CL attestation participation (if validating), post-Cancun blob gossip peer count, and Engine API latency. Use when checking an ETH/Sepolia node's consensus-side health, after attaching a CL, when attestations are missed, or when blob sidecars seem to be dropped. ETH/Sepolia only — for the general/ETC health verdict use fukuii-node-health-check; for Engine API faults use fukuii-engine-api-debug.

Bring up and diagnose ETH Sepolia testnet sync on Fukuii — set network-type, chain-id and Engine API, understand the pre-Merge (peer-driven) vs post-Merge (CL-driven) sync phases, verify with eth_syncing, and handle post-Cancun blob payloads. Use when standing up a Sepolia node, when Sepolia sync stalls, or when deciding whether an EL-peer issue or a CL-driver issue is to blame. Sepolia (chain-id 11155111) only — for ETC/Mordor use fukuii-sync-troubleshooting; for CL/Engine API faults use fukuii-cl-setup and fukuii-engine-api-debug.

Scan the Fukuii codebase for Scala 2 legacy patterns and produce a ranked tech-debt inventory for MITHRIL sprint planning. Counts implicit val/def, implicit class, sealed trait + case object hierarchies, and wildcard imports by file. Use when asked for "tech debt", "modernization targets", "implicit audit", "what should mithril focus on", or before planning a Scala 3 modernization sprint. Read-only; safe to run anytime. Does NOT require a running node.

Back up and restore a Fukuii node — node key, keystore, config, known peers, and the RocksDB blockchain/state database — plus chain export/import for portable backups. Use when asked to back up before an upgrade or risky change, set up a backup strategy, restore after data loss/corruption, or run disaster recovery. Backups are read-only; restore and chain import are irreversible writes that must follow the guarded-write protocol.

Stand up a private, consortium, or otherwise custom EVM network on Fukuii — author a custom genesis (chain id, allocs, fork schedule), wire bootstrap/static nodes, and configure consensus, without modifying source. Use when creating a private chain, a consortium/enterprise network, an L2-style custom-genesis chain, or a local multi-node test network. Genesis/config authoring plus the node start are setup actions; key/alloc generation is security-sensitive under the guarded-write protocol.

Generate and handle Fukuii cryptographic material via the `fukuii cli` subcommands — node private keys, key pairs, address derivation, key encryption, and genesis allocation snippets. Use when bootstrapping a node identity, creating accounts/keys, deriving an address from a private key, encrypting a key for the keystore, or building genesis allocs for a custom network. Keys are secrets — handling them is an irreversible, security-sensitive action under the guarded-write protocol.

Validate and control Ethereum Classic (ETC) PoW/Ethash mining on a Fukuii node — check mining state, start/stop the internal miner, set the coinbase, inspect hashrate and work, and wire up external miners. Use when asked to start/stop mining, verify a miner is producing blocks, change the reward address, or debug why mining isn't working. ETC-only (PoW); status checks are read-only, start/stop/set-etherbase are reversible writes under the guarded-write protocol.

Produce a comprehensive health verdict for a running Fukuii node — client version, sync state, peer count, latest block height, mining state, and a recent-log scan — rolled into HEALTHY / DEGRADED / ACTION REQUIRED. Use when asked to "check the node", "is my node OK", do a routine/scheduled health check, or verify a node before or after maintenance. Read-only; safe to run anytime.

Review and tighten a Fukuii node's security posture — block/unblock abusive peer IPs, manage trusted peers, audit which RPC namespaces and interfaces are exposed, and apply RPC/TLS exposure best practices. Use when responding to abusive peers, before exposing a node, during a security/audit review, or to lock down RPC. IP blocking and trusted-peer changes are reversible writes; config/exposure changes that need a restart are irreversible — all under the guarded-write protocol.

Diagnose and fix stalled, slow, or stuck blockchain synchronization on a Fukuii node — SNAP sync and full/regular sync alike — covering pivot stalls, account/storage-range progress, peer starvation, and performance tuning. Use when sync is "stuck", "not progressing", "too slow", block height isn't advancing, or after a restart that won't catch up. Diagnosis is read-only; tuning changes config (restart required) under the guarded-write protocol.

Secure Fukuii's JSON-RPC endpoint with TLS/HTTPS — switch the RPC server to https, configure the certificate keystore and password, and rotate certs. Use when exposing RPC beyond localhost, hardening an endpoint, fixing TLS/cert errors, or meeting an audit requirement for encrypted RPC. Changing the RPC mode is a config edit that requires a restart — an irreversible/disruptive action under the guarded-write protocol.