| name | fukuii-node-configuration |
| description | 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. |
Fukuii node configuration
Read ../CONVENTIONS.md first. Almost every config change needs a restart → 🔴
(back up config first; the node is unavailable during restart).
When to use
- Enable/disable an RPC namespace (e.g. add
mcp or admin).
- Switch sync mode, set the datadir, change ports, tune resources.
- Pick an operating profile for a role (RPC provider, miner, bootnode, …).
Config model
- HOCON, layered: base fragments in
src/main/resources/conf/base/*.conf
(network.conf, sync.conf, mining.conf, db.conf, …) composed per network
(etc.conf, mordor.conf, sepolia.conf, …). Operators override via their own
conf/fukuii.conf and -Dconfig.file=.
- Templates worth reading:
conf/enterprise-template.conf,
src/universal/custom-config-example.conf.
High-value keys (verified)
| Concern | Key(s) |
|---|
| RPC namespaces | network.rpc.apis (default eth,web3,net,personal,fukuii,debug,qa,admin; add mcp for MCP tools) |
| RPC bind/port | network.rpc.http.{interface,port,mode} (default localhost:8546, http) |
| Sync strategy | sync.do-snap-sync, sync.do-fast-sync (ETC/Mordor — EL manages sync directly) |
| Rapid sync | sync.checkpoint-sync-file / -url (→ fukuii-checkpoint-service; ETC/Mordor only) |
| Chain family selector | network-type (in base/chains/<chain>.conf): "etc" for ETC/Mordor, "eth" for ETH/Sepolia (verified in eth-chain.conf / sepolia-chain.conf). This selects the consensus/fork-dispatch path; ETH/Sepolia additionally requires the engine-api section with a jwt-secret-path. |
| Fork dispatch | ETC uses OlympiaOpCodes / forBlock() (block-number forks); ETH/Sepolia uses OsakaOpCodes / forTimestamp() (timestamp forks). These code paths MUST NOT be mixed. |
| Engine API | network.engine-api.{enabled,interface,port,jwt-secret-path} — ETH/Sepolia only; the CL connects here; default port 8551, disabled by default. Enable and set jwt-secret-path to connect a CL client. |
| Mining | mining.mining-enabled, mining.coinbase (ETC/Mordor only → fukuii-mining-operations) |
| TLS | network.rpc.http.mode + nested network.rpc.http.certificate { keystore-path, keystore-type, password-file } (→ fukuii-tls-operations) |
| P2P | network.server-address.port, network.discovery.port (default 30303) |
Procedure
- Back up current config (🟢) — copy
fukuii.conf aside (fukuii-backup-restore).
- Make the smallest change (🔴) — edit one concern at a time; keep overrides
in the operator config, don't hand-edit shipped
base/*.conf.
- Validate before restart — sanity-check HOCON syntax; cross-check key paths
against the
base/*.conf source (typos silently fall back to defaults).
- Restart & verify (🔴) — restart, then confirm the change took effect
(e.g.
rpc_modules for enabled apis, eth_syncing for sync mode) and run
fukuii-node-health-check.
- Roll back — if the node misbehaves, restore the backed-up config and restart.
Deep reference
docs/runbooks/node-configuration.md, docs/runbooks/operating-modes.mdsrc/main/resources/conf/base/ (authoritative key names/defaults)
Output
CONVENTIONS §4 block. Evidence = the key(s) changed, old→new values, and the
post-restart verification result.
