Knuth

Upstream docs: github.com/k-nuth/kth · kth.cash

Knuth is a high-performance Bitcoin Cash full node written in C++. This StartOS package mirrors the BCHN / BCHD / Flowee schema: per-network ports, optional JSON-RPC (v1.3.0+), Tor dependency, and test-network data isolation under /data/<network>/.

Versioning: the number before : is kth upstream (today 1.3.0). The number after : is the StartOS package revision, starting at :0 (1.3.0:0, 1.3.0:1, …). Packaging-only fixes bump :N only — never invent a fake kth version.

---

Table of Contents

1. Image and Container Runtime
2. Volume and Data Layout
3. Installation and First-Run Flow
4. Default Networking
5. Configuration Management
6. Network Access and Interfaces
7. Actions (StartOS UI)
8. Backups and Restore
9. Health Checks
10. Dependencies
11. Default Overrides
12. Limitations and Differences
13. What Is Unchanged from Upstream
14. Contributing
15. Quick Reference for AI Consumers

---

1. Image and Container Runtime

Field	Value
Image ID	knuth
Build	Dockerfile copies kth + GCC 15 runtime from upstream ghcr.io/k-nuth/kth (or a local RPC-enabled build until upstream ships rpc=True)
Architectures	x86_64, aarch64, riscv64 (kth is compiled on amd64; other arches use StartOS qemu via emulateMissingAs)
Command	kth -c /data/kth.cfg --init_run --network <name>

---

2. Volume and Data Layout

Volume Name	Mount Point	Purpose
main	/data	Config, store, and all chain data

StartOS-managed files:

Path	Managed By	Purpose
kth.cfg	knuth.conf file model	Node INI config (v1.3.0 key names: net.*, db.*, chain.*, node.*, rpc.*)
store.json	store.json file model	network, rpcEnabled, credentials, IPC/UTXOZ/Tor flags

Chain layout (same schema as BCHN/BCHD/Flowee):

Path	Network
/data/blockchain	mainnet chain DB
/data/peers.dat	mainnet hosts pool
/data/testnet3, /data/testnet4, /data/scalenet, /data/chipnet, /data/regtest	per-testnet chain + peers

---

3. Installation and First-Run Flow

1. Seed store.json + kth.cfg (mainnet, RPC off, IPC/UTXOZ on, generated RPC creds).
2. Launch kth -c /data/kth.cfg --init_run --network mainnet.
3. Health: chaindir liveness when RPC is off; RPC + sync checks when RPC is on.
4. Enable JSON-RPC in Node Settings for mining pools / Fulcrum / Explorer backends.

---

4. Default Networking

Transport	Default	How to Change
Clearnet	Enabled	StartOS interfaces
Tor	Off	Node Settings + Tor package
I2P	Not implemented	—

---

5. Configuration Management

Group	Settings
Network	mainnet / testnet3 / testnet4 / scalenet / chipnet / regtest — rewrites peer port, RPC port, db.directory, net.hosts_file (the peer port, db.directory and net.hosts_file are also reasserted on every start, because kth tells chipnet from testnet4 only by peer port 48333)
Node Settings	db mode (full / blocks / pruned), max size (pruned), connections, latency, verbose log, JSON-RPC toggle, IPC, UTXOZ, Tor

---

6. Network Access and Interfaces

Interface	Port (mainnet)	Purpose	Condition
Peer	8333	P2P	Always
JSON-RPC	8332	API	When rpcEnabled

Per-network peer/RPC ports match the shared BitcoinCash1 table (see Quick Reference).

---

7. Actions (StartOS UI)

Action ID	Name	Group
runtime-info	Node Info	Info
network-config	Network	Configuration
node-settings	Node Settings	Configuration
rpc-credentials	RPC Credentials	Credentials
delete-peer-list	Delete Peer List	Maintenance (stopped only)
delete-test-network-data	Delete Test Network Data	Maintenance (stopped only; can wipe the active testnet)
rebuild-chain-data	Rebuild Blockchain Database	Maintenance (stopped only)
autoconfig	Auto-Configure	Hidden (cross-package)

---

8. Backups and Restore

Backed up: kth.cfg, store.json (credentials, flags).

Excluded: chain dirs (/blockchain, testnet subdirs), peers.dat, logs.

---

9. Health Checks

Check	When	Method
RPC (daemon ready)	Always	getblockchaininfo when JSON-RPC is on; otherwise the kth process
Blockchain Sync	Always	Sidecar getblockchaininfo (lifts stale kth blocks to the blk*.dat tip). A <0.1% header gap at the tip is Synced, not Syncing 100%. With no peers, or a newest block more than 3 hours old (24 hours on scalenet, never on regtest), it stays loading instead of Synced, because a node cut off from the chain still finds its tip at the top of its own headers.
Peer Connections	Always	Knuth Peers: n/m status log (no getpeerinfo in v1.3.0)
Tor	Always	Optional — listed as a dependency; health is disabled until Tor routing is turned on
I2P	Always	Disabled (same as BCHN/Flowee until implemented)
Clearnet	Always	Outbound unless a public address is published
UTXO-Z Storage / IPC / C-API	Always	Knuth-specific capability rows

---

10. Dependencies

Package	Optional	Purpose
tor	yes (optional)	Always listed on the Dependencies tab (kind: exists when Tor Routing is off, kind: running when on). Not required to be running unless Node Settings → Tor Routing is enabled.

---

11. Default Overrides

Setting	StartOS value	Reason
--init_run	always	init chain then run
--network	from store	v1.3.0 network select
db.db_mode	full	indexed; required for Fulcrum/Explorer
rpc.enabled	false	opt-in; credentials pre-generated
rpc.bind	0.0.0.0	reachable from other containers
net.hosts_file	under /data	kth defaults to CWD /
IPC / UTXOZ	true	capability flags for dependents

---

12. Limitations and Differences

1. Built from source. The official ghcr.io/k-nuth/kth image is built without rpc=True (see k-nuth/docker-images PR #7), so the Dockerfile compiles kth with the JSON-RPC server enabled. check-upstream.yml checks the official image daily; once the image for the pinned version ships JSON-RPC, scripts/use-upstream-image.sh swaps the Dockerfile for scripts/Dockerfile.upstream (a thin wrapper around the official image), commits it to master and dispatches Tag and Release.
2. No initialblockdownload / verificationprogress — sync health uses Knuth's coordinator log (RPC getblockchaininfo.blocks is often 0 at the tip).
3. gRPC not exposed in this package.
4. Tor proxy passthrough to kth is opt-in; verify after enabling.
5. RPC compatibility sidecar — kth 1.3.0 fetch_block() is a stub after the LMDB→blk*.dat move (object does not exist for every hash). The package runs scripts/rpc_compat.py on the public RPC port and leaves kth on 127.0.0.1:19332. Ready probes kth on that internal port so the sidecar can start. The sidecar also implements getnetworkinfo, classic getblocktemplate (from getblocktemplatelight), submitblock→submitblocklight, and cashaddr validateaddress. JSON-RPC bodies end with a trailing LF so ckpool/EloPool (read_socket_line) does not hang 20s after HTTP/1.1 200 OK.

---

13. What Is Unchanged from Upstream

• Consensus / P2P protocol from k-nuth/kth
• Config key names and db_mode values from v1.3.0
• IPC/C-API and UTXOZ behavior

---

14. Contributing

See CONTRIBUTING.md

check-upstream.yml looks for a new Knuth release on k-nuth/kth daily. When one appears, scripts/auto-bump.sh sets ARG KNUTH_VERSION in the Dockerfile, sets startos/versions/current.ts to <upstream>:0, resets ALLOW_DOWNGRADE to false, commits the bump straight to master, and dispatches Tag and Release, which builds and publishes the new version. Package-only fixes bump the revision after the colon by hand.

---

15. Quick Reference for AI Consumers

package_id: knuth-bch
upstream_repo: https://github.com/k-nuth/kth
package_repo: https://github.com/BitcoinCash1/knuth-bch-startos
command: [kth, -c, /data/kth.cfg, --init_run, --network, <name>]
networks:
  mainnet:  { peer: 8333,  rpc: 8332,  db: /data/blockchain, hosts: /data/peers.dat }
  testnet3: { peer: 18333, rpc: 18332, db: /data/testnet3 }
  testnet4: { peer: 28333, rpc: 28332, db: /data/testnet4 }
  scalenet: { peer: 38333, rpc: 38332, db: /data/scalenet }
  chipnet:  { peer: 48333, rpc: 48332, db: /data/chipnet }
  regtest:  { peer: 18444, rpc: 18443, db: /data/regtest }
config_keys_v1_3_0: [net.*, db.*, chain.*, node.*, rpc.*, log.*]
db_mode: [full, blocks, pruned]   # not full_indexed/normal
rpc_available: true               # when image built with rpc=True and toggle on
schema_reference: bitcoin-cash-node-startos