Skip to main content

Tutorial

Currently, we have two approaches to issuing on-chain credentials: on-chain merklized issuer and on-chain non-merklized issuer. The difference between these two approaches:

  1. The on-chain merklized issuer calculates the Merkle root for a credential on the backend and stores the core claim of the credential on-chain using a smart contract, because merklization process is too expensive to do in a smart contract by the user. Credential data and metadata can stay private on issuer side and only hash of the credential will be published on chain. We can think of it as a centralized issuer with the ability to store trees on the blockchain.

  2. The on-chain non-merklized issuer can use information from the blockchain (such as balance, token ownership, etc.) to issue a credential directly on the blockchain. This approach is decentralized and trustless - no need to trust an issuer to act honestly, because it's enforced by the smart contract and auditable on chain. But it comes with a few limitations: max 4 data fields in the credential and data is public. More about non-merklized credentials.

This guide presents an example of how to use the on-chain merklized issuer. We created a small application, where we communicate with Metamask to retrieve the user's balance and a claim about this balance is generated via the on-chain issuer. In this case, the credential will be created locally and stored to on-chain issuer.

There are two main components in this application:

  1. On-chain merklized issuer (demo|contract)
  2. Front-end component for communication with Metamask

Requirements:​

  1. Node js => 18.x
  2. Go => 1.20.x
  3. npm => 9.x.x
  4. docker => 20.x
  5. docker-compose => 2.23.x
  6. Polygon ID wallet app
  7. Ngrok

How to run the On-chain Issuer​

  1. Clone this repository:

    git clone https://github.com/0xPolygonID/onchain-merklized-issuer-demo

  2. Deploy an on-chain merklized issuer contract. You can use this sample or create your own smart contract with custom logic.

    Clone smart contracts repository:

    git clone https://github.com/0xPolygonID/contracts.git

    Deploy Identity Example contract:

    export AMOY_PRIVATE_KEY={private_key} && \
    export AMOY_RPC_URL={rpc_url} && \
    npx hardhat run scripts/deployIdentityExample.ts --network amoy
note

You can find more information on how to deploy a smart contract using Hardhat in this readme.

  1. Use the utility to calculate the issuerDID from the smart contract address:

    go run utils/convertor.go --contract_address=<ADDRESS_OF_IDENTITY_DEPLOYED_CONTRACT>

  2. Run ngrok on 8080 port.

    ngrok http 8080

  3. Fill the .env config file with the proper variables:

SUPPORTED_RPC="80002=<RPC_POLYGON_AMOY>"
ISSUERS_PRIVATE_KEY="<ISSUER_DID>=<PRIVATE_KEY_OF_THE_CONTRACT_DEPLOYER>"
EXTERNAL_HOST="<NGROK_URL>"
SUPPORTED_STATE_CONTRACTS="80002=0x1a4cC30f2aA0377b0c3bc9848766D90cb4404124"

  1. Run docker-compose:

    docker-compose build
    docker-compose up -d

  2. Go to: http://localhost:3000

Don't forget to download and install the Polygon ID wallet app before you go the next steps.

Issue and fetch credential​

  1. Open http://localhost:3000.

  2. Select an issuer:

  1. Scan the QR code with your Polygon ID wallet app and follow the instructions on the application.
  1. You will see your DID and now you can connect to MetaMask. Follow the flow on the MetaMask app.
  1. The on-chain issuer application will now display your account. You can get your balance in gwei.
  1. The account balance will be shown in gwei together with some other information about the claim.
  1. Clicking on Get Claim will finally lead to the QR Code used to fetch the credential with MTP proof. Here we are making a request to the on-chain issuer node. This node then saves this claim in a contract address. Scan it with the Polygon ID wallet.
  1. Clicking on Accept should add the credential to the mobile app.

Here is the credential on the mobile app:

Use already deployed demo​

You can use already deployed demo: https://onchain-merklized-issuer-demo.polygonid.me

How to verify the balance claim​

  1. Visit the Query builder website.

  2. You now need to define the query.

    Here is an example:

  3. Click Create Query. Now select the Network as Polygon Amoy (testnet) and click Test query which should result with a QR code. Scan and follow the instructions on the mobile app.

  1. Click on Approve. After which, the process of generating the proof is starts:

5.Finally, the proof is generated. The verifier will check the revocation status and some additional information. The proof is then sent and validated by the verifier. You will receive the following response on the Query builder website