config: add island federation and NAT traversal support for federated mesh architecture

- Add island configuration fields (island_id, island_name, is_hub, island_chain_id, hub_discovery_url, bridge_islands)
- Add NAT traversal configuration (STUN/TURN servers and credentials)
- Add DEFAULT_ISLAND_ID using UUID for new installations
- Extend PeerNode with public_address, public_port, island_id, island_chain_id, and is_hub fields
- Update DiscoveryMessage to include island metadata and public endpoint

docs/advanced/01_blockchain/6_networking.md

@@ -22,6 +22,104 @@ If behind a NAT, configure port forwarding:
 - External port 7070 → Internal IP:7070
 - External port 8080 → Internal IP:8080
 
+## Federated Mesh Architecture
+
+AITBC supports a federated mesh network architecture with independent mesh islands, node hubs, and optional island bridging.
+
+### Overview
+
+- **Islands**: Independent P2P networks with UUID-based IDs and separate blockchains
+- **Hubs**: Any node can volunteer as a hub to provide peer lists
+- **Multi-Chain**: Nodes can run parallel bilateral/micro-chains
+- **Bridging**: Optional connections between islands (requires mutual approval)
+
+### Island Configuration
+
+Configure your node's island membership in `/etc/aitbc/.env`:
+
+```bash
+# Island Configuration
+ISLAND_ID=550e8400-e29b-41d4-a716-446655440000
+ISLAND_NAME=default
+IS_HUB=false
+ISLAND_CHAIN_ID=ait-island-default
+HUB_DISCOVERY_URL=hub.aitbc.bubuit.net
+BRIDGE_ISLANDS=
+```
+
+**Configuration Fields**:
+- `ISLAND_ID`: UUID-based island identifier (auto-generated if not set)
+- `ISLAND_NAME`: Human-readable island name
+- `IS_HUB`: Set to `true` if this node acts as a hub
+- `ISLAND_CHAIN_ID`: Separate chain ID for this island
+- `HUB_DISCOVERY_URL`: DNS endpoint for hub discovery
+- `BRIDGE_ISLANDS`: Comma-separated list of islands to bridge (optional)
+
+### Creating a New Island
+
+```bash
+aitbc node island create --island-name "eu-west" --chain-id "ait-island-eu-west"
+```
+
+This generates a new UUID for the island and sets up a separate blockchain.
+
+### Joining an Existing Island
+
+```bash
+aitbc node island join <island-id> <island-name> <chain-id> [--is-hub]
+```
+
+### Hub Registration
+
+Any node can register as a hub to provide peer lists:
+
+```bash
+aitbc node hub register --public-address <public-ip> --public-port 7070
+```
+
+To unregister as a hub:
+
+```bash
+aitbc node hub unregister
+```
+
+### Island Bridging
+
+Bridging allows optional connections between islands (requires mutual approval):
+
+```bash
+# Request bridge to another island
+aitbc node bridge request <target-island-id>
+
+# Approve a bridge request
+aitbc node bridge approve <request-id> <approving-node-id>
+
+# Reject a bridge request
+aitbc node bridge reject <request-id> --reason "<reason>"
+
+# List active bridges
+aitbc node bridge list
+```
+
+### Multi-Chain Support
+
+Nodes can run parallel bilateral/micro-chains alongside the default chain:
+
+```bash
+# Start a new parallel chain
+aitbc node chain start <chain-id> --chain-type micro
+
+# Stop a parallel chain
+aitbc node chain stop <chain-id>
+
+# List active chains
+aitbc node chain list
+```
+
+Chain types:
+- `bilateral`: Chain between two parties
+- `micro`: Small chain for specific use case
+
 ## Bootstrap Nodes
 
 ### Default Bootstrap Nodes
@@ -66,20 +164,25 @@ Nodes are scored based on:
 
 | Method | Description |
 |--------|-------------|
+| STUN | Public IP discovery via STUN servers |
 | AutoNAT | Automatic NAT detection |
-| Hole Punching | UDP hole punching |
-| Relay | TURN relay fallback |
+| Hole Punching | UDP hole punching (future) |
+| Relay | TURN relay fallback (future) |
 
 ### Configuration
 
-```yaml
-p2p:
-  nat:
-    enabled: true
-    method: auto  # auto, hole_punching, relay
-    external_ip: 203.0.113.1
+```bash
+# STUN Servers (comma-separated)
+STUN_SERVERS=stun.l.google.com:19302,jitsi.bubuit.net:3478
+
+# TURN Server (future)
+TURN_SERVER=jitsi.bubuit.net:3478
 ```
 
+### STUN Discovery
+
+Nodes automatically discover their public endpoint via STUN servers configured in the environment. This enables nodes behind NAT to participate in the mesh network.
+
 ## Troubleshooting
 
 ### Check Connectivity
@@ -94,12 +197,35 @@ aitbc-chain p2p check-connectivity
 aitbc-chain p2p connections
 ```
 
+### List Known Islands
+
+```bash
+aitbc node island list
+```
+
+### List Known Hubs
+
+```bash
+aitbc node hub list
+```
+
 ### Debug Mode
 
 ```bash
 aitbc-chain start --log-level debug
 ```
 
+## DNS Configuration for Hub Discovery
+
+Add A records for hub discovery:
+
+```
+# hub.aitbc.bubuit.net
+hub1.aitbc.bubuit.net A 10.1.1.1
+hub2.aitbc.bubuit.net A 10.1.1.2
+hub3.aitbc.bubuit.net A 10.1.1.3
+```
+
 ## Next
 
 - [Quick Start](./1_quick-start.md) — Get started