Private Network roles

Roles in a Rayls Private Network work at two levels:

• Parties. The Private Network operator and the participants, and the role each participant has in the Hub's participant registry.
• On-chain permissions. Every chain in the network, the Private Network Hub and each Rayls Sovereign chain (Privacy Node in the code), has its own access manager (RaylsAccessManagerV1). It decides which accounts may call which contract functions on that chain. Each chain's access manager is independent: a role on the Hub gives no rights on a Rayls Sovereign chain, and the reverse.

This page describes both, as the code defines them.

The parties

What the operator can read

The operator's governance services hold the network's view secret key (ML-KEM-768). Each participant's key service encrypts the participant's view private key to the operator when it registers, and registration can't complete without it. With those keys, the governance listener decrypts:

• every token transfer and arbitrary message relayed through the Hub, including senders, receivers and amounts;
• every Enygma transfer and the terms of every DvP (delivery-versus-payment) swap.

The view keys can't move funds. See Who sees what and Auditing.

Participant roles in the Hub registry

Each participant has one of three roles, and one of four statuses, in the Hub's participant registry (ParticipantStorageV1).

Each participant also has an allowedToBroadcast flag. When it is set, the participant can send one message to every other participant at once.

🚧

The auditor role doesn't restrict transacting

Only issuers can register tokens, and participants can send and receive them. A participant with the AUDITOR role can also transact like any other active participant: the code doesn't stop it.

How the access managers work

Every Rayls contract that has privileged functions asks its chain's access manager whether the caller may call the function. The access manager is adapted from OpenZeppelin's AccessManager.

• ADMIN (role 0) can call every restricted function on that chain, whatever the mapping says. It can also grant and revoke roles, map functions to roles, pause a contract's restricted functions in an emergency, and upgrade the contracts.
• PUBLIC (role 1) marks a function anyone can call.
• TOKEN_OWNER (role 2) is granted per token contract, usually to the account that deployed it. It controls that token's owner functions, such as mint and burn.
• Named roles are registered on each chain and mapped to specific functions. A function that isn't mapped to any role can only be called by ADMIN.

Each role has an admin role, which can grant and revoke it, and can have a guardian role, which can cancel its scheduled operations. A grant can carry an execution delay: the member must then schedule each call and wait out the delay before executing it. A role can also have a grant delay before new members become active.

Roles on the Private Network Hub

Business roles

These roles are for the people and systems that govern the network. The task activate-business-roles-pnh in rayls-sovereign-contracts registers and maps them, and grant-business-role grants them.

Some operator actions have no business role and need ADMIN: adding a single participant with addParticipant, removing a participant, changing a participant's broadcast permission, pausing a contract and upgrading the Hub contracts.

Anyone can propose a contract template for Enygma program steps (propose is open). Only PRIVATE_NETWORK_OPERATOR or ADMIN can approve or revoke one.

System roles

The Hub deployment also registers roles that only contracts and relayers hold: ENYGMA_CREATOR, DVP_FACTORY_CALLER, REGISTRY_CALLER, ENDPOINT_SENDER, FACTORY_ADMIN, ENYGMA_V1, COIN_VAULT, DVP_CONTRACT, RELAYER, MESSAGE_EXECUTOR, MESSAGE_RECEIVER and RESOURCE_REGISTRAR. The one the operator manages directly is RELAYER: it grants it to each participant's relayer signing addresses, so that relayer can deliver messages to the Hub and register the participant's keys.

Roles on each Rayls Sovereign chain

Business roles

The task activate-business-roles-pn registers and maps these on a Rayls Sovereign chain. The participant's ADMIN grants them.

Token owners

Any account on the chain can deploy a standard token through the chain's contract factory (RNContractFactoryV1), with functions such as deployErc20AsUser and deployEnygmaAsUser. The caller becomes the token's TOKEN_OWNER and can mint and burn it. Before the token can move between chains, the chain's operator must register and authorise it and submit it to the Hub, and the Private Network operator must approve it. See Supported token standards.

System roles

As on the Hub, a Rayls Sovereign chain has roles that only contracts and relayers hold: PN_TOKEN_REGISTRY_ADMIN and PN_TOKEN_REGISTRY_UPGRADER (granted to the deploying account), ENDPOINT_SENDER, FACTORY_ADMIN, FACTORY_DEPLOYER, RELAYER, TOKEN_CREATOR, MESSAGE_EXECUTOR, MESSAGE_RECEIVER and RESOURCE_REGISTRAR. A custom contract that sends cross-chain messages needs ENDPOINT_SENDER, granted by the chain's administrator. See Interacting with a Private Network.

Is there an auditor?

Not as a separate party with its own keys. In the code today:

• the Hub's NETWORK_AUDITOR role and the Rayls Sovereign chain's AUDITOR role have no functions mapped to them;
• the AUDITOR participant role labels the operator's own entry and has no effect in any check;
• the Auditor Explorer is the operator's tool: it reads the governance API, which shows the whole network;
• comments in the template registry call template approval an "auditor" action, but the deployed role mapping gives it to PRIVATE_NETWORK_OPERATOR.

There are no scoped or time-limited view keys. If a regulator needs to see activity, the operator can give it access to the Auditor Explorer, which shows every cross-chain transfer in the network. See Auditing.

Check the roles on a chain

From a checkout of rayls-sovereign-contracts, configured for the chain:

npx hardhat list-roles --chain pnh                    # roles on the Hub
npx hardhat list-roles --pn A                         # roles on Rayls Sovereign chain A
npx hardhat list-roles --chain pnh --account 0x...   # roles held by one account