RPC Protocol

Sigilry uses JSON-RPC 2.0 for dApp to wallet communication. Methods and schemas are defined in OpenRPC and validated with Zod at runtime.

Request and response shapes

import type { JsonRpcRequest, JsonRpcResponse } from "@sigilry/dapp/messages";

const request: JsonRpcRequest = {
  jsonrpc: "2.0",
  id: "request-id",
  method: "status",
};

const success: JsonRpcResponse = {
  jsonrpc: "2.0",
  id: "request-id",
  result: {
    /* method result */
  },
};

const failure: JsonRpcResponse = {
  jsonrpc: "2.0",
  id: "request-id",
  error: { code: -32601, message: "Method not found" },
};

Methods

Method	Params	Result
status	none	StatusEvent
connect	none	ConnectResult
disconnect	none	null
isConnected	none	ConnectResult
getActiveNetwork	none	Network
listAccounts	none	Wallet[]
getPrimaryAccount	none	Wallet
prepareExecute	JsPrepareSubmissionRequest	null
prepareExecuteAndWait	JsPrepareSubmissionRequest	{ tx: TxChangedExecutedEvent }
signMessage	{ message: string }	SignMessageResult
ledgerApi	LedgerApiRequest	Record<string, unknown> | unknown[]

SignMessageResult always carries signature and may carry optional signedBy, publicKey, signingAlgorithmSpec, format, and encoding fields; see @sigilry/dapp.

Event methods are defined in the OpenRPC spec but delivered as provider events:

• accountsChanged
• txChanged
• statusChanged — CIP-103 §4.2.2 provider status transitions; disconnects route through here per §4.2.2:216
• connected — CIP-103 login-flow completion event (not one of the §4.2.2 three); identical payload to statusChanged

Error handling

@sigilry/dapp exposes common error codes via RpcErrorCode and helpers like rpcError.

import "@sigilry/dapp/browser-globals";
import { RpcClientError } from "@sigilry/dapp";

async function getStatus() {
  if (!window.canton) throw new Error("No Canton wallet injected");
  try {
    return await window.canton.request({ method: "status" });
  } catch (err) {
    const parsed = RpcClientError.fromError(err);
    console.error(parsed.code, parsed.message);
    throw parsed;
  }
}

getStatus();

Validation

createCantonServer validates params using Zod schemas generated from OpenRPC. Invalid params return RpcErrorCode.INVALID_PARAMS with a concise error message.