Skip to content

Commit a99ff4c

Browse files
vmidyllicvmidyllic
authored
Merge pull request #235 from 0xPolygonID/circuits
circuits overview & linkedmultiquery additions
2 parents cedb876 + 79ce6c8 commit a99ff4c

File tree

3 files changed

+211
-1
lines changed

3 files changed

+211
-1
lines changed

‎docs/verifier/circuits.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
id: circuits
3+
title: "Circuits"
4+
sidebar_label: "Circuits"
5+
description: "Explore the essential Circom circuits used in Iden3’s decentralized identity protocol. Learn how state transitions, authentication, and advanced credential verification techniques work together for robust digital identity management."
6+
keywords:
7+
- iden3
8+
- circuits
9+
- decentralized identity
10+
- identity verification
11+
- circom
12+
- zkSNARKs
13+
- state transition
14+
- authentication
15+
- credential verification
16+
- merkle tree
17+
- on-chain
18+
- off-chain
19+
- digital identity
20+
- cryptography
21+
---
22+
23+
24+
25+
The following is the overview of the most important `circom` circuits used in Privado ID protocol and ecosystem. These circuits play a crucial role in enabling secure identity ownership, trustworthy credential verification, and efficient on-chain or off-chain checks.
26+
## 1. stateTransition
27+
28+
**Circuit Purpose:**
29+
Validates an identity state transition from an old user state to the new one, ensuring the identity owner is the one making the update.
30+
31+
**Usage Notes:**
32+
33+
- Used whenever an identity’s Claims Tree, Revocation Tree, or Roots Tree is updated (e.g., adding or revoking a claim).
34+
- Relies on the Prover’s signature to confirm ownership of the old state before finalizing the new state.
35+
- Typically verified on-chain via a `transitState` function, which updates the global identity mapping and GIST upon successful proof verification.
36+
37+
## 2. authV2
38+
39+
**Circuit Purpose:**
40+
Confirms that the Prover (identity holder) owns a specific identity by controlling a BabyJubJub private key and including its state in the GIST (global identity state tree) or being at genesis state.
41+
42+
**Usage Notes:**
43+
44+
- `authV2` is the standard circuit for proving an identity’s ownership with on-chain or off-chain identity state consistency checks.
45+
- It is a main circuit to be used in authentication and authorization flows in JWZ (JSON WEB Zero-Knowledge tokens).
46+
47+
## 3. credentialAtomicQueryMTPV2
48+
49+
**Circuit Purpose:**
50+
Proves that the Prover holds a valid credential (issued by an issuer) that satisfies a Verifier’s query. The credential's representation is stored in the issuer’s Claims Tree, and the circuit relies on:
51+
52+
- Checking that the core claim representation hash is included in this tree via a Merkle Tree Proof (MTP) approach.
53+
- Verifying the non-revocation of the credentials in the issuer’s Revocation Tree.
54+
- Checking the validity of the issuer's state and its existence in the state contract.
55+
- Ensuring that the Prover uses an identity that controls the credential subject identifier.
56+
- Supporting queries on any credential field, thanks to the unique JSON-LD merklization algorithm.
57+
58+
**Usage Notes:**
59+
60+
- Designed for off-chain verifications with atomic queries.
61+
62+
## 4. credentialAtomicQueryMTPV2Onchain
63+
64+
**Circuit Purpose:**
65+
Same as `credentialAtomicQueryMTPV2`, but with support for output optimizations, making it more efficient for on-chain use. **Note:** It does not support selective disclosure.
66+
67+
**Usage Notes:**
68+
69+
- Designed for on-chain verifiers.
70+
71+
## 5. credentialAtomicQuerySigV2
72+
73+
**Circuit Purpose:**
74+
Similar to `credentialAtomicQueryMTPV2` but for credentials that are signed by the issuer's BabyJubJub key rather than being included in the issuer’s Merkle Tree. It:
75+
76+
- Verifies the issuer’s signature over the core claim representation of a W3C credential (including the Merkle root of the JSON-LD document).
77+
- Checks that the BabyJubJub key is included in the issuer state (which is either at genesis or published on-chain) and that key is not revoked in the latest issuer state.
78+
79+
**Usage Notes:**
80+
81+
- Suitable when the issuer issues credentials in a purely signature-based manner, rather than including them in state and performing state transitions.
82+
83+
## 6. credentialAtomicQuerySigV2Onchain
84+
85+
**Circuit Purpose:**
86+
Builds on `credentialAtomicQuerySigV2` by adding on-chain verifier support. It:
87+
88+
- Checks that a credential signed by the issuer meets the verifier’s query.
89+
- Verifies that the Prover controls the identity to which the credential belongs.
90+
- Ensures that the credential is not expired or revoked.
91+
- Computes a hash of query-related inputs (such as schema, operator, value, etc.) for cheaper on-chain verification of the proof.
92+
93+
**Usage Notes:**
94+
95+
- Ideal for smart contract verifiers that need to confirm a user’s credentials without relying on the issuer’s Merkle tree (i.e., signature-based issuance).
96+
- The circuit’s proof can be submitted to a contract function (often verifying via an on-chain zkSNARK), reducing gas costs by exposing fewer public inputs.
97+
98+
## 7. credentialAtomicQueryV3-beta.1
99+
100+
**Circuit Purpose:**
101+
An enhanced version of `credentialAtomicQueryV2` that supports:
102+
103+
- Optional revocation checks.
104+
- Credential expiration checks.
105+
- Selective disclosure of specific credential fields.
106+
- Computation of nullifiers for one-time or limited-use proofs.
107+
108+
This circuit combines the verification of BabyJubJub signatures and Iden3SparseMerkleTreeProof in a single circuit, ideal for advanced credential scenarios where flexible issuance (signature- or Merkle-based) and partial data disclosure are required.
109+
110+
- **Supports Nullifiers:** The proof can only be used once for the same verifier, credential, user identity, and nullifier session id.
111+
- Supports linkage between proofs.
112+
113+
**Usage Notes:**
114+
115+
- Supports more comparison operators.
116+
- Can be integrated with on-chain or off-chain verifiers; if on-chain, the V3OnChain variant is typically used to reduce public inputs.
117+
118+
## 8. credentialAtomicQueryV3Onchain-beta.1
119+
120+
**Circuit Purpose:**
121+
Designed for smart contract verifiers, this circuit builds on `credentialAtomicQueryV3` by adding two major enhancements:
122+
123+
1. It can check that the Prover controls the identity, similar to how `authV2` works (if authentication is enabled).
124+
2. It computes a hash of all query-related inputs (e.g., `claimSchema`, `slotIndex`, `operator`, `claimPathKey`, `claimPathNotExists`, and any field values) so they don’t need to be exposed individually as public inputs on-chain.
125+
126+
**Usage Notes:**
127+
128+
- Ideal for on-chain verification where minimizing public inputs is crucial to reduce gas costs.
129+
- Retains all capabilities of `credentialAtomicQueryV3`, such as selective disclosure, expiration checks, and optional revocation checks.
130+
- If authentication is enabled, the Prover must demonstrate identity ownership in the same way as `authV2` before the proof is accepted.
131+
- The reduced set of public inputs lowers the overhead for smart contract verification, making it more efficient for complex or frequent credential proofs on Ethereum.
132+
133+
## 9. linkedMultiQuery10-beta.1
134+
135+
**Circuit Purpose:**
136+
Generates a single proof capable of verifying up to **10 parameters** in a single query. This allows multiple credential attributes or conditions (e.g., age, location, graduation) to be checked together, simplifying and streamlining multi-parameter verifications.
137+
138+
**Usage Notes:**
139+
140+
- Batching multiple parameter checks into one proof reduces overhead and improves efficiency compared to issuing separate queries.
141+
- Ideal for composite credential checks (e.g., age, residence, and education) in a single proof step.
142+
- Should be used by verifiers **only in conjunction with** the `credentialAtomicV3` circuit to ensure all checks (including signatures) are properly performed.
143+
- Supports integration with both on-chain and off-chain verifiers, providing flexibility for a range of identity and credential scenarios.
144+
145+
## Source Code:
146+
147+
[Circuits Github link](https://github.com/iden3/circuits)
148+
149+
## Public Verification Keys
150+
151+
All public verification keys for the Iden3 circuits, generated following the [trusted setup](https://github.com/0xPolygonID/phase2ceremony), are available at [this link](https://github.com/0xPolygonID/verifier-backend/tree/develop/keys). This resource ensures transparency and makes it easier to verify proofs.

‎docs/verifier/verification-library/zk-query-language.md‎

Lines changed: 58 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -980,8 +980,65 @@ In the example below, the verifier requests two different proof queries in the s
980980
}
981981
```
982982

983+
## Multi query from a single Credential
984+
985+
To efficiently query multiple attributes from a single credential, use the [LinkedMultiQuery Circuit](./../circuits#9-linkedmultiquery10circom). It supports up to 10 queries in a single proof response, reducing redundancy while ensuring security.
986+
987+
The LinkedMultiQuery Circuit verifies multiple field-based predicate requests, while the V3 Atomic Query Circuit validates credential integrity (signature, Merkle proof, non-revocation, etc.). Both proofs must be from the same credential and share the same groupId to ensure validity. Verification is only valid when both proofs pass.
988+
989+
** Example Query**
990+
991+
This request includes a LinkedMultiQuery (for multiple fields) and a V3 Atomic Query (for credential validation).
992+
993+
994+
```json
995+
{
996+
"id": "f8aee09d-f592-4fcc-8d2a-8938aa26676c",
997+
"typ": "application/iden3comm-plain-json",
998+
"type": "https://iden3-communication.io/authorization/1.0/request",
999+
"thid": "f8aee09d-f592-4fcc-8d2a-8938aa26676c",
1000+
"from": "did:iden3:polygon:amoy:2qFroxB5kwgCxgVrNGUM6EW3khJgCdHHnKTr3VnTcp",
1001+
"body": {
1002+
"callbackUrl": "https://test.com/callback",
1003+
"reason": "Employee verification",
1004+
"message": "test message",
1005+
"scope": [
1006+
{
1007+
"id": "1",
1008+
"circuitId": "linkedMultiQuery10-beta.1",
1009+
"query": {
1010+
"groupId": 1,
1011+
"proofType": "BJJSignature",
1012+
"allowedIssuers": ["*"],
1013+
"type": "KYCEmployee",
1014+
"context": "https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v101.json-ld",
1015+
"credentialSubject": {
1016+
"documentType": { "$eq": 1 },
1017+
"position": { "$eq": "boss", "$ne": "employee" }
1018+
}
1019+
}
1020+
},
1021+
{
1022+
"id": "2",
1023+
"circuitId": "credentialAtomicQueryV3-beta.1",
1024+
"query": {
1025+
"groupId": 1,
1026+
"proofType": "BJJSignature",
1027+
"allowedIssuers": ["*"],
1028+
"type": "KYCEmployee",
1029+
"context": "https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v101.json-ld",
1030+
"credentialSubject": {
1031+
"hireDate": { "$eq": "2023-12-11" }
1032+
}
1033+
},
1034+
}
1035+
]
1036+
}
1037+
}
1038+
```
1039+
9831040
:::warning "Allowed Issuers"
9841041

9851042
When we use `*` in the "allowed issuers" segment (`allowedIssuers: ['*']`), we mean that we accept any entity that might have provided the credential. Even though this seems to be convenient for testing purposes, it may also be considered risky. Applying due diligence by **actually choosing trusted specific issuers** should be the best approach. Only in rare cases, a verifier would accept any issuer, so we advise not to use `*`.
9861043

987-
:::
1044+
:::

‎sidebars.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,8 +154,10 @@ module.exports = {
154154
},
155155
"verifier/query-builder",
156156
"verifier/verification-library/zk-query-language",
157+
"verifier/circuits",
157158
"verifier/v3-circuit",
158159

160+
159161
],
160162
},
161163
{

0 commit comments

Comments
 (0)