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
Optimism0x5558D441779Eca04A329BcD6b47830D2C6607769Etherscan (opens in a new tab)
OP Sepolia [Testnet]0xe53C60F8069C2f0c3a84F9B3DB5cf56f3100ba56Etherscan (opens in a new tab)
OP Goerli [Testnet]0xa9f07557c2AAf8C9b2FeAA82150C24bA094670e0Etherscan (opens in a new tab)
Base Goerli [Testnet]0xa652BE6A92c7efbBfEEf6b67eEF10A146AAA8ADcBasescan (opens in a new tab)

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

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)
Linea

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 Attestation registry0x3de3893aa4Cdea029e84e75223a152FD08315138Lineascan (opens in a new tab)

EAS Schema

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

Verax schema

schemauid
passport0x501e6fcade7e3483d0ae7fcfebb732907ebda12b209f5116e52c02697062a50e
score0x01f031da36192c34057c764239eb77bb6ec8ebfb808f72a7bb172f37a5bec31f
Base Goerli

The Base Goerli chain ID is 84531 (opens in a new tab).

contractaddresslink
issuer0x5f603Ed913738d9105bAf3BD981AA4750016B167BaseScan (opens in a new tab)
EAS0xAcfE09Fd03f7812F022FBf636700AdEA18Fd2A7ABaseScan (opens in a new tab)
GitcoinResolver0xA10606c17d94a4DBDc4dD804d1B88fF5030aeE94BaseScan (opens in a new tab)
GitcoinVerifier0x5bC95C6e11520D25BE8c7bDf7AAc3E2eEAbD8564BaseScan (opens in a new tab)
GitcoinAttester0x5bbbc733e12f50e6834c40a90066f2f9ffb820e0BaseScan (opens in a new tab)

EAS Schema

schemauidlink
passport0x9d43e5c201404b9ab0913bcd6475c78e32d32a4d78233b2c309e9b6828f59e45BaseScan (opens in a new tab)
score0xf72ba57b5fb4c12a5f967574bc44a11efb8be76bcfbf47ced36e1afe226ba702BaseScan (opens in a new tab)

Attestation Schemas

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