Skip to content

docs: correct the bridge-address mechanism AGENTS.md still describes - #76

Merged
MattDHill merged 1 commit into
masterfrom
docs/agents-bridge-address-mechanism
Jul 25, 2026
Merged

docs: correct the bridge-address mechanism AGENTS.md still describes#76
MattDHill merged 1 commit into
masterfrom
docs/agents-bridge-address-mechanism

Conversation

@helix-nine

Copy link
Copy Markdown

Why

AGENTS.md is auto-loaded by every agent working in this repo (CLAUDE.md is literally @AGENTS.md), so a wrong mechanism description there propagates.

#75 updated the helper name to sdk.host.getBridgeAddress but kept the clause describing the mechanism #74 removed:

the OS bridge IP (sdk.getOsIp) plus the assigned external port of bitcoind's rpcHostId/peerHostId bindings

Both halves are now false. git grep getOsIp -- 'startos/**' returns nothing, and reading the assigned port is precisely the coupling getBridgeAddress exists to remove — it resolves the binding's own derived address instead.

What changed

Two lines, docs only.

AGENTS.md — describes what the code does now, and records the one genuinely non-obvious decision in bitcoindBridge: why the RPC lookup passes ssl: false and the P2P lookup passes nothing.

startos/main.ts — "the mapped address" named the map callback the deleted local helper took. getBridgeAddress has no such parameter, so a reader following the word into utils.ts finds no mapping step. Now "the bridge address". Comment text only.

On the ssl: rationale

Worth stating precisely, because the SDK's own docstring is loose here and I initially inherited its looseness:

  • RPC — bitcoind binds it protocol: 'http', which desugars to secure: null plus a generated addSsl. BindInfo::new only skips assigned_port when secure.ssl == true and addSsl is set, so this binding carries both ports and publishes a plaintext and a TLS bridge address side by side. The discriminator is genuinely required; an undiscriminated lookup is order-dependent.
  • P2Pprotocol: null, addSsl: null, secure: {ssl: false}, so plaintext only. Note ssl: false there would in fact match (the filter is ssl === undefined || a.ssl === ssl) — it is not that a discriminator selects nothing, it is that pinning one re-asserts bitcoind's TLS arrangement, which is the coupling being removed.

So the doc no longer claims "only one of assignedPort/assignedSslPort is ever populated" — for an http binding both are, and that overstatement would send someone debugging a null address down the wrong path.

Verification

npm run check and prettier clean. No republish: tagAndRelease.yml has paths-ignore: ['*.md'], and main.ts's change is comment-only, so no version bump is warranted.

PR #75 swapped the helper name to sdk.host.getBridgeAddress but kept the
clause describing the mechanism it replaced — resolution via sdk.getOsIp
plus the binding's assigned external port. getOsIp is no longer called
anywhere in startos/, and reading the assigned port is the coupling the
helper exists to remove.

Records why the RPC lookup passes ssl: false and the P2P one passes no
discriminator, and drops 'mapped', which named an argument the deleted
local helper took and getBridgeAddress does not.

@MattDHill MattDHill left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verified against current master (2574ec6). Both claims hold: getOsIp appears nowhere under startos/, and the RPC/P2P ssl: asymmetry is correct — bitcoind binds RPC protocol: 'http' (secure: null + generated addSsl), so BindInfo::new allocates both ports and the bridge publishes a plaintext and a TLS leg; P2P is secure: {ssl:false}, one leg. Dropping the SDK docstring's "only one of those is ever populated" is the right call — that overstatement is false for an http binding and should be fixed at the source in start-sdk.

No republish, confirmed rather than assumed: 0.11.1:13 is now on community-prod at git hash 2574ec6, so the Check production registry step returns non-empty and sets skip=true, which gates both Force-push release tag and the entire Release job. The startos/main.ts hunk rides along for free.

@MattDHill
MattDHill merged commit 2a556ef into master Jul 25, 2026
3 checks passed
@MattDHill
MattDHill deleted the docs/agents-bridge-address-mechanism branch July 25, 2026 15:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants