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
opertusGitHub 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%.
| Contract | Address |
|---|---|
| Pool | 0x950c20818eaF36d218001a7b57Eb096d597dCD5B |
| Executor | 0x1f3a18AE44DCa7CBF3105dA84d7e920680271aF5 |
| Deployment block | 11886708 |
Install
Create a project with this 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:
blockExoticSubdeps: falsegit config --global url."git@github.com:".insteadOf "https://github.com/"
pnpm installThe 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 xzThis 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:
| Variable | Value |
|---|---|
SEPOLIA_RPC | Your Sepolia RPC URL |
MNEMONIC | Your Opertus recovery phrase (see the next step) |
PRIVATE_KEY | The funded Sepolia account that pays gas, as 0x-prefixed hex |
Start index.ts with the Sepolia values:
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
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
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
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
domainit 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.