Installing a Private Network

You can run a complete Rayls Private Network on one machine with the Rayls CLI: a Private Network Hub; two to six participants, each with a Rayls Sovereign chain (Privacy Node in the code), a private relayer and a key service (CTS); the proofs API; the governance services; and the Auditor Explorer. It is a development and demonstration setup. This page shows how to start it, what it runs, and what a production network needs instead.

🚧

Development and demonstration only

The local stack uses development settings throughout. Don't use it for production or for anything of value:

• The Hub is a single Hyperledger Besu node with peer-to-peer networking off and a minimum gas price of zero.
• Each Rayls Sovereign chain is a single Axyl node in development mode, with no gas fees.
• One deployer key controls every chain. By default it is a publicly known development key.
• The key services store keys unencrypted, with no key management service (KMS).
• The proving keys come from a single-party setup, not a multi-party ceremony.

Prerequisites

• Docker and Docker Compose v2.24 or newer.
• The Rayls CLI: download a pre-built binary, or build it from source with Go 1.25.4 or newer.

A Private Network started with --full needs no funded account: its chains run inside the stack.

Install the CLI

Download the binary for your platform, for example on macOS with Apple Silicon:

curl -fL https://cli.rayls.com/rayls-darwin-arm64 -o rayls
chmod +x rayls
sudo mv rayls /usr/local/bin/

The other builds are rayls-darwin-amd64, rayls-linux-amd64 and rayls-linux-arm64. To build from source instead:

git clone https://github.com/raylsnetwork/rayls-sovereign-cli.git
cd rayls-sovereign-cli
go build -o rayls .

Start a Private Network

rayls init --full                 # two participants
rayls init --full --members 4     # two to six participants

The first run pulls the images one at a time from a public Amazon Elastic Container Registry, which can take several minutes. The contracts service then deploys and configures every contract before the relayers start.

🚧

Use --full

A bare rayls init doesn't start a Private Network. It starts a single Rayls Sovereign chain, with no Hub. rayls init --with-hub adds a minimal Hub for a single participant, without governance services. Only --full runs several participants connected through the Hub.

Options

What --full runs

Every port listens on 127.0.0.1 only, so the stack isn't reachable from other machines. Ports for participants go up by one for each participant after a.

The Hub and the Rayls Sovereign chains are ordinary EVM (Ethereum Virtual Machine) chains: point any Ethereum tool at their JSON-RPC addresses.

What the deployment sets up

The contracts service runs the same steps a real network goes through (see Running a Private Network):

1. Deploys the Hub contracts and generates the operator's view key pair. It registers the operator's entry (chain ID 999) and registers every participant as an active issuer.
2. Registers the Hub's business roles.
3. Deploys each Rayls Sovereign chain's contracts and registers its business roles.
4. Authorises each participant's relayer addresses on its own chain and on the Hub.
5. Seeds the standard contract templates in the Hub's template registry.

The deployer key (PRIVATE_KEY_SYSTEM) holds ADMIN on every chain. To use your own, set it before the first init:

PRIVATE_KEY_SYSTEM=0x<your key> rayls init --full

Manage the stack

rayls ps                      # list the services
rayls logs relayer-a -f       # follow one service's logs
rayls stop                    # stop, keeping the containers
rayls start                   # start again
rayls down                    # remove containers, keep data
rayls down -v                 # remove containers and data

Next steps

• Bring an Enygma token into service and send it: Running Rayls Enygma.
• Watch the transfers in the Auditor Explorer at http://localhost:8181.
• Explore the governance API's Swagger page at http://localhost:9100/swagger/index.html.
• See the other interfaces in Interacting with a Private Network.

Production networks

The public repositories contain every component the local stack runs, each with its configuration documented in its README and .env.example:

They don't include a production installation package, or tooling for sizing, high availability or disaster recovery. To run a production network, contact Rayls. Compared with the local stack, a production network needs at least:

• its own keys for each chain's administrator, held securely;
• key services that encrypt keys with a KMS: the key service supports Amazon Web Services (AWS) KMS and Google Cloud KMS;
• proving keys from a multi-party setup ceremony (see Cryptographic foundations);
• a Hub network and Besu configuration chosen by the operator;
• the governance API reachable only from the operator's own network (see Interacting with a Private Network).