Privacy Audit Authorization and Disclosure

mechanism privacy

Every shielded request now carries an audit envelope and per-output disclosure metadata — the chain pins the active audit key and circuit set, and clients discover both through IPrivacy view methods.

The IPrivacy state-changing requests (deposit, transfer, withdraw, and their batch and *WithAuthorization variants) are now structured around two reusable payloads: a PrivacyAuditAuthorization { keyId, epoch, envelope } carried on the request, and a PrivacyOutputEffect per output that carries the commitment, ciphertext, view tag, and a bundle of disclosure fields (userPrivacyPolicy, userDisclosureMode, userDisclosureDigest, userDisclosureTargetPubkey, userDisclosurePayload, selfFullDisclosureDigest, selfViewDisclosurePayload). The chain validates the audit envelope against the audit-key record for the named epoch, and validates each output's disclosure fields against the chain-wide PrivacyDisclosureConfig.

Audit authorization on every request

PrivacyAuditAuthorization names the keyId (the audit-authority identifier), the epoch of the key under which the envelope was produced, and the serialized envelope itself. The chain checks the envelope against the audit key registered for that epoch — the record the auditKey(epoch) view returns — and rejects a request whose envelope does not verify against it. (Calling the auditKey view yourself pre-charges 400,640 gas for canonical-field revalidation; that cost is the view's, not every request's.) To choose the epoch, read auditKeySchedule() first: activeEpoch is the one the chain will accept, nextActivationHeight / nextEpoch warn you when it is about to rotate, and halted means the chain is not currently accepting shielded requests at all.
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 schedule = await publicClient.readContract({
  address: iPrivacyAddress,
  abi: iPrivacyAbi,
  functionName: "auditKeySchedule",
});
if (schedule.halted) throw new Error("shielded surface is halted");

const audit = {
  keyId: "0x" as const,            // keyId bytes as returned by your audit provider
  epoch: schedule.activeEpoch,
  envelope: "0x" as const,         // serialized envelope your prover produced
};

Output disclosure metadata

Every outbound note is a PrivacyOutputEffect. Alongside the cryptographic fields (commitment, ciphertext, viewTag) it carries five user-facing disclosure fields and two self-view fields. userPrivacyPolicy (uint32) and userDisclosureMode (uint32) pick a policy / mode pair that the chain declares in disclosureConfig().supportedUserPolicies / supportedUserModes; the three userDisclosure* fields and the two self* fields carry the actual payload for whichever policy / mode the output chose. An output that uses the all-private sentinel must use mode NONE and leave the digest / target / payload at zero; an output that discloses to a specific target pubkey must fill userDisclosureTargetPubkey.

Why clients read disclosureConfig and circuitConfig

disclosureConfig() returns the payloadVersion string (which clients must match against the payloadVersion on a scanned output) plus the enum spaces for userPrivacyPolicy / userDisclosureMode. circuitConfig() returns the activeSetId, the elliptic curve, the manifest filename, the artifact list (verifying key / wasm filenames and their SHA-256), and the PrivacyCircuitSetIdentity that pins each circuit's verifying-key digest. Read both once at startup: the wallet refuses to build a proof under a circuit set that the chain does not advertise, and pins activeSetId to detect a mid-flight circuit rotation. auditConfiguration() returns the chain's networkNonce, initialHeight, and the same PrivacyCircuitSetIdentity — treat the nonce as a fingerprint of the deployed chain and refuse to send a request if it changes between the pre-flight read and the submit.
const dc = await publicClient.readContract({
  address: iPrivacyAddress,
  abi: iPrivacyAbi,
  functionName: "disclosureConfig",
});
console.log(dc.payloadVersion, dc.auditDisclosureRequired);
console.log("policies:", dc.supportedUserPolicies);
console.log("modes:   ", dc.supportedUserModes);

const cc = await publicClient.readContract({
  address: iPrivacyAddress,
  abi: iPrivacyAbi,
  functionName: "circuitConfig",
});
console.log("active circuit set:", cc.activeSetId, cc.curve);

How audit metadata flows through a scanned output

A note the chain delivers via privacyScan carries the audit / circuit identity used when it was created — circuitSetId, payloadVersion, scanSchemaVersion, auditKeyId, auditKeyEpoch, auditTargetPubkey, plus fullDisclosureDigest, auditDisclosurePayload, and selfViewDisclosurePayload. A wallet should match the output's circuitSetId and payloadVersion against the values it pinned from circuitConfig() and disclosureConfig() before decrypting. If they drift, the chain has rotated; re-read the config views before building any new request.

What privacyScan reports when a stored record is malformed

These are not errors a request can trigger: privacyScan validates each stored record before returning it and fails on one that breaks these shapes. Such a failure arrives as the shared typed error QueryFailed("privacyScan", reason), and reason contains one of these strings, usually behind context such as privacy scan output N does not match summary/state: …: "privacy scan all-private disclosure must use mode NONE and zero digest/target/payload", "privacy scan deposit output must use encrypted_note and an empty ciphertext/view tag", "privacy scan output must use exact zero disclosure sentinels", "undisclosed amount must use zero sentinel", "undisclosed recipient keys must use zero sentinels", "undisclosed sender keys must use zero sentinels", and, for audit identity mismatches, "privacy scan output audit identity does not match summary". Decode QueryFailed with the IPrivacy ABI and show reason as text; a scanner that hits one cannot trust that page and should report it rather than skip the output.
ESC
Type to search