Zoo node reference

Technical reference for the Zoo service. The Zoo is OctoMY™'s global discovery and NAT traversal service.

Security Consideration

The Zoo is designed with minimal knowledge - it helps nodes find each other but never sees message contents. All actual communication is encrypted peer-to-peer. The Zoo only temporarily stores connection metadata (IP addresses, public keys) needed for hole-punching, and this data is automatically purged after 5-30 minutes.

Overview

Architecture

The Zoo is architecturally different from other node types - it's a standalone HTTP server, not a Node subclass:

Core components

ZooServer class

class ZooServer : public qhttp::server::QHttpServer {
    QSharedPointer<AppContext> mContext;
    QSharedPointer<KeyStore> mKeyStore;
    Identicon mIdenticon;
    Hashstore mStorage;
    PunchRegistry mPunches;
    DiscoveryServer mDiscovery;
    // ...
};

Key components

Services provided

1. UDP hole-punching

Helps nodes connect through NAT firewalls:

The Zoo never sees the actual communication content - it only helps establish the initial connection.

2. Discovery escrow

Nodes can deposit discovery information for others to find:

POST /api/discovery/escrow
{
  "node_id": "abc123...",
  "gps": {"lat": 37.7749, "lon": -122.4194},
  "addresses": ["192.168.1.5:8124"],
  "timestamp": 1705312800
}

Other nodes can query by proximity:

GET /api/discovery/nearby?lat=37.78&lon=-122.42&radius=1000

3. Identicon service

Generate visual identities from node IDs:

GET /identicon/{node_id}.png

Returns a procedurally generated icon based on the cryptographic identity.

API endpoints

Discovery API

Punch API

Utility API

Security design

The Zoo is designed with minimal knowledge:

What Zoo knows

What Zoo does NOT know

• Message contents (encrypted P2P)
• Node configurations
• Trust relationships
• User identities
• Communication history

Data retention

Background timer prunes stale data:

• Punch registrations: 5 minute timeout
• Discovery escrow: 30 minute timeout

Configuration

Command line

# Start on default port (8123)
./zoo

# Start on custom port
./zoo --port 9999

# Start with admin interface enabled
./zoo --admin-path /secret-admin-path

# Enable debug output
./zoo --debug

Environment variables

Storage

Hashstore

The Zoo uses a simple key-value store:

/var/lib/octomy-zoo/
├── hashstore.db      # Key-value storage
├── keystore.json     # Server identity
└── logs/             # Access logs

Data schema

Punch Registration:

{
  "node_id": "abc123...",
  "address": "1.2.3.4:8124",
  "partner_id": "def456...",
  "registered": 1705312800
}

Discovery Escrow:

{
  "node_id": "abc123...",
  "type": "agent",
  "gps": {"lat": 37.7749, "lon": -122.4194},
  "addresses": ["192.168.1.5:8124", "10.0.0.1:8124"],
  "timestamp": 1705312800,
  "expires": 1705314600
}

Deployment

Systemd service

[Unit]
Description=OctoMY Zoo Discovery Service
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/zoo --port 8123
Restart=always
User=octomy
Group=octomy

[Install]
WantedBy=multi-user.target

Docker

FROM ubuntu:22.04
RUN apt-get update && apt-get install -y libqt6-dev
COPY zoo /usr/local/bin/
EXPOSE 8123
CMD ["zoo", "--port", "8123"]

Cloud deployment

Monitoring

Health check

curl http://zoo.octomy.org/
# Returns: {"status": "ok", "uptime": 86400, "version": "1.0.0"}

Metrics

Hardware requirements

The Zoo is intentionally lightweight to enable easy deployment.

Client integration

Nodes use ZooClient to communicate with the Zoo:

class ZooClient : public QObject {
    // Register for hole-punching
    void registerForPunch(QString partnerId);

    // Query discovery
    void queryNearby(QGeoCoordinate location, qreal radius);

    // Deposit discovery info
    void depositDiscovery(QVariantMap info);
};

Client library