---
updatedAt: 2026-10-22T13:15:02.000Z
agentTools:
  projectIndex: https://docs.rayls.com/llms.txt
---

# Interacting with a Private Network

Each party in a Rayls Private Network uses different interfaces. Applications talk to their own institution's Rayls Sovereign chain (Privacy Node in the code). The Private Network operator governs through contracts on the Private Network Hub, and inspects the network through the governance API and the Auditor Explorer. Nobody sends transactions to the Hub on a participant's behalf except that participant's private relayer.

## At a glance

| Who                                       | Interface                                                                                | Use it to                                                                                                                                    |
| ----------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| An institution's applications and clients | The JSON-RPC (remote procedure call) endpoint of the institution's Rayls Sovereign chain | Deploy and call contracts, hold and transfer tokens, send Enygma transfers, DvP (delivery-versus-payment) swaps and messages to other chains |
| An institution's administrators           | Contracts on its Rayls Sovereign chain, through the same endpoint, with on-chain roles   | Deploy tokens, authorise them, submit them to the Hub, manage users and roles                                                                |
| The Private Network operator              | Contracts on the Hub, through the Hub's JSON-RPC endpoint, with on-chain roles           | Register participants, approve tokens and templates, freeze participants and tokens                                                          |
| The operator, and anyone it gives access  | The governance API and the Auditor Explorer                                              | Search and inspect cross-chain transactions, participants, tokens, balances and flags                                                        |

## Applications: the Rayls Sovereign chain

Each Rayls Sovereign chain runs the Axyl node, which serves the standard Ethereum JSON-RPC interface. Ethereum tools such as ethers and Hardhat work against it. The institution that runs the chain decides who can reach the endpoint. In the [local setup](https://docs.rayls.com/docs/installing-a-private-network), participant `a`'s chain is at `http://localhost:8545`, with chain ID 12345.

What you do on the chain:

* **Deploy and use tokens.** Deploy a standard token through the chain's contract factory, then mint and transfer it like any ERC token. See [Supported token standards](https://docs.rayls.com/docs/supported-erc-token-standards) and [Deploying smart contracts](https://docs.rayls.com/docs/deploying-smart-contracts).
* **Send private payments and swaps.** Call the Enygma token's `crossTransfer`, or the DvP functions. See [Send Enygma transactions](https://docs.rayls.com/docs/send-enygma-transactions) and [Private DvP with Enygma](https://docs.rayls.com/docs/enygma-private-dvp).
* **Send messages to contracts on other chains.** See [Your own cross-chain contracts](#your-own-cross-chain-contracts).
* **Follow a transfer.** Read the events your transaction emits and the transfer's status on each chain. Cross-chain transfers settle asynchronously: the call returns when the sending chain accepts it, not when it arrives.

## Administrators: contracts on the Rayls Sovereign chain

An institution's administrators use the same endpoint, from accounts that hold roles in the chain's access manager. Typical tasks:

* **Bring a token into the network.** Register it in the chain's token registry (`registerToken`), authorise it on the chain (`updatePrivacyNodeStatus`) and submit it to the Hub (`submitToHub`). The Private Network operator then approves it. See [Registering a token within a Private Network](https://docs.rayls.com/docs/registering-a-token-in-a-private-network).
* **Grant roles** such as `PRIVACY_NODE_OPERATOR` and `BANK_EMPLOYEE`. See [Private Network roles](https://docs.rayls.com/docs/private-network-roles).
* **Freeze a token on the chain** (`freezeOnPrivacyNode`).

The repository [rayls-sovereign-contracts](https://github.com/raylsnetwork/rayls-sovereign-contracts) has Hardhat tasks for these, for example `tokens:register`, `tokens:approve-pn`, `submitTokenToHub` and `grant-business-role`.

## Your own cross-chain contracts

A contract that sends messages to other chains inherits `RaylsApp` from the Rayls SDK and calls its send functions (`_raylsSend`, `_raylsSendToResourceId` and their batch versions), which pass the message to the chain's endpoint contract. On the receiving chain, the message executor calls the target contract, which can read the origin chain and the original sender. See [RaylsApp](https://docs.rayls.com/docs/raylsapp) and [Send cross Private Network arbitrary messages](https://docs.rayls.com/docs/send-cross-private-network-arbitrary-messages).

The chain's administrator must set the contract up first:

1. grant it the `ENDPOINT_SENDER` role in the chain's access manager, without which it can't send;
2. register its resource ID with the chain's endpoint, so that messages addressed to that resource ID reach it.

Messages to other chains are encrypted for the receiving participant, and the Private Network operator can decrypt them.

## The operator: contracts on the Hub

The operator governs by calling contracts on the Hub, through the Hub's JSON-RPC endpoint (Hyperledger Besu), from accounts that hold the Hub's business roles. The contract addresses are listed in the Hub's deployment registry (`DeploymentProxyRegistryV1`). rayls-sovereign-contracts has Hardhat tasks for the common actions:

| Action                                       | Task                                                                                                             |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Add a participant                            | Call `addParticipant` on the participant registry (see [Adding new participants](https://docs.rayls.com/docs/adding-new-participants)) |
| Change a participant's role or status        | `participants:update-role`, `participants:update-status`                                                         |
| Authorise a participant's relayer on the Hub | `add-authorized-relayers-pnh`                                                                                    |
| Approve a token                              | `tokens:approve-hub`                                                                                             |
| Freeze or unfreeze a token for participants  | `freeze-token`, `unfreeze-token`                                                                                 |
| Grant a role, or list the roles on the Hub   | `grant-business-role`, `list-roles`                                                                              |

See [Adding new participants](https://docs.rayls.com/docs/adding-new-participants), [Approving new tokens](https://docs.rayls.com/docs/approving-new-tokens), [Freezing participants](https://docs.rayls.com/docs/freezing-participants) and [Freezing tokens](https://docs.rayls.com/docs/freezing-tokens).

## Governance API

The governance API is a read-only HTTP API over the data that the governance listener indexes and decrypts from the Hub. It doesn't change anything on any chain: approvals and freezes are Hub contract calls. It listens on port 8080; in the local setup it is at `http://localhost:9100`. Its Swagger page is at `/swagger/index.html`.

| Endpoint                                                                                     | Returns                                                                                                                                                                 | Authentication |
| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `GET /audit/transactions`                                                                    | Cross-chain transactions, filtered by `sourceChainId`, `destinationChainId`, `fromAddress`, `toAddress`, `resourceId`, `messageId`, `messageType` and time, with paging | None           |
| `GET /audit/transactions/{messageId}`                                                        | One transaction                                                                                                                                                         | None           |
| `GET /audit/transactions/batch/{batchId}`, `GET /audit/transactions/enygma/batch/{batchId}`  | The transactions in a batch, or in an Enygma batch                                                                                                                      | None           |
| `GET /audit/transactions/dvp/{transactionId}`, `GET /audit/transactions/dvp/swap/{sharedId}` | A DvP transaction, or both sides of a swap                                                                                                                              | None           |
| `GET /audit/participants`, `GET /audit/participants/{chainId}`                               | Participants                                                                                                                                                            | None           |
| `GET /audit/tokens`, `GET /audit/tokens/{resourceId}`                                        | Tokens in the Hub's registry                                                                                                                                            | None           |
| `GET /audit/header-proofs`                                                                   | Block headers that participants' relayers have posted to the Hub                                                                                                        | None           |
| `GET /flagged`                                                                               | Flagged transactions                                                                                                                                                    | None           |
| `GET /resources/{chainId}/` and `/resources/{chainId}/{resourceId}`                          | Token balances on one chain, as tracked from cross-chain activity                                                                                                       | Login          |
| `GET /resource_info_all_chains/{resourceId}`, `POST /resource_info_list_chains`              | A token's balances across all, or chosen, chains                                                                                                                        | Login          |
| `GET /participant_info/{chainId}`, `GET /token_status/{resourceId}`                          | A participant, or a token's status                                                                                                                                      | Login          |
| `POST /private-network/signup`, `POST /private-network/login`                                | Create an account; log in and receive a JSON Web Token in a cookie                                                                                                      | None           |

> 🚧 Keep the API on the operator's network
>
> The responses include decrypted transaction details: addresses and amounts. In the code, the `/audit` endpoints, `/flagged` and the sign-up endpoint need no authentication. Make the API reachable only from the operator's own network, for example behind a gateway that authenticates users.

## Auditor Explorer

The [Auditor Explorer](https://docs.rayls.com/docs/private-network-auditor-explorer) is a web interface over the governance API. It searches transactions by message ID, transaction ID, source or destination chain, address or resource ID, and shows batches, Enygma transfers and DvP swaps in detail. In the local setup it is at `http://localhost:8181`.

## Other services in the repositories

* **Rayls Custody API** ([rayls-sovereign-custody-light](https://github.com/raylsnetwork/rayls-sovereign-custody-light)). A service that manages wallets, with keys in AWS (Amazon Web Services) KMS (key management service) or a local keystore, and sends ERC-20 transactions on one chain.
* **Rayls Sovereign Ops API** ([rayls-sovereign-ops-api](https://github.com/raylsnetwork/rayls-sovereign-ops-api)). An operations service for a single Rayls Sovereign chain: token deployment, minting and burning, wallet balances and role indexing, with signing through a custody service. It isn't part of the Rayls CLI stack.

There is no JavaScript or Python SDK for Private Networks in the public repositories. The Rayls SDK is the set of Solidity contracts in rayls-sovereign-contracts. See [Building using Rayls SDK](https://docs.rayls.com/docs/building-using-rayls-sdk).