Building with Passport
Smart Contracts
Quick start

Smart contract quick start

The Gitcoin Passport smart contracts are deployed on several chains, covering both testnets and live networks. There are several contracts that interact with each other to provide the Gitcoin Passport backend and API.

This quick start will illustrate different ways that you can quickly test pulling data from the Gitcoin decoder contract.

Retrieving data from Block Explorers

You can use a block explorer to find the Passport smart contracts and query their API directly in the browser, without having to write any code at all.

  1. Navigate to the decoder contract on a network supported by onchain Passport. In this example, we'll use the decoder deployed to the Optimism Sepolia network (opens in a new tab).
  2. Make sure the Read as Proxy tab is open. This is where you can view the methods exposed by the contract.
  3. Open the getPassport() or getScore() method.
  4. Enter a ETH wallet address, click Query, and view the results.

Available methods:

  • The getPassport method will provide the Stamps owned by the given address in the browser.
  • The getScore method will provide the user's score as a 4 digit number. Divide this by 100 to get the user's unique humanity score.
  • There are also several lower level functions that give access to encoded data and intermediate values.

Here's what a response from getPassport function on the block explorer looks like:

Retrieving data programmatically

You can also query the API programmatically from the terminal or in an app.

The steps are:

    1. instantiate a web3 provider
    1. instantiate the decoder contract
    1. call the contract functions

Here's a minimal example of how to call the getPassport() and getScore() methods using Web3js in a Javascript app:

Instantiate a web3 provider

The provider is your entry point to the blockchain. Ultimately it is the address for a node that exposes a set of methods that allows you to interact with the blockchain. If you run your own node, you can use it as your provider. It is also common to use third party "RPC" providers. This is equivalent to using someone else's node. If you are not sure what to use as your provider, your wallet will expose the URLs it is using, and you can copy them into your Javascript application as shown below.

To use an RPC provider:

const Web3 = require("web3");
const rpcUrl = '<your url here>';
const web3 = new Web3(new Web3.providers.HttpProvider(rpcUrl));

To use a local node (in this case, Geth using IPC):

var web3 = new Web3(new Web3.providers.IpcProvider('/Users/myuser/Library/Ethereum/geth.ipc', net))

Now you have a variable, web3 representing your web3 connection. You can use this to interact with contracts on the blockchain.

Note please ensure your web3 provider is connected to the correct network.

Instantiate the decoder contract

Instantiating a contract allows you to interact with a contract deployed on the blockhain as if it were a Javascript object. This requires you to pass the contract ABI (application Binary Interface) and the address on the blockchain where the contract is deployed. The contract ABI can usually be found by querying the contract address on a block explorer, or alternatively it is usually available on a project's Github if the project is open source. The Gitcoin decoder contract ABI can be found on both block explorers and the Gitcoin Github (opens in a new tab).

var Contract = require('web3-eth-contract');
var abi = <paste ABI here>
 
var contract = new Contract(jsonInterface, address);

The contract variable is a Javascript object exposing the contract methods.

Call the contract methods

You can use the contract methods just like Javascript object methods, i.e. contract.method(args). To call the decoder contract's getPassport() method:

var passportInfo = contract.getPassport("<user-address>")

To call the contract's getScore() method:

var score = contract.getScore("<user-address>")

Summary

This quick start guide demonstrated how to grab information from the Gitcoin Passport decoder contract. You have the option to query the contract using the block explorer UI or programatically using a library such as web3js. There are equivalent libraries in other languages too, such as web3py (opens in a new tab) for Python, web3 (opens in a new tab) for Go, and ethers for Rust (opens in a new tab) and Javascript (opens in a new tab).

Next steps

Explore our contract reference page to find all the details about the various Gitcoin Passport contract deployments. Then you could try our more advanced smart contract app tutorial.

If you have mroe questions you can chat in our developer support channel on Discord (opens in a new tab).

OverviewTutorial