fix: render the Electrum address as ssl://; 0.11.1:18 → 0.11.1:19

[helix-nine]

The report

A user who had just migrated from 0.3.5.1 found Electrs running, fully synced, and reporting "Electrum Server is ready and accepting connections". The Interfaces page showed the Main IPv4 endpoint as 192.168.x.x:50001. Sparrow could reach neither that nor the onion, returning only "Retries exhausted".

The endpoint was fine. nc reached 50001, and openssl s_client against it came back with the StartOS certificate chain. Setting Private Electrum → port 50001 → Use SSL ON connected immediately, to electrs/0.11.1, protocol 1.4.

Their words: "the current Electrs Interfaces page shows :50001, but it isn't obvious from that screen that Sparrow needs SSL enabled. The Electrs Instructions also appear to reference SSL on port 50002, which made troubleshooting more confusing."

Both halves of that are our bug.

Nothing said the endpoint was TLS

MultiHost.bindPort with protocol: null returns new Origin(this, internalPort, null, null) — scheme and sslScheme are both null, and this package passed schemeOverride: null on top. addressHostToUrl omits the :// prefix entirely when the effective scheme is null, so StartOS printed a bare host:port. The only SSL signal on the row is the certificate column reading "Root CA", which is easy to miss, and the interface was called "Main".

schemeOverride: { ssl: 'ssl', noSsl: 'tcp' } makes every address render ssl://host:port — the form Electrum wallets expect to be handed. This is well-worn in the fleet: coturn uses turns/turn, owntracks mqtts/mqtt, lnd lndconnect, simplex smp.

The interface is renamed Main → Electrum (SSL). That name is accurate rather than aspirational: the plaintext leg's forward is gated on !reqs.secure && !info.secure() (net/forward.rs:705), and info.secure() holds only for Loopback | Bridge, so no LAN or WAN gateway ever gets a rule for it. TLS is the only way in from off the box.

The plaintext port is not unbound, though — it is reachable at the bridge IP from the host and from other services over lxcbr0, source-filtered to that subnet. That is what getBridgeAddress(…, { ssl: false }) returns, and what replaced the retired electrs.startos DNS name.

The docs named a port StartOS never promised

instructions.md named 50002 three times. preferredExternalPort is a preference: BindInfo::new tries it and otherwise falls back to alloc(), and an assigned binding then never changes its external port — integrations depend on it, so only uninstall and reinstall reassigns. The number is per-server and fixed for the life of the install.

Which is exactly why this user was on 50001. Their 0.3.x manifest bound one port and had lan-config commented out:

interfaces:
  electrum:
    tor-config:
      port-mapping:
        50001: "50001"
    # lan-config:
    #   443:
    #     ssl: true
    #     internal: 50001

The v1 compat shim maps that to {preferredExternalPort: 50001, addSsl: null} (addSsl comes only from lan-config), giving assignedPort: 50001, assignedSslPort: None. The 0.4 package reuses the same host id (electrum) and internal port, so installing it hit BindInfo::update rather than new, where the since-removed carried handed that lone number to the TLS leg. Start9Labs/start-technologies#3638 stops that happening again; it does not and should not move servers already assigned.

So instructions.md no longer names a port. It points at the Interfaces page, and names the toggle — Private Electrum → Use SSL in Sparrow, the s suffix in Electrum — since the failure mode is a generic timeout that mentions neither TLS nor the certificate.

A wrong claim in the developer docs

README.md and AGENTS.md both said no plain-TCP port is exposed externally. One is allocated and reachable over the bridge, as above. Corrected in both, and AGENTS.md keeps one bullet on it — the interface is TLS-only from off the box, the plaintext port is the bridge address dependents resolve, and no literal external port belongs in docs.

Version

0.11.1:18 → 0.11.1:19. Interface metadata and docs only, so no migration — but :18 carried the clearTask migration for bitcoind's action renames, so it is frozen into startos/versions/v0.11.1_18.ts and added to the graph to keep it reachable from :17 and below.

Verified with npm run check and prettier. Not installed on a box — the change is exportServiceInterface metadata, which setupInterfaces re-emits on update.