프라이버시 프리컴파일 조회 메서드

component privacy

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를 사전 과금합니다.
ESC
검색어를 입력하세요