circles/src/server/README.md

server: The Circles WebSocket Server

The server crate provides a secure, high-performance WebSocket server built with Actix. It is the core backend component of the circles ecosystem, responsible for handling client connections, processing JSON-RPC requests, and executing Rhai scripts in a secure manner.

Features

• Actix Framework: Built on Actix, a powerful and efficient actor-based web framework.
• WebSocket Management: Uses actix-web-actors to manage each client connection in its own isolated actor (CircleWs), ensuring robust and concurrent session handling.
• JSON-RPC 2.0 API: Implements a JSON-RPC 2.0 API for all client-server communication. The API is formally defined in the root openrpc.json file.
• Secure Authentication: Features a built-in secp256k1 signature-based authentication system to protect sensitive endpoints.
• Stateful Session Management: The CircleWs actor maintains the authentication state for each client, granting or denying access to protected methods like play.
• Webhook Integration: Supports HTTP webhook endpoints for external services (Stripe, iDenfy) with signature verification and script execution capabilities.

Core Components

spawn_circle_server

This is the main entry point function for the server. It configures and starts the Actix HTTP server and sets up the WebSocket route with path-based routing (/{circle_pk}).

CircleWs Actor

This Actix actor is the heart of the server's session management. A new instance of CircleWs is created for each client that connects. Its responsibilities include:

• Handling the WebSocket connection lifecycle.
• Parsing incoming JSON-RPC messages.
• Managing the authentication state of the session (i.e., whether the client is authenticated or not).
• Dispatching requests to the appropriate handlers (fetch_nonce, authenticate, and play).

Authentication

The server provides a robust authentication mechanism to ensure that only authorized clients can execute scripts. The entire flow is handled over the WebSocket connection using two dedicated JSON-RPC methods:

1. fetch_nonce: The client requests a unique, single-use nonce (a challenge) from the server.
2. authenticate: The client sends back the nonce signed with its private key. The CircleWs actor verifies the signature to confirm the client's identity.

For a more detailed breakdown of the authentication architecture, please see the ARCHITECTURE.md file.

Webhook Integration

The server also provides HTTP webhook endpoints for external services alongside the WebSocket functionality:

• Stripe Webhooks: POST /webhooks/stripe/{circle_pk} - Handles Stripe payment events
• iDenfy Webhooks: POST /webhooks/idenfy/{circle_pk} - Handles iDenfy KYC verification events

Webhook Features

• Signature Verification: All webhooks use HMAC signature verification for security
• Script Execution: Webhook events trigger Rhai script execution via the same Redis-based system
• Type Safety: Webhook payload types are defined in the heromodels library for reusability
• Modular Architecture: Separate handlers for each webhook provider with common utilities

For detailed webhook architecture and configuration, see WEBHOOK_ARCHITECTURE.md.

How to Run

As a Library

The server is designed to be used as a library by the launcher, which is responsible for spawning a single multi-circle server instance that can handle multiple circles via path-based routing.

To run the server via the launcher with circle public keys:

cargo run --package launcher -- -k <circle_public_key1> -k <circle_public_key2> [options]

The launcher will start a single server instance that can handle multiple circles through path-based WebSocket connections at /{circle_pk}.

Standalone Binary

A standalone binary is also available for development and testing purposes. See cmd/README.md for detailed usage instructions.

# Basic standalone server
cargo run

# With authentication and TLS
cargo run -- --auth --tls --cert cert.pem --key key.pem