Privacy Precompile Queries
The IPrivacy precompile exposes 15 view methods for nullifier status, Merkle tree state and proofs, disclosure and circuit config, reserve and asset metadata, paginated note scanning, and audit-key discovery.
IPrivacy at 0x100000000000000000000000000000000000000b is a shielded-pool precompile whose state-changing methods (deposit, transfer, withdraw, and their batch / authorization variants) spend notes under zero-knowledge proofs. Alongside those write methods it now exposes 15 view methods that return every piece of state a client needs to build a proof, scan for incoming notes, verify module solvency, and discover the active audit key — so clients no longer have to reach into a side indexer for that information. Every query returns a Solidity struct (or tuple) defined in IPrivacy.sol; there is no equivalent exposed over EVM JSON-RPC.
Architecture
flowchart LR C["dApp / wallet"] P["IPrivacy precompile<br/>0x…000b"] C -->|"treeState / merklePath"| P C -->|"checkNullifier(s)"| P C -->|"privacyScan"| P C -->|"auditKey / auditKeySchedule"| P C -->|"reserve / assetByDenom"| P P -->|"structs (tree, path, scan page, audit record)"| C classDef evm fill:#0096AA,stroke:#0096AA,color:#fff; classDef precompile fill:#FF8C50,stroke:#FF8C50,color:#fff; class C evm; class P precompile;
Clients read tree state, Merkle paths, nullifier status, scan pages, reserves and audit metadata directly from the IPrivacy precompile — no side indexer needed.
Nullifier status
checkNullifier(bytes32) returns whether a single nullifier has already been spent. checkNullifiers(bytes32[]) returns a PrivacyNullifierStatus[] for a batch of nullifiers — one { nullifier, used } row per input. Use these before relaying a transfer to make sure none of the inputs you plan to spend have been consumed by a race.import { createPublicClient, http } from "viem";
import { iPrivacyAbi, iPrivacyAddress } from "@maroo-chain/contracts/abi/precompiles/privacy/IPrivacy";
const publicClient = createPublicClient({ transport: http("https://rpc-testnet.maroo.io") });
const statuses = await publicClient.readContract({
address: iPrivacyAddress,
abi: iPrivacyAbi,
functionName: "checkNullifiers",
args: [[
"0x0000000000000000000000000000000000000000000000000000000000000001",
"0x0000000000000000000000000000000000000000000000000000000000000002",
]],
});
for (const s of statuses) {
console.log(s.nullifier, s.used);
} Merkle tree state and path proofs
treeState() returns a PrivacyTreeState struct — the current root, leafCount, depth, initialized flag, and the configured maxLeaves / remainingLeaves. commitmentInfo(bytes32) returns (bool found, uint64 leafIndex) for a single commitment. merklePath(bytes32) returns the sibling path, pathHelper directions, and the live root — this is what a transfer prover needs. The path proof uses the live tree; for a historical snapshot use commitmentPathsAtRoot (next section).Historical path proofs — commitmentPathsAtRoot
commitmentPathsAtRoot(bytes32[] commitments, bytes32 root, int64 snapshotHeight) returns a PrivacyCommitmentPaths struct with up to the configured snapshot-query maximum commitments against a specific historical root. Pass snapshotHeight = 0 to let the chain look it up by root, or a positive height to assert both. If the live tree has drifted past that snapshot the chain rebuilds the paths, but only when the snapshot has at most the configured rebuild-leaves budget — larger snapshots revert. The method reverts with the shared typed error QueryFailed("commitmentPathsAtRoot", reason), whose reason is "commitment path snapshot requires 1..N commitments" for an empty or oversized batch and "commitment not found in snapshot" when a listed commitment is absent at that snapshot.const paths = await publicClient.readContract({
address: iPrivacyAddress,
abi: iPrivacyAbi,
functionName: "commitmentPathsAtRoot",
args: [
[noteCommitment], // bytes32: the commitment of a note you hold (from your scan)
pastRoot, // bytes32: a root you recorded earlier (treeState().root)
0n, // 0 → resolve height from the root
],
});
console.log(paths.snapshotHeight, paths.leafCount, paths.paths[0].path.length); Disclosure and circuit configuration
disclosureConfig() returns a PrivacyDisclosureConfig listing the payload version string, whether an audit disclosure is required, and the NAMES of the user privacy policies and disclosure modes the chain supports (supportedUserPolicies / supportedUserModes, as strings). The matching userPrivacyPolicy / userDisclosureMode fields on an outbound PrivacyOutputEffect are numeric uint32 codes, so these names do not go into the request as they are. circuitConfig() returns the active circuit set — its schemaVersion, activeSetId, elliptic curve, manifest filename and availability, generated-at timestamp, artifact list (verifying key / wasm filenames with their SHA-256 and env-var names), and the PrivacyCircuitSetIdentity that pins each circuit's verifying-key digest. Read circuitConfig() once at client start to verify the prover you link against matches the chain; disclosure config is best read when building a request, as a chain upgrade may expand the supported policy / mode enums.Reserve and asset metadata
reserve(string denom) returns a PrivacyReserve for the given canonical denom (atokrw on the testnet) with the module balance, total deposited, total withdrawn, expected module balance, invariant flag, and the surplus / shortfall figures. assetByDenom(string canonicalDenom) and assetByID(bytes32 assetId) both return a PrivacyAssetResponse carrying the { canonicalDenom, assetId } pair and the mappingVersion. Use the latter two whenever you need to translate a human-readable denom to the chain's internal 32-byte asset id or the other way.Audit key discovery
auditKey(uint64 epoch) returns a PrivacyAuditRecord for a specific epoch — the serialized record, its store key, and the state height that produced it. auditKeySchedule() returns the activeEpoch, the next nextActivationHeight / nextEpoch, and a halted flag; use it to decide which auditKey epoch to encrypt for. auditConfiguration() returns the network networkNonce, initialHeight, and the PrivacyCircuitSetIdentity — pin this value on the client and refuse to send a shielded request if it ever changes mid-flight. Both audit-key queries pre-charge 400,640 gas for canonical-field validation before any store reads.const schedule = await publicClient.readContract({
address: iPrivacyAddress,
abi: iPrivacyAbi,
functionName: "auditKeySchedule",
});
const active = await publicClient.readContract({
address: iPrivacyAddress,
abi: iPrivacyAbi,
functionName: "auditKey",
args: [schedule.activeEpoch],
});
console.log(active.stateHeight, active.record.length, "bytes"); Gas considerations
staticcall for example). Only eth_call reads from an off-chain client are free. privacyScan additionally pre-charges a response-size budget (3 gas per byte, with per-summary and per-output allowances) BEFORE the chain maps the response to the ABI struct; a tighter outputLimit / eventLimit / maxEncodedBytes keeps that charge low. auditKey and auditKeySchedule each pre-charge 400,640 gas for canonical-field revalidation.