Neon-Rings

A purely Python, lightweight, P2P WebSocket-based transport layer and SQLite-backed DHT for the Red-Pill ecosystem.

---

1. CLI Usage

1.1 Server (Bootstrap Node)

Run the bootstrap server with an in-memory SQLite database (for testing) or a file for persistence:

neon-rings-server --host 0.0.0.0 --port 50000 --db node.db

1.2 Client CLI

You can test the server from the command line:

neon-rings-client --endpoint ws://127.0.0.1:50000 info
neon-rings-client put --key "greeting" --value "Hello Swarm!"
neon-rings-client get --key "greeting"

---

2. Programmatic Python SDK Usage

Below is a complete example demonstrating how to integrate RingsClient programmatically.

import asyncio
from neon_rings.client import RingsClient
from neon_rings.crypto import KeyPair

async def main():
	# 1. Instantiate and connect client
	async with RingsClient("ws://127.0.0.1:50000") as client:
		# 2. Register node unique identifier
		await client.register("node-alpha-01")

		# 3. Define callback to handle incoming messages
		async def on_message(sender_id: str, payload: any):
			print(f"📩 Received message from {sender_id}: {payload}")

		client.set_message_handler(on_message)

		# 4. Perform SQLite-backed DHT operations (signed cryptographically)
		kp = KeyPair.generate()
		await client.dht_put(kp, "secure_payload_data")
		
		# Retrieve the value using the public key hex
		value = await client.dht_get(kp.public_key_hex)
		print(f"🔑 DHT Value retrieved: {value}")

		# 5. Route a message to a specific registered node
		await client.send_message(
			target_id="node-beta-02",
			payload={"event": "sync_request", "data": {"version": "0.1.1"}}
		)

		# Keep the listen loop alive
		await asyncio.sleep(2)

if __name__ == "__main__":
	asyncio.run(main())

---

3. System Architecture & Message Flow

The sequence below illustrates how nodes register on the neon-rings hub and exchange payloads or interact with the DHT:

sequenceDiagram
    autonumber
    participant A as Agent A (Client)
    participant H as Neon-Rings Hub (Server)
    participant B as Agent B (Client)

    A->>H: JSON-RPC {"method": "register", "params": {"node_id": "agent-a"}}
    H-->>A: {"result": {"ok": true, "node_id": "agent-a"}}
    B->>H: JSON-RPC {"method": "register", "params": {"node_id": "agent-b"}}
    H-->>B: {"result": {"ok": true, "node_id": "agent-b"}}

    Note over A,B: Direct Routing (P2P-over-WebSocket)
    A->>H: {"method": "send_message", "params": {"target_id": "agent-b", "payload": "..."}}
    H->>B: Push Event {"method": "message_receive", "params": {"sender_id": "agent-a", "payload": "..."}}
    H-->>A: {"result": {"ok": true, "delivered": true}}

---

4. JSON-RPC 2.0 Protocol Specification

neon-rings communicates over WebSockets using JSON-RPC 2.0. Clients can implement this specification in any language.

4.1 register

Registers a unique node identifier with the server.

• Request:

  {
    "jsonrpc": "2.0",
    "method": "register",
    "params": {
      "node_id": "client-node-01"
    },
    "id": 1
  }
  

• Response:

  {
    "jsonrpc": "2.0",
    "result": {
      "ok": true,
      "node_id": "client-node-01"
    },
    "id": 1
  }
  

4.2 send_message

Routes a payload to another connected node or broadcasts it to all other registered connections.

• Request (Direct Message):

  {
    "jsonrpc": "2.0",
    "method": "send_message",
    "params": {
      "target_id": "client-node-02",
      "payload": {
        "type": "heartbeat",
        "status": "active"
      }
    },
    "id": 2
  }
  

• Response (Successful delivery):

  {
    "jsonrpc": "2.0",
    "result": {
      "ok": true,
      "delivered": true
    },
    "id": 2
  }
  

• Response (Target offline):

  {
    "jsonrpc": "2.0",
    "result": {
      "ok": true,
      "delivered": false,
      "reason": "Node offline"
    },
    "id": 2
  }
  

• Request (Broadcast):

  {
    "jsonrpc": "2.0",
    "method": "send_message",
    "params": {
      "target_id": "broadcast",
      "payload": {
        "message": "Global swarm alert"
      }
    },
    "id": 3
  }
  

• Response (Broadcast):

  {
    "jsonrpc": "2.0",
    "result": {
      "ok": true,
      "delivered": true,
      "broadcast_count": 3
    },
    "id": 3
  }
  

4.3 message_receive (Server-to-Client Notification)

Pushes a message sent via send_message to the target client.

• Event Notification:

  {
    "jsonrpc": "2.0",
    "method": "message_receive",
    "params": {
      "sender_id": "client-node-01",
      "payload": {
        "type": "heartbeat",
        "status": "active"
      },
      "ts": 1716654890.123
    }
  }
  

4.4 dht_put

Stores a cryptographically signed key-value pair in the SQLite-backed DHT. The key must be the hexadecimal representation of the public key verifying the signature.

• Request:

  {
    "jsonrpc": "2.0",
    "method": "dht_put",
    "params": {
      "key": "025cf26d9c...",
      "value": "payload_content",
      "signature": "30440220..."
    },
    "id": 4
  }
  

• Response:

  {
    "jsonrpc": "2.0",
    "result": {
      "ok": true
    },
    "id": 4
  }
  

4.5 dht_get

Retrieves the stored value for a given public key hex.

• Request:

  {
    "jsonrpc": "2.0",
    "method": "dht_get",
    "params": {
      "key": "025cf26d9c..."
    },
    "id": 5
  }
  

• Response:

  {
    "jsonrpc": "2.0",
    "result": "payload_content",
    "id": 5
  }
  

---

5. High Availability & Scaling

neon-rings supports horizontal scale-out architectures via LiteFS for SQLite replication or node-to-node Federation.

See docs/HIGH_AVAILABILITY.md for architectural and deployment details.

---

6. Security & Encryption

Important: neon-rings is 100% payload-agnostic. It is designed to run quickly without decrypting client payloads. In the Red-Pill architecture, pure-mls or openmls is used to encrypt payloads before they are transmitted via neon-rings.

---

7. Development & Conventions

This repository is co-authored by Biological and Artificial agents under the docs/CORE/PROTOCOL_OF_SILENCE.md and CONVENTIONS.md.

• All python code must use tabs only for indentation.
• Double-blank lines and ornamental comments are forbidden.
• Code coverage is enforced by CI to be at or above 96%.