feat(cln): add expose_private_channels config option

[4xvgal]

Summary

• Add expose_private_channels config option to cdk-cln backend (default: false)
• When enabled, passes exposeprivatechannels: true to CLN's invoice RPC so private channels become route hint candidates in bolt11 invoices
• Uses call_raw to bypass cln-rpc's typed API limitation (Option<Vec<ShortChannelId>> cannot represent boolean true)
• Includes integration test that verifies private channels are included as route hint candidates

Context

CLN's default behavior for route hint selection is non-deterministic — it depends on internal heuristics around inbound capacity, channel count, and other factors. In practice, this means mint nodes with private channel inbound liquidity may intermittently fail to receive payments, because CLN omits the private channel route hints that payers need for routing. This option lets mint operators explicitly include private channels as route hint candidates.

See also: ElementsProject/lightning#7601 for the upstream cln-rpc typing limitation.

Closes #1757

CHANGED

• Cln::new() now accepts expose_private_channels: bool parameter

ADDED

• expose_private_channels field in [cln] config section
• CDK_MINTD_CLN_EXPOSE_PRIVATE_CHANNELS environment variable
• ClnClient::open_private_channel() for integration tests
• create_cln_backend_with_options() helper for integration tests
• Integration test test_expose_private_channels

Test plan

• cargo test -p cdk-cln passes
• cargo clippy -p cdk-cln -- -D warnings passes
• cargo fmt passes
• Regtest integration test (test_expose_private_channels): opens private channel between CLN-1 and CLN-2, generates 10 invoices with expose_private_channels=true, verifies at least one invoice includes private channel route hint (6/10 in local test)
• CI integration tests pass (existing CLN tests should not break since default is false)

🤖 Generated with Claude Code

[4xvgal]

This PR uses call_raw to bypass a cln-rpc typing limitation where exposeprivatechannels is typed as Option<Vec> and cannot represent boolean true.
I've opened an upstream issue to address the root cause: ElementsProject/lightning#8964. If upstream adds UnionField support for this field, this PR can be simplified to
use the typed call_typed API instead of call_raw.

[4xvgal]

The current test generates 10 invoices and asserts that at least one includes a private channel route hint. In local testing this passed at 6/10, but since CLN selects route hints from 3 candidates (LND-1, LND-2, CLN-2) non-deterministically, there's a ~1.7% chance ((2/3)^10) that all 10 miss the private channel.

Would it be better to loop until the first private channel hint is found, with an upper bound of 100 attempts?

The probability of 100 consecutive misses is (2/3)^100 ≈ 2.5 × 10⁻¹⁸, making it effectively impossible to flake. The test would still exit immediately on first success, so typical runtime stays at 1-3 iterations.

[thesimplekid]

Would it be better to loop until the first private channel hint is found, with an upper bound of 100 attempts?

Yeah I think this makes sense if you saw it fail 4/10 times locally would like to reduce flakiness where we can if we know there is a potential source of it, since we already have some issues with our ci just because its so heavy.

[thesimplekid]

Would another option be on the start up of the mint list the cln channels and then pass in the channel ides on the exposeprivatechannels field of the request? I'm not necessarily requesting we do that instead this is probably simpler just trying to understand the api.

[4xvgal]

That would be cleaner from a cdk<-> cln API perspective. however, fetching short cheannel ids only at start up wouldn't detect channels opened after launch.

The root cause is that cln-rpc doesn't expose the needed fields in its tyepd API yet. Once the upstream issue is resolved, we won't need the startup-based approach or the raw JSON workaround in this PR.

For now, I think it makes sense to go with json-raw approach and switch over when the typed API catches up.

[4xvgal]

Would it be better to loop until the first private channel hint is found, with an upper bound of 100 attempts?

Yeah I think this makes sense if you saw it fail 4/10 times locally would like to reduce flakiness where we can if we know there is a potential source of it, since we already have some issues with our ci just because its so heavy.

Updated. The test now iterates up to 100 times, It breaks on the first match.