Overview

An application can reach Rayls Sovereign at several levels, and the right choice depends on whether the institution wants to construct and sign Ethereum transactions itself or would rather work against a REST interface.

Because the Rayls Sovereign ledger is fully Ethereum compatible, the simplest integration is direct JSON-RPC with Hardhat, Foundry, ethers.js, web3.js, viem or MetaMask. Nothing about Rayls requires a bespoke client library at this level.

---

Choosing between direct JSON-RPC and the Backend

The Backend is optional in every deployment. It exists so that an institution can drive onchain operations from its existing systems without those systems needing to understand Ethereum transaction encoding.

---

What the Backend does

The Backend is a custody-agnostic transaction construction service. It builds transactions with gas estimation and nonce management, hands them to a custody solution for signing, broadcasts them to the Rayls Sovereign ledger or to the public chain endpoint, and tracks their status.

Its REST surface is organised into two groups, both bearer-authenticated, alongside a public health check.

• A user group, covering onboarding, token registration and listing, token locking, and address-pair queries.
• An operator group, covering onboarding-status and token-status approvals and the corresponding pending lists.

---

How a transaction is constructed

The Backend follows the same sequence for every token operation.

1. Validate the inputs. Confirm that the required fields are present, that the addresses are valid, and that the token standard matches the parameters supplied.

2. Verify the token. Query the token governance contract and confirm that the token is approved.

3. Build the call data. Parse the amount or token identifier as a big integer and ABI-encode the function call.

4. Construct the transaction. Fetch the nonce and the gas price from the chain, create the unsigned transaction, and RLP-encode it for transport.

5. Sign and broadcast. Hand the payload to the custody service, wait for the transaction to be mined, and return the transaction hash.

Each transaction is constructed with the following parameters.

---

The token lock request

Token locking is the operation that begins a bridge to the public chain. The /api/user/tokenLock endpoint accepts the following fields.

The call data the Backend builds from those fields corresponds to the teleport function for the relevant standard, as set out in Connecting Rayls Sovereign to the Rayls Public Chain.

---

Error handling

Where a transaction fails onchain, the Backend detects that the receipt status is not equal to 1, simulates the transaction to extract the revert reason, and returns a readable error to the client rather than a bare failure.

The reasons seen most often are an insufficient token balance, a token that has not been approved for transfer, an invalid token identifier on an NFT, and a contract that has been paused.

---

Custody

The Backend abstracts custody behind a small interface, so that any custody provider capable of signing a transaction can be used.

type CustodyService interface {
    CreateWallets(ctx context.Context, quantity int) ([]Wallet, error)
    SignAndTransact(ctx context.Context, payload []byte, signerAddress, chainID string) (string, error)
}

CreateWallets is called during onboarding, and SignAndTransact is called for every transaction, with the chainID parameter determining which endpoint receives the signed transaction. Signing follows EIP-155, so the chain identifier is included in the signature for replay protection.

The design is genuinely custody-agnostic, which means that integrating a production custody provider is an implementation of this interface and an initialisation change, with no other code affected. It also means that custody is an integration step in a Rayls Sovereign deployment rather than something that arrives configured. The implementation shipped with the Backend generates keys locally and is intended for development, and it should not be used to hold production key material.

For the key handling that Rayls itself performs, which is a separate matter from application custody, see Key management and cryptography in Rayls Sovereign.

---

Proof generation

Applications that use Enygma or DvP do not generate zero-knowledge proofs themselves. The Relayer requests them from the Gnark API, which exposes transfer, deposit and withdraw proof endpoints at each anonymity level, together with join-split and ownership endpoints for DvP. The inputs are the witness fields and the output is the proof with its public signals. An integrating application does not call the Gnark API directly.