Module address_book 

AddressBook - global PeerId → (Vec<Address>, ref_count) registry per ENGINE.md §10.5 + docs/ADDRESSING.md.

Real-world peers expose multiple reachable endpoints (/ip4/.../tcp/..., /ip6/.../quic/..., /relay/...); the AddressBook holds the ordered list per peer (insertion order = peer-stated preference) and the host transport adapter picks one based on its networking capabilities.

Entries are reference-counted: multiple overlay protocols can independently “own” the same peer without duplicating address records. add_peer increments the count; drop_peer decrements; the entry is removed when the count hits zero. Components that need peer metadata (gossip overlays, peer-sampling views) store their own metadata in their own state and call lookup here for addresses - addresses live in exactly one place.

The wire syscall (src/syscall/wire.rs) consults this on every wire::Send to populate WireEnvelope.dest_peer_addresses with the resolved list; a lookup miss surfaces as EngineStep::PeerResolveFailed.

Addresses in bytes-and-brains are multiaddrs. The framework only carries the segments it routes on internally - transport segments (Ip4 / Tcp / etc.) and any other host-managed routing data live in the host adapter. The framework’s Protocol enum is the four BB-internal variants only:

• P2p(PeerId) - peer identity, consulted by the AddressBook.
• Site(NodeSiteId) - data-plane slot fill target.
• Component(ComponentRef) - control-plane component identity.
• Op(String) - control-plane op name for dispatch_atomic.

Receivers route directly by parsing the multiaddr suffix - no per-message-type subscription tables, no endpoint id lookups. Hosts that need IP/port/sim-channel identity prepend whatever bytes they like; the framework treats those bytes as opaque.

Structs

Address

Multiaddr - a sequence of typed Protocol segments describing a delivery path. Per docs/ADDRESSING.md, this is BB’s canonical address type: the suffix segments tell the receiver where to route inside its own node, so no per-message-type or per-endpoint-id lookup tables are needed.

AddressBook

Ref-counted PeerId → Vec<Address> registry. Single source of truth for “where can I reach this peer.”

Enums

AddressBookError

Errors surfaced by AddressBook mutation methods.

AddressError

Decode errors surfaced by Address::from_bytes and Address::parse_str.

Protocol

One typed protocol segment in an Address multiaddr. Each variant maps to a stable BB-specific multiaddr code in the 0xE1-0xEF range (P2p reuses the libp2p code 0x55 since it carries the BB PeerId identity that crosses transport adapters). The binary encoding is code (u8) || payload where the payload’s length is fixed for every variant except Op (which is length-prefixed).

Constants

DEFAULT_ADDRESS_BOOK_CAP

Default cap on tracked peer entries. Adversarial peer-discovery floods (gossip announcements, peer-list responses, multi-address chatter) would otherwise grow entries without bound.

Type Aliases

Multiaddress

Public DSL alias - the chosen name for Address on the graph surface. The internal type is framework::Address; the alias keeps user-facing code (Output<Multiaddress>, Multiaddress constants) reading naturally without introducing a second type.