From 605c7edbc3ad92b090e911326efcf23328decc33 Mon Sep 17 00:00:00 2001 From: Nuno Date: Tue, 25 Aug 2026 14:29:55 +0100 Subject: [PATCH 1/2] fix: chaning RAYLS to USDr plus a few image related corrections --- README.md | 22 ++++++++-------- internal/docker/docker_config.go | 3 ++- internal/stacks/publicchainbalance.go | 30 +++++++++++----------- internal/stacks/publicchainbalance_test.go | 12 ++++----- internal/stacks/publicchainkey.go | 4 +-- 5 files changed, 36 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 3da719c..cab1e9e 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ The **Rayls CLI** is a developer tool for provisioning and managing the [Rayls]( Currently, this tool focuses on deploying a **local demo environment** on a single host, making it ideal for sales demonstrations, proof-of-concept exploration, and local development. It automates the generation of Docker Compose configurations and manages the lifecycle of the Rayls components. -> **v2.0.0** — the privacy node is now the **Axyl** (`rayls-network`) node, running gaslessly in its local dev-mode profile, and replacing the previous Geth-based ledger. The **default** `rayls init` now spins up a single local privacy node bridged to a public chain (the primary use case); the full multi-participant demo stack moved behind `--full`. +> **What changed recently** — the privacy node is now the **Axyl** (`rayls-network`) node, running gaslessly in its local dev-mode profile, and replacing the previous Geth-based ledger. The **default** `rayls init` now spins up a single local privacy node bridged to a public chain (the primary use case); the full multi-participant demo stack moved behind `--full`. For a deeper understanding of the Rayls architecture and ecosystem, please visit the [Official Rayls Documentation](https://docs.rayls.com/docs/a-warm-introduction-to-rayls). @@ -32,7 +32,7 @@ For a deeper understanding of the Rayls architecture and ecosystem, please visit * **Automated Setup:** Generates a dynamic `docker-compose.yaml` tailored to your specifications. * **Sequential Image Pulling:** Automatically pulls container images one-by-one — in every mode, `--local` included — to stay under ECR Public's per-IP pull rate limit, cooling off and retrying if a registry throttles anyway. * **Lifecycle Management:** Specialized commands to start, stop, and tear down the stack. -* **Monitoring & Observability:** Optional OpenTelemetry stack with eBPF auto-instrumentation, Grafana, Loki, Prometheus, and Tempo. +* **Monitoring & Observability:** Optional OpenTelemetry stack (a single `grafana/otel-lgtm` container: OTel collector, Grafana, Loki, Prometheus, Tempo, and Pyroscope). * **Per-Node Block Explorers:** Blockscout deployment per privacy node (default-on). * **Version Management:** Built-in version checking and update notifications. * **Environment Verification:** Tools to verify the integrity of the setup, including an end-to-end public-chain bridge smoke test. @@ -50,10 +50,10 @@ Before using the Rayls CLI, ensure you have the following installed on your syst Stacks that bridge to the **Rayls testnet** (what a bare `rayls init` does) deploy the public-chain contracts and seed each participant's relayer wallets **from your own deployer key**. Funding happens outside the CLI: 1. Create a fresh key with any wallet tool (e.g. `cast wallet new`). -2. Request testnet RAYLS for its address through the [Rayls community](https://www.rayls.com/community). Budget roughly **5 RAYLS per participant** (each participant's public-relayer wallets are seeded with 2.5 RAYLS, plus deploy gas). +2. Request testnet USDr (the Rayls public chain's native gas token) for its address through the [Rayls community](https://www.rayls.com/community). Budget roughly **5 USDr per participant** (each participant's public-relayer wallets are seeded with 2.5 USDr in total, plus deploy gas). 3. Run `./rayls init`; it prompts for the key (input hidden, `0x` prefix optional) and stores it in the stack directory's `.env` (created with `0600` permissions), where every later `rayls` / `docker compose` run picks it up automatically. For CI or scripting, set `PUBLIC_CHAIN_PRIVATE_KEY=` in the environment instead because it overrides `.env` and is never written to disk. -`rayls init` **preflights the balance**: it derives your key's address, queries the chain, and refuses immediately (naming the account, balance, and shortfall) if it can't cover a fresh deploy (~2 RAYLS gas + 2.5 per participant). This replaces the opaque mid-deploy failures an underfunded key used to cause. Note that every fresh init (after `rayls down -v`) spends that amount again, and each restart of the contracts container re-seeds the relayer wallets with 2.5, so prefer `rayls stop`/`start` over wipe-and-redeploy while iterating. +`rayls init` **preflights the balance**: it derives your key's address, queries the chain, and refuses immediately (naming the account, balance, and shortfall) if it can't cover a fresh deploy (~2 USDr gas + 2.5 USDr per participant). This replaces the opaque mid-deploy failures an underfunded key used to cause. Note that every fresh init (after `rayls down -v`) spends that amount again, and each restart of the contracts container re-seeds the relayer wallets with 2.5, so prefer `rayls stop`/`start` over wipe-and-redeploy while iterating. Use a **testnet-only key** and never reuse a mainnet key: like any compose environment value it is visible in `docker inspect` on your machine. Fully local stacks (`rayls init --local`, `--privacy-node-only`, or `--full` without a public chain) need no funding at all since their chains run in-stack and are genesis-funded. @@ -131,7 +131,7 @@ If a `docker-compose.yaml` already exists, you'll be prompted to overwrite or us * `--members `: Number of privacy node participants. With `--full`: 2–6 (default **2**). For the hub-less default topology: 1–6 (default **1**) — the nodes intercommunicate via the public chain, so any count is meaningful. Ignored on hub-carrying lean stacks (`--with-hub` runs a single participant; use `--full` for the multi-participant hub). * `--public-chain `: Public chain preset to bridge to — `local` (an Axyl public chain running **inside the stack**: service `public-chain`, RPC `localhost:8845`, chain id `7331`, deployer genesis-funded, no external connectivity) or `rayls-testnet` (the external testnet). Applied by default for the default (lean) stack — in the hub-less default the public chain is the privacy nodes' only interconnection path: **`local` with `--local`, `rayls-testnet` otherwise**. `--full --local` also defaults to `local` (the 3.0.1 source deploy requires a public chain); only `--full` with pulled images runs without one. Adds per-participant `pubrelayer` services. * `--privacy-node-only`: Run just a single Axyl privacy node, with no bridge or surrounding services. Ignores all other flags. -* `--monitoring`: Enable the observability stack (Grafana, Loki, Prometheus, Tempo) with eBPF auto-instrumentation. Default: off. +* `--monitoring`: Enable the observability stack (Grafana, Loki, Prometheus, Tempo, Pyroscope, plus an OTLP collector on `4317`/`4318`). Default: off. * `--blockscout `: Comma-separated participant letters that should get a Blockscout explorer (e.g. `a,b`). Defaults to **every participant**; use this to narrow the set. * `--no-blockscout`: Disable the per-node Blockscout explorers entirely (overrides `--blockscout`). * `--local`: Dev mode. Build the Rayls app components (kos/CTS, pubrelayer, private relayer, contracts — plus governance, proofs-api and audit-explorer in hub topologies) from source (short names, `pull_policy=build`/`never`) instead of pulling them from ECR. Also defaults the topology to **hub-less** and `--public-chain` to `local`, so a `--local` init runs **everything on your machine with no hub** — pair with `--public-chain rayls-testnet` to keep bridging to the testnet instead. The infra images (NATS, the Private Network Hub, Postgres, nginx, Blockscout) still come from their registries and are pre-pulled one at a time, same as the published stack. @@ -173,7 +173,7 @@ PUBLIC_CHAIN_PRIVATE_KEY= ./rayls init --public-chain rayls-testnet # 0x Once the stack is healthy, bridge a token end-to-end (see [Verifying the bridge](#verifying-the-bridge)). -> This mode uses the dedicated `rayls-contracts:lean-no-pnh` contracts image (built from the sibling `rayls-privacy-contracts` repo, branch `cli-lean-no-pnh`) and the `rayls-privacy-axyl` node image. Both are published to ECR, so the default `init` works out of the box. +> This mode uses the `rayls-contracts:latest` contracts image (the 3.0.1 `HUB_ENABLED`-aware deploy built from `rayls-sovereign-contracts` `main`; the older `:lean-no-pnh` tag points at the same digest and is kept only for backward compatibility) and the `rayls-privacy-axyl` node image. Both are published to ECR, so the default `init` works out of the box. #### 2. Full demo stack (`--full`) @@ -216,7 +216,7 @@ Useful when external tooling only needs an EVM RPC endpoint. All other flags are #### 5. With monitoring -Adds Grafana (`:3300`), Loki, Prometheus, Tempo, and eBPF auto-instrumentation. Combines with the default or `--full` modes. +Adds a single `grafana/otel-lgtm` container: Grafana (`:3300`), Loki (`:3100`), Prometheus (`:3090`), Tempo (`:3200`), Pyroscope (`:3040`) and an OTLP collector (`:4317` gRPC / `:4318` HTTP). Services are not auto-instrumented; point them at the collector to ship telemetry. Combines with the default or `--full` modes. ```bash ./rayls init --monitoring @@ -279,14 +279,14 @@ docker build -f etc/docker-network/Dockerfile \ Pauses running containers without removing them. ```bash ./rayls stop # Stop all services - ./rayls stop pl-b # Stop specific services + ./rayls stop privacy-node-b # Stop specific services ``` * **Tear down the environment:** Stops and removes containers and networks. By default, volumes are preserved (data is kept). ```bash ./rayls down # Remove containers/networks, keep volumes (data preserved) ./rayls down -v # Remove containers/networks AND volumes (destructive) - ./rayls down --remove-orphans # Also remove orphaned containers + ./rayls down -y # Skip the confirmation prompt (orphaned containers are always removed) ``` ### Monitoring & Inspection @@ -441,7 +441,7 @@ When running with `--full`, the CLI provisions the complete Rayls stack: **Infrastructure Layer** * **Postgres** - Relational database for relayer/KOS/governance data * **Commit Chain** - Besu-based blockchain for cross-ledger coordination -* **OpenTelemetry Stack** - Optional (when `--monitoring` is enabled): eBPF auto-instrumentation, Grafana, Loki, Tempo, Prometheus +* **OpenTelemetry Stack** - Optional (when `--monitoring` is enabled): one `grafana/otel-lgtm` container bundling the OTel collector, Grafana, Loki, Tempo, Prometheus, and Pyroscope **Contract Deployment Layer** * **Proofs API** - Zero-knowledge proof generation service @@ -472,7 +472,7 @@ This orchestration ensures that all required dependencies are available before d ## Troubleshooting -* **`invalid empty ssh agent socket` during a `--local` build:** the git build contexts are private, so BuildKit needs your ssh-agent — make sure `SSH_AUTH_SOCK` is set and your GitHub key is loaded (`ssh-add -l`). +* **`invalid empty ssh agent socket` during a `--local` build:** the default git build contexts are public `https://` URLs and need no agent; this appears when a `*_REPO` override uses a `git@`/`ssh://` URL (e.g. a private fork), which makes BuildKit request ssh forwarding — make sure `SSH_AUTH_SOCK` is set and your GitHub key is loaded (`ssh-add -l`). * **BuildKit can't resolve a custom SSH host alias:** git contexts are cloned by the Docker daemon, which doesn't read your `~/.ssh/config`. Use the plain `github.com` host in `*_REPO` URLs and select the right key via your agent, or fall back to a local checkout with `rayls dev`. * **`docker-compose.override.yaml exists but was not generated by rayls dev`:** you have a hand-written override; move it aside (its job is likely covered by `rayls dev` now). diff --git a/internal/docker/docker_config.go b/internal/docker/docker_config.go index c9c64fb..c748680 100644 --- a/internal/docker/docker_config.go +++ b/internal/docker/docker_config.go @@ -115,7 +115,8 @@ const ( localPublicChainChainID = 7331 ) -// FundingURL is where users request testnet RAYLS for their own deployer key +// FundingURL is where users request testnet USDr (the public chain's gas token) +// for their own deployer key // (funding happens outside the CLI). const FundingURL = "https://www.rayls.com/community" diff --git a/internal/stacks/publicchainbalance.go b/internal/stacks/publicchainbalance.go index c6cead2..806055d 100644 --- a/internal/stacks/publicchainbalance.go +++ b/internal/stacks/publicchainbalance.go @@ -19,17 +19,17 @@ import ( // Preflight for testnet-bridged inits: an underfunded deployer key fails // MINUTES into the deploy with errors that name neither account nor amount. // Cost model (observed on rayls-testnet at the deploy's fixed 100 gwei): -// ~2 deploy gas (~1.67 upfront) + 0.5 x 5 relayer wallets per participant, +// ~2 USDr deploy gas (~1.67 upfront) + 0.5 x 5 relayer wallets per participant, // re-spent on every fresh deploy; auth re-seeds on each contracts restart. const ( - deployGasRaylsX10 = 20 // ~2.0 deploy gas, in tenths to stay integer - perParticipantSeedRaylsX10 = 25 // 2.5 relayer seeding per participant, in tenths + deployGasUsdrX10 = 20 // ~2.0 deploy gas, in tenths to stay integer + perParticipantSeedUsdrX10 = 25 // 2.5 relayer seeding per participant, in tenths ) func requiredInitFundsWei(participants int) *big.Int { - tenthRayls := new(big.Int).Exp(big.NewInt(10), big.NewInt(17), nil) // 0.1 in wei - tenths := int64(deployGasRaylsX10) + int64(perParticipantSeedRaylsX10)*int64(participants) - return new(big.Int).Mul(big.NewInt(tenths), tenthRayls) + tenthUsdr := new(big.Int).Exp(big.NewInt(10), big.NewInt(17), nil) // 0.1 in wei + tenths := int64(deployGasUsdrX10) + int64(perParticipantSeedUsdrX10)*int64(participants) + return new(big.Int).Mul(big.NewInt(tenths), tenthUsdr) } // deployerAddress derives the 0x EVM address from a bare or 0x-prefixed hex @@ -83,8 +83,8 @@ func fetchBalanceWei(rpcURL, address string) (*big.Int, error) { return bal, nil } -// weiToRayls renders wei as a decimal string with 4 fractional digits. -func weiToRayls(wei *big.Int) string { +// weiToUsdr renders wei as a decimal USDr string with 4 fractional digits. +func weiToUsdr(wei *big.Int) string { r := new(big.Rat).SetFrac(wei, new(big.Int).Exp(big.NewInt(10), big.NewInt(18), nil)) return r.FloatString(4) } @@ -106,19 +106,19 @@ func checkDeployerBalance(pc *docker.PublicChain, privKeyHex string, participant } required := requiredInitFundsWei(participants) if balance.Cmp(required) >= 0 { - fmt.Printf("Deployer %s balance on %s: %s (needs ~%s for a fresh deploy) ✓\n", - address, pc.Name, weiToRayls(balance), weiToRayls(required)) + fmt.Printf("Deployer %s balance on %s: %s USDr (needs ~%s USDr for a fresh deploy) ✓\n", + address, pc.Name, weiToUsdr(balance), weiToUsdr(required)) return nil } shortfall := new(big.Int).Sub(required, balance) return fmt.Errorf(`insufficient funds on the deployer account for %s. account: %s - balance: %s - required: ~%s (deploy gas ~2 + 2.5 x %d participant(s) relayer seeding) - shortfall: %s + balance: %s USDr + required: ~%s USDr (deploy gas ~2 + 2.5 x %d participant(s) relayer seeding) + shortfall: %s USDr Top up via %s and re-run.`, - pc.Name, address, weiToRayls(balance), weiToRayls(required), participants, - weiToRayls(shortfall), pc.Faucet) + pc.Name, address, weiToUsdr(balance), weiToUsdr(required), participants, + weiToUsdr(shortfall), pc.Faucet) } diff --git a/internal/stacks/publicchainbalance_test.go b/internal/stacks/publicchainbalance_test.go index 1faebe9..8007123 100644 --- a/internal/stacks/publicchainbalance_test.go +++ b/internal/stacks/publicchainbalance_test.go @@ -42,16 +42,16 @@ func TestRequiredInitFundsWei(t *testing.T) { return new(big.Int).Mul(big.NewInt(tenths), new(big.Int).Exp(big.NewInt(10), big.NewInt(17), nil)) } if got := requiredInitFundsWei(1); got.Cmp(rayls(45)) != 0 { // 2 + 2.5 - t.Errorf("1 participant: got %s, want 4.5 RAYLS", weiToRayls(got)) + t.Errorf("1 participant: got %s, want 4.5 USDr", weiToUsdr(got)) } if got := requiredInitFundsWei(3); got.Cmp(rayls(95)) != 0 { // 2 + 7.5 - t.Errorf("3 participants: got %s, want 9.5 RAYLS", weiToRayls(got)) + t.Errorf("3 participants: got %s, want 9.5 USDr", weiToUsdr(got)) } } -func TestWeiToRayls(t *testing.T) { +func TestWeiToUsdr(t *testing.T) { wei, _ := new(big.Int).SetString("1566278887397589872", 10) - if got := weiToRayls(wei); got != "1.5663" { + if got := weiToUsdr(wei); got != "1.5663" { t.Errorf("got %s, want 1.5663", got) } } @@ -73,7 +73,7 @@ func TestCheckDeployerBalance(t *testing.T) { key := strings.Repeat("ab", 32) t.Run("sufficient balance passes", func(t *testing.T) { - srv := stubRPC(t, "0x4563918244f40000") // 5 RAYLS > 4.5 required + srv := stubRPC(t, "0x4563918244f40000") // 5 USDr > 4.5 required defer srv.Close() pc := &docker.PublicChain{Name: "rayls-testnet", RPC: srv.URL, Faucet: docker.FundingURL} if err := checkDeployerBalance(pc, key, 1); err != nil { @@ -82,7 +82,7 @@ func TestCheckDeployerBalance(t *testing.T) { }) t.Run("insufficient balance refuses with shortfall and funding URL", func(t *testing.T) { - srv := stubRPC(t, "0x15bcacb1eb98fdf0") // ~1.5663 RAYLS < 4.5 + srv := stubRPC(t, "0x15bcacb1eb98fdf0") // ~1.5663 USDr < 4.5 defer srv.Close() pc := &docker.PublicChain{Name: "rayls-testnet", RPC: srv.URL, Faucet: docker.FundingURL} err := checkDeployerBalance(pc, key, 1) diff --git a/internal/stacks/publicchainkey.go b/internal/stacks/publicchainkey.go index 9e271be..c1a3c6d 100644 --- a/internal/stacks/publicchainkey.go +++ b/internal/stacks/publicchainkey.go @@ -135,7 +135,7 @@ func ensurePublicChainKey(pc *docker.PublicChain) (string, error) { A deployer key funded on %s is required: the deploy pays public-chain gas and seeds each participant's public-relayer wallets from it. There is no shared default key; fund your own key first via %s -(roughly 5 RAYLS per participant), then enter it below. It will be stored in +(roughly 5 USDr per participant), then enter it below. It will be stored in this directory's .env (permissions 0600) and reused by every later run. `, pc.Name, pc.Faucet) @@ -189,7 +189,7 @@ func warnIfEnvFileCommittable() { func missingPublicChainKeyError(chainName string) error { return fmt.Errorf(`no funded deployer key for %s. -Deploying to %s needs your own private key, funded with testnet RAYLS; there +Deploying to %s needs your own private key, funded with testnet USDr; there is no shared default key. Get funds at %s, then provide the key one of these ways: From a85856d3b0495015eb8b370b6408259921451ff4 Mon Sep 17 00:00:00 2001 From: Nuno Date: Tue, 25 Aug 2026 14:46:57 +0100 Subject: [PATCH 2/2] fix: replacing more text to sovereign --- README.md | 70 +++++++++++++++++++++++++++---------------------------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index cab1e9e..25ea5b3 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # Rayls CLI -**Provision and manage a local Rayls blockchain stack on a single host — a privacy node bridged to a public chain by default, or the full multi-participant demo.** +**Provision and manage a local Rayls blockchain stack on a single host — a Rayls Sovereign bridged to a public chain by default, or the full multi-participant demo.** [![License: Apache 2.0][license-badge]][license-url] [![Go][go-badge]][go-url] @@ -20,20 +20,20 @@ The **Rayls CLI** is a developer tool for provisioning and managing the [Rayls]( Currently, this tool focuses on deploying a **local demo environment** on a single host, making it ideal for sales demonstrations, proof-of-concept exploration, and local development. It automates the generation of Docker Compose configurations and manages the lifecycle of the Rayls components. -> **What changed recently** — the privacy node is now the **Axyl** (`rayls-network`) node, running gaslessly in its local dev-mode profile, and replacing the previous Geth-based ledger. The **default** `rayls init` now spins up a single local privacy node bridged to a public chain (the primary use case); the full multi-participant demo stack moved behind `--full`. +> **What changed recently** — the Rayls Sovereign is now the **Axyl** (`rayls-network`) node, running gaslessly in its local dev-mode profile, and replacing the previous Geth-based ledger. The **default** `rayls init` now spins up a single local Rayls Sovereign bridged to a public chain (the primary use case); the full multi-participant demo stack moved behind `--full`. For a deeper understanding of the Rayls architecture and ecosystem, please visit the [Official Rayls Documentation](https://docs.rayls.com/docs/a-warm-introduction-to-rayls). ## Features -* **Local privacy node → public chain by default:** A bare `rayls init` runs a single Axyl privacy node bridged to a public chain (Rayls testnet). -* **Gasless Axyl node:** The privacy node runs the Axyl `local` hardfork profile (EIP-1559 active from block 0 with a zero base-fee floor), so relayer/pubrelayer transactions on the node need no gas funding. +* **Local Sovereign → public chain by default:** A bare `rayls init` runs a single Rayls Sovereign (Axyl) bridged to a public chain (Rayls testnet). +* **Gasless Axyl node:** The Rayls Sovereign runs the Axyl `local` hardfork profile (EIP-1559 active from block 0 with a zero base-fee floor), so relayer/pubrelayer transactions on the node need no gas funding. * **Full demo stack on demand:** `--full` brings up the multi-participant stack with a local Private Network Hub (commit chain), governance, and proofs API — 2 to 6 participants. * **Automated Setup:** Generates a dynamic `docker-compose.yaml` tailored to your specifications. * **Sequential Image Pulling:** Automatically pulls container images one-by-one — in every mode, `--local` included — to stay under ECR Public's per-IP pull rate limit, cooling off and retrying if a registry throttles anyway. * **Lifecycle Management:** Specialized commands to start, stop, and tear down the stack. * **Monitoring & Observability:** Optional OpenTelemetry stack (a single `grafana/otel-lgtm` container: OTel collector, Grafana, Loki, Prometheus, Tempo, and Pyroscope). -* **Per-Node Block Explorers:** Blockscout deployment per privacy node (default-on). +* **Per-Node Block Explorers:** Blockscout deployment per Sovereign (default-on). * **Version Management:** Built-in version checking and update notifications. * **Environment Verification:** Tools to verify the integrity of the setup, including an end-to-end public-chain bridge smoke test. @@ -121,29 +121,29 @@ To set up a new environment, run the `init` command. This will: ./rayls init ``` -By default this spins up **Axyl privacy node(s) bridged to a public chain**, with **hub-less as the default topology**: the nodes intercommunicate via the public chain only, no Private Network Hub. With `--local` everything runs on your machine (source builds + an in-stack Axyl public chain). Pulled-image inits (no `--local`) bridge to the Rayls testnet, deploying from **your own funded testnet key**: `rayls init` prompts for it and saves it to the stack `.env` (see [Funding](#funding)). Every participant also gets a Blockscout explorer by default (`--no-blockscout` disables). `--with-hub` opts a lean stack into the minimal hub explicitly; `--full` brings the complete hub demo stack. +By default this spins up **Rayls Sovereign(s) bridged to a public chain**, with **hub-less as the default topology**: the nodes intercommunicate via the public chain only, no Private Network Hub. With `--local` everything runs on your machine (source builds + an in-stack Axyl public chain). Pulled-image inits (no `--local`) bridge to the Rayls testnet, deploying from **your own funded testnet key**: `rayls init` prompts for it and saves it to the stack `.env` (see [Funding](#funding)). Every participant also gets a Blockscout explorer by default (`--no-blockscout` disables). `--with-hub` opts a lean stack into the minimal hub explicitly; `--full` brings the complete hub demo stack. If a `docker-compose.yaml` already exists, you'll be prompted to overwrite or use the existing file. If you choose to keep the existing file, the CLI will proceed with pulling images and starting containers. **Options:** -* `--full`: Bring up the full multi-participant demo stack (local Private Network Hub / commit chain, governance, proofs API, multiple privacy nodes). Combine with `--members` and/or `--public-chain`. -* `--with-hub`: Include the **Private Network Hub** in the default (lean) stack — a **functional hub**: PNH plus the private relayer and proofs-api, so PN↔PNH messaging and Enygma work. Without it, **hub-less is the default** (both pulled-image and `--local` stacks): no PNH, no private relayer, no proofs API — the privacy nodes intercommunicate via the public chain only, and the contracts deploy runs with `HUB_ENABLED=false`. Every `--local` init records its build sources in the stack `.env` — the local sibling checkouts (`../rayls-sovereign-contracts`, `../rayls-sovereign-relayer`, recorded as relative paths) via `CONTRACTS_SRC`/`RELAYER_SRC` when present (whatever branch is checked out there is what builds), else the `main` git contexts via `CONTRACTS_REF`/`RELAYER_REF`. `--full` always includes the full hub. -* `--members `: Number of privacy node participants. With `--full`: 2–6 (default **2**). For the hub-less default topology: 1–6 (default **1**) — the nodes intercommunicate via the public chain, so any count is meaningful. Ignored on hub-carrying lean stacks (`--with-hub` runs a single participant; use `--full` for the multi-participant hub). -* `--public-chain `: Public chain preset to bridge to — `local` (an Axyl public chain running **inside the stack**: service `public-chain`, RPC `localhost:8845`, chain id `7331`, deployer genesis-funded, no external connectivity) or `rayls-testnet` (the external testnet). Applied by default for the default (lean) stack — in the hub-less default the public chain is the privacy nodes' only interconnection path: **`local` with `--local`, `rayls-testnet` otherwise**. `--full --local` also defaults to `local` (the 3.0.1 source deploy requires a public chain); only `--full` with pulled images runs without one. Adds per-participant `pubrelayer` services. -* `--privacy-node-only`: Run just a single Axyl privacy node, with no bridge or surrounding services. Ignores all other flags. +* `--full`: Bring up the full multi-participant demo stack (local Private Network Hub / commit chain, governance, proofs API, multiple Sovereigns). Combine with `--members` and/or `--public-chain`. +* `--with-hub`: Include the **Private Network Hub** in the default (lean) stack — a **functional hub**: PNH plus the private relayer and proofs-api, so Sovereign↔PNH messaging and Enygma work. Without it, **hub-less is the default** (both pulled-image and `--local` stacks): no PNH, no private relayer, no proofs API — the Rayls Sovereigns intercommunicate via the public chain only, and the contracts deploy runs with `HUB_ENABLED=false`. Every `--local` init records its build sources in the stack `.env` — the local sibling checkouts (`../rayls-sovereign-contracts`, `../rayls-sovereign-relayer`, recorded as relative paths) via `CONTRACTS_SRC`/`RELAYER_SRC` when present (whatever branch is checked out there is what builds), else the `main` git contexts via `CONTRACTS_REF`/`RELAYER_REF`. `--full` always includes the full hub. +* `--members `: Number of Sovereign participants. With `--full`: 2–6 (default **2**). For the hub-less default topology: 1–6 (default **1**) — the nodes intercommunicate via the public chain, so any count is meaningful. Ignored on hub-carrying lean stacks (`--with-hub` runs a single participant; use `--full` for the multi-participant hub). +* `--public-chain `: Public chain preset to bridge to — `local` (an Axyl public chain running **inside the stack**: service `public-chain`, RPC `localhost:8845`, chain id `7331`, deployer genesis-funded, no external connectivity) or `rayls-testnet` (the external testnet). Applied by default for the default (lean) stack — in the hub-less default the public chain is the Rayls Sovereigns' only interconnection path: **`local` with `--local`, `rayls-testnet` otherwise**. `--full --local` also defaults to `local` (the 3.0.1 source deploy requires a public chain); only `--full` with pulled images runs without one. Adds per-participant `pubrelayer` services. +* `--privacy-node-only`: Run just a single Rayls Sovereign (Axyl), with no bridge or surrounding services. Ignores all other flags. * `--monitoring`: Enable the observability stack (Grafana, Loki, Prometheus, Tempo, Pyroscope, plus an OTLP collector on `4317`/`4318`). Default: off. * `--blockscout `: Comma-separated participant letters that should get a Blockscout explorer (e.g. `a,b`). Defaults to **every participant**; use this to narrow the set. * `--no-blockscout`: Disable the per-node Blockscout explorers entirely (overrides `--blockscout`). * `--local`: Dev mode. Build the Rayls app components (kos/CTS, pubrelayer, private relayer, contracts — plus governance, proofs-api and audit-explorer in hub topologies) from source (short names, `pull_policy=build`/`never`) instead of pulling them from ECR. Also defaults the topology to **hub-less** and `--public-chain` to `local`, so a `--local` init runs **everything on your machine with no hub** — pair with `--public-chain rayls-testnet` to keep bridging to the testnet instead. The infra images (NATS, the Private Network Hub, Postgres, nginx, Blockscout) still come from their registries and are pre-pulled one at a time, same as the published stack. * `--no-pull`: Skip the image-pull step; `up` then fetches only the images missing locally, one at a time. Use to keep a locally-built image (e.g. a custom node/contracts build) instead of overwriting it from ECR. -* `--lean`: **Deprecated** — the lean privacy-node → public-chain bridge is now the default, so this flag is a no-op. Use `--full` for the multi-participant stack. +* `--lean`: **Deprecated** — the lean Sovereign → public-chain bridge is now the default, so this flag is a no-op. Use `--full` for the multi-participant stack. Example: ```bash ./rayls init # default: 1 Axyl node -> rayls-testnet + explorer (http://localhost:10004) ./rayls init --local # fully local: source builds + local Axyl public chain ./rayls init --local --public-chain rayls-testnet # source builds, but bridge to the testnet -./rayls init --local --members 3 # 3 hub-less privacy nodes, fully local +./rayls init --local --members 3 # 3 hub-less Sovereigns, fully local ./rayls init --local --with-hub # keep the minimal PNH (lean hub stack) ./rayls init --full --members 3 --monitoring # full 3-participant demo stack + monitoring ``` @@ -154,16 +154,16 @@ Example: The `init` flags compose into several distinct stack flavors: -#### 1. Default — local privacy node → public chain +#### 1. Default — local Sovereign → public chain -A **minimal privacy-node → public-chain bridge** for a single participant (`a`): the Axyl privacy node plus the services needed to bridge to an external public chain, with **no** private relayer, gnark/proofs API, or governance. This is what a bare `rayls init` does. +A **minimal Sovereign → public-chain bridge** for a single participant (`a`): the Rayls Sovereign (Axyl) plus the services needed to bridge to an external public chain, with **no** private relayer, gnark/proofs API, or governance. This is what a bare `rayls init` does. ```bash -./rayls init # bridge to rayls-testnet (default) + privacy-chain explorer +./rayls init # bridge to rayls-testnet (default) + Sovereign ledger explorer ./rayls init --public-chain rayls-testnet # same; --public-chain overrides the target ``` -Hub-less (the default topology) the stack is 7 core services: `postgres` (shared Postgres — backs the pubrelayer + KOS databases), `nats`, `privacy-node-a`, `public-chain` (the in-stack Axyl public chain with `--local`; omitted when bridging to the testnet), `contracts`, `kos-a`, `pubrelayer-a` — plus the per-node Blockscout explorer services (default-on; `--no-blockscout` drops them). KOS is kept because the pubrelayer fetches its signing keys from it. With `--with-hub` the stack additionally runs `private-network-hub` (the Besu commit chain), `relayer-a` (the private relayer, PN↔PNH message relaying) and `proofs-api` (Enygma proofs). +Hub-less (the default topology) the stack is 7 core services: `postgres` (shared Postgres — backs the pubrelayer + KOS databases), `nats`, `privacy-node-a`, `public-chain` (the in-stack Axyl public chain with `--local`; omitted when bridging to the testnet), `contracts`, `kos-a`, `pubrelayer-a` — plus the per-node Blockscout explorer services (default-on; `--no-blockscout` drops them). KOS is kept because the pubrelayer fetches its signing keys from it. With `--with-hub` the stack additionally runs `private-network-hub` (the Besu commit chain), `relayer-a` (the private relayer, Sovereign↔PNH message relaying) and `proofs-api` (Enygma proofs). Bridging to the testnet deploys from **your own funded key**: `rayls init` prompts for it and saves it to the stack `.env` (see [Funding](#funding)). Non-interactive/CI runs pass it via the environment instead: @@ -177,7 +177,7 @@ Once the stack is healthy, bridge a token end-to-end (see [Verifying the bridge] #### 2. Full demo stack (`--full`) -The full Rayls stack with N participants, a **local Besu commit chain** (`private-network-hub`), proofs API, and governance services. Bridging happens between the privacy nodes and the local commit chain, plus a public chain: with `--local` the in-stack `local` preset is included by default (the 3.0.1 source deploy requires a public chain — its PN deploy ABI-encodes `PUBLIC_CHAIN_ID`); with pulled images the public chain stays optional (the 3.0.0-era deploy supports the commit-chain-only demo). +The full Rayls stack with N participants, a **local Besu commit chain** (`private-network-hub`), proofs API, and governance services. Bridging happens between the Rayls Sovereigns and the local commit chain, plus a public chain: with `--local` the in-stack `local` preset is included by default (the 3.0.1 source deploy requires a public chain — its Sovereign deploy ABI-encodes `PUBLIC_CHAIN_ID`); with pulled images the public chain stays optional (the 3.0.0-era deploy supports the commit-chain-only demo). ```bash ./rayls init --full # 2 participants, local commit chain (pulled images) @@ -186,7 +186,7 @@ The full Rayls stack with N participants, a **local Besu commit chain** (`privat ./rayls init --full --public-chain rayls-testnet # full stack + external public chain ``` -The deployer for the local Besu / privacy nodes can be overridden: +The deployer for the local Besu / Sovereigns can be overridden: ```bash PRIVATE_KEY_SYSTEM=<0x-hex> ./rayls init --full @@ -194,17 +194,17 @@ PRIVATE_KEY_SYSTEM=<0x-hex> ./rayls init --full #### 3. Hub-less (the default topology) -The default topology runs the environment **without the Private Network Hub**, mirroring `start_dev.sh --no-hub` in the `rayls-sovereign-relayer` repo: no `private-network-hub` (Besu), no private relayers, no proofs API, no governance and no audit explorer (those belong to the hub topologies — use `--with-hub` or `--full` for them). The privacy nodes intercommunicate through the **public chain only**, so a public chain is always configured — with `--local` it defaults to the `local` preset (an Axyl public chain inside the stack), making the whole system **fully self-contained on one host**; pass `--public-chain rayls-testnet` to bridge to the external testnet instead. The contracts deploy runs with `HUB_ENABLED=false`, writes no `PNH_*` values into the per-participant env files, and the CTS detects hub-less mode from their absence. +The default topology runs the environment **without the Private Network Hub**, mirroring `start_dev.sh --no-hub` in the `rayls-sovereign-relayer` repo: no `private-network-hub` (Besu), no private relayers, no proofs API, no governance and no audit explorer (those belong to the hub topologies — use `--with-hub` or `--full` for them). The Rayls Sovereigns intercommunicate through the **public chain only**, so a public chain is always configured — with `--local` it defaults to the `local` preset (an Axyl public chain inside the stack), making the whole system **fully self-contained on one host**; pass `--public-chain rayls-testnet` to bridge to the external testnet instead. The contracts deploy runs with `HUB_ENABLED=false`, writes no `PNH_*` values into the per-participant env files, and the CTS detects hub-less mode from their absence. ```bash -./rayls init --local # single PN <-> local public chain, fully isolated -./rayls init --local --members 3 # N PNs interconnected via the local public chain +./rayls init --local # single Sovereign <-> local public chain, fully isolated +./rayls init --local --members 3 # N Sovereigns interconnected via the local public chain ./rayls init --local --public-chain rayls-testnet # hub-less, bridged to the testnet ``` > Hub-less needs the `HUB_ENABLED`-aware contracts deploy and the hub-less-capable CTS, which ship in the 3.0.1 `rayls-sovereign-contracts` / `rayls-sovereign-relayer` components — now published to ECR, so hub-less is the default for pulled-image inits too. For `--local`, the CLI records the build sources in the stack `.env` — preferring the local sibling checkouts (`CONTRACTS_SRC`/`RELAYER_SRC`, so in-flight hub-less branches build as checked out) and falling back to the `main` git contexts (`CONTRACTS_REF`/`RELAYER_REF`). Override either in `.env` if needed. -#### 4. Privacy node only +#### 4. Sovereign only Minimal stack: a single Axyl `privacy-node-a`, with no bridge or surrounding services. The EVM JSON-RPC is exposed on `127.0.0.1:8545` (gasless, chain id `12345`). No contracts, relayer, KOS, governance, NATS, postgres, commit chain, or proofs API — Axyl self-stores in its datadir. @@ -251,7 +251,7 @@ Once the default (or `--public-chain`) stack is healthy, bridge a token end-to-e ./rayls verify public-chain ``` -This creates a user, deploys a fresh `DEMO_*` ERC-20 on the privacy node, waits for the pubrelayer to deploy the mirror token on the public chain, bridges 100 DEMO, and confirms the destination balance. It prints the privacy-node token, the public-chain token, the recipient, and the public chain id; verify the public-chain token on the explorer (https://testnet-explorer.rayls.com/). +This creates a user, deploys a fresh `DEMO_*` ERC-20 on the Rayls Sovereign, waits for the pubrelayer to deploy the mirror token on the public chain, bridges 100 DEMO, and confirms the destination balance. It prints the token on the Sovereign ledger, the public-chain token, the recipient, and the public chain id; verify the public-chain token on the explorer (https://testnet-explorer.rayls.com/). If a step (usually relayer authorization on the public chain) hasn't propagated yet, a clean `./rayls down -v` and re-run typically clears it. @@ -332,12 +332,12 @@ docker build -f etc/docker-network/Dockerfile \ After successful initialization, the exposed services depend on the mode. -**Default (local privacy node → public chain):** -* **Privacy Node RPC:** `http://localhost:8545` — Axyl EVM JSON-RPC (chain id `12345`, gasless) +**Default (local Sovereign → public chain):** +* **Sovereign RPC:** `http://localhost:8545` — Axyl EVM JSON-RPC (chain id `12345`, gasless) * **Private Network Hub:** `http://localhost:3445` — the minimal commit chain (only with `--with-hub` or `--full`; the hub-less default has none) * **Pubrelayer:** `http://localhost:9050` — bridges to the public chain * **KOS (Key Orchestration):** `localhost:8080` — the CTS gRPC endpoint (mTLS, not plain HTTP) -* **Blockscout explorer:** `http://localhost:10004` — privacy-chain explorer for node `a` (default-on; per-node at `10004 + 100·i`) +* **Blockscout explorer:** `http://localhost:10004` — Sovereign ledger explorer for node `a` (default-on; per-node at `10004 + 100·i`) **Full stack (`--full`) — additional shared services:** * **Block Explorer:** `http://localhost:8181` - View blockchain transactions and blocks @@ -349,7 +349,7 @@ For each participant (A, B, C, …) in `--full`, services are exposed on increme | Service | Participant A | Participant B | Participant C | |---------|--------------|--------------|--------------| -| Privacy Node (PL) | `http://localhost:8545` | `http://localhost:8546` | `http://localhost:8547` | +| Sovereign | `http://localhost:8545` | `http://localhost:8546` | `http://localhost:8547` | | Relayer | `http://localhost:9000` | `http://localhost:9001` | `http://localhost:9002` | | KOS (Key Orchestration) | `http://localhost:8080` | `http://localhost:8081` | `http://localhost:8082` | @@ -363,7 +363,7 @@ A bare `rayls init` pulls the published `rayls-demo` images from ECR. `rayls ini |---|---|---| | kos, pubrelayer, private relayer, contracts | published ECR `rayls-demo` images | **built by Docker** from the pinned git refs (the `rayls-sovereign-*` repos on `main`), or your checkouts via `rayls dev` | | `--full` extras: governance-api/listener/flagger, proofs-api (gnark), audit-explorer | ECR | **built by Docker** from their `rayls-sovereign-*` repos on `main` (see note on gnark's Git-LFS keys below) | -| Axyl privacy node | pulled from ECR | pulled from ECR + retagged (a local `rayls-privacy-axyl:latest` you built yourself is left alone) | +| Sovereign (Axyl) | pulled from ECR | pulled from ECR + retagged (a local `rayls-privacy-axyl:latest` you built yourself is left alone) | | nats, Private Network Hub (Besu) | ECR | ECR (pulled — infra images aren't source-built) | | Third-party (postgres, blockscout, nginx, grafana) | public registries | public registries | @@ -430,9 +430,9 @@ The stack directory's `.env` file drives both the CLI and compose; the process e ## Architecture -### Privacy node (Axyl) +### Sovereign (Axyl) -Each privacy node is an **Axyl (`rayls-network`) node** running in its single-validator dev mode. It exposes an Ethereum-compatible JSON-RPC (`eth_*`, `net_*`, `web3_*`, `debug_*`, `trace_*`) on `8545+i`, keeps chain state in its own datadir (a named volume, no external database), and runs the `local` hardfork profile so it is **gasless** (EIP-1559 active from block 0 with a 0 base-fee floor). The genesis is generated externally at startup via a one-shot init container (keytool + genesis ceremony), keeping the node image config-free. +Each Rayls Sovereign is an **Axyl (`rayls-network`) node** running in its single-validator dev mode. It exposes an Ethereum-compatible JSON-RPC (`eth_*`, `net_*`, `web3_*`, `debug_*`, `trace_*`) on `8545+i`, keeps chain state in its own datadir (a named volume, no external database), and runs the `local` hardfork profile so it is **gasless** (EIP-1559 active from block 0 with a 0 base-fee floor). The genesis is generated externally at startup via a one-shot init container (keytool + genesis ceremony), keeping the node image config-free. ### Full demo stack (`--full`) @@ -445,14 +445,14 @@ When running with `--full`, the CLI provisions the complete Rayls stack: **Contract Deployment Layer** * **Proofs API** - Zero-knowledge proof generation service -* **Contracts** - Smart contract compilation and deployment service (deploys to all privacy nodes and the commit chain) +* **Contracts** - Smart contract compilation and deployment service (deploys to all Sovereigns and the commit chain) **Governance Layer** * **Governance API / Listener / Flagger** - governance operations, event listening, and feature flags **Per-Participant Services** For each participant (A, B, C, …): -* **Privacy Node (PL)** - Axyl private blockchain node (e.g. `privacy-node-a`, aliases `pl-a`/`pn-a`) +* **Sovereign** - Axyl private blockchain node (e.g. `privacy-node-a`, aliases `pl-a`/`pn-a`) * **KOS (Key Orchestration Service)** - Cryptographic key management (e.g. `kos-a`) * **Relayer** - Cross-chain transaction relay service (e.g. `relayer-a`) @@ -463,8 +463,8 @@ A single shared **NATS** instance is deployed for all participants and the gover The stack uses health checks and dependency ordering to ensure services start in the correct sequence: 1. Infrastructure services (Postgres, NATS) start first -2. Privacy nodes (and, in `--full`, the commit chain) start after their init/infrastructure is healthy -3. Contract deployment waits for the privacy nodes (and, in `--full`, the proofs API and commit chain) +2. Sovereigns (and, in `--full`, the commit chain) start after their init/infrastructure is healthy +3. Contract deployment waits for the Rayls Sovereigns (and, in `--full`, the proofs API and commit chain) 4. Application services (KOS, relayers, pubrelayer) wait for contracts to be deployed 5. Governance services (in `--full`) start after contracts and databases are ready