Private Network Technical Architecture

A Rayls Private Network is multiple Rayls Sovereign chains connected together via a central Hyperledger Besu chain, the Private Network Hub.

This page describes each component, what runs on the Hub and on each chain, and how a message travels from one chain to another. For a shorter overview, see Rayls Private Networks.

Components at a glance

Each participating institution runs three components. The Private Network operator runs the Hub and the services around it.

Component	Run by	Code
Rayls Sovereign chain (Privacy Node in the code)	Each institution	The Axyl node, with the Rayls contracts deployed on it
Private relayer	Each institution, one per chain	`relayer` in rayls-sovereign-relayer
Key service (CTS, the Cryptography Trust Suite)	Each institution	`cts` in rayls-sovereign-relayer
Private Network Hub	Private Network operator	A Hyperledger Besu chain with the Hub contracts from rayls-sovereign-contracts (`src/privateHub`, plus the Enygma and delivery-versus-payment (DvP) modules)
Governance services: API, listener and flagger	Private Network operator	rayls-sovereign-pnh-governance
Auditor Explorer	Private Network operator	rayls-sovereign-pnh-auditor-ui
Proofs API	Shared by the network	rayls-sovereign-gnark-api

The same set-up repeats for every participant: each one connects only to the Hub, never directly to another participant's chain.

The Private Network Hub

The Private Network Hub is a Hyperledger Besu chain at the centre of every Rayls Private Network, run by the Private Network operator. Every message between Rayls Sovereign chains passes through it. It holds the network's registries for participants, tokens and approved contract templates, the cross-chain messaging contracts, and the Enygma and DvP contracts.

The Hub's contracts are:

Contracts	What they hold or do
Access manager (`RaylsAccessManagerV1`)	Who may call each restricted function on the Hub. The Hub has its own instance, separate from each chain's.
Participant registry (`ParticipantStorageV1`)	Each participant's chain ID, role (participant, issuer or auditor) and status (new, active, inactive or frozen). Also each participant's public view key, the ciphertexts of the key agreements between participants, and each participant's view key encrypted to the operator.
Token registry (`TokenRegistryV1`)	The tokens registered for cross-chain use, their status, and which participants each token is frozen for. Issuers report mints and burns here.
Resource registry (`ResourceRegistryV1`)	The code of each registered token, so a relayer can deploy the same token on a chain that receives it for the first time.
Template registry (`TemplateRegistryV1`)	The contract code and functions approved for Enygma program steps.
Messaging (`EndpointV1`, `Proofs` and the message batch store)	The endpoint and its sender and receiver modules; the store for encrypted message batches between chains; and the latest block headers of each Rayls Sovereign chain (`Proofs`).
Enygma (`EnygmaFactory`, one `EnygmaV1` per token, verifiers)	Each Enygma token's balance commitments, nullifiers and supply, and the zero-knowledge proof verifiers. See How Enygma works.
DvP (`Dvp`, coin vaults, asset groups, verifiers)	The vaults that hold assets during a swap, and the swap logic. See Private DvP with Enygma.
Address book (`DeploymentProxyRegistryV1`)	The addresses of the Hub contracts, which the relayers and governance services read at start-up.

The Hub copies its registries to every Rayls Sovereign chain: the participant list, the per-participant token freezes and the approved templates. Each chain therefore checks the network's rules locally, before a message leaves it.

Consensus

The code doesn't fix a consensus algorithm or a number of validators for the Hub. Those are decisions for each deployment. The local stack that the Rayls CLI starts runs the Hub as a single Besu node, with peer-to-peer networking off and a zero gas price. That is a development set-up, not a production design.

On each Rayls Sovereign chain

Each institution's chain is an ordinary EVM (Ethereum Virtual Machine) chain, with the Rayls contracts deployed next to the institution's own:

Contracts	What they do
Access manager	Who may call each restricted function on this chain. The institution administers it.
Endpoint and message modules (`RNEndpointV1`, `EndpointV1`, sender, receiver, executor)	Send messages to other chains, and execute the messages that arrive.
Copies of the Hub registries (`ParticipantStorageReplicaV1`, `PNTokenRegistryV1`, `TemplateRegistryReplicaV1`)	Let the chain check participants, token status and freezes, and approved templates without a round trip to the Hub. The Hub keeps them up to date with cross-chain messages.
Programmability executor	Runs Enygma program steps on arrival, if they match an approved template.
Contract factories	Deploy tokens from the standard Rayls templates.
Enygma events and PN communicator	Coordinate Enygma transfers and DvP swaps with the relayer.

Private relayer

Each Rayls Sovereign chain has one private relayer. It:

watches its chain for outgoing messages, collects them into batches and sends them to the Hub;
encrypts each batch for its destination chain, using a key it gets from its key service;
watches the Hub for batches addressed to its chain, decrypts them, checks them and executes them on its chain;
builds Enygma transactions, asks the proofs API for their proofs and submits them to the Hub, and does the same for DvP steps;
deploys a token on its chain the first time the chain receives it;
posts every block header of its chain to the Hub.

The relayer submits its Hub transactions from accounts that the operator authorises on the Hub (the RELAYER role), and it signs them through its key service.

Key service (CTS)

Each participant has one key service. It stores the participant's keys encrypted with a key management service (KMS): AWS KMS or Google Cloud KMS. A plaintext mode exists for local development only. The keys are:

the accounts the relayer uses to sign transactions on its chain and on the Hub;
a view key, a key pair for ML-KEM-768 (Module-Lattice-Based Key-Encapsulation Mechanism, a post-quantum standard), used to agree secrets with the other participants and to read messages addressed to this participant;
an Enygma spend key, used to prove ownership in Enygma transfers;
a shared secret with every other participant, which the relayer uses to encrypt and recognise messages.

When a participant joins, its key service:

publishes its public view key on the Hub;
agrees a shared secret with every other participant, using ML-KEM, and posts the key-agreement ciphertexts on the Hub;
encrypts its view private key to the Private Network operator and stores the result on the Hub. Registration doesn't complete without this step.

Step 3 is what lets the operator decrypt the network's traffic. See Auditing.

Governance services and Auditor Explorer

The operator runs three governance services against the Hub, which share a database:

the listener indexes Hub events. It holds the operator's view secret key, recovers every participant's view key and shared secrets from the Hub, and decrypts message batches, Enygma transfers and DvP terms;
the flagger keeps a running balance per chain and token from the decrypted transfers, mints and burns. It flags a transfer that would take a chain's balance below zero (for tokens that Enygma's proofs don't already cover) and a participant whose block headers stop arriving;
the API serves this data: transactions, participants, tokens, header proofs and flagged items.

The Auditor Explorer is a web interface over the API, for searching and inspecting decrypted transactions, Enygma batches and DvP swaps.

Proofs API

The proofs API generates the Groth16 zero-knowledge proofs for Enygma transfers and DvP steps. Relayers call it. See Cryptographic foundations of Enygma.

How a message flows

Bank A's chain sends an arbitrary message, a call to a contract, to Bank B's chain:

Send. A contract on chain A calls its endpoint. Before the message leaves, chain A checks its copies of the registries: both chains must be active participants, and the token involved, if any, must not be frozen for either of them.
Batch and encrypt. Every second, relayer A collects up to 100 pending messages and groups them by destination chain. For each message it builds a proof that the originating transaction is in a chain A block. It encrypts each group for its destination with AES-256-GCM (the Advanced Encryption Standard with 256-bit keys, in Galois/Counter Mode), using a key derived from the A–B shared secret, and adds a message tag that only the destination can recognise.
Store on the Hub. Relayer A submits each encrypted batch to the Hub, one Hub transaction per destination chain.
Receive. Relayer B watches the Hub, recognises the tag, decrypts the batch through its key service and checks the proofs.
Execute. Relayer B calls the endpoint on chain B, which checks the message's nonce and runs the call on the destination contract. Relayer B then posts an encrypted receipt to the Hub.
Index. The operator's listener decrypts the same batch and records the message.

Enygma transfers and DvP swaps use their own contracts on the Hub, with zero-knowledge proofs, but the same relayers and key services. See How Enygma works and Private DvP with Enygma.

Who does what

Role	Who	Runs	Can
Participant	A financial institution	Its Rayls Sovereign chain, private relayer and key service	Transact on its own chain; send and receive cross-chain messages, Enygma transfers and DvP swaps. An issuer can also register tokens for the network.
Private Network operator	Usually a financial market infrastructure (FMI) provider, such as a central bank, a clearing house or an exchange, or the parent of a banking group	The Hub, the governance services and the Auditor Explorer	Admit participants and set their roles, approve tokens and templates, freeze participants and tokens, and read all cross-chain traffic
Auditor	Whoever the operator gives access to its governance services or Auditor Explorer, such as a regulator	Nothing separate	See what the operator's tools show. There is no separate auditor key.

See Private Network roles for the operator's tasks in detail.

📘
Capabilities developed for clients
Some capabilities, such as configurable levels of auditor access or custom governance rules, can be developed for a client's own deployment. This page describes the architecture that runs in production today, as published in the open-source code. See also Governance and Auditing.