From 2be56c39023bb43a8b0ea71ce5b509ade61176cf Mon Sep 17 00:00:00 2001 From: Martin Saporiti Date: Wed, 10 Jan 2024 09:20:38 -0300 Subject: [PATCH 1/2] chore: add verifier backend api --- docs/verifier/verifier-backend.md | 185 +++++++++++++++++++++++++++++ sidebars.js | 1 + static/img/verifier-backend-f1.svg | 21 ++++ static/img/verifier-backend-f2.svg | 21 ++++ 4 files changed, 228 insertions(+) create mode 100644 docs/verifier/verifier-backend.md create mode 100644 static/img/verifier-backend-f1.svg create mode 100644 static/img/verifier-backend-f2.svg diff --git a/docs/verifier/verifier-backend.md b/docs/verifier/verifier-backend.md new file mode 100644 index 00000000..0aca61d1 --- /dev/null +++ b/docs/verifier/verifier-backend.md @@ -0,0 +1,185 @@ +--- +id: verifier-backend +title: Verifier Backend API +sidebar_label: Verifier Backend API +description: Verifier Backend API. +keywords: + - docs + - polygon id + - ID holder + - verifier +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +The [Verifier Backend](https://github.com/0xPolygonID/verifier-backend) project is a JSON API that enables [Off Chain Verifications](verification-library/verification-api-guide.md) of zero knowledge proofs for verifiable credentials. Within the trust triangle, it serves as the verifier. + +It is built using libraries developed by the iden3 protocol team. Below, we'll explain how to install it using Docker and how it can be used to perform zero knowledge proofs. + +You can try our [Verifier Backend API](https://verifier-backend.polygonid.me/) running. + +## Local Installation +To run the verifier backend with Docker, after cloning the code from the repository, simply follow these steps: + +1. Create a file named `resolvers_settings.yaml`, using the `resolvers_settings_samples.yaml` file as a base. In this file, configure only your RPC for the Polygon Mumbai and Main networks, i.e., the two variables named `networkURL`. +```yaml +polygon: + mumbai: + contractAddress: 0x134B1BE34911E39A8397ec6289782989729807a4 + networkURL: https://polygon-mumbai.g.alchemy.com/v2/xaP2_t9EUM2VYDgCgMI0k9KqDyJPvZ89 + main: + contractAddress: 0x624ce98D2d27b20b8f8d521723Df8fC4db71D79D + networkURL: https://polygon-mainnet.g.alchemy.com/v2/X2HI8cErI_6RYdUVS0SvSfCZCYDCSrzt +``` + +2. Create a .env file (you can use the .env-sample file as a base). +```shell +VERIFIER_BACKEND_HOST=https://your-public-ip +VERIFIER_BACKEND_PORT=3010 +VERIFIER_BACKEND_KEY_DIR=./keys +VERIFIER_IPFS_URL=https://gateway.pinata.cloud +VERIFIER_BACKEND_MUMBAI_SENDER_DID=did:polygonid:polygon:mumbai:2qH7TstpRRJHXNN4o49Fu9H2Qismku8hQeUxDVrjqT +VERIFIER_BACKEND_MAIN_SENDER_DID=did:polygonid:polygon:main:2q4Q7F7tM1xpwUTgWivb6TgKX3vWirsE3mqymuYjVv +VERIFIER_BACKEND_RESOLVER_SETTINGS_PATH=./resolvers_settings.yaml +``` +From this file, it's important and necessary to modify the following variable: +```shell +VERIFIER_BACKEND_HOST: must be the public IP of the machine where the verifier backend is running. +``` + +3. Run `make run`: This command will create a Docker image and start a Docker container listening on port 3010. The public IP configured in the previous step should point to that port. + +If everything went well, you will be able to see the API documentation at: `https://your-public-ip/` + + +### Alternative 1 +The following image shows the simplest flow to generate a QR code to request a ZK Proof as a verifier: + +
+ +
+ + +The endpoint `/sign-in` allows creating that QR code and configuring the backend to later validate the proof. A possible body for this endpoint could be the following: + +```json +{ + "chainID": "80001", + "circuitID": "credentialAtomicQuerySigV2", + "skipClaimRevocationCheck": false, + "query": { + "context": "https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v3.json-ld", + "allowedIssuers": ["*"], + "type": "KYCAgeCredential", + "credentialSubject": { + "birthday": { + "$eq": 19960424 + } + } + } +} +``` +Keep in mind that: + +- the `chainID` field can be 80001 for Mumbai or 137 for the Mainnet. +- the `circuitID` field can be `credentialAtomicQuerySigV2` (for signature proofs) or `credentialAtomicQueryMTPV2` (for MTP proofs). + +This endpoint will respond with a similar response to the following: + +```json +{ + "qrCode": { + "body": { + "callbackUrl": "https://your-public-ip/callback?sessionID=975903", + "reason": "test flow", + "scope": [ + { + "circuitId": "credentialAtomicQuerySigV2", + "id": 1, + "query": { + "allowedIssuers": [ + "*" + ], + "context": "https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v3.json-ld", + "credentialSubject": { + "birthday": { + "$eq": 19960424 + } + }, + "skipClaimRevocationCheck": false, + "type": "KYCAgeCredential" + } + } + ] + }, + "from": "did:polygonid:polygon:mumbai:2qH7TstpRRJHXNN4o49Fu9H2Qismku8hQeUxDVrjqT", + "id": "7f38a193-0918-4a48-9fac-36adfdb8b542", + "thid": "7f38a193-0918-4a48-9fac-36adfdb8b542", + "typ": "application/iden3comm-plain-json", + "type": "https://iden3-communication.io/authorization/1.0/request" + }, + "sessionID": 975903 +} +``` + + +The value of the `qrCode` field is the one that should be displayed as a QR code to be scanned by the Polygon ID wallet. + +The `sessionID` should be used to check the status of the proof. To query the status of the proof, i.e., whether it was valid or not, you should call the endpoint `/status?sessionID=975903`. + +### Alternative 2 - QR Store +Flow 2 allows the generation of QR codes that are sometimes more comfortable to read for certain mobile phones. + + +
+ +
+ + +In this case, after calling the '/sign-in' endpoint, you should call the '/qr-store' endpoint using as a body the response obtained from the '/sign-in' endpoint in the 'qrCode' field. + +For example, + +```json +{ + "body": { + "callbackUrl": "https://your-public-ip/callback?sessionID=975903", + "reason": "test flow", + "scope": [ + { + "circuitId": "credentialAtomicQuerySigV2", + "id": 1, + "query": { + "allowedIssuers": [ + "*" + ], + "context": "https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v3.json-ld", + "credentialSubject": { + "birthday": { + "$eq": 19791109 + } + }, + "type": "KYCAgeCredential" + } + } + ] + }, + "from": "did:polygonid:polygon:mumbai:2qH7TstpRRJHXNN4o49Fu9H2Qismku8hQeUxDVrjqT", + "id": "7f38a193-0918-4a48-9fac-36adfdb8b542", + "thid": "7f38a193-0918-4a48-9fac-36adfdb8b542", + "typ": "application/iden3comm-plain-json", + "type": "https://iden3-communication.io/authorization/1.0/request" +} +``` + +response from the '/qr-store' endpoint will be something similar to the following: + +```text +iden3comm://?request_uri=https://your-public-ip/qr-store?id=9d5beb41-3108-4341-a51c-984de762145e +``` + +This response is the one you should then display as a QR code. + + +### Some extra commands +To stop the verifier backend, you can execute `make stop`. The preceding command halts the Docker container. If you want to restart the verifier backend, for instance, if you updated the code, you can execute `make restart`. \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 0d3fe829..efa813b3 100644 --- a/sidebars.js +++ b/sidebars.js @@ -136,6 +136,7 @@ module.exports = { "verifier/verification-library/config", "verifier/verification-library/request-api", "verifier/verification-library/verification-api", + "verifier/verifier-backend", ], }, "verifier/verification-library/verifier-setup", diff --git a/static/img/verifier-backend-f1.svg b/static/img/verifier-backend-f1.svg new file mode 100644 index 00000000..1cd07c81 --- /dev/null +++ b/static/img/verifier-backend-f1.svg @@ -0,0 +1,21 @@ + + + + + + + + Verifier Backend/sign-inQR Code + session ID/status?sessionID=6736JWZ/callbackexpose QR CodePolygon ID Walletwith the ZK Proof \ No newline at end of file diff --git a/static/img/verifier-backend-f2.svg b/static/img/verifier-backend-f2.svg new file mode 100644 index 00000000..c28bb74d --- /dev/null +++ b/static/img/verifier-backend-f2.svg @@ -0,0 +1,21 @@ + + + + + + + + Verifier Backend/sign-inQR Code + session ID/status?sessionID=6736JWZ/callbackPolygon ID Walletwith the ZK Proof/qr-storeQR Codeexpose QR Codetiny QR Code \ No newline at end of file From d5066826ff36623e1834bb2e1c18cc64fae5d4bf Mon Sep 17 00:00:00 2001 From: Martin Saporiti Date: Tue, 16 Jan 2024 08:26:21 -0300 Subject: [PATCH 2/2] chore: update alchemy urls --- docs/verifier/verifier-backend.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/verifier/verifier-backend.md b/docs/verifier/verifier-backend.md index 0aca61d1..6c484cfc 100644 --- a/docs/verifier/verifier-backend.md +++ b/docs/verifier/verifier-backend.md @@ -26,10 +26,10 @@ To run the verifier backend with Docker, after cloning the code from the reposit polygon: mumbai: contractAddress: 0x134B1BE34911E39A8397ec6289782989729807a4 - networkURL: https://polygon-mumbai.g.alchemy.com/v2/xaP2_t9EUM2VYDgCgMI0k9KqDyJPvZ89 + networkURL: https://polygon-mumbai.g.alchemy.com/v2/xa main: contractAddress: 0x624ce98D2d27b20b8f8d521723Df8fC4db71D79D - networkURL: https://polygon-mainnet.g.alchemy.com/v2/X2HI8cErI_6RYdUVS0SvSfCZCYDCSrzt + networkURL: https://polygon-mainnet.g.alchemy.com/v2/X2 ``` 2. Create a .env file (you can use the .env-sample file as a base).