Opertus

@opertus/sdk

Typed client for the Opertus wallet extension.

This package is the client a dapp uses to talk to the installed Opertus wallet at window.opertus. The extension holds keys, notes, and proofs. See keys and notes for the meta-address the wallet returns, and the privacy model before a dapp asks the user to connect or send.

Extension client

@opertus/wallet is the library a wallet uses to derive keys and scan notes. This package only sends typed requests to a wallet that is already installed.

Install

@opertus/sdk installs from the private opertus GitHub organization, the same way as the other SDK packages.

package.json
{
  "dependencies": {
    "@opertus/sdk": "git+ssh://git@github.com/opertus/wallet-sdk.git#semver:>=0.1.0"
  }
}

Add viem when you use opertusActions(). It is an optional peer dependency (viem >= 2).

package.json
{
  "dependencies": {
    "viem": "^2.55.19"
  }
}

Not published to npm

The package is not on a registry yet, so npm install @opertus/sdk will not resolve. Install it from the private GitHub repo at the latest release tag. The published files are built JavaScript and type declarations.

Create a client

createOpertusClient() binds window.opertus. Pass an OpertusProvider when there is no window, such as a test or a custom transport. The examples below continue from this client.

import { createOpertusClient, ETH, type OpertusProvider } from '@opertus/sdk';

declare const provider: OpertusProvider;

const opertus = createOpertusClient();
const usdc = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' as const;

const testClient = createOpertusClient(provider);

Calling createOpertusClient() with no argument and no window.opertus throws No Opertus provider found.

Prop

Type

on and removeListener are optional. See provider events.

Read status

Call getStatus() before prompting the user. It reports whether this chain has a pool, how fresh the wallet's sync is, and the fee rates the wallet last read. On Sepolia those pool and executor addresses match the deployment table.

const status = await opertus.getStatus();

if (!status.supported || status.sync.state !== 'live') {
  throw new Error('Wallet is not ready');
}

The readiness check above waits for live. syncing and error are valid reports; unavailable means the wallet has no sync state to show.

Prop

Type

OpertusStatus

Prop

Type

A malformed status, including an unknown sync.state, throws.

sync.stateExtra fieldsMeaning
unavailableNoneThe wallet has no sync cursor
syncingcursor, headIndexed through cursor, chain head is head
livecursor, headThe cursor has caught the head
errorcursor, messageSync stopped; message is the wallet's error string

cursor and head are 0x-prefixed hex quantities.

Connect

requestAccount() asks the extension to connect and returns the selected meta-address. That string is what another Opertus user pays. The meta-address carries no chain id and no private key.

const { metaAddress } = await opertus.requestAccount();

The wallet may return either a meta-address string or { metaAddress }. The client always resolves { metaAddress }. An empty or missing value throws Invalid opertus_requestAccount response.

Prop

Type

Balances

ETH is 0x0000000000000000000000000000000000000000, the native token id in the shielded pool. getBalance always calls opertus_getBalance with { tokens } and returns a record of bigint values, keyed by the addresses you passed.

const balances = await opertus.getBalance({ tokens: [ETH, usdc] });
const eth = balances[ETH];

Pass at least one token. An empty list throws Expected at least one token address. A token that is not a 20-byte address throws. Use ETH for native ETH.

The wallet response must be a record. Each requested token is matched case-insensitively and must be a hex quantity. A missing or non-hex entry throws Invalid opertus_getBalance response.

Prop

Type

Clone address

getCloneAddress asks the wallet for the user's deterministic CREATE2 clone. The diversifier is an app-chosen string or hex value; the same diversifier always yields the same clone for that account. The app does not compute the salt. The proof binds a nonzero salt as Poseidon(spendScalar, diversifier); see proofs and settlement. Tokens left on a persistent clone stay there until a later call returns them. See known limits.

const { cloneAddress, cloneSalt } = await opertus.getCloneAddress({
  diversifier: 'aave-v3-position-1',
});

Prop

Type

A response missing a valid cloneAddress or cloneSalt throws.

Send

sendTransaction asks the wallet to prove and submit one shielded action. It returns the transaction hash. Amounts accept a bigint or a 0x hex quantity; the client always sends a hex quantity. to is forwarded as a string: a meta-address, a 0x address, or an ENS name. The transactions guide describes what the wallet proves for each case.

to is the recipient meta-address. The wallet spends private notes and creates the recipient's note. No public asset moves.

const hash = await opertus.sendTransaction({
  to: metaAddress,
  token: ETH,
  amount: 1_000_000_000_000_000n,
});

Prop

Type

The client rejects the request before it reaches the wallet when:

  • token or a returning token is not a 20-byte address;
  • amount or minAmount is negative, or is hex that is empty or not 0x-prefixed;
  • data is present and is not hex;
  • returning lists more than four assets.

A response that is not hex throws Invalid opertus_sendTransaction response.

Viem

opertusActions() decorates a viem client whose transport speaks the Opertus provider. Each action takes the same arguments as the matching method above and returns the same parsed result.

import { createClient, custom } from 'viem';
import { opertusActions } from '@opertus/sdk';

const client = createClient({
  transport: custom(window.opertus),
}).extend(opertusActions());

const { metaAddress } = await client.requestOpertusAccount();
const balances = await client.getOpertusBalance({ tokens: [ETH] });

Prop

Type

Provider events

The client does not subscribe for you. Listen on opertus.provider when the provider implements on. Each listener receives an untyped payload. The event names are accountsChanged, chainChanged, connect, and disconnect.

function onAccountsChanged(payload: unknown) {
  console.log(payload);
}

opertus.provider.on?.('accountsChanged', onAccountsChanged);
opertus.provider.removeListener?.('accountsChanged', onAccountsChanged);

Prop

Type

Other exports

formatHexQuantity is the helper sendTransaction uses for amounts. It accepts a non-negative bigint or a 0x hex string of at least one digit. A negative bigint, a missing 0x prefix, or an empty 0x throws.

import { formatHexQuantity } from '@opertus/sdk';

formatHexQuantity(100_000_000n); // 0x5f5e100

Prop

Type

On this page