Peer-to-peer communication

aikyo operates on a P2P network built upon libp2p. This enables a fully decentralized architecture where companions can communicate directly without relying on central servers.

P2P Network Using libp2p

Network Architecture

Each companion and the Firehose server participate as libp2p nodes in the P2P network.

By default, the following features are enabled:

• TCP/IP communication
• mDNS peer discovery
• Gossipsub Pubsub messaging
• Noise encryption
• Yamux stream multiplexing

Peer Discovery and Connection

mDNS automatically discovers and attempts to connect to companions on the same local network.

Metadata Exchange

Custom protocols are used during peer connections to exchange metadata.

Upon establishing a connection, the system retrieves the companion’s metadata (including ID, name, and personality) from the connected peer and stores it in the companionList.

Gossipsub Communication

aikyo utilizes four primary topics for Gossipsub messaging:

Topic List

Topic	Purpose	Message Type
messages	Conversation messages	Message
states	Turn-taking states	State
queries	Query requests/responses	Query, QueryResult
actions	Action notifications	Action

Firehose Server

The Firehose serves as a bridge between WebSocket clients and the libp2p network.

It allows participation in the P2P network from any environment capable of establishing a WebSocket connection.

JSON-RPC 2.0 Protocol

aikyo standardizes all messages using the JSON-RPC 2.0 format for consistency.

export const MessageSchema = z.object({
  jsonrpc: z.literal("2.0"),
  method: z.literal("message.send"),
  params: z.object({
    id: z.string(),
    from: z.string(),
    to: z.array(z.string()),
    message: z.string(),
    metadata: z.record(z.string(), z.any()).optional(),
  }),
});

This standardization ensures consistent message handling between clients and the server.