Building with Passport
Smart Contracts
Contract reference

Smart Contract Reference

The Gitcoin 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 Gitcoin Passport 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:

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

How Gitcoin adds Passport 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).

Gitcoin 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

Gitcoin Passport, 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:

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

Decoder contract addresses

The decoder is currently deployed to the following networks:

NetworkContract addressLink
Arbitrum0x2050256A91cbABD7C42465aA0d5325115C1dEB43Arbiscan (opens in a new tab)
Linea0x423cd60ab053F1b63D6F78c8c0c63e20F009d669Explorer (opens in a new tab)
Optimism0x5558D441779Eca04A329BcD6b47830D2C6607769Etherscan (opens in a new tab)
Optimism Sepolia0xe53C60F8069C2f0c3a84F9B3DB5cf56f3100ba56Etherscan (opens in a new tab)
ZkSync Era0x1166FCDCA3B04311Ba9E2eD5ad2c660E730e1386Explorer (opens in a new tab)
ZkSync Sepolia0x23AF92Af3b5D6faAD920C3CAA4F9A3d4352D6834Explorer (opens in a new tab)

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

Available methods

MethodDescription
getPassport(userAddress)Returns a list of valid credentials for a given ETH address.

Example response:
tuple[] :  [[Ens,0x2479874ec45bdedd5e2cb64169817b494137e9b554cf2bd99792caf90cfab965,1704482571,1712258571][ethPossessionsGte#1,0x55ab3ccca2f571375b683c5a00416e89e121dfdb79b42d9a6b2f1278df52c731,1704482571,1712258571][FirstEthTxnProvider,0x4753373bdcb5b9e61c388e1e8ea273e090673b665ee8e5d20aa1ce6942a64d88,1704482571,1712258571][EthGTEOneTxnProvider,0x373a3919e1db0035bcb3f74d2f7813a3cab60774dfd044828ec049e95211c25e,1704482571,1712258571][EthGasProvider,0x1a280f39044250aea077a8b15b3cbe5777fbd546c91dcd70dfb019b1b334a223,1704482571,1712258571][NFT,0xb7dd9a7654804a77c2361b95d413910f0ba2033e885cc2d9d724b8b876357d77,1704482571,1712258571][GnosisSafe,0x2f659efe4c40e251957b94edeb6797b6023e958b4141b7587d4de1f17d6afb3e,1704482571,1712258571][GuildPassportMember,0xda29097372dff5752bc1b1815daec79eb16a2a680ee48db07a7fb9e275b25b6b,1704482571,1712258571][TrustaLabs,0xb96f090d48dc0285488c1424fc4f319159c0d8c9e824fd42acf32e1af2710191,1704482571,1712258571]]
getScore(userAddress)Returns a user’s valid score as a 4-digit value. Divide the value by 100 to get the user’s score. 
This function will read the user’s score first from the cache in the GitcoinResolver and fall back to reading the score from the EAS score attestation. This method will revert with an error is a valid score is not found.

Example response:
uint256 :  143890
isHuman(userAddress)Returns a single boolean, indicating if the user’s score is below or above the minimum threshold, which is currently set to 20. It uses getScore() to retrieve the value that is compared against this threshold.

Example responses:
bool :  false
bool :  true

Alternative method

Please note that this method only enables you to receive decoded onchain Stamp data, and not score data.

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 Mainnet

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

contractaddresslink
issuer0x804233b96cbd6d81efeb6517347177ef7bD488EDArbiscan (opens in a new tab)
EAS0xbD75f629A22Dc1ceD33dDA0b68c546A1c035c458Arbiscan (opens in a new tab)
GitcoinResolver0x90E2C4472Df225e8D31f44725B75FFaA244d5D33Arbiscan (opens in a new tab)
GitcoinVerifier0xc4858e4D177Bf0d14571F91401492d62aa608047Arbiscan (opens in a new tab)
GitcoinAttester0x7848a3578Ff2E1F134659a23f64A404a4D710475Arbiscan (opens in a new tab)

EAS Schema

schemauidlink
passport0x8ae6ee946bf1c936584cacc969bf7e9d0b274631c818df7e45c246051b364341EasScan (opens in a new tab)
score0x24620f482734b3806102678e4b8bb68baafb1adc1ec29e524bcd69c85f15b915EasScan (opens in a new tab)
Linea Mainnet

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

contractaddresslink
issuer0x4B70C4308ea49d17FD946dDacD6884e8e1e18B56Lineascan (opens in a new tab)
EAS0xaEF4103A04090071165F78D45D83A0C0782c2B2aLineascan (opens in a new tab)
GitcoinVeraxPortal0xCAa9E817f02486cE076560B77A86235Ef91c5d5DLineascan (opens in a new tab)
GitcoinResolver0x0a774AECE542a1A819107Eb3a06E9D515C67257aLineascan (opens in a new tab)
GitcoinVerifier0xc94aBf0292Ac04AAC18C251d9C8169a8dd2BBbDCLineascan (opens in a new tab)
GitcoinAttester0xBC778313E52b1184A15D163b5d3a72AEF8d510A2Lineascan (opens in a new tab)

Verax schema

schemauid
passport0x501e6fcade7e3483d0ae7fcfebb732907ebda12b209f5116e52c02697062a50e
score0x01f031da36192c34057c764239eb77bb6ec8ebfb808f72a7bb172f37a5bec31f

EAS Schema

schemauidlink
passport0x69b9d63ff6b161097cb4930e197a722bcf423f832d4e4cd3692449d5a1e1319fEasScan (opens in a new tab)
score0x4da1eaac6346b8b79a705e3898a308062ca607f56c07762ef7b7ff8a7661843cEasScan (opens in a new tab)
Optimism Mainnet

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

Gitcoin

contractaddresslink
issuer0x804233b96cbd6d81efeb6517347177ef7bD488EDEtherscan (opens in a new tab)
EAS0x4200000000000000000000000000000000000021Etherscan (opens in a new tab)
GitcoinResolver0xc94aBf0292Ac04AAC18C251d9C8169a8dd2BBbDCEtherscan (opens in a new tab)
GitcoinVerifier0xa8eD4d2C3f6f98A55cdDEd97C5aE9B932B0633A4Etherscan (opens in a new tab)
GitcoinAttester0x843829986e895facd330486a61Ebee9E1f1adB1aEtherscan (opens in a new tab)

EAS Schema

schemauidlink
passport0xd7b8c4ffa4c9fd1ecb3f6db8201e916a8d7dba11f161c1b0b5ccf44ceb8e2a39EasScan (opens in a new tab)
score0x6ab5d34260fca0cfcf0e76e96d439cace6aa7c3c019d7c4580ed52c6845e9c89EasScan (opens in a new tab)
Optimism Sepolia (testnet)

The Optimism Sepolia chain ID is 11155420.

Gitcoin

contractaddresslink
issuer0x4200000000000000000000000000000000000021Etherscan (opens in a new tab)
EAS0x4200000000000000000000000000000000000020Etherscan (opens in a new tab)
GitcoinResolver0x074761E1Dc6E6cF9cdeE67dd180E01E818716Ce0Etherscan (opens in a new tab)
GitcoinVerifier0x8D21C3360dcE1a9EBD3Da4373c4dAB7F81dd7233Etherscan (opens in a new tab)
GitcoinAttester0x8B1A76795e3CbadD79C5410d2C4D4827D9C1503aEtherscan (opens in a new tab)

EAS Schema

schemauidlink
passport0x7026a3d524ee3dae5859aa00cfc0f17a3dac05af70eb758b5c0a40692f1e60f3EasScan (opens in a new tab)
score0xe9071177c724d1bd712e4b05b4ce5426e60e141d8aaec86e4e03f25901d0cd91EasScan (opens in a new tab)
ZkSync Era

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

contractaddresslink
issuer0x804233b96cbd6d81efeb6517347177ef7bD488EDExplorer (opens in a new tab)
EAS0x21d8d4eE83b80bc0Cc0f2B7df3117Cf212d02901Explorer (opens in a new tab)
GitcoinResolver0x8789129C5968EdcA5Cb392C4a9A9D7EFB590A838Explorer (opens in a new tab)
GitcoinVerifier0xfCC2d308FD4De098D08f056c424C969d728912bFExplorer (opens in a new tab)
GitcoinAttester0x2B5D97CBE50eA9bf809CbE18A2003E4Cb4D283cCExplorer (opens in a new tab)

EAS Schema

schemauidlink
passport0x71b9da9e4a2ecd8c87ad57d29ef64b9e63887d54039c97c294a6ecba8a8dfb4eEasScan (opens in a new tab)
score0xfa8f39bf31b38893697a46f2607ef58ef3ec66308840a1e351304d26823a297cEasScan (opens in a new tab)
ZkSync Sepolia (testnet)

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

contractaddresslink
issuer0x5f603Ed913738d9105bAf3BD981AA4750016B167Explorer (opens in a new tab)
EAS0x21d8d4eE83b80bc0Cc0f2B7df3117Cf212d02901Explorer (opens in a new tab)
GitcoinResolver0x8789129C5968EdcA5Cb392C4a9A9D7EFB590A838Explorer (opens in a new tab)
GitcoinVerifier0xfCC2d308FD4De098D08f056c424C969d728912bFExplorer (opens in a new tab)
GitcoinAttester0x2B5D97CBE50eA9bf809CbE18A2003E4Cb4D283cCExplorer (opens in a new tab)

Attestation Schemas

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