🧬 How Cellule.ai pools federate

Cellule.ai is a community-owned network of AI pools. Each pool is an independent instance — its own hardware, its own operator, its own workers. But pools talk to each other to share load, replicate data, and coordinate. This page explains how that conversation is secured and what you control as a pool operator.

⚠ PREPROD / testnet phase. The federation protocol is live but $IAMINE credits have no market value yet. Every design choice below is made with the future on-chain economy in mind — we protect wallets today so the system holds when real value flows tomorrow.

The mental model — no master, just a molecule

A traditional cloud has one boss: the cloud provider. If they ban you, you're out. If they get hacked, everyone loses.

Cellule.ai works the other way around. There are no master pools. Each pool is sovereign. When a pool wants something from another pool (a query, an action), it asks — and the target pool's human admin decides. No automation, no central authority, no silent override.

How it's secured — Ed25519 signatures

Every single cross-pool message is cryptographically signed by the pool that sends it. Think of it as a notarized letter:

Sender identity = a public key (Ed25519, 256-bit). Your pool's ID (atom_id) is literally sha256(pubkey). You can't fake being another pool without stealing its private key.
Content integrity = the signature covers the full request body. If a middle-man changes one byte, the signature fails.
Anti-replay = each message carries a nonce that's remembered for 5 minutes. Replaying an old message is refused.
Trust level = your pool classifies each peer (trust 0 to 4). Only peers bonded at trust ≥ 3 (replication-bonded) can send admin requests.

✓ What this means for you
If someone tries to impersonate a peer pool to make your pool do something, the signature check rejects the message before anything happens. An attacker would need the peer's private key — and that key never leaves the peer's machine.

The 2 types of cross-pool actions

There are two kinds of things a peer pool can ask yours to do. They have very different impact, so Cellule.ai treats them differently.

Kind	Example	What it does	Default
READ	`query_events`	Lets a peer read your molecule events log (circuit open/close, worker join/leave, handshakes). Filtered: only whitelisted types, only last 7 days, no cross-peer leakage.	ON by default
WRITE	`circuit_reset`	Lets a peer ask your pool to clear its worker blacklist and reset quality scores. You still manually approve — but if approved, it modifies state.	OFF by default

Why this split?

Reading events is harmless to your wallet. No credit moves, no worker is re-authorized, no slashing is bypassed. It's observability. So we make it ON by default — it helps the community see the health of the network.

Writing actions can indirectly affect money. A circuit_reset, for example, could re-authorize a worker that was penalized for bad quality. If two pool operators collude, they could reset each other's penalized workers forever, draining the fairness mechanism. So writes stay OFF by default — you have to knowingly turn them on.

⚠ The wallet rule. Any endpoint that can affect — directly or indirectly — the revenue ledger, slashing events, worker shares, or settlement flows is opt-in OFF by default. This is a firm invariant, validated by the project's economic guardian. It's how we protect the future on-chain economy today.

Your 2 toggles in `/admin/pool`

In your pool's admin UI (/admin → Federation tab for the VPS, /admin/pool for community pool operators), you'll see two checkboxes:

☑ Accept read requests (query_events)

Recommended ON. Lets peers read your filtered event log. No economic impact. Helps cross-pool observability.

☐ Accept write requests (circuit_reset + future actions)

Keep OFF unless you know why you need it. Protects your workers' economic state. If ON, you still get a manual Approve/Reject prompt for each incoming request — plus automatic blocks (slashing guard, 6h cooldown per peer, signature verification). But the safest posture is OFF.

What happens when a peer sends you a request

Signature check — Ed25519 verification. Fails silently if bad.
Trust check — refuses if peer trust < 3.
Opt-in check — refuses with 403 disabled if the matching toggle (read or write) is OFF.
Rate limit — max 10 pending requests per peer. 11th gets 429.
Cooldown (writes only) — 6 hours minimum between two approved circuit_reset from the same peer.
Slashing guard (circuit_reset only) — blocked with 409 if any slashing event is pending. You can force an override — but it's logged permanently with a full snapshot.
Manual approve — the request lands in your inbox. You click Approve or Reject. Nothing runs until you do.
Signed callback — result is signed and sent back to the originating pool.
Audit log — every step is written append-only on both sides.

What a cross-pool request looks like on the wire

POST /v1/federation/admin/request
Content-Type: application/json
X-IAMINE-Atom-Id:   3fdcd7c0318d...          # who signs this
X-IAMINE-Timestamp: 1776358800
X-IAMINE-Nonce:     a8f3...                  # one-shot
X-IAMINE-Signature: base64(ed25519_sign(body))

{
  "request_id":       "fadm_abc123...",
  "origin_pool_id":   "3fdcd7c0318d...",
  "action_type":      "query_events",
  "action_params":    { "limit": 100 },
  "from_admin_email": "[email protected]"   // display only, NEVER used for auth
}

Note on the admin email. The from_admin_email field is purely cosmetic. Your pool never uses it to decide whether to accept the request. Only the Ed25519 signature counts. An attacker could put any email — the signature would still have to match the peer's registered public key.

Future: separate admin key (Phase 2.2)

Today, admin requests are signed with the pool's identity key. Tomorrow, a separate admin key will be required — so if the pool key is compromised, the attacker still can't push admin actions without also owning the admin key.

The federation_admin_identities table already exists in the schema (migration 023). When Phase 2.2 ships, enabling write actions on a pool will require registering at least one admin Ed25519 key distinct from the pool key. No admin key → no writes. This is guardian invariant #12.

Disabling federation completely

If you ever want to cut your pool off:

# Kill switch — instantly stops all federation traffic
sudo touch /etc/iamine/fed_disable

# Remove kill switch to resume
sudo rm /etc/iamine/fed_disable

The kill switch is checked on every single federated endpoint. No configuration, no restart, instant effect.

TL;DR

🔐 Everything is signed — Ed25519, nonces, trust levels.
👁 Read is ON by default — it helps the community, doesn't touch money.
🔒 Write is OFF by default — it can touch money, so you opt in knowingly.
🤝 Nothing runs automatically — every incoming action waits for your manual approve.
🚪 You can kill federation instantly — touch a file, done.
📜 Everything is logged — append-only, both sides, forever.

→ See the source on GitHub · → Run your own pool · → Open admin