Skip to main content
HOW-TO

Boson Integration

PC2 integrates with the Boson Network for decentralized identity and connectivity.

Boson Services​

PC2 implements five Boson-related services:

IdentityService​

Manages the node's cryptographic identity:

{
  "nodeId": "2abc...xyz",
  "did": "did:boson:2abc...xyz",
  "publicKey": "<Uint8Array>",
  "privateKey": "<Uint8Array>"
}

Storage: data/identity/identity.json

UsernameService​

Registers human-readable usernames:

alice.ela.city -> nodeId -> IP:port

Usernames are stored in the DHT and resolved by super nodes.

ConnectivityService​

Detects network conditions:

  • Public IP detection
  • NAT type detection
  • Port availability
  • Super node reachability

ActiveProxyClient​

Connects to Active Proxy for NAT traversal. See NAT Traversal for details.

BosonService​

Orchestrates all Boson services on startup.

Identity Creation​

Identity is created during the Setup Wizard on first login.

Flow​

  1. Generate random entropy
  2. Create BIP39 mnemonic (12 words)
  3. Derive Ed25519 keypair from seed
  4. Compute Node ID = Base58(publicKey)
  5. Create DID = "did:boson:" + nodeId
  6. Save to identity.json

Recovery Phrase​

The 12-word mnemonic can restore your identity on any PC2 node.

warning

Store safely: anyone with this phrase can impersonate your node.

DHT Operations​

Storing Data​

await dht.put(
  sha256("username:alice"),
  {
    nodeId: "2abc...",
    endpoint: "http://1.2.3.4:4200",
    timestamp: Date.now(),
    signature: sign(data, privateKey)
  }
);

Retrieving Data​

const result = await dht.get(sha256("username:alice"));
// { nodeId, endpoint, timestamp, signature }

Super Node Connection​

PC2 nodes connect to super nodes for:

PurposeProtocolPort
DHT BootstrapUDP39001
Active ProxyTCP8090
Gateway RegistrationHTTPS443

Bootstrap Flow​

  1. Connect to known super node
  2. Join DHT network
  3. Announce presence
  4. Discover peers

Signatures​

All DHT data is signed with Ed25519:

const signature = sign(JSON.stringify(data), privateKey);
const valid = verify(signature, data, publicKey);

This prevents tampering and impersonation.

DID Format​

PC2 uses the Boson DID method:

did:boson:2abcdefghijklmnopqrstuvwxyz123456789
         └─────────── Node ID (Base58) ─────────┘

DIDs enable verifiable identity, cross-platform authentication, and decentralized PKI.

Configuration​

Super nodes are configured in data/config/pc2.json:

{
  "boson": {
    "superNodes": [
      {
        "host": "198.51.100.1",
        "dhtPort": 39001,
        "proxyPort": 8090
      }
    ],
    "enabled": true
  }
}

Troubleshooting​

Identity not found: Check cat data/identity/identity.json. If missing, delete data directory and re-run setup wizard.

DHT connection failed: Test super node connectivity: nc -vuz 198.51.100.1 39001. Check firewall allows UDP outbound.

Username conflict: Choose a different username, or contact admin if you believe it's yours.