프라이버시 프리컴파일 조회 메서드
IPrivacy 프리컴파일은 nullifier 상태, Merkle 트리 상태와 경로 증명, disclosure와 회로 설정, 리저브와 자산 매핑, 페이징된 노트 스캔, audit 키 조회를 위한 15개의 view 메서드를 제공합니다.
0x100000000000000000000000000000000000000b의 IPrivacy는 비공개 풀 프리컴파일이며, 상태 변경 메서드(deposit, transfer, withdraw와 배치 및 authorization 변형)는 영지식 증명으로 노트를 소비합니다. 이 쓰기 메서드들과 함께 이제 15개의 view 메서드가 노출되어, 클라이언트가 증명을 구성하고 들어오는 노트를 스캔하고 모듈의 지급 능력을 확인하고 활성 audit 키를 발견하는 데 필요한 모든 상태를 반환합니다. 별도의 인덱서가 필요하지 않습니다. 모든 조회는 IPrivacy.sol에 정의된 Solidity struct(또는 튜플)를 반환하며, EVM JSON-RPC에는 대응하는 메서드가 없습니다.
아키텍처
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;
클라이언트는 IPrivacy 프리컴파일에서 트리 상태, Merkle 경로, nullifier 상태, 스캔 페이지, 리저브, audit 메타데이터를 직접 읽습니다. 별도의 인덱서가 필요하지 않습니다.
Nullifier 상태 조회
checkNullifier(bytes32)는 단일 nullifier가 이미 소비되었는지를 반환합니다. checkNullifiers(bytes32[])는 입력마다 { nullifier, used } 행을 담은 PrivacyNullifierStatus[]를 반환합니다. 전송을 릴레이하기 전에 두 메서드로 소비할 입력들이 경쟁 조건으로 이미 소비되지는 않았는지 확인합니다.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 트리 상태와 경로 증명
treeState()는 PrivacyTreeState struct를 반환합니다. 현재 root, leafCount, depth, initialized 플래그, 설정된 maxLeaves / remainingLeaves를 포함합니다. commitmentInfo(bytes32)는 단일 commitment에 대해 (bool found, uint64 leafIndex)를 반환합니다. merklePath(bytes32)는 sibling path, pathHelper 방향, 현재 root를 반환하며, 전송 증명자가 필요로 하는 값입니다. 이 경로 증명은 현재 트리를 사용합니다. 과거 스냅샷이 필요하면 다음 절의 commitmentPathsAtRoot를 사용합니다.과거 경로 증명 — commitmentPathsAtRoot
commitmentPathsAtRoot(bytes32[] commitments, bytes32 root, int64 snapshotHeight)는 특정 과거 root에 대해 설정된 스냅샷 조회 최대 개수까지의 commitment에 대해 PrivacyCommitmentPaths struct를 반환합니다. snapshotHeight에 0을 전달하면 체인이 root로 높이를 조회하고, 양수 높이를 전달하면 둘 다 일치하는지 확인합니다. 현재 트리가 스냅샷보다 뒤로 밀려 있어도 체인이 경로를 재구성하지만, 스냅샷이 재구성 용량 안에 있을 때만 그렇게 합니다. 더 큰 스냅샷은 revert됩니다. 이 메서드는 공통 타입 오류 QueryFailed("commitmentPathsAtRoot", reason)로 revert됩니다. reason은 빈 배열 또는 과도한 크기의 배치이면 "commitment path snapshot requires 1..N commitments", 스냅샷에 commitment가 없으면 "commitment not found in 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 → root로 높이 조회
],
});
console.log(paths.snapshotHeight, paths.leafCount, paths.paths[0].path.length); Disclosure와 회로 설정
disclosureConfig()는 PrivacyDisclosureConfig를 반환하며, payload 버전 문자열, audit disclosure 필수 여부, 체인이 지원하는 사용자 privacy 정책과 disclosure 모드의 이름(supportedUserPolicies / supportedUserModes, 문자열)을 포함합니다. 외부 PrivacyOutputEffect의 userPrivacyPolicy / userDisclosureMode 필드는 숫자 uint32 코드이므로, 이 이름을 요청에 그대로 넣지 않습니다. circuitConfig()는 활성 회로 세트를 반환합니다. schemaVersion, activeSetId, 타원 곡선, manifest 파일명과 가용성, 생성 시각, 아티팩트 목록(verifying key / wasm 파일명, SHA-256, 환경 변수명), 각 회로의 verifying key 다이제스트를 고정한 PrivacyCircuitSetIdentity를 담습니다. 연결된 증명자가 체인과 일치하는지 확인하기 위해 클라이언트 시작 시 circuitConfig()를 한 번 읽습니다. disclosure 설정은 체인 업그레이드로 지원되는 정책 / 모드 enum이 확장될 수 있으므로 요청을 구성할 때 읽는 것이 좋습니다.리저브와 자산 메타데이터
reserve(string denom)는 지정한 표준 denom(테스트넷은 atokrw)에 대한 PrivacyReserve를 반환하며, 모듈 잔액, 총 입금액, 총 출금액, 예상 모듈 잔액, 불변성 플래그, 잉여 / 부족 금액을 포함합니다. assetByDenom(string canonicalDenom)과 assetByID(bytes32 assetId)는 모두 { canonicalDenom, assetId } 쌍과 mappingVersion을 담은 PrivacyAssetResponse를 반환합니다. 사람이 읽을 수 있는 denom을 체인 내부의 32바이트 자산 ID로, 또는 그 반대로 변환할 때 두 메서드를 사용합니다.Audit 키 조회
auditKey(uint64 epoch)는 특정 epoch에 대한 PrivacyAuditRecord를 반환합니다. 직렬화된 레코드, 저장소 키, 레코드를 생성한 상태 높이를 포함합니다. auditKeySchedule()은 activeEpoch, 다음 nextActivationHeight / nextEpoch, halted 플래그를 반환하며, 어느 auditKey epoch로 암호화할지 판단할 때 사용합니다. auditConfiguration()은 네트워크의 networkNonce, initialHeight, PrivacyCircuitSetIdentity를 반환합니다. 이 값을 클라이언트에 고정하고, 비공개 요청 도중 값이 바뀌면 전송을 거부합니다. 두 audit 키 조회는 저장소 읽기 전에 표준 필드 검증을 위해 400,640 gas를 사전 과금합니다.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 고려사항
view 메서드도 온체인에서 호출될 때는 gas를 소비합니다(예: Solidity 컨트랙트에서
staticcall). 오프체인 클라이언트의 eth_call 읽기만 무료입니다. privacyScan은 체인이 응답을 ABI struct로 매핑하기 전에 응답 크기 예산을 추가로 사전 과금합니다(바이트당 3 gas, summary와 output마다 할당). 더 좁은 outputLimit / eventLimit / maxEncodedBytes를 지정하면 이 요금이 낮아집니다. auditKey와 auditKeySchedule은 각각 표준 필드 재검증을 위해 400,640 gas를 사전 과금합니다.