Fulcrum BCH on StartOS

Upstream project: https://github.com/cculianu/Fulcrum

Everything not listed in this document should behave the same as upstream Fulcrum. If a feature, setting, or behavior is not mentioned here, the upstream documentation is accurate and fully applicable.

Fulcrum is a fast, feature-complete SPV server for Bitcoin Cash, written by Cculianu. It indexes the BCH blockchain via Bitcoin Cash Node and serves the Electrum protocol to BCH wallets and the BCH Explorer.

---

Table of Contents

• Image and Container Runtime
• Volume and Data Layout
• Installation and First-Run Flow
• Configuration Management
• Network Access and Interfaces
• Backups and Restore
• Health Checks
• Dependencies
• Limitations and Differences
• What Is Unchanged from Upstream
• Contributing
• Quick Reference for AI Consumers

---

Image and Container Runtime

Property	Value
Fulcrum	cculianu/fulcrum:v2.1.0 (upstream, unmodified)
Architectures	x86_64, aarch64
Runtime	Single container

Volume and Data Layout

Volume	Mount Point	Purpose
main	/data	Fulcrum index data + configuration

StartOS-specific files:

File	Volume	Purpose
fulcrum.conf	main	Fulcrum configuration (managed by StartOS)
banner.txt	main	MOTD banner shown to Electrum clients on connect
store.json	main	StartOS state (selected node package ID)

Installation and First-Run Flow

1. Ensure a BCH node package is installed (default: bitcoincashd) and fully synced
2. Install Fulcrum BCH from the StartOS marketplace
3. Selected BCH node backend will be automatically configured with:
   • txindex=true (transaction indexing enabled)
   • prune=0 (pruning disabled)
   • zmqEnabled=true (ZMQ notifications enabled)
4. Wait for selected node backend to finish syncing
5. Fulcrum will begin indexing the full BCH blockchain — this may take several hours on first run

Install alert: Fulcrum BCH requires Bitcoin Cash Node to be fully synced before it begins indexing. Initial indexing of the full BCH blockchain may take several hours.

Uninstall alert: Uninstalling Fulcrum BCH will permanently delete all index data. You will need to re-index from scratch if reinstalled.

Configuration Management

Fulcrum is configured via fulcrum.conf, managed by StartOS. RPC credentials are automatically injected from the selected node backend's store.json.

Node Backend Selection

Use Actions -> Select Node Backend to choose which StartOS package ID Fulcrum should use.

• Default: bitcoincashd
• You can switch to any compatible BCH node package ID without refactoring Fulcrum internals

User-Configurable Settings

From the Actions tab in StartOS, select Configure to adjust:

Setting	Default	Description
Server Banner	(set)	MOTD shown to Electrum clients on connect
Bitcoin RPC Timeout (seconds)	30	Timeout for RPC calls to Bitcoin Cash Node
Bitcoin RPC Clients	3	Simultaneous RPC connections to selected node backend
Worker Threads (0 for auto)	0	Threads for serving Electrum clients
Database Memory (MB)	2048	RAM allocated to database cache
Database Max Open Files	1000	Max files the database keeps open

Auto-Configured by StartOS

Setting	Value	Purpose
bitcoind	<selected-node>.startos:8332	Selected BCH node RPC host
rpcuser	From selected node store.json	RPC authentication
rpcpassword	From selected node store.json	RPC authentication
datadir	/data	Index data directory
tcp	0.0.0.0:50001	Electrum TCP port

Node Backend Requirements

StartOS automatically configures the selected BCH node backend with critical tasks:

• txindex=true — Transaction indexing enabled (required)
• prune=0 — Pruning disabled (required for full index)
• zmqEnabled=true — ZMQ block notifications (required)

These are enforced via StartOS critical tasks — if the settings don't match, the user is prompted to apply them.

Network Access and Interfaces

Interface	Port	Protocol	Purpose
Electrum	50001	TCP (Electrum protocol)	Serves Electrum clients and BCH Explorer

The Electrum interface is exposed as a non-HTTP API interface (raw TCP).

Backups and Restore

Volumes backed up:

• main — Full Fulcrum index data and configuration

Restore behavior: All index data is restored from the backup. If the index is corrupted or too old, Fulcrum may need to re-index. Consider letting it catch up after restore.

Health Checks

Check	Method	Messages
Electrum	Port 50001 listening	Success: "The Electrum interface is ready" / Loading: "Electrum interface not ready — syncing BCH blockchain..."
Sync Progress	Port 50001 + log parsing	Success: "Fulcrum BCH is fully synced" / Loading: Shows current sync progress from Fulcrum's <Controller> log

The sync progress health check parses Fulcrum's stdout for <Controller> messages and displays them in the StartOS UI, so you can see exact sync status (e.g., block height, percentage).

Dependencies

Dependency	Required	Mounted Volume	Purpose	Auto-Config
BCH Node Backend (bitcoincashd by default)	Yes	main → /mnt/node	Blockchain data + RPC	txindex=true, prune=0, zmqEnabled=true

Selected node backend must be running and passing its primary health check.

The selected node store.json at /mnt/node/store.json is used for RPC authentication.

Limitations and Differences

1. Bitcoin Cash only — This package is configured for BCH mainnet only
2. No SSL — The Electrum interface runs on plain TCP (port 50001), not TLS/SSL
3. Single network — Only mainnet is supported

What Is Unchanged from Upstream

• Full Electrum protocol support
• Complete UTXO index
• Fast initial sync
• Address history and balance queries
• Transaction broadcast
• Block header notifications
• Mempool monitoring
• All Electrum protocol methods

Contributing

Contributions are welcome. Please open an issue or pull request on the GitHub repository.

For build instructions, see the Makefile.

---

Upstream Tracking

This package is adapted from Start9Labs/fulcrum-startos for Bitcoin Cash.

The StartOS wrapper (health checks, SDK patterns, actions, backups) tracks Start9Labs upstream. The Fulcrum binary itself comes from the Docker image (cculianu/fulcrum) — track releases at cculianu/Fulcrum for version bumps.

To set up upstream tracking locally:

git remote add upstream-startos https://github.com/Start9Labs/fulcrum-startos.git
git fetch upstream-startos

Cherry-pick relevant upstream commits (bug fixes, SDK updates, health check improvements) rather than merging wholesale, since this package has diverged in dependency wiring (bitcoin-cash-node instead of bitcoind) and auth method (RPC user/password instead of cookie auth).

git fetch upstream-startos
git log upstream-startos/master --oneline
git cherry-pick <commit-hash>

Architecture Support

Currently x86_64 only. To add aarch64 (ARM) support in the future:

1. Build multi-arch Docker images:

   docker buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/cyberashven/fulcrum-bch:latest .

2. Update startos/manifest.ts image arch fields:

   arch: ['x86_64', 'aarch64'],

---

Quick Reference for AI Consumers

package_id: fulcrum-bch
upstream_version: 2.1.0
images:
  main: cculianu/fulcrum:v2.1.0
architectures: [x86_64, aarch64]
volumes:
  main: /data (index + config)
ports:
  electrum: 50001 (TCP, Electrum protocol)
dependencies:
  - bitcoincashd (required default, version >=29.0.0:0; overridable via Select Node Backend action)
health_checks:
  - electrum: port_listening 50001
  - sync-progress: port_listening 50001 + log parsing
backup_strategy: volume rsync (main)
config_files:
  - /data/fulcrum.conf (managed by StartOS)
  - /data/banner.txt (MOTD banner)

Roadmap

• aarch64 support — Planned for the next release.