IPrivacy.privacyScan으로 비공개 풀 스캔하기
지갑은 커서와 세 가지 제한 예산으로 온체인 privacyScan view를 페이징하여 들어오는 비공개 노트를 발견합니다. 이 가이드에서는 커서 형식, 세 가지 제한, 이벤트 타입 필터링, 호출 간에 스캔을 이어가는 패턴을 다룹니다.
privacyScan은 PrivacyScanPage를 반환합니다. 이벤트 summary와 그 output들의 제한된 조각, 그리고 다음 호출을 이어갈 nextCursor를 담습니다. 체인은 반환하는 모든 summary와 output을 검증합니다. 페이지가 가득 차거나 바이트 예산을 초과하면 hasMore = true로 설정하고 커서를 마지막 가시 위치에 고정합니다. 클라이언트는 hasMore가 false가 될 때까지 반복해서 읽습니다.커서와 세 가지 제한
커서는
PrivacyScanCursor { int64 height, uint64 globalSequence, uint32 outputIndex }입니다. 첫 호출에는 { 0, 0, 0 }을 전달합니다. 각 페이지는 세 가지 제한으로 크기가 제한됩니다. outputLimit은 output 행 수, eventLimit은 스캔되는 이벤트 summary 수, maxEncodedBytes는 체인이 응답에 담는 protobuf 크기를 각각 제한합니다. 셋 중 어느 값에 0을 전달하면 체인 기본값을 사용합니다. 체인의 하드 최대치를 초과하는 값은 어느 인자가 문제인지 알려주는 InvalidPageRequest로 revert됩니다(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 }, // 시작
64, // outputLimit
32, // eventLimit
0n, // maxEncodedBytes — 0은 기본값 사용
[], // eventTypes — 빈 배열은 전체
],
});
console.log(firstPage.summaries.length, firstPage.outputs.length, firstPage.hasMore); 이벤트 타입으로 필터링
다섯 번째 인자로 이벤트 타입 문자열 배열을 전달하면 체인이 반환하는 내용을 제한합니다. 빈 배열은 모든 이벤트 타입을 의미하며, 값은
deposit, withdraw, shielded_transfer, batch_transfer입니다. 필터된 이벤트도 eventLimit에 그대로 카운트되므로(필터된 스캔도 필터되지 않은 스캔과 동일한 수의 블록을 순회), 체인은 그 summary를 summaries에 포함하지 않습니다. 필터된 이벤트가 하는 일은 커서를 전진시키는 것뿐입니다. 어떤 페이지에 이미 가시적인 내용이 추가된 상태에서 필터된 이벤트가 나타나면, 체인은 hasMore = true를 설정하고 중단하여 클라이언트가 output을 지나는 증명 없는 커서 점프를 받아들일 필요가 없게 합니다.const transfersOnly = await publicClient.readContract({
address: iPrivacyAddress,
abi: iPrivacyAbi,
functionName: "privacyScan",
args: [
{ height: 0n, globalSequence: 0n, outputIndex: 0 },
64,
32,
0n,
["shielded_transfer"],
],
}); nextCursor로 스캔 이어가기
각 페이지에서
response.nextCursor를 다음 호출의 첫 번째 인자로 그대로 전달합니다. response.hasMore가 false이면 중단합니다. 커서는 이벤트 내부에서도 전진합니다. (height, globalSequence)가 이벤트를 식별하고 outputIndex는 해당 이벤트의 마지막 가시 output입니다. 이벤트 도중에 중단된 스캔은 앞의 output을 다시 처리하지 않고 정확히 다음 output부터 이어갑니다.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("스캔한 총 output 수:", allOutputs.length); 참고: 오프체인 클라이언트에서
eth_call로 privacyScan을 호출하면 gas가 들지 않습니다. Solidity 컨트랙트에서 staticcall로 호출하면 체인이 결과를 매핑하기 전에 응답 크기 예산(바이트당 3 gas, summary와 output마다 할당)을 사전 과금하므로, 컨트랙트에서 호출할 때는 세 가지 제한을 낮게 설정합니다. 스캔 output에 담긴 내용
필터되지 않은 페이지가 반환하는 각
PrivacyScanOutput은 지갑이 노트를 식별하는 데 필요한 원본 바이트(commitment, ciphertext, encryptedNote, viewTag), 트리 내 위치(leafIndex, leafIndexFound), disclosure 메타데이터(userPrivacyPolicy, userDisclosureMode, userDisclosureDigest, userDisclosureTargetPubkey, userDisclosurePayload, fullDisclosureDigest, auditDisclosurePayload, selfViewDisclosurePayload)를 담습니다. 또한 식별 필드(circuitSetId, payloadVersion, scanSchemaVersion, auditKeyId, auditKeyEpoch, auditTargetPubkey)와 원본 txHash / eventType을 포함합니다. output을 신뢰하기 전에 circuitSetId와 payloadVersion을 circuitConfig()와 disclosureConfig() 읽기 값과 대조하여 고정합니다.마무리
privacyScan은 비공개 노트를 발견하는 공식적인 온체인 방법입니다. 지갑이 수신된 노트를 찾는 데 별도의 인덱서가 필요하지 않습니다. merklePath(또는 과거 스냅샷을 위한 commitmentPathsAtRoot)와 함께 사용하여 다음 transfer / withdraw의 입력을 구성합니다.