Detect backend and fail fast when zcashd lacks required experimental feature

[ronykris]

Closes #375
Updated/validated behavior: during startup, lightwalletd detects the backend using getinfo.subversion.

zcashd (/MagicBean:): lightwalletd calls getexperimentalfeatures and requires that either lightwalletd or insightexplorer is enabled; otherwise startup fails with a clear error.

zebrad (/Zebra:): skips the experimental feature check (zebrad does not implement getexperimentalfeatures and supports required RPCs by default).

Test Plan:

go test ./...

Manual – zcashd missing feature:

• Run zcashd without -experimentalfeatures=lightwalletd/insightexplorer.
• Start lightwalletd.
  Expected: startup fails with appropriate error message.

Manual – zcashd with feature enabled:

• Run zcashd with -experimentalfeatures=lightwalletd (or insightexplorer).
• Start lightwalletd.
  Expected: startup succeeds.

Manual – zebrad backend:

• Point lightwalletd at zebrad.
  Expected: startup succeeds

[LarryRuane]

Here's a suggestion for testing. Modifying those zcashd configuration flags on mainnet or even testnet is pretty disruptive, so instead:

$ mkdir /tmp/zrtest
cat <<EOF >/tmp/zrtest/zcash.conf
regtest=1
lightwalletd=1
experimentalfeatures=1
i-am-aware-zcashd-will-be-replaced-by-zebrad-and-zallet-in-2025=1
rpcpassword=light
EOF
$ zcashd -datadir=/tmp/zrtest

In a different window, start lightwalletd:

go run main.go --zcash-conf-path /tmp/zrtest/zcash.conf --no-tls-very-insecure --log-file /dev/stdout

(You'll get an error, getblock 0 failed, will retry, but that will be after this new code runs.)

You can try the various combinations of lightwalletd and insightexplorer being present or not.

[ronykris]

Here's a suggestion for testing. Modifying those zcashd configuration flags on mainnet or even testnet is pretty disruptive, so instead:

I incorporated the changes you requested, but did not get time to run the tests. I will do it ASAP and share an update here.

[LarryRuane]

Thanks for the updates, looks good now, except I still have one question. Yes, please test carefully, even if manual testing, and please report the testing you have done here, thanks! I'm out of town so I won't be able to test until next week on Wednesday probably.

[LarryRuane]

Suggested change

	common.Log.Infof("zcashd backend detected but getexperimentalfeatures RPC failed: %s", rpcErr.Error())
	common.Log.Fatalf("zcashd backend detected but getexperimentalfeatures RPC failed: %s", rpcErr.Error())

Don't you think we should fail here? I'm not sure what is the point of trying to go on?

[ronykris]

Yes, we should fail here. No point proceeding.

[ronykris]

Here's a suggestion for testing. Modifying those zcashd configuration flags on mainnet or even testnet is pretty disruptive, so instead:

$ mkdir /tmp/zrtest
cat <<EOF >/tmp/zrtest/zcash.conf
regtest=1
lightwalletd=1
experimentalfeatures=1
i-am-aware-zcashd-will-be-replaced-by-zebrad-and-zallet-in-2025=1
rpcpassword=light
EOF
$ zcashd -datadir=/tmp/zrtest

In a different window, start lightwalletd:

go run main.go --zcash-conf-path /tmp/zrtest/zcash.conf --no-tls-very-insecure --log-file /dev/stdout

(You'll get an error, getblock 0 failed, will retry, but that will be after this new code runs.)

You can try the various combinations of lightwalletd and insightexplorer being present or not.

Thank you for the pointer Larry. Below are the tests I attempted and pasted are the relevant snippets.

Test 1: lightwalletd feature enabled

Pass: It went through the startup sequence and starts the gRPC server
{"app":"lightwalletd","level":"info","msg":"Starting gRPC server on 127.0.0.1:9067","time":"2026-01-26T01:12:43+05:30"}

oger@roger:~/dev/code/lightwalletd$ zcash-cli -datadir=/tmp/zrtest getexperimentalfeatures

`[
"lightwalletd"
]

oger@roger:~/dev/code/lightwalletd$ go run main.go --zcash-conf-path /tmp/zrtest/zcash.conf --no-tls-very-insecure --log-file /dev/stdout --data-dir /tmp/lwdata

{"app":"lightwalletd","buildDate":"","buildUser":"","gitCommit":"","level":"info","msg":"Starting lightwalletd process version v0.0.0.0-dev","time":"2026-01-26T01:12:43+05:30"} {"app":"lightwalletd","level":"warning","msg":"Starting insecure no-TLS (plaintext) server","time":"2026-01-26T01:12:43+05:30"} Starting insecure server {"app":"lightwalletd","level":"info","msg":"Got sapling height 0 block height 0 chain regtest branchID 00000000","time":"2026-01-26T01:12:43+05:30"} {"app":"lightwalletd","level":"info","msg":"Reading 0 blocks (since Sapling activation) from disk cache ...","time":"2026-01-26T01:12:43+05:30"} {"app":"lightwalletd","level":"info","msg":"Done reading 0 blocks from disk cache","time":"2026-01-26T01:12:43+05:30"} {"app":"lightwalletd","level":"info","msg":"Starting gRPC server on 127.0.0.1:9067","time":"2026-01-26T01:12:43+05:30"}

Test 2: insightexplorer enabled

Pass: It went through the startup process, read the blocks and started the gRPC server

oger@roger:~/dev/code/lightwalletd$ zcash-cli -datadir=/tmp/zrtest getexperimentalfeatures

[ "insightexplorer" ]

oger@roger:~/dev/code/lightwalletd$ go run main.go --zcash-conf-path /tmp/zrtest/zcash.conf --no-tls-very-insecure --log-file /dev/stdout --data-dir /tmp/lwdata

"app":"lightwalletd","buildDate":"","buildUser":"","gitCommit":"","level":"info","msg":"Starting lightwalletd process version v0.0.0.0-dev","time":"2026-01-26T01:25:03+05:30"} {"app":"lightwalletd","level":"warning","msg":"Starting insecure no-TLS (plaintext) server","time":"2026-01-26T01:25:03+05:30"} Starting insecure server {"app":"lightwalletd","level":"info","msg":"Got sapling height 0 block height 0 chain regtest branchID 00000000","time":"2026-01-26T01:25:03+05:30"} {"app":"lightwalletd","level":"info","msg":"Reading 0 blocks (since Sapling activation) from disk cache ...","time":"2026-01-26T01:25:03+05:30"} {"app":"lightwalletd","level":"info","msg":"Done reading 0 blocks from disk cache","time":"2026-01-26T01:25:03+05:30"} {"app":"lightwalletd","level":"info","msg":"Starting gRPC server on 127.0.0.1:9067","time":"2026-01-26T01:25:03+05:30"}

Test 3 : Neither feature enabled

Fail: Execution stops with a meaningful error

oger@roger:~/dev/code/lightwalletd$ zcash-cli -datadir=/tmp/zrtest getinfo
{ "version": 6110050, "build": "v6.11.0", "subversion": "/MagicBean:6.11.0/", "protocolversion": 170140, "walletversion": 60000, "balance": 0.00000000, "blocks": 0, "timeoffset": 0, "connections": 0, "proxy": "", "difficulty": 1, "testnet": false, "keypoololdest": 1769363950, "keypoolsize": 101, "paytxfee": 0.00000000, "relayfee": 0.00000100, "errors": "", "errorstimestamp": 1769371718 }

roger@roger:~/dev/code/lightwalletd$ zcash-cli -datadir=/tmp/zrtest getexperimentalfeatures
[ ]

roger@roger:~/dev/code/lightwalletd$ go run main.go --zcash-conf-path /tmp/zrtest/zcash.conf --no-tls-very-insecure --log-file /dev/stdout --data-dir /tmp/lwdata

{"app":"lightwalletd","buildDate":"","buildUser":"","gitCommit":"","level":"info","msg":"Starting lightwalletd process version v0.0.0.0-dev","time":"2026-01-26T01:39:18+05:30"} {"app":"lightwalletd","level":"warning","msg":"Starting insecure no-TLS (plaintext) server","time":"2026-01-26T01:39:18+05:30"} Starting insecure server {"app":"lightwalletd","level":"info","msg":"Got sapling height 0 block height 0 chain regtest branchID 00000000","time":"2026-01-26T01:39:18+05:30"} {"app":"lightwalletd","level":"fatal","msg":"zcashd is running without the required experimental feature enabled; enable 'lightwalletd' or 'insightexplorer'","time":"2026-01-26T01:39:18+05:30"} Lightwalletd died with a Fatal error. Check logfile for details. exit status 1

Test 4: Zebra backend

Pass: Detects Zebrad backend; skips experimental feature check and proceeds with starting gRPC server

roger@roger:~/dev/code/lightwalletd$ go run main.go --zcash-conf-path /tmp/lw-zebra/zcash.conf --no-tls-very-insecure --log-file /dev/stdout --data-dir /tmp/lwdata

"app":"lightwalletd","level":"info","msg":"Got sapling height 419200 block height 0 chain main branchID 00000000","time":"2026-01-26T02:06:11+05:30"} {"app":"lightwalletd","level":"info","msg":"Detected zebrad backend; skipping experimental feature check","time":"2026-01-26T02:06:11+05:30"} {"app":"lightwalletd","level":"info","msg":"Reading 0 blocks (since Sapling activation) from disk cache ...","time":"2026-01-26T02:06:11+05:30"} {"app":"lightwalletd","level":"info","msg":"Done reading 0 blocks from disk cache","time":"2026-01-26T02:06:11+05:30"} {"app":"lightwalletd","level":"info","msg":"Starting gRPC server on 127.0.0.1:9067","time":"2026-01-26T02:06:11+05:30"} {"app":"lightwalletd","level":"info","msg":"Waiting for zebrad height to reach Sapling activation height (419200)...","time":"2026-01-26T02:06:11+05:30"}

Test 5 : Unsupported backend

Fail: Detects unsupported backend; prevents execution with an error

Changed subver in the code to the below
subver := "/FooNode:1.0.0/"

oger@roger:~/dev/code/lightwalletd$ go run main.go --zcash-conf-path /tmp/lw-zebra/zcash.conf --no-tls-very-insecure --log-file /dev/stdout --data-dir /tmp/lwdata

{"app":"lightwalletd","buildDate":"","buildUser":"","gitCommit":"","level":"info","msg":"Starting lightwalletd process version v0.0.0.0-dev","time":"2026-01-26T02:17:02+05:30"} {"app":"lightwalletd","level":"warning","msg":"Starting insecure no-TLS (plaintext) server","time":"2026-01-26T02:17:02+05:30"} Starting insecure server {"app":"lightwalletd","level":"info","msg":"Got sapling height 419200 block height 11600 chain main branchID 00000000","time":"2026-01-26T02:17:02+05:30"} {"app":"lightwalletd","level":"fatal","msg":"unsupported backend subversion \"/FooNode:1.0.0/\" (expected zcashd or zebrad)","time":"2026-01-26T02:17:02+05:30"} Lightwalletd died with a Fatal error. Check logfile for details. exit status 1

Please let me know if you need more tests executed.

Thank you!

[ronykris]

@LarryRuane Please review the test runs whenever you get the time and let me know if you have questions.

[LarryRuane]

Looks great, one small suggestion, and also please squash down to one commit, thanks.

[LarryRuane]

My IDE (vscode, aka code) automatically runs an excellent tool called goimports whenever I modify and save a file. It formats the code and organizes imports consistently. I recommend you run this; it will move this import down to its own "section" (you'll see). Can you please make that change?

The entire code base isn't quite clean from this tool's prespective, but close (except for the protobuf generated files, unfortunately), and I'd like to keep it that way.

[ronykris]

As requested -

• ran goimports to format the imports
• squashed the commits into a single commit

Please let me know if other edits are needed.

github doesn't understand that the requested change has been made

[LarryRuane]

ACK c679ce1