@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.
{
"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).
{
"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.state | Extra fields | Meaning |
|---|---|---|
unavailable | None | The wallet has no sync cursor |
syncing | cursor, head | Indexed through cursor, chain head is head |
live | cursor, head | The cursor has caught the head |
error | cursor, message | Sync 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:
tokenor a returningtokenis not a 20-byte address;amountorminAmountis negative, or is hex that is empty or not0x-prefixed;datais present and is not hex;returninglists 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); // 0x5f5e100Prop
Type