> For the complete documentation index, see [llms.txt](https://docs.zk.me/hub/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zk.me/hub/how-built/credential-sys/selective-disclosure.md). # Selective Disclosure Selective disclosure is a core privacy-preserving feature within the zkMe Credential System. It allows a Holder to share only specific attributes from a credential with an AI Agent or Verifier, rather than revealing the entire document or data payload. This capability is essential for minimizing data exposure and adhering to the principle of least privilege in the agent economy. ## The Privacy Problem In traditional verification systems, proving eligibility often requires over-sharing. For example, proving that a user is over 18 years old typically involves presenting a full ID document, which unnecessarily exposes the user’s exact date of birth, full name, address, and document number. When AI agents act on behalf of users, handing over complete credentials to every third-party service or agent creates an unacceptable attack surface. The agent only needs to know the specific data point required to execute its task. Selective disclosure solves this by enabling the Holder to generate a zero-knowledge proof that attests only to the required condition or reveals only the requested field, without exposing the underlying raw data. *** ## Mechanism and Implementation The system utilizes the latest zero-knowledge circuit architecture to enable selective disclosure. When an AI agent or Verifier needs to request a specific data field, they construct a query using the `SD` operator (operator code `16`). The circuit evaluates the credential, validates its cryptographic integrity, and extracts the requested field value into a designated public output. ### The Verification Flow 1. **Query Construction:** The Verifier (or the Agent acting as a verifier) constructs a query using the ZK Query Language. To request selective disclosure, the Verifier sends an empty array `[]` as the value for the specific field they wish to extract, and sets the operator to `$sd`. 2. **Circuit Processing:** The on-chain verification circuit processes this request. When the `SD` operator is triggered, the circuit evaluates the credential, validates its cryptographic integrity, and extracts the requested field value. It places this selectively disclosed value into a specific public input designated as `operatorOutput`. 3. **On-Chain Retrieval:** The verification smart contract identifies that a selective disclosure operation occurred (by checking if `operator == 16`) and extracts the `operatorOutput`. This value is then made available for the business logic or the requesting AI agent to consume. ### Query Example The following JSON illustrates a selective disclosure query where an AI agent requests the Holder’s country code from a Proof-of-Citizenship credential. The `operator` is set to `$sd` and the `values` array is left empty, because selective disclosure does not perform a comparison; it simply extracts and reveals the targeted field. ```json { "credentialSchema": "urn:schema:proof-of-citizenship-v1", "claim_proofs": [ { "claim": "countryCode", "operator": "$sd", "value": [] } ] } ``` For more complex scenarios, an agent can combine selective disclosure with conditional operators in a single batch query. For example, the following query simultaneously proves that the Holder is over 18 (without revealing the exact date of birth) and selectively discloses their country code: ```json { "credentialSchema": "urn:schema:kyc-v1", "claim_proofs": [ { "claim": "age", "operator": ">=", "value": 18 }, { "claim": "countryCode", "operator": "$sd", "value": [] } ] } ``` After on-chain verification, the agent retrieves the disclosed country code through the contract’s storage interface: ```solidity // Retrieve the selectively disclosed value after proof verification uint256 disclosedCountryCode = zkpVerifier.getProofStorageField( holderAddress, requestId, "operatorOutput" ); ``` This approach allows AI agents to obtain precise, verified data points (like a specific nationality or a verified age range) directly from a comprehensive credential without accessing the entire data structure. *** ## Enhanced Query Operators To support complex decision-making by AI agents, the zero-knowledge circuit supports 14 distinct operators that allow for nuanced data filtering and logical conditions. These operators enable agents to execute sophisticated logic, such as multi-interval precise matching, by combining different conditions to filter users based on complex criteria before executing a transaction. ### Standard Comparison Operators The following operators provide conventional comparison and set-membership logic. They behave identically to their counterparts in standard query languages.
OperatorCodeDescription
NOOP0Proof of credential issuance without specific condition checks. The SDK clears query values for this operation.
EQ1Strict equality match.
LT2Less than the specified value.
GT3Greater than the specified value.
IN4Value exists within a specified array of acceptable values.
NIN5Value does not exist within a specified array.
NE6Not equal to the specified value.
LTE7Less than or equal to the specified value.
GTE8Greater than or equal to the specified value.
BETWEEN9Value falls within a specified numerical range (inclusive).
NONBETWEEN10Value falls strictly outside a specified numerical range.
EXISTS11Verifies the presence of an optional field within the credential schema, without revealing its value.
### Privacy-Specific Operators These two operators are unique to the zkMe circuit architecture and serve specialized privacy and security functions.
OperatorCodeDescription
SD16Selective Disclosure. Extracts and reveals the exact field value into the operatorOutput public signal. The Verifier receives the raw value of the targeted field, but no other fields from the credential are exposed.
NULLIFY17Nullifier Generation. Produces a deterministic, one-way hash that serves as a unique anonymous identifier for the user within a specific session context. Used for anti-Sybil enforcement. See Anti-Sybil Mechanisms for details.
### Gas Optimization The on-chain verification process is highly optimized for gas efficiency. It utilizes a `circuitQueryHash` to compress public inputs. During on-chain verification, the contract compares the `circuitQueryHash` (provided as a public input from the proof) with the `queryHash` derived from the request data: ```solidity // On-chain gas optimization via hash comparison require( pubSignals.circuitQueryHash == credAtomicQuery.queryHash, "Query hash does not match the requested one" ); ``` This cryptographic compression significantly reduces the gas costs associated with verifying complex, multi-operator queries on EVM-compatible chains. Instead of passing every query parameter as a separate public input (which increases calldata and verification cost linearly), the entire query specification is compressed into a single 256-bit hash. The circuit proves internally that the hash was computed correctly from the actual query parameters, while the contract only needs to verify this single value against the expected hash. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.zk.me/hub/how-built/credential-sys/selective-disclosure.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.