Scanning the Privacy Pool with IPrivacy.privacyScan
A wallet discovers incoming shielded notes by paginating the on-chain privacyScan view with a cursor and the triple-limit budget. This guide walks through the cursor format, the three limits, event-type filtering, and the pattern for resuming a scan across calls.
privacyScan returns a PrivacyScanPage — a bounded slice of event summaries and their outputs, plus the nextCursor to resume from. The chain validates every summary and output it returns; when a page fills up or the byte budget is hit it sets hasMore = true and pins the cursor to the last visible position. A client reads in a loop until hasMore is false.The cursor and the three limits
The cursor is
PrivacyScanCursor { int64 height, uint64 globalSequence, uint32 outputIndex }. Pass { 0, 0, 0 } on the first call. Three limits bound each page: outputLimit caps the number of output rows, eventLimit caps the number of event summaries scanned, and maxEncodedBytes caps the protobuf-size of what the chain packs into the response. Pass 0 on any of them to use the chain's default; any value above the chain's hard maximum reverts with InvalidPageRequest naming the offending argument index (1 = outputLimit, 2 = eventLimit, 3 = maxEncodedBytes).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 firstPage = await publicClient.readContract({
address: iPrivacyAddress,
abi: iPrivacyAbi,
functionName: "privacyScan",
args: [
{ height: 0n, globalSequence: 0n, outputIndex: 0 }, // start
64, // outputLimit
32, // eventLimit
0n, // maxEncodedBytes — 0 uses the default
[], // eventTypes — empty = all
],
});
console.log(firstPage.summaries.length, firstPage.outputs.length, firstPage.hasMore); Filtering by event type
Pass a list of event-type strings in the fifth argument to restrict what the chain returns. An empty array means every event type; the values are
deposit, withdraw, shielded_transfer and batch_transfer. Filtered events still count against eventLimit (so a filtered scan traverses the same number of blocks as an unfiltered one would), but the chain never emits their summaries into summaries — the only thing a filtered event does is advance the cursor. If a page has already added visible content when a filtered event appears, the chain sets hasMore = true and stops so the client never has to accept an unproven cursor jump past outputs.const transfersOnly = await publicClient.readContract({
address: iPrivacyAddress,
abi: iPrivacyAbi,
functionName: "privacyScan",
args: [
{ height: 0n, globalSequence: 0n, outputIndex: 0 },
64,
32,
0n,
["shielded_transfer"],
],
}); Resuming a scan with nextCursor
On each page, pass
response.nextCursor back as the first argument of the next call. Stop when response.hasMore is false. The cursor advances inside an event — (height, globalSequence) identifies the event and outputIndex is the last visible output of that event — so a scan that is paused mid-event picks up on the exact next output rather than reprocessing the earlier ones.let cursor = { height: 0n, globalSequence: 0n, outputIndex: 0 };
const allOutputs: unknown[] = [];
for (;;) {
const page = await publicClient.readContract({
address: iPrivacyAddress,
abi: iPrivacyAbi,
functionName: "privacyScan",
args: [cursor, 64, 32, 0n, []],
});
allOutputs.push(...page.outputs);
if (!page.hasMore) break;
cursor = page.nextCursor;
}
console.log("total outputs scanned:", allOutputs.length); Note: A
privacyScan view call from an off-chain client via eth_call costs no gas. Calling it from a Solidity contract through staticcall pre-charges a response-size budget (3 gas per byte, with per-summary and per-output allowances) before the chain maps the result — tune the three limits down when a contract reads the surface. What's in a scan output
Each
PrivacyScanOutput returned by a non-filtered page carries the raw bytes a wallet needs to recognize a note (commitment, ciphertext, encryptedNote, viewTag), its position in the tree (leafIndex, leafIndexFound), and the disclosure metadata (userPrivacyPolicy, userDisclosureMode, userDisclosureDigest, userDisclosureTargetPubkey, userDisclosurePayload, fullDisclosureDigest, auditDisclosurePayload, selfViewDisclosurePayload). It also carries identity fields (circuitSetId, payloadVersion, scanSchemaVersion, auditKeyId, auditKeyEpoch, auditTargetPubkey) and the originating txHash / eventType — pin circuitSetId and payloadVersion against your circuitConfig() and disclosureConfig() reads before you trust an output.Conclusion
privacyScan is the authoritative on-chain way to discover shielded notes — no side indexer is needed for a wallet to find what has been sent to it. Combine it with merklePath (or commitmentPathsAtRoot for a historical snapshot) to build the inputs for the next transfer / withdraw.