Smart Contract Reference

The Passport smart contract stack allows developers to pull Stamp data directly from the blockchain rather than having to make requests to a centralized server. The smart contract stack is built on top of the Ethereum Attestation Service (EAS).

This page will outline the Passport XYZ smart contract stack and provide all the deployment details you need to integrate onchain Stamp data in your app.

This page is broken into two sections:

• How Passport adds metadata to the blockchain
• How to query for onchain Passport data

You can always chat in our Telegram developer support channel (opens in a new tab) if you have questions about the Passport smart contracts.

How Passport adds data to the blockchain

We will not cover this in depth, as it is already documented in our GitHub docs (opens in a new tab).

Passport uses a combination of private Passport smart contracts and EAS contracts to create Passport attestations and mint them to the blockchain. This process is triggered when a user opts-in to minting their Passport’s score and Stamps onchain via the Passport app, and ends with two attestations being minted on EAS that can be accessed by third-party developers.

During this process, the user is charged a $2 mint fee to write the attestations onchain.

How to query for onchain Passport data

Passport XYZ, EAS, and Verax have created several smart contracts that can be used to retrieve users’ Passport attestations. There are a couple of different flows you can follow, but we strongly recommend using the GitcoinDecoder contract.

Available flows:

• [Recommended] GitcoinPassportDecoder flow
• GitcoinResolver >> EAS/Verax flow

GitcoinPassportDecoder

The decoder is a greatly simplified version of the alternative flow, and delivers all data you would need to integrate with Passport in a human-readable format.

Here is a rundown of the GitcoinPassportDecoder flow:

1. A request is sent to the GitcoinPassportDecoder contract, passing the user address and method associated with the data you’d like to receive.
2. The smart contract delivers the data associated with the user and method.
3. Your integration then either gates access to just those users over a specified score threshold, or displays the Passport data to help prove a users reputation.

GitHub links

• Smart contract: https://github.com/passportxyz/eas-proxy/blob/main/contracts/GitcoinPassportDecoder.sol (opens in a new tab)
• Interface contract: https://github.com/passportxyz/eas-proxy/blob/main/contracts/IGitcoinPassportDecoder.sol (opens in a new tab)
• ABI: https://github.com/passportxyz/eas-proxy/blob/main/deployments/abi/GitcoinPassportDecoder.json (opens in a new tab)

Decoder contract addresses

The decoder is currently deployed to the following networks:

You can learn more about working with testnets via our guide on Test Mode.

Available methods

Alternative method

This alternative flow represents a subset of the tasks that the decoder contract automatically works thorugh, which is why we don’t recommend using it. It is, however, useful to understand.

If you decide to go this route, you will follow this flow:

1. A request is sent to the Resolver contract passing the user address
2. The Resolver contract returns a UID
3. The UID is passed to the EAS contract
4. The EAS contract returns an encoded Attestation
5. Decode the Attestation and extracts the Stamp data

GitcoinResolver contract

The GitcoinResolver contract is used to request a UID for an address.

The Attestations are stored in a mapping, where the Attestation is stored as raw bytes (allowing Attestations with any schema to be included).

In order to ensure the integrity of the data that the contract stores, the resolver smart contract shall only validate and store date from trusted sources:

• a trusted EAS contract
• a trusted Attester

EAS contract

The EAS contract is where you can pass the UIDreceived from the GitcoinResolver contract to receive an Attestation.

Alternative flow contract addresses

Arbitrum

The Arbitrum chain ID is 42161 (opens in a new tab).

EAS Schema

Linea

The Linea chain ID is 59144 (opens in a new tab).

Verax schema

EAS Schema

Optimism

The Optimism chain ID is 10 (opens in a new tab).

Gitcoin

EAS Schema

Optimism Sepolia

The Optimism Sepolia chain ID is 11155420 (opens in a new tab).

Gitcoin

EAS Schema

Scroll

The Scroll chain ID is 534352 (opens in a new tab).

Gitcoin

EAS Schema

Scroll Sepolia

The Scroll chain ID is 534351 (opens in a new tab).

Gitcoin

EAS Schema

Shape

The Shape chain ID is 360 (opens in a new tab).

Gitcoin

EAS Schema

Shape Sepolia

The Shape chain ID is 11011 (opens in a new tab).

Gitcoin

EAS Schema

ZkSync Era

The ZkSync chain ID is 324 (opens in a new tab).

EAS Schema

ZkSync Sepolia

The ZkSync chain ID is 300 (opens in a new tab).

Attestation Schemas

We discuss the Passport (Stamp) and score schemas in our Attestation schema guide.