> ## Documentation Index
> Fetch the complete documentation index at: https://ckb.danielasaboro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Operating Fiber on Multiple Network Addresses

> Week 20 explains Fiber's multi-address listener configuration, startup failure boundaries, peer identity, and reachability evidence.

# Operating Fiber on Multiple Network Addresses

Week 19 verified the binary and rollout path. Week 20 asks what happens when that node must be reachable through more than one network address: IPv4 and IPv6, separate interfaces, or multiple transport endpoints.

Fiber [PR #1642](https://github.com/nervosnetwork/fiber/pull/1642), merged September 24, 2026, adds `fiber.listening_addrs` alongside the existing singular `fiber.listening_addr`. The additional values are appended to the primary address, a listener is started for every effective address, and the existing WebSocket port-reuse behavior is preserved for each TCP address. Existing configurations with no additions behave as before.

This is merged post-v0.9.0 development behavior as of September 24. It is not described here as part of the v0.9.0 release artifact.

## Configuration is an ordered compatibility contract

The old field remains the primary address. The new list extends it:

```yaml theme={null}
fiber:
  listening_addr: "/ip4/0.0.0.0/tcp/8228"
  listening_addrs:
    - "/ip6/::/tcp/8228"
```

Exercise 77 preserves primary-first ordering, accepts an array or comma-separated CLI/environment representation, trims values, removes exact duplicates, and rejects invalid multiaddresses or transport ports. With no additions, its effective list contains exactly the legacy address.

The real PR appends configured strings through Fiber/Tentacle’s address handling. The exercise’s reduced multiaddress parser and duplicate policy are teaching hardening, not a claim about Fiber’s exact parser implementation.

## Partial listener startup must be visible

Multiple addresses create a new failure mode: the first socket binds and the second fails. An operator must not believe the declared configuration is fully served while the process silently runs on a subset.

Exercise 78 models all-or-explicit-failure startup. It opens listeners in order. If an address cannot bind, it closes only the handles created by that startup attempt and reports the failed address. It never closes listeners owned by another running instance. A clean retry can then bind the complete set.

PR #1642’s verified implementation starts a Tentacle listener for each effective address and includes an integration test that connects through the second address. The atomic rollback policy in Exercise 78 is a local operational model, not a quoted Fiber guarantee.

## An address is reachability, not identity

One Fiber node may now have several routes to the same peer identity. The IP version, socket, or transport does not create another node. Conversely, successfully connecting to an address does not prove which node answered.

Exercise 79 signs a handshake transcript containing node ID, complete address, transport, and nonce. The same node identity is accepted over IPv4, IPv6, TCP, and a WebSocket companion endpoint. A signature cannot be transferred to another claimed node, and replaying the nonce fails.

The HMAC fixture is not Fiber’s cryptography or handshake format. It makes the stable security boundary visible: authenticated node keys define peer identity; addresses describe how to reach that identity.

## Desired, bound, advertised, and reachable are different facts

An address can exist in configuration without being bound. It can be bound to a wildcard interface without being safe to advertise. It can be advertised but blocked by a firewall. It can be reachable while presenting the wrong node identity.

Exercise 80 records four layers for each endpoint:

| Layer      | Evidence                                                           |
| ---------- | ------------------------------------------------------------------ |
| Configured | The normalized effective address list contains it.                 |
| Bound      | Startup returned a listener for it.                                |
| Advertised | Public node metadata exposes the intended public endpoint.         |
| Reachable  | An external probe connects and authenticates the expected node ID. |

Every public endpoint needs its own probe. IPv4 success says nothing about IPv6 reachability. Wildcard bind addresses are local listening intent, not public addresses, so the exercise does not require them to be advertised.

## Evidence boundaries

| Claim                                                                                                                                          | Classification                              |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `listening_addrs`, primary-plus-additional merge, one listener per effective address, WebSocket reuse, and second-address integration coverage | Merged Fiber PR #1642 behavior              |
| Presence in Fiber v0.9.0                                                                                                                       | Not claimed                                 |
| Reduced parser, deduplication, atomic startup rollback, HMAC handshake, and audit thresholds                                                   | Simplified local teaching/operational model |
| Public reachability of a configured endpoint                                                                                                   | Unknown until externally probed             |

The [Fiber architecture guide](https://www.nervos.org/knowledge-base/what_is_fiber) supplies the payment-channel context, while the official [Fiber repository](https://github.com/nervosnetwork/fiber) remains the authority for configuration and implementation. [CKB Quest](https://ckb-quest.vercel.app/) inspires the visible test checkpoints, and [Nervos Nation](https://nervosnation.com/) remains optional ecosystem framing.

## Run the exercises

```bash theme={null}
cd week20/fiber-multi-address-operations
npm test
```

* `77-effective-listening-addresses.ts` derives a deterministic backward-compatible address list.
* `78-atomic-listener-startup.ts` prevents silent partial startup and unsafe cleanup of another instance.
* `79-transport-independent-peer-identity.ts` authenticates one node identity across several endpoints and transports.
* `80-multi-address-reachability-audit.ts` compares configured, bound, advertised, reachable, and observed-identity evidence.

Week 20 closes the missed-week arc by connecting release trust to network reality: the correct binary still needs every intended listener to bind, every public route to work, and every route to authenticate the same Fiber node.