Opertus

Getting started

Install the Opertus SDK, create a wallet, and make your first private deposit on Sepolia.

This page takes you from an empty folder to a private balance on Sepolia: you install the SDK, create a wallet, deposit test ETH, and read it back. From there, the transactions guide shows how to transfer and unshield.

Internal access

The packages install from the private opertus GitHub organization over SSH, so you need access to the organization and an SSH key on your GitHub account. ssh -T git@github.com should greet you by name.

What you need

  • Node.js 20 or later, and pnpm.
  • SSH access to the opertus GitHub organization.
  • A Sepolia RPC URL.
  • A Sepolia account with some test ETH from a faucet, for gas and the deposit.

Sepolia

A pool is deployed on Sepolia (chain ID 11155111). You pay your own gas. Any Sepolia ETH or ERC-20 can be shielded. Deposit and unshield each take 0.5%.

ContractAddress
Pool0x950c20818eaF36d218001a7b57Eb096d597dCD5B
Executor0x1f3a18AE44DCa7CBF3105dA84d7e920680271aF5
Deployment block11886708

Install

Create a project with this package.json:

package.json
{
  "type": "module",
  "dependencies": {
    "@opertus/core": "git+ssh://git@github.com/opertus/core.git#semver:>=0.0.1-alpha",
    "@opertus/wallet": "git+ssh://git@github.com/opertus/wallet.git#semver:>=0.0.1-alpha",
    "@scure/bip39": "^2.2.0",
    "viem": "^2.55.19"
  },
  "devDependencies": {
    "tsx": "^4.22.3"
  }
}

The semver: range installs the latest release tag of each package. The lockfile records the exact commit; run pnpm update @opertus/core @opertus/wallet to move to a newer release.

The SDK packages depend on each other through GitHub too, which pnpm blocks by default. Allow it for this project, and let pnpm reach the private repos over SSH:

pnpm-workspace.yaml
blockExoticSubdeps: false
git config --global url."git@github.com:".insteadOf "https://github.com/"
pnpm install

The examples below are one Node script, index.ts. Run it with npx tsx index.ts. It has to run in Node because the prover reads its keys from disk.

Download the proving keys

Download and unpack the proving archive. The SDK does not download it for you.

curl -L "https://jade-dear-sturgeon-531.mypinata.cloud/ipfs/bafybeif5xk7ubu7a6cdfg5xxk3ic5ibjp67v7py7pji2xipzz2ts6l52va" | tar xz

This creates a proving/ folder with keys/ and one transfer_*x3_js/ folder per circuit width. Pass it to createProver('./proving').

Configure

The script reads three environment variables:

VariableValue
SEPOLIA_RPCYour Sepolia RPC URL
MNEMONICYour Opertus recovery phrase (see the next step)
PRIVATE_KEYThe funded Sepolia account that pays gas, as 0x-prefixed hex

Start index.ts with the Sepolia values:

index.ts
import { ETH } from '@opertus/core';

const rpcUrl = process.env.SEPOLIA_RPC!;
const poolAddress = '0x950c20818eaF36d218001a7b57Eb096d597dCD5B';
const poolDeployBlock = 11886708n;
const token = ETH;

Create a wallet

Generate a recovery phrase once and save it as MNEMONIC:

npx tsx -e "import { generateMnemonic } from '@scure/bip39'; import { wordlist } from '@scure/bip39/wordlists/english.js'; console.log(generateMnemonic(wordlist))"

This phrase holds your private notes. It is separate from the gas account in PRIVATE_KEY, which stays an ordinary public Ethereum account.

Set up clients

index.ts
import { createPublicClient, createWalletClient, http, type Hex } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { sepolia } from 'viem/chains';
import { OpertusClient, createProver } from '@opertus/core';
import { KeyManager } from '@opertus/wallet';

const publicClient = createPublicClient({ chain: sepolia, transport: http(rpcUrl) });
const walletClient = createWalletClient({
  account: privateKeyToAccount(process.env.PRIVATE_KEY as Hex),
  chain: sepolia,
  transport: http(rpcUrl),
});

const client = new OpertusClient({
  publicClient,
  poolAddress,
  prover: createProver('./proving'),
});

const wallet = KeyManager.fromMnemonic(process.env.MNEMONIC!);
const domain = {
  chainId: BigInt(await publicClient.getChainId()),
  poolAddress: BigInt(poolAddress),
};

OpertusClient reads the pool and builds calls; walletClient signs and sends them. KeyManager holds your Opertus keys, and domain identifies the chain and pool your notes belong to.

Read your balance

index.ts
import { Scanner } from '@opertus/wallet';

async function readBalance() {
  const { payloads, spentNullifiers } = await client.getLogs({
    fromBlock: poolDeployBlock,
    blockRange: 10_000n,
  });

  const notes = await Scanner.scan(wallet.exportViewingKey(), payloads, domain);
  return notes
    .filter((record) => !spentNullifiers.has(record.note.getNullifier()))
    .filter((record) => record.note.payload.tokenId === BigInt(token))
    .reduce((sum, record) => sum + record.note.payload.value, 0n);
}

console.log('balance before:', await readBalance());

A new wallet reads 0n. That's expected: you haven't deposited yet.

getLogs downloads the pool's events in chunks your RPC accepts. Scanner.scan keeps only the notes your view key can decrypt, and the spent nullifiers tell you which of them are already used. To keep syncing later without starting over, see sync incrementally.

Deposit test ETH

index.ts
import { OpertusBuilder } from '@opertus/core';
import { Sender } from '@opertus/wallet';

const amount = 10_000_000_000_000_000n; // 0.01 ETH
const noteValue = OpertusBuilder.predictShieldNote(amount, 0n, await client.getDepositFeeBps());
const recipient = await Sender.prepareSend(wallet.getMetaAddress(), BigInt(token), noteValue, domain);

const hash = await walletClient.writeContract(client.deposit({ recipient, amount, token }));
await publicClient.waitForTransactionReceipt({ hash });

console.log('balance after:', await readBalance());

The note holds the deposit minus the 0.5% fee, so the second balance is 9_950_000_000_000_000n. Run the script again and both lines show your growing private balance.

Good to know

  • Notes belong to one chain and pool. Your meta-address works anywhere, but each note is tied to the domain it was created for.
  • The view key reads, the spend key spends. Reading a balance needs only the view key. See keys and notes.
  • Deposits and withdrawals are public. Transfers inside the pool are private. The privacy model lists exactly what is visible.

Next steps

On this page