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, 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 and Deploying smart contracts.
Send private payments and swaps. Call the Enygma token's crossTransfer, or the DvP functions. See Send Enygma transactions and Private DvP with Enygma.
Send messages to contracts on other chains. See 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.
Grant roles such as PRIVACY_NODE_OPERATOR and BANK_EMPLOYEE. See Private Network roles.
Freeze a token on the chain (freezeOnPrivacyNode).

The repository 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 and Send cross Private Network arbitrary messages.

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

grant it the ENDPOINT_SENDER role in the chain's access manager, without which it can't send;
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)
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, Approving new tokens, Freezing participants and 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 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). 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). 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.