├── .env.example ├── .env.local ├── .gitignore ├── Dockerfile ├── Makefile ├── README.md ├── docker-compose.yml ├── next-env.d.ts ├── next-sitemap.config.js ├── next.config.js ├── openapi.yaml ├── package.json ├── pages ├── _meta.json ├── building-with-passport │ ├── _meta.json │ ├── data-services.mdx │ ├── models │ │ ├── _meta.json │ │ ├── api-reference.mdx │ │ ├── available-models.mdx │ │ ├── getting-access.mdx │ │ ├── index.mdx │ │ └── tutorials │ │ │ └── double-verification.mdx │ └── stamps │ │ ├── _meta.json │ │ ├── create-a-stamp │ │ ├── _meta.json │ │ ├── index.md │ │ └── integrating-a-new-stamp.mdx │ │ ├── custom-passport.md │ │ ├── index.mdx │ │ ├── major-concepts │ │ ├── _meta.json │ │ ├── api-pagination.md │ │ ├── credential-map-and-weights.mdx │ │ ├── deduplicating-stamps.mdx │ │ ├── educating-users.mdx │ │ ├── expirations.md │ │ └── scoring-thresholds.mdx │ │ ├── passport-api-v1 │ │ ├── _meta.json │ │ ├── api-reference.mdx │ │ ├── data-dictionary.mdx │ │ ├── index.mdx │ │ ├── tutorials.mdx │ │ └── tutorials │ │ │ ├── _meta.json │ │ │ ├── client-side-scoring.mdx │ │ │ ├── gating-access-with-passport-scores.mdx │ │ │ ├── integrating-stamps-and-scorers.mdx │ │ │ ├── requiring-a-passport-score-for-airdrop-claim.mdx │ │ │ └── working-with-stamp-metadata.mdx │ │ ├── passport-api │ │ ├── _meta.json │ │ ├── api-reference.mdx │ │ ├── data-dictionary.mdx │ │ ├── getting-access.mdx │ │ ├── index.mdx │ │ ├── migrate.mdx │ │ ├── quick-start-guide.mdx │ │ └── status-and-error-codes.md │ │ ├── passport-embed │ │ ├── _meta.json │ │ ├── component-reference.mdx │ │ ├── customization.mdx │ │ ├── getting-access.mdx │ │ ├── index.mdx │ │ ├── quick-start-guide.mdx │ │ └── tutorial │ │ │ ├── _meta.json │ │ │ └── protecting-sensitive-programs-with-passport-embed.mdx │ │ └── smart-contracts │ │ ├── _meta.json │ │ ├── attestation-schema.mdx │ │ ├── contract-reference.mdx │ │ ├── index.mdx │ │ ├── integrating-onchain-stamp-data.md │ │ ├── onchain-expirations.md │ │ ├── quick-start-guide.mdx │ │ └── test-mode.md ├── community │ ├── _meta.json │ ├── getting-involved.mdx │ ├── passport-github-projects.mdx │ └── style-guide.mdx ├── index.mdx └── overview │ ├── _meta.json │ ├── active-integrations.mdx │ ├── changelog.mdx │ ├── index.mdx │ ├── key-terms.mdx │ └── use-cases.md ├── pnpm-lock.yaml ├── public ├── 2023-08-04 10-13-01.mp4 ├── Passport Airdrop (1).png ├── Passport Airdrop.png ├── Screenshot from 2023-08-04 10-17-11.png ├── Screenshot from 2023-08-04 10-17-16.png ├── Screenshot from 2023-08-04 10-17-19.png ├── api-key.png ├── app-failure.png ├── app-success.png ├── bankless.jpg ├── bankless2.jpg ├── bankless3.jpg ├── bankless4.png ├── bankless5.png ├── bankless6.jpg ├── basescan.png ├── custom-scorer.png ├── favicon.png ├── favicon.svg ├── improve experience.png ├── logos │ ├── Passport_Lockup_Black.svg │ ├── Passport_Lockup_IceBlue.svg │ ├── Passport_Lockup_Iris.svg │ ├── Passport_Lockup_IrisIceBlue_Gradient_Black.svg │ ├── Passport_Lockup_IrisIceBlue_Gradient_White.svg │ ├── Passport_Lockup_IrisSeaFoam_Gradient_Black.svg │ ├── Passport_Lockup_IrisSeaFoam_Gradient_White.svg │ ├── Passport_Lockup_NightBlue.svg │ ├── Passport_Lockup_SeaFoam.svg │ └── Passport_Lockup_White.svg ├── onchain-stamp-explorer-1.png ├── onchain-stamp-explorer-2.png ├── onchain-stamp-explorer-3.png ├── passport-app-ethereum-activity.png ├── passport-hero.png ├── passport-homepage.png ├── petstore-minimal.json ├── protect-communication.png ├── protect-governance.png ├── protect-marketplace.png ├── protect-rewardspng.png ├── prove-reputation.png ├── quick-start-app (1).png ├── quick-start-app.png ├── robots.txt ├── scorer-page.png ├── scorer-use-case.png ├── scoring-mechanisms.png ├── sign-in-to-scorer.png ├── sitemap-0.xml ├── sitemap.xml ├── snapshot.jpg ├── social-card.png ├── stamp-collector-app-showing-stamps.png ├── stamp-logo-examples.png ├── stamps-page.png ├── test-mode-app.png ├── trusted-user-app-2.png ├── trusted-user-app-pt1.png ├── trusted-user-app.png └── weigh-activities.png ├── retired-content └── composedb.md ├── theme.config.tsx ├── tsconfig.json └── utils └── data └── weights.ts /.env.example: -------------------------------------------------------------------------------- 1 | NODE_ENV=development 2 | NEXT_PUBLIC_GA_MEASUREMENT_ID= -------------------------------------------------------------------------------- /.env.local: -------------------------------------------------------------------------------- 1 | NODE_ENV=development 2 | NEXT_PUBLIC_GA_MEASUREMENT_ID= -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | .next 3 | settings.json 4 | package-lock.json -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | # Use the official Node.js image as a base 2 | FROM node:18 3 | 4 | # Set the working directory 5 | WORKDIR /app 6 | 7 | # Copy package.json and package-lock.json first to leverage Docker cache 8 | COPY package*.json ./ 9 | 10 | # Install dependencies 11 | RUN npm install 12 | 13 | # Copy the rest of the application code 14 | COPY . . 15 | 16 | # The default command to run the app 17 | #CMD ["npm", "run", "dev"] 18 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | .PHONY: up 2 | up: 3 | docker-compose up --build 4 | 5 | .PHONY: in 6 | in: 7 | docker exec -it gitcoin_passport_docs /bin/bash 8 | 9 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Introducing Human Passport 2 | 3 | Human Passport is an identity verification application. It enables you to collect verifiable credentials that prove your identity and trustworthiness without exposing personally identifying information. Apps and organizations can then use your Passport to coordinate your rights and responsibilities. 4 | 5 | To coordinate and scale an open internet, we need tools like Human Passport to enable successful and trustworthy collective decision-making that is not vulnerable to bots and bad actors. 6 | 7 | **Human Passport is your citizenship pass for the decentralized internet.** 8 | 9 | ![](../public/passport-hero.png) -------------------------------------------------------------------------------- /docker-compose.yml: -------------------------------------------------------------------------------- 1 | version: '3' 2 | 3 | services: 4 | app: 5 | container_name: gitcoin_passport_docs 6 | build: . 7 | image: node:18 8 | working_dir: /app 9 | volumes: 10 | - .:/app 11 | ports: 12 | - "3000:3000" 13 | command: tail -f /dev/null 14 | environment: 15 | - NODE_ENV=development 16 | -------------------------------------------------------------------------------- /next-env.d.ts: -------------------------------------------------------------------------------- 1 | /// 2 | /// 3 | 4 | // NOTE: This file should not be edited 5 | // see https://nextjs.org/docs/basic-features/typescript for more information. 6 | -------------------------------------------------------------------------------- /next-sitemap.config.js: -------------------------------------------------------------------------------- 1 | /** @type {import('next-sitemap').IConfig} */ 2 | module.exports = { 3 | siteUrl: process.env.SITE_URL || "https://docs.passport.xyz", 4 | generateRobotsTxt: true, 5 | }; 6 | -------------------------------------------------------------------------------- /openapi.yaml: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "passport-docs", 3 | "version": "0.0.1", 4 | "description": "Passport documentation", 5 | "scripts": { 6 | "dev": "next dev", 7 | "build": "next build", 8 | "postbuild": "next-sitemap", 9 | "start": "next start" 10 | }, 11 | "repository": { 12 | "type": "git", 13 | "url": "git+https://github.com/" 14 | }, 15 | "author": "Passport XYZ DevRel", 16 | "license": "MIT", 17 | "bugs": { 18 | "url": "https://github.com/passportxyz/passport-docs/issues" 19 | }, 20 | "homepage": "https://docs.passport.xyz/", 21 | "dependencies": { 22 | "debug": "^4.3.4", 23 | "fsevents": "^2.3.3", 24 | "next": "^13.0.6", 25 | "next-sitemap": "^4.2.3", 26 | "nextra": "2.13.2", 27 | "nextra-theme-docs": "latest", 28 | "react": "^18.2.0", 29 | "react-dom": "^18.2.0", 30 | "react-gtm-module": "^2.0.11", 31 | "uuid": "^9.0.1" 32 | }, 33 | "devDependencies": { 34 | "@types/node": "18.11.10", 35 | "typescript": "^4.9.3" 36 | }, 37 | "dependenciesMeta": { 38 | "nextra": { 39 | "injected": true 40 | }, 41 | "nextra-theme-docs": { 42 | "injected": true 43 | } 44 | } 45 | } 46 | -------------------------------------------------------------------------------- /pages/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "index": "Home", 3 | "overview": "Overview", 4 | "building-with-passport": "Building with Passport", 5 | "community": "Community", 6 | "passport-app_link": { 7 | "title": "Passport App", 8 | "type": "page", 9 | "href": "https://app.passport.xyz", 10 | "newWindow": true 11 | }, 12 | "developer_portal_link": { 13 | "title": "Developer Portal", 14 | "type": "page", 15 | "href": "https://developer.passport.xyz/", 16 | "newWindow": true 17 | }, 18 | "blog_link": { 19 | "title": "Blog", 20 | "type": "page", 21 | "href": "https://passport.human.tech/blog", 22 | "newWindow": true 23 | } 24 | } -------------------------------------------------------------------------------- /pages/building-with-passport/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "stamps": "Stamps API", 3 | "models": "Models API", 4 | "data-services": "Data services" 5 | } -------------------------------------------------------------------------------- /pages/building-with-passport/data-services.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Data Services 3 | description: Human Passport's Data Services are designed for partners who have a list of wallet addresses and wish to assess the likelihood that each address represents a unique human. 4 | --- 5 | 6 | # Passport Data Services 7 | 8 | Human Passport’s Data Services provide advanced, ML-driven Sybil detection and wallet analysis, helping partners confidently distinguish genuine users from Sybil attackers. 9 | 10 | ## Overview 11 | 12 | Passport’s Data Services offer batch analysis of wallet addresses, designed specifically for scenarios where you have a predefined list of addresses (such as airdrops, event registrations, or community campaigns). It complements Passport’s real-time verification tools like [Passport API](/building-with-passport/passport-api) and [smart contract-based verification](/building-with-passport/smart-contracts). 13 | 14 | ## Use Cases 15 | 16 | Common scenarios where Passport’s Data Services deliver significant value include: 17 | 18 | * **Airdrops and Token Distributions**: Vet wallet addresses before distributing tokens to ensure only legitimate users receive rewards. 19 | * **Community Campaign Audits**: Identify bot-driven farming in referral campaigns, growth initiatives, or contests. 20 | * **Sybil Attack Investigations**: Assess and remediate suspected Sybil activities post-event or campaign. 21 | 22 | ## How It Works 23 | 24 | The process is straightforward and collaborative: 25 | 26 | ### 1. Submit Your Wallet List 27 | 28 | Securely share the wallet addresses you want analyzed. 29 | 30 | ### 2. Advanced Analysis 31 | 32 | Passport’s data team conducts comprehensive analysis, including: 33 | 34 | * **ML-based Sybil Classification**: Our machine learning models analyze wallet transaction patterns across multiple chains (Ethereum, Arbitrum, Optimism, Base, Polygon, zkSync), assigning a Unique Humanity Score from 0-100. 35 | * **Sybil Clustering Analysis**: Detect related wallets based on funding patterns, behavior similarities, and transaction clustering. 36 | * **Low-Activity Wallet Handling**: Special handling and heuristics for wallets with minimal activity, ensuring fair evaluation without compromising security. 37 | * **Expert Consultation**: Human analysts review findings, validate results, and provide tailored insights and recommendations. 38 | 39 | ### 3. Actionable Reports 40 | 41 | Receive detailed reports with clear classification, identified Sybil clusters, actionable recommendations, and guidance on implementation. 42 | 43 | ### 4. Ongoing Support (Optional) 44 | 45 | Continuous monitoring and periodic analyses for long-term campaigns or community management. 46 | 47 | ## Pricing 48 | 49 | * \$0.05 per address analyzed. 50 | * Bulk discounts available starting at 500,000 addresses. 51 | 52 | ## Getting Started 53 | 54 | Ready to leverage Passport’s Data Services? Fill out our [Data Services partner form](https://tally.so/r/3X81KL). Our team will contact you to discuss your use case, integration details, and next steps. 55 | 56 | [→ Contact the Passport Team](https://tally.so/r/3X81KL) 57 | -------------------------------------------------------------------------------- /pages/building-with-passport/models/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "index": "Introduction", 3 | "getting-access": "Getting access", 4 | "tutorials": "Tutorials", 5 | "available-models": "Available models and score thresholds", 6 | "api-reference": "API reference" 7 | } 8 | -------------------------------------------------------------------------------- /pages/building-with-passport/models/api-reference.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Models API reference 3 | description: Reference documentation for the Models API. 4 | --- 5 | 6 | # Models API Reference 7 | 8 | The Models API enables developers to retrieve different [model-based unique humanity scores](available-models) in real-time, enabling you to score any EVM wallet address without requiring the users to create and build up a Passport score. 9 | 10 | Need a batch or more in-depth Sybil classification and clustering analysis? Learn more about our [Data Services](/building-with-passport/data-services). 11 | 12 | You can also experiment with the Models API using our [API playground tool](https://api.passport.xyz/v2/docs) and adding your API keys via the 'Authorize' button. 13 | 14 | 15 | ## Rate Limits 16 | 17 | |Tier |Rate limit | 18 | |--|--| 19 | |Tier 1 | *[DEFAULT]* 15 requests per 15 minutes | 20 | |Tier 2 | 350 requests per 15 minutes | 21 | |Tier 3 | 2000 requests per 15 minutes | 22 | 23 | These rate limits are completely separate from the existing Passport API rate limits. 24 | 25 | If you'd like to request elevated rate limits, please fill out our [rate limit elevation form](https://docs.google.com/forms/d/e/1FAIpQLSe5B7zXTUQUt_aWdqTiUhjAhz56pS49Q8meuzLSgGxYTZRwAw/viewform). 26 | 27 | 28 | ## Retrieve Model scores 29 | 30 | Use this endpoint to request a model-based score for a specified user. You can find all of the available models and recommended score thresholds via our [available models](available-models) page. 31 | 32 | * **Endpoint:** `GET /v2/models/score/{address}` 33 | * **Base URL:** `https://api.passport.xyz` 34 | * **Authentication:** API Key – Can be the same [API Key](../passport-api/getting-access) that is used with the Passport API 35 | 36 | ### Parameters 37 | 38 | |Parameter |Type |Description | 39 | |--|--|--| 40 | |`address` |Path parameter| *[Required]* Pass a single EVM wallet address. | 41 | |`model` |Query parameter | Include one of the following [available models](available-models) to request that model's score for the specified wallet address:
`aggregate`, `ethereum_activity`, `nft`, `arbitrum`, `base`, `optimism`, `polygon`, and `zksync`

If you don't include this parameter, the API will return the `aggregate` model by default. | 42 | 43 | 44 | ### Default example 45 | 46 | #### Request 47 | 48 | ```bash 49 | curl --request GET \ 50 | --url 'https://api.passport.xyz/v2/models/score/{address}?model=aggregate' \ 51 | --header 'Content-Type: application/json' \ 52 | --header 'X-API-KEY: {API KEY}' 53 | ``` 54 | 55 | #### Response 56 | 57 | ```json 58 | { 59 | "address": "string", 60 | "details": { 61 | "models": { 62 | "aggregate": { 63 | "score": 50 64 | } 65 | } 66 | } 67 | } 68 | ``` 69 | 70 | 71 | ### Arbitrum model example 72 | 73 | #### Request 74 | 75 | ```bash 76 | curl --request GET \ 77 | --url 'https://api.passport.xyz/v2/models/score/{address}?model=arbitrum' \ 78 | --header 'Content-Type: application/json' \ 79 | --header 'X-API-KEY: {API KEY}' 80 | ``` 81 | 82 | #### Response 83 | 84 | ```json 85 | { 86 | "address": "string", 87 | "details": { 88 | "models": { 89 | "arbitrum": { 90 | "score": 50 91 | } 92 | } 93 | } 94 | } 95 | ``` -------------------------------------------------------------------------------- /pages/building-with-passport/models/getting-access.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Getting access to the Models API 3 | description: Explainer for how to get access to the Models API. 4 | --- 5 | import { Callout } from 'nextra/components' 6 | 7 | # Getting Access: API Key 8 | 9 | The Models API provides programmatic access to variety of different model-based Sybil detection scores. 10 | 11 | Once you have your API key, you need to include it with each request you make to the API. This allows Human Passport to identify your app and verify that you are authorized to access the API. 12 | 13 | 14 | Please note:

You do not need a Scorer or Scorer ID to use the Models API. 15 | 16 | 17 | ### Getting Your API Key 18 | 19 | 1. **Log in to the developer portal:** Go to [developer.passport.xyz](https://developer.passport.xyz) and log in to your account by connecting your wallet. 20 | 2. **Navigate to the API Keys section:** After logging in, go to the "API Keys" section. 21 | 3. **Generate an API key:** Click on the "+ Create a Key" button to generate a unique API key for your account. 22 | 4. **Store your API key securely:** Store your API key in a secure place, as it will be used to access the Models API as well as the Passport API. 23 | 24 | 25 | ### Next step 26 | 27 | Review one of the following pages to learn how you can use your API key with the Models API. 28 | - [Review the API Reference](api-reference) 29 | - [Review the tutorial explaining how to use this score](tutorials/double-verification) 30 | -------------------------------------------------------------------------------- /pages/building-with-passport/models/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Models API -- Introduction 3 | description: The Models API enables partners to utilize Passport-grade supervised machine learning models to identify Sybils vs humans. 4 | --- 5 | 6 | import { Callout } from 'nextra/components' 7 | 8 | # Models API 9 | 10 | The Models API enables partners to protect programs against Sybils in real-time, regardless of whether they have a Passport account or not. 11 | 12 | This API is designed to return the results of model-based detection methods. It can score any EVM addresses against several different models that analyze transaction history against dozens of different data features to identify if that address is likely Human or Sybil. 13 | 14 | 15 | 16 | Need more in-depth analysis? 17 | 18 | We also offer batch Sybil classification and clustering analyses via our [data services](/building-with-passport/data-services). 19 | 20 | To learn more, please fill out our [contact form](https://tally.so/r/3X81KL). 21 | 22 | 23 | 24 | The current [available models](available-models) include the following: 25 | 26 | * Aggregate unique humanity model 27 | * Ethereum (L1) unique humanity model 28 | * NFT (L1) unique humanity model 29 | * Arbitrum unique humanity model 30 | * Base unique humanity model 31 | * Optimism unique humanity model 32 | * Polygon unique humanity model 33 | * zkSync unique humanity model 34 | 35 | This essentially opens up Sybil detection and defense to all EVM wallet addresses, regardless of whether the user has a Passport with verified Stamps or not. 36 | 37 | This new API is the perfect compliment to the existing [Passport API](/building-with-passport/stamps/passport-api) as it offers the following benefits: 38 | 39 | * **Score any address:** Any EVM wallet address can be scored, regardless of whether they have a Passport or not. 40 | * **Reduced user friction:** Users don’t need to do anything to be scored by this endpoint. 41 | * **More difficult for Sybils:** When we make adjustments to our Stamp offering and weights, we are essentially providing a roadmap for Sybils, requiring us to make changes periodically which can add friction for users. The model features are hidden from the public, making it more difficult for Sybils to cheat. 42 | * **Modular verification:** Using the MBD API along with the [Stamp-based verification](/building-with-passport/stamps/passport-api) approach made available via the Passport API can enable you to provide multiple verification options that reduce user friction for the majority of users while offering an additional verification tool for users who don’t pass the initial check. 43 | * **Faster and less impactful iteration cycles:** Sybil behavior changes, and so should Passport. While we know updates to our [Stamp-based verification](/building-with-passport/stamps/passport-api) are both required and help improve ease and effectiveness, those changes can cause user friction. The model-based verification enables us to tune our the models more frequently without this friction, allowing us to respond to changes in Sybil behavior more quickly. 44 | 45 | 46 | ## Getting Access 47 | 48 | This API is generally available to all developers today, but you will need to utilize an API key that is required to access the Stamp-based Passport API. 49 | 50 | Please visit our [getting access page](/building-with-passport/models/getting-access) to learn how to generate an API key. 51 | 52 | During the initial beta phase, rate limits will be limited. You can read more in our [API Reference](api-reference). 53 | 54 | 55 | ## Use cases 56 | 57 | This new API is designed to complement the existing suite of endpoints to offer a comprehensive approach to protecting and understanding your community's constituents. 58 | 59 | Starting with the MBD API, you can quickly determine if a wallet is a suspected human or Sybil actor. If they are a suspected Sybil (or if we don't have enough data to score them), you can have them utilize our [Stamp-based verification](/building-with-passport/stamps/passport-api) to prove their humanness. 60 | 61 | When thinking about applying this new API, there are two primary use cases that it enables: 62 | 63 | 1. **[Protecting access](/overview/use-cases#protect-access-rewards):** Preventing Sybils and other malicious bots from being able to participate in a variety of different web3 programs. 64 | 2. **Data analysis:** Analyzing a set of wallet addresses against the Passport Model Based Detection score to identify which wallets are likely Humans or Sybils. You can also get in contact with us to have our team perform more in-depth data analysis around a list of wallet addresses by filling out [this form](https://docs.google.com/forms/d/e/1FAIpQLScDHGifo2IWkBxsMKcGJ2Qr24mnYM6G5hao7oin5f3OOZFkgw/viewform). 65 | 66 | 67 | ## Recommended developer flow: Protect access 68 | 69 | Protecting access is Passport’s primary [use case](/overview/use-cases). There are many different types of programs that can be protected with Passport, including rewards, governance, community access, marketplace, and communication programs. 70 | 71 | In this section, we will describe a few different developer flows that can be used to protect access to programs: 72 | 73 | * Single verification using a Model Based Detection score 74 | * Double verification using a Model Based Detection score and the Unique Humanity Score 75 | * Double verification using a Model Based Detection score and other verification methods 76 | 77 | ### Single verification using MBD 78 | 79 | This is the lightest-weight verification tool available with the current Passport developer tooling. 80 | 81 | If you’d like to quickly verify if potential participants are likely human or sybil based on the model-based evaluation, this is for you. 82 | 83 | However, this verification method does not provide a secondary verification option for users, such as crypto beginners. If this is a concern, we recommend that you explore using one of the double verification methods. 84 | 85 | **Technical integration details:** 86 | 87 | * Collect the wallet address from the user 88 | * Pass the wallet address to the [`GET /v2/models/score/{address}`](api-reference) endpoint, which will deliver the specified model score (0-100). 89 | * Compare this score against a predetermined [score threshold](available-models), and either grant or deny access depending on that evaluation. 90 | 91 | 92 | ### Double verification using MBD and Unique Humanity score 93 | 94 | We've developed a tutorial around this offering: [Double Verification with the Model Based Detection and Stamp-based APIs](tutorials/double-verification) 95 | 96 | This verification method will cause the least amount of user friction for the majority of users, while also providing a secondary verification check to users (especially crypto beginners) in case they want to contest an initial check’s rejection. 97 | 98 | Many users will be able pass the initial MBD check with no user friction, while a portion of them will need to go through the Stamp-based process (in other words, creating a Passport, verifying Stamps, and building up a unique humanity score). 99 | 100 | **Technical integration details:** 101 | 102 | * Collect the wallet address from the user 103 | * Pass the wallet address to the [`GET /v2/models/score/{address}`](api-reference) endpoint, which will deliver the specified model score (0-100). 104 | * Compare this model score against a predetermined [score threshold](available-models), and either grant access to the user or present the secondary verification method to them, depending on that evaluation. 105 | * Assuming the user didn’t pass primary verification, retrieve the user’s Stamp-based Unique Humanity Score from the Passport API v2 using the [`GET /v2/stamps/{scorer_id}/score/{address}`](/building-with-passport/stamps/passport-api/api-reference#retrieve-latest-score-for-a-single-address) endpoint. 106 | * Evaluate the Unique Humanity Score against a predetermined [score threshold](/building-with-passport/stamps/major-concepts/scoring-thresholds), and will either grant or deny access based on that evaluation. 107 | 108 | 109 | ### Double verification using MBD and other verification methods 110 | 111 | This option will look very similar to the previous double verification method, but can utilize a custom Passport scorer and set of Stamps, or a separate 1st or 3rd-party verification system to verify users who weren’t able to pass the initial MBD verification flow. 112 | 113 | 114 | ## Next steps 115 | 116 | You can retrieve a model-based score with a simple API request. Try it out using our [API playground tool](https://api.passport.xyz/v2/docs). 117 | 118 | One of our recomended flows is to use double verification with both the MBD API and the Stamp-based Passport API. We have provided a [walkthrough tutorial](tutorials/double-verification) to show you how it's done. 119 | 120 | Review technical details within the [API Reference](api-reference) to understand what all is available via this API. 121 | 122 | Review our page that describes all [available models and recommended score thresholds](available-models). 123 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "index": "Introduction", 3 | "major-concepts": "Major concepts", 4 | "---": { 5 | "type": "separator" 6 | }, 7 | "passport-api": "Passport API v2", 8 | "passport-api-v1": "Passport API v1 (deprecated)", 9 | "passport-embed": "Passport Embed", 10 | "custom-passport": "Custom Passport", 11 | "smart-contracts": "Onchain Passport", 12 | "create-a-stamp": "Create a Stamp" 13 | } 14 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/create-a-stamp/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "index": "Introduction", 3 | "integrating-a-new-stamp": "Stamp integration tutorial" 4 | } 5 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/create-a-stamp/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Stamps developer overview 3 | description: Instructions for creating new Stamps 4 | --- 5 | 6 | ## What is a Stamp? 7 | 8 | Stamps are the key identity verification mechanism of Passport. A Stamp is a collection of one or more [verifiable credentials](#verifiable-credentials-vcs) from an identity provider that is collected in a Passport. Stamps are provided by a variety of web2 and web3 identity authenticators including Google, BrightID, Holonym, Civic, ENS, and more. Stamps do not store any personally identifiable information, only the verifiable credentials issued by the identity authenticator. 9 | 10 | Passport aggregates Stamps and assigns each Stamp a different weight according to the needs of a particular community. This weight is used to calculate the cost of forgery of an identity, a score which reflects the credibility of a potential participant’s online identity. 11 | 12 | The Passport team is highly selective about the new Stamps that are added to the platform. To be considered, you can follow the steps outlined in on this page. 13 | 14 | ## Stamp assessment criteria 15 | 16 | When new Stamps are proposed we evaluate them according to some key criteria: 17 | 18 | - **Strong non-Sybil signal** 19 | 20 | Stamps should represent some strong method for identifying Sybils vs non-Sybils so that we can ensure that each Stamp helps to improve the Sybil-defense that Passport offers. We prioritize new signals that are unique or different to the signals we have already have in Passport. It’s ideal if there’s already data, from internal efforts, indicating the effectiveness of the credentials. 21 | 22 | - **Free** (or very cheap) 23 | 24 | We have heard feedback from end users who are frustrated by the costs of some of the existing Stamps. Where possible we'd like to expand the set of free or very cheap options available to our users. 25 | 26 | - **Easy to use** 27 | 28 | Ensuring that a user can quickly get set up and verified is important to the overall Passport and partner platform's success. We’ll prioritize those Stamps and credentials that can be included in the existing ‘1-click’ verification flow. 29 | 30 | - **Strong partnership** 31 | 32 | We pass Sybil data back and forth in an aggregate and anonymized way with our strongest partners to help all parties improve Sybil defense. We expect future partners to participate in this program as well. 33 | 34 | - **Substantial user base** 35 | 36 | The more users you have, the more users we can start offering Sybil defense to. This also helps grow the Passport ecosystem as each new partner helps grow all partners. 37 | 38 | 39 | ## What types of Stamps would we like to see more of? 40 | 41 | We are specifically interested in Stamps that are accessible in areas of the world that are currently under-represented, such as Asia, Africa, and Latin America. This is so people in those regions don't find it more difficult to prove themselves to be real users than people from other areas. 42 | 43 | Similarly, we are interested to see more Stamps that are accessible to new-comers to Web3, but still match our key criteria. 44 | 45 | ## Process 46 | 47 | If you believe your Stamp meets the criteria described above, then you should submit your Stamp using [this form](https://docs.google.com/forms/d/e/1FAIpQLSffvrP4JJiPnvCvHDz9B7-lpCJFGQVwWoI0nut8w57hmURwMg/viewform). 48 | 49 | We review form submissions periodically and will get back to partners who's Stamps we want to integrate as soon as possible. 50 | 51 | If we decide to move forward with your Stamp, the next step is to follow the instructions in [this guide](https://docs.passport.xyz/stamps/integrating-a-new-stamp). 52 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Passport Stamps 3 | description: An overview of Passport Stamps, the ID verification aggregate tool 4 | --- 5 | 6 | import { Cards, Card } from 'nextra/components' 7 | import { Callout } from 'nextra/components' 8 | 9 | # Passport Stamps 10 | 11 | Passport Stamps are a way to collect and present data without exposing it or giving up ownership. 12 | 13 | ## What are Stamps? 14 | 15 | Passport Stamps is an aggregate, real-time verification tool that can enable users to prove their unique humanity using a variety of different verification methods, and for developers to access these humanity proofs via the [Passport API](/building-with-passport/stamps/passport-api) or [smart contracts](/building-with-passport/stamps/smart-contracts). 16 | 17 | **Verified Credentials do not contain any personal identifying information!** They simply demonstrate, using a cryptographic signature, that the user gave access to a specific app and that some criteria were met. Learn more about how Human Passport is [privacy preserving](https://passport.human.tech/privacy). 18 | 19 | ## Use cases 20 | 21 | Developers can integrate Passport in a variety of different programs and apps in the web3 ecosystem, as demonstrated by the following use case examples: 22 | 23 | - Sybil resistance for faucets, bundlers and airdrops 24 | - Gating access to content, events, polls, or communities 25 | - Priority weighting votes 26 | - Proving trustworthiness 27 | 28 | Passport Stamps is a versatile and valuable tool for managing access, promoting transparency, and establishing trust within different web3 environments. 29 | 30 | [Learn more about Passport use cases](../overview/use-cases). 31 | 32 | 33 | ## Available developer tools 34 | 35 | Passport score and Stamp data can be retrieved in two ways: 36 | 37 | * **[Passport API v2](/building-with-passport/stamps/passport-api):** Retrieves the Stamp-based Unique Humanity Score and associated metadata for a specified address. 38 | * **[Passport Smart Contracts](/building-with-passport/stamps/smart-contracts):** Interacts with a blockchain to retrieve Stamp-based Unique Humanity Scores associated with a specific address. 39 | 40 | Passport's Stamps-based product can also be delivered to users in a few different ways: 41 | 42 | * **[Passport App](https://app.passport.xyz):** The standard Passport app that allows users to manage their Stamps and view their Passport score. 43 | * **[Passport Embed](/building-with-passport/stamps/passport-embed):** A widget that can be embedded on a website or app to allow users to verify their identity. 44 | * **[Custom Passport](/building-with-passport/custom-passport):** A dashboard that can be customized to the unique needs of your ecosystem. 45 | 46 | ### Passport API v2 47 | 48 | The Passport API v2 serves as a powerful tool for developers, offering access to Passport scores and Stamps via several REST endpoints. 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | ### Passport Embed 58 | 59 | Passport Embeds is a premium offering that lets websites integrate Human Passport's Stamps-based verification directly on their website or app, eliminating the need for users to be redirected elsewhere. 60 | 61 | 62 | 63 | 64 | 65 | ### Custom Passport 66 | 67 | Custom Passport is a premium offering that enables partners to develop a Human Passport dashboard that is customized to the unique needs of their ecosystem. This offering enables several additional features above and beyond what is offered on the standard Passport app, which can enable tailored proof of humanity solutions. 68 | 69 | 70 | 71 | 72 | 73 | 74 | ### Onchain Passport 75 | 76 | Passport's smart contracts enable you to pull score and Stamp data directly from the blockchain to enable a truly decentralized integration. 77 | 78 | 79 | 80 | 81 | 82 | 83 | ## Getting Started 84 | 85 | To begin your development journey with Human Passport, follow these steps: 86 | 87 | - [Get an API key and scorer ID for the APIs](/building-with-passport/stamps/passport-api/getting-access) 88 | - [Use the API playground tool (requires API keys)](https://api.passport.xyz/v2/docs) 89 | - [Get to "Hello World" with Passport API v2](/building-with-passport/stamps/passport-api/quick-start-guide) 90 | 91 | By following these steps, you'll be well-equipped to start integrating Passport into your platform. 92 | 93 | If you have questions or need support, you can chat with us on our [developer support channel on Telegram](https://t.me/+Mcp9RsRV7tVmYjZh). 94 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/major-concepts/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "scoring-thresholds": "Scoring thresholds", 3 | "credential-map-and-weights": "Credential Map and Weights", 4 | "deduplicating-stamps": "Deduplicating Stamps", 5 | "expirations": "Stamp and score expiry", 6 | "api-pagination": "API pagination", 7 | "educating-users": "Educating users" 8 | } 9 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/major-concepts/api-pagination.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: API pagination 3 | description: Learn how to paginate through API responses. 4 | --- 5 | 6 | # API pagination 7 | 8 | Some requests are likely to return a large amount of data. You can paginate it by adding `?limit=`, where `x` is the number of elements of the dataset you wish to return in each response, to the end of the request. This instructs the server to only send x "pages" of the response. 9 | 10 | For the Stamps endpoint, `x` refers to the number of Stamp objects to return in each response. The full request to the Stamp endpoint, including the pagination instruction and headers, could look as follows: 11 | 12 | ```bash 13 | curl --request GET 'https://api.passport.xyz/v2/stamps/{address}?limit=3' \ 14 | --header 'X-API-KEY: {API-KEY}' 15 | ``` 16 | 17 | In this example, the API will return three Stamps in each response. 18 | 19 | To help you navigate, the returned data includes values in the `prev` and `next` fields. These are endpoint URLs with pre-filled query parameters you can use to retrieve the previous or next chunk of data. Note that if you request a `limit` of 3, your `next` value is also going to have a `limit` of 3. For example, if the response contains Stamps 4, 5 and 6, the URL in `prev` will return Stamps 1, 2, and 3. The URL in `next` will return Stamps 7, 8, and 9. 20 | 21 | This is what a response looks like with the `next` and `prev` fields. Notice these fields values are endpoint URLs. 22 | 23 | ```json 24 | { 25 | "next": "https://api.passport.xyz/v2/stamps/{address}?token=bmVw%4dFNQ9fM3TcxMTcD%3D&limit=3", 26 | "prev": "https://api.passport.xyz/v2/stamps/{address}?token=c9fMTcHJlTcwdlxMNQ%3D%3D&limit=3", 27 | "items": [ 28 | { 29 | "version": "1.0.0", 30 | "credential": {...} 31 | } 32 | ] 33 | } 34 | ``` 35 | 36 | To retrieve the next page of results you can use the URL provided in the `next` field, in this case: 37 | 38 | ```bash 39 | curl --request GET 'https://api.passport.xyz/v2/stamps/{address}?token=bmVw%4dFNQ9fM3TcxMTcD%3D&limit=3' \ 40 | --header 'X-API-KEY: {API-key}' 41 | ``` 42 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/major-concepts/credential-map-and-weights.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Credential Map and Weights 3 | description: The Stamp-based verification system uses a set of Stamps and underlying weighted credentials to determine the score of a Passport. 4 | --- 5 | 6 | # Credential Map and Weights 7 | 8 | The Stamp-based verification system uses a set of Stamps and underlying weighted credentials to determine the score of a Passport. 9 | 10 | ## Stamps and credentials 11 | 12 | Each Stamp partner or concept has their own Stamp that users can see and interact with see in their Passport. Each Stamp can have one or multiple underlying weighted credentials, which represent an identity verification activity within the Stamp partner's ecosystem. 13 | 14 | The weights assigned to each credential represent how strong of a human signal the underlying verification activity represents. The higher the point allocation to a credential, the better the human signal. 15 | 16 | ## Custom Passport 17 | 18 | If you'd like to customize these credentials -- either remove them from your community's Passport or adjust the weights -- you can do so with [Custom Passport](../custom-passport.md). 19 | 20 | Custom Passport enables you to customize the Passport Stamp-based offering around your ecosystem's unique needs. Choose which credentials to include at which weights, and even create your own custom Stamps. 21 | 22 | Learn more about [Custom Passport](../custom-passport.md). 23 | 24 | 25 | ## Credential Map and Weights 26 | 27 | The following table will help you understand how to map the different available credentials to their corresponding Stamps and weights. It is sorted based on the Stamp, orderred highest points to least. 28 | 29 | *These weights were last updated December 2024* 30 | 31 | | Stamp | credential | new_weight | 32 | |--------------|--------------------------------------------------------------|------------| 33 | | ETH Activity | **total** | 22.541 | 34 | | | ETHScore#50 | 16.021 | 35 | | | ETHScore#90 | 2.926 | 36 | | | ETHScore#75 | 2.399 | 37 | | | ETHDaysActive#50 | 0.207 | 38 | | | ETHGasSpent#0.25 | 0.778 | 39 | | | ETHnumTransactions#100 | 0.210 | 40 | | NFT | **total** | 22.053 | 41 | | | NFTScore#50 | 16.246 | 42 | | | NFTScore#90 | 2.413 | 43 | | | NFTScore#75 | 2.362 | 44 | | | NFT | 1.032 | 45 | | Holonym | **total** | 17.547 | 46 | | | HolonymGovIdProvider | 16.026 | 47 | | | HolonymPhone | 1.521 | 48 | | GTC Staking | **total** | 12.506 | 49 | | | TrustedCitizen | 4.009 | 50 | | | SelfStakingGold | 2.700 | 51 | | | ExperiencedCommunityStaker | 2.161 | 52 | | | SelfStakingSilver | 2.066 | 53 | | | SelfStakingBronze | 0.897 | 54 | | | BeginnerCommunityStaker | 0.673 | 55 | | Coinbase | CoinbaseDualVerification | 10.042 | 56 | | Binance | BinanceBABT | 10.021 | 57 | | Idena | **total** | 9.736 | 58 | | | IdenaState#Newbie | 5.892 | 59 | | | IdenaState#Verified | 1.924 | 60 | | | IdenaState#Human | 1.921 | 61 | | Civic | **total** | 8.867 | 62 | | | CivicUniquenessPass | 5.005 | 63 | | | CivicLivenessPass | 3.038 | 64 | | | CivicCaptchaPass | 0.823 | 65 | | Gitcoin | **total** | 6.237 | 66 | | | GitcoinContributorStatistics#totalContributionAmountGte#1000 | 4.997 | 67 | | | GitcoinContributorStatistics#totalContributionAmountGte#100 | 1.017 | 68 | | | GitcoinContributorStatistics#totalContributionAmountGte#10 | 0.223 | 69 | | GitHub | **total** | 6.026 | 70 | | | githubContributionActivityGte#120 | 2.259 | 71 | | | githubContributionActivityGte#60 | 1.888 | 72 | | | githubContributionActivityGte#30 | 1.879 | 73 | | Linkedin | Linkedin | 1.531 | 74 | | Guild | **total** | 0.708 | 75 | | | GuildAdmin | 0.468 | 76 | | | GuildPassportMember | 0.240 | 77 | | Google | Google | 0.525 | 78 | | Discord | Discord | 0.516 | 79 | | Snapshot | SnapshotProposalsProvider | 0.239 | 80 | | Lens | Lens | 0.230 | 81 | | Safe | GnosisSafe | 0.222 | 82 | | ENS | Ens | 0.208 | 83 | | BrightID | Brightid | 0.202 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/major-concepts/deduplicating-stamps.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Deduplicating Stamps 3 | description: >- 4 | Stamp deduplication is important for preventing users from using the same 5 | Stamps across multiple Passports to influence some specific outcome. 6 | --- 7 | 8 | # Deduplicating Stamps 9 | 10 | ### Why is deduplication necessary? 11 | 12 | Stamp deduplication is a crucial feature that prevents users from amplifying their influence over some specific outcome by submitting the same Stamps across multiple Passports. 13 | 14 | It is important for users to be able to hold multiple Passports representing different user profiles that might be used to as identification in specific communities. However, without deduplication logic, this could allow users to repeatedly attach the same Stamps to multiple Passports, fooling an app into treating each Passport as a real, verified human. 15 | 16 | Deduplication ensures that a user can only associate an individual Stamp to one single identity within a specific context. 17 | 18 | 19 | 20 | ### Do you need to handle deduplication in your app? 21 | 22 | If your app uses a Passport default Scorer, then deduplication is already handled server-side. When you request a score through the API, we calculate scores after already deduplicating Stamps, meaning you don't have to implement any deduplication logic yourself. 23 | 24 | However, if you are using your own custom scoring mechanism based on Stamp data, you will have to implement deduplication for yourself. Each Stamp has a `hash` field that can be used as a unique identifer. You can store hashes and compare them across all your users' Passports to ensure they are not being used multiple times. Our Scorer uses a Last-In-First-Out mechanism to handle duplicates, but you might want to use your own algorithm in your custom Scorer. 25 | 26 | 27 | 28 | ### How does Human Passport handle duplicate Stamps? 29 | 30 | Passport handles the issue of Stamp duplication by automatically identifying and eliminating duplicate Stamps. This prevents users from using the same credentials to verify their Stamps and identity across multiple Passports. This ensures that each user in an application has a unique and consistent digital identity. 31 | 32 | By default, the Passport API uses a **Last In, First Out (LIFO)** Stamp deduplication method. 33 | 34 | This means that, in a given scoring instance, if a Passport holder submits a Stamp that has already been submitted by another user, the _duplicate_ Stamp is ignored and not counted towards the score. 35 | 36 | For example, let’s say you build an application that uses the Passport API to verify the unique humanity of your users. Two Passports, “Passport A” and “Passport B,” present the same Stamp based on the same Twitter account. In this scenario, the Last-in-First-out deduplication method would only count the Stamp instance that was submitted earliest, ignoring the one that was submitted later. 37 | 38 | For example, if Passport A submitted the Twitter Stamp first, followed by Passport B, your app would only count the instance of the Twitter Stamp submitted by Passport A. The same rule applies to any subsequent instances of the Stamp. 39 | 40 | This LIFO method ensures that each Passport’s score accurately reflects the unique identity of its holder. This prevents duplicate Stamps from skewing the verification process and prevents users from re-using evidence of personhood across multiple Passports within an application. 41 | 42 | ### Things to note 43 | 44 | Stamps are unique to scoring instances. For example, one user uses Passport holder A with one Twitter account in an application that uses scoring instance X, and another user uses the same Twitter account in a distinct Passport in an independent scoring instance Y. In this case, both users will get scored for the Twitter account. As long as the scoring instances are independent, there is no concern for double counting or interference between instances. This allows users to create multiple personas that they use in different contexts but prevents double-counting of their credentials within a context. 45 | 46 | The scores assigned to Passports will not change once they are issued. This means that there is no need to recalculate Passport scores or synchronize them again in case of duplicate Stamp submissions. Once a score is assigned to a Passport, it remains fixed and can be relied upon for future verifications, even if a duplicate Stamp is submitted by a new Passport. This makes the scoring process more efficient and streamlined, which is particularly important for large and complex applications that score a high volume of verifiable credentials. 47 | 48 | Also note that because Stamp deduplication is achieved using a 'last in, first out' model, it is possible for Passports with identical Stamps to return different scores from different Scorers. The reason is that if the identical passports A and B are submitted to Scorer 1 in the order `A,B`, the returned score could be different to the same Passports submitted to Scorer 2 in the order `B,A`, because different instances of duplicate Stamps would be removed. 49 | 50 | 51 | ### Summary 52 | 53 | The LIFO deduplication strategy has several benefits for Passport holders and developers. It ensures that each Passport holder (in other words, Ethereum address) is assessed based on their unique set of Stamps, and that no one receives an unfair advantage due to having the same Stamp as another Passport holder within a given scoring instance. This means that for applications using the Passport API, there will be no double-counting of Stamps within the app, ensuring a fair and accurate assessment of each user’s unique identity. 54 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/major-concepts/expirations.md: -------------------------------------------------------------------------------- 1 | # Expirations 2 | 3 | Stamps and scores eventually become invalid. This is a security feature that provides a degree of confidence that the Stamps and scores you query in your application are still valid. 4 | 5 | Without some mechanism for Stamp expiry, a Stamp issued once would remain valid forever, even if the evidence supporting that Stamp or score had long since changed. 6 | 7 | For example, a user could mint a Stamp using an account on some Web2 service in the small window between creating the account and it being shut down by the service's compliance team. Without expiry, you would not be able to tell, but with expiry, after some time the user would simply not be able to reverify the Stamp. 8 | 9 | The shorter the time between the issuance date and the expiration date, the more security you gain, but the trade off is that the user experience deteriorates because users are forced to reverify frequently. 10 | 11 | 12 | ## Offchain Stamps 13 | 14 | Offchain Stamps expire after 90 days. This is handled by the Human Passport server. 15 | 16 | Users can bump the expiry date by another 90 days by reverifying your Stamps on the [Passport app](https://app.passport.xyz). 17 | 18 | 19 | ## Onchain Stamps 20 | 21 | Like offchain Stamps, onchain Stamps also expire. For Passport attestations, there is a key in the schema called `Expiration Dates`. An integrator can query this field to see whether the current time is later or earlier than the `expiryDate` and use this to determine whether a Stamp has expired. The `expiryDate` is automatically set to 90 days after the `issuanceDate`. Reverification requires issuing a new Passport attestation. 22 | 23 | Onchain scores do not have an explicit expiry date associated with them. Integrators can use the attestation transaction time as a proxy for the issuance date. As a rule of thumb, we recommend expiring scores 90 days after it was created. Offchain Stamps also expire after 90 days. 24 | 25 | You can read more detail about onchain Samp and score expiry [here](../smart-contracts/onchain-expirations.md). 26 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/major-concepts/scoring-thresholds.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Scoring thresholds 3 | description: Explanation of the thresholds used to asess Passports. 4 | --- 5 | 6 | # Scoring thresholds 7 | 8 | A very common [use case](../../overview/use-cases.md) for Human Passport is gating access based on Passport scores. 9 | In order to do this, application owners have to determine a cutoff for users that are, and are not, allowed to access some content or function. 10 | Typically, this cutoff is a certain Passport score above which users are allowed access; otherwise they are blocked. 11 | This is known as the **threshold score**. 12 | 13 | ## Human Passport's Scorer 14 | 15 | The `Unique Humanity (binary)` Scorer provided on the Passport app applies a threshold to users' Passport scores. 16 | This is how the Scorer is able to return a binary Sybil/non-Sybil response. 17 | 18 | The algorithm adds up the weights of each Stamp owned by each user and compares the result to a pre-defined threshold value. 19 | Each users score either exceeds that threshold or it doesn't, making it possible to assign them a binary score. 20 | 21 | **The threshold used by the Passport app is 20**. 22 | 23 | This is designed to be an effective default threshold value for general-purpose use. 24 | 25 | Passport data scientists use datasets of known Sybils and known humans to analyze how credentials are used by good and bad actors, and what threshold most effectively separates the two groups. 26 | However, it is important to note that it is not a perfect system. Not all Sybils will be eliminated at that threshold. 27 | On the other hand, higher thresholds might create excessively high barriers to entry that eliminate honest human users. 28 | 29 | ## Trade-offs 30 | 31 | Choosing a threshold is always a balance between eliminating bad actors on the one hand, and making your application useable for honest humans on the other. 32 | A very high threshold will be more effective at eliminating Sybils because the time, effort and possibly money expended to meet the threshold are greater. 33 | This means it is less economically viable for bad actors to create large numbers of fake accounts. 34 | However, your honest users also have to meet those same criteria. 35 | If they are too onerous or difficult, your honest users might be unable or unwilling to participate. 36 | Therefore, there is always a balance to strike between widening honest participation and reducing dishonest participation. 37 | Where the right balance lies will differ from project to project. The Passport default of 20 is thought to be a good all round starting point. 38 | 39 | |Unique Humanity score | Effectiveness at eliminating Sybils | Risk of screening out real users | 40 | |---------------|---------------|---------------| 41 | | 20 | Effective | Low | 42 | | 25 | More effective | Medium | 43 | |30 | Most effective | High | 44 | 45 | 46 | By implementing your own Scorer, you can tweak the entry requirements to your application more finely. 47 | Not only can you change the threshold, but you can upweight or downweight certain Stamps that are particularly strong signals for your specific use-case. 48 | You could even have certain Stamps as absolute requirements, or use a combination of required Stamps and an overall score threshold. 49 | 50 | Learn more about custom Scorers in our [tutorial](../tutorials/client-side-scoring.md). 51 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/passport-api-v1/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "index": "Introduction", 3 | "api-reference": "API reference", 4 | "data-dictionary": "Data dictionary" 5 | } 6 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/passport-api-v1/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Passport API v1 overview 3 | description: General overview of the Passport API v1 4 | --- 5 | import { Callout } from 'nextra/components'; 6 | 7 | # Passport API v1 8 | 9 | 10 | **Please note:**
In November 2024, we soft-launched [Passport API v2](/building-with-passport/stamps/passport-api).

We have not announced any deprecation or retirement timelines for v1 yet, but do strongly recommend using v2 moving forward.

You can learn more about the differences between v1 and v2 via our [migration guide](migrate). 11 | 12 | 13 | ## Available v1 endpoints 14 | 15 | | Endpoint action | Endpoint | 16 | | ------------------------------------------- | ------------------------------------------- | 17 | | Retrieval of signing messages | `GET /registry/signing-message` | 18 | | Submitting Passports for scoring or refresh | `POST /registry/submit-passport` | 19 | | Retrieval of scores for one address | `GET /registry/score/{scorer_id}/{address}` | 20 | | Retrieval of scores for multiple addresses | `GET /registry/score/{scorer_id}` | 21 | | Retrieval of Stamps linked to Passports | `GET /registry/stamps/{address}` | 22 | | Retrieval of all available Stamps | `GET /registry/stamp-metadata` | 23 | | Retreival of community staking amounts | `GET /registry/gtc-stake/{address}` | 24 | 25 | Learn more about each of these endpoints on our [API Reference](api-reference) page. 26 | 27 | ## Next steps 28 | 29 | Learn more about the Passport API v1: 30 | * [API reference](api-reference) 31 | * [Data dictionary](data-dictionary) 32 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/passport-api-v1/tutorials.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Tutorials (v1) 3 | description: Landing page for the Passport API v1 tutorials. 4 | --- 5 | import { Callout } from 'nextra/components'; 6 | import { Cards, Card } from 'nextra/components' 7 | 8 | # Tutorials 9 | 10 | This section includes several tutorials for integrating Human Passport into your apps with v1 of the API. 11 | 12 | * [Gating access with Passport scores](tutorials/gating-access-with-passport-scores) 13 | * [Retrieve Passport data and display it to your UI](tutorials/integrating-stamps-and-scorers) 14 | * [How to retrieve, handle and display Stamp metadata in a simple app](tutorials/working-with-stamp-metadata) 15 | * [Requiring a Passport score for airdrop claim](tutorials/requiring-a-passport-score-for-airdrop-claim) 16 | * [Integrating onchain Stamp data using smart contracts](tutorials/integrating-onchain-stamp-data) 17 | 18 | 19 | **Please note:**
In November 2024, we soft-launched [Passport API v2](/building-with-passport/stamps/passport-api).

We have not announced any deprecation or retirement timelines for v1 yet, but do strongly recommend using v2 moving forward.

We are actively working on updating the v1 tutorials to use v2.

You can learn more about the differences between v1 and v2 via our [migration guide](migrate). 20 | 21 | 22 | 23 | ## Where to start 24 | 25 | If you are taking your first steps into building apps with the Passport API, please make sure to use [Passport API v2](/building-with-passport/stamps/passport-api). All of the below tutorials are still using v1 of the API. 26 | 27 | If you need additional support or you have questions about developing with Passport, you can chat in our dedicated developer support channel on [Telegram](https://t.me/+Mcp9RsRV7tVmYjZh). 28 | 29 | 30 | ## Tutorials 31 | 32 | ### Gating access with Passport scores 33 | 34 | This tutorial will guide you through building a simple "knowledge hub" app with some specific content that can only be accessed by users with a Passport score above a threshold. 35 | Read more about thresholds on the [scoring thresholds](../major-concepts/scoring-thresholds) page. 36 | 37 | The app is built using [Next.js](https://nextjs.org/), [Chakra-ui](https://chakra-ui.com/), and [ethers](https://docs.ethers.org/v5/). 38 | 39 | 40 | 41 | 42 | 43 | ### Integrating Stamps and scores 44 | 45 | This tutorial will guide you through building a simple app that shows whether a user is "trusted" or not based upon their Passport score and ownership of specific Stamps. Multiple users can connect to the app and the Stamps they own are displayed in the app's UI. 46 | 47 | The app is built using [Next.js](https://nextjs.org/), [Chakra-ui](https://chakra-ui.com/), and [ethers](https://docs.ethers.org/v5/). 48 | 49 | 50 | 51 | 52 | 53 | ### How to retrieve, handle and display Stamp metadata in a simple app 54 | 55 | This tutorial will guide you through building a simple app that displays the Stamps that are connected to a specified wallet and Passport. 56 | 57 | The app is built using [Next.js](https://nextjs.org/), [Chakra-ui](https://chakra-ui.com/), and [ethers](https://docs.ethers.org/v5/). 58 | 59 | 60 | 61 | 62 | 63 | ### Requiring a Passport score for airdrop claim 64 | 65 | This guide demonstrates using Passport scores to shield your airdrop from airdrop farmers and other bad actors. 66 | 67 | This app is built using [Next.js](https://nextjs.org/), [RainbowKit](https://www.rainbowkit.com/docs/installation), and [wagmi](https://wagmi.sh/). 68 | 69 | 70 | 71 | 72 | 73 | ### How to integrate onchain Passport data using smart contracts 74 | 75 | _Please note that this tutorial is not related to the Passport API, and instead uses the Passport smart contract stack._ 76 | 77 | This tutorial will guide you how to show different content to users depending on their Passport data, all pulled from the blockchain. 78 | 79 | The app is built using [Next.js](https://nextjs.org/), [Chakra-ui](https://chakra-ui.com/), and [ethers](https://docs.ethers.org/v5/). 80 | 81 | 82 | 83 | 84 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/passport-api-v1/tutorials/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "gating-access-with-passport-scores": "Protecting access with Passport scores", 3 | "integrating-stamps-and-scorers": "Integrating Stamps and Scorers", 4 | "working-with-stamp-metadata": "Working with Stamp metadata", 5 | "requiring-a-passport-score-for-airdrop-claim": "Requiring a Passport score for airdrop claim", 6 | "client-side-scoring": "Custom client-side Passport scoring" 7 | } -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/passport-api/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "index": "Introduction", 3 | "getting-access": "Getting access", 4 | "quick-start-guide": "Quick start", 5 | "api-reference": "API reference", 6 | "data-dictionary": "Data dictionary", 7 | "status-and-error-codes": "Status and error codes", 8 | "migrate": "Migrate: v1 to v2" 9 | } -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/passport-api/getting-access.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Getting access to the Passport API v2 3 | description: Explainer for how to get access to the Passport API v2. 4 | --- 5 | import { Callout } from 'nextra/components' 6 | 7 | # Getting Access: Scorer ID and API Key 8 | 9 | The Passport API provides programmatic access to a wallet's Passport score. Once you have your API key, you need to include it with each request you make to the API. This allows Human Passport to identify your app and verify that you are authorized to access the API. 10 | 11 | ### Getting Your API Key 12 | 13 | 1. **Log in to the developer portal:** Go to [developer.passport.xyz](https://developer.passport.xyz) and log in to your account by connecting your wallet. 14 | 2. **Navigate to the API Keys section:** After logging in, go to the "API Keys" section. 15 | 3. **Generate an API key:** Click on the "+ Create a Key" button to generate a unique API key for your account. 16 | 4. **Store your API key securely:** Store your API key in a secure place, as it will be used to access the Passport API. 17 | 18 | 19 | ### Getting your Scorer ID 20 | A Scorer is an developer element that can be used to organize different use cases. You need to create a Scorer and associated Scorer ID to be able to request user data via the Passport API. If you are using the Passport API in multiple use cases, you should set up separate Scorers for each one. 21 | 22 | 1. **Log in to the Developer Portal:** Go to [developer.passport.xyz](https://developer.passport.xyz) and log in to your account by connecting your wallet. 23 | 2. **Navigate to the Scorer section:** After logging in, go to the "Scorer" section 24 | 3. **Create a Scorer:** Click on the "+ Create a Scorer" button and input a Scorer name, description, and [score threshold](/building-with-passport/stamps/major-concepts/scoring-thresholds) (recommended 20). You only need to add a score threshold if you plan to use the Passport Embed product, or plan to use the `passing_score` field in the Passport API response. 25 | 4. **Find your Scorer ID:** Once created, you can find your Scorer ID from the main Scorers page in the Developer Portal. 26 | 27 | ### Next step 28 | 29 | * [Make your first API request](quick-start-guide) 30 | * [Review the API Reference to learn more about the available endpoints](api-reference) -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/passport-api/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Passport API v2 overview 3 | description: General overview of the Passport API v2 4 | --- 5 | import { Callout } from 'nextra/components' 6 | 7 | # Passport API v2 8 | 9 | The Passport API serves as a powerful tool for developers, offering access to Passport's Stamp-based score metadata using REST endpoints. 10 | 11 | ## Why use the API 12 | 13 | The API offers a simple integration; one that requires just two requests to submit and request user Human Passport data. This data is retrieved from the centralized Human Passport servers, meaning it is the most up-to-date data available for Human Passport users. 14 | 15 | ### Example flow 16 | 17 | An excellent [use case](/overview/use-cases) for Human Passport is to protect access to a reward or governance program. To make this happen, follow these steps: 18 | 19 | 1. [Creating a Passport Project/Scorer and API key](getting-access) 20 | 2. Retrieve a user's Passport score and Stamp data using the [GET /v2/stamps/\{scorer_id\}/score/\{address\}](api-reference#retrieve-latest-score-for-a-single-address) endpoint. 21 | 3. Find the user's Unique Humanity Score or `passing_score` within the returned data. 22 | 3. Compare the Unique Humanity Score against a [threshold](../major-concepts/scoring-thresholds) that you set, or utilize the binary `passing_score` field that uses our recommended threshold of 20. 23 | 24 | If a user was able to build up a score greater than this threshold, they've effectively proven their humanity and you can grant access to the protected program. 25 | 26 | ## Available endpoints 27 | 28 | | Endpoint action | Endpoint | 29 | | ----------------------------------------------- | ------------------------------------------- | 30 | | [Retrieve latest score for a single address](#retrieve-latest-score-for-a-single-address) | `GET /v2/stamps/{scorer_id}/score/{address}` | 31 | | [Retrieve historical score for a single address](#retrieve-historical-score-for-a-single-address) | `GET /v2/stamps/{scorer_id}/score/{address}/history` | 32 | | [Retrieve Stamps verified by a single address](#retrieve-stamps-verified-by-a-single-address) | `GET /v2/stamps/{address}` | 33 | | [Retrieve all Stamps available in Passport](#retrieve-all-stamps-available-in-passport) | `GET /registry/stamp-metadata` | 34 | 35 | Learn more about each of these endpoints on our [API Reference](api-reference) page, or experiment with them using our [API playground](https://api.passport.xyz/v2/docs) (requires [API key and Scorer/Project](getting-access)). 36 | 37 | ## Next steps 38 | 39 | * [Set up an API key and Scorer/Project](getting-access) 40 | * [Make your first API request](quick-start-guide) 41 | * [Review the API Reference to get to know the available endpoints](api-reference) 42 | * [Get support via our Telegram channel](https://t.me/+Mcp9RsRV7tVmYjZh) 43 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/passport-api/migrate.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Passport API migration guide 3 | description: This guide explains the differences between v1 and v2 of the Passport API 4 | --- 5 | 6 | # Passport API v2 migration guide 7 | 8 | Migrating to Passport API V2 is designed to be straightforward. This guide outlines the key changes and provides step-by-step instructions to help you update your integration smoothly. 9 | 10 | But first, why should you migrate? 11 | * Retrieve user scores with a single, intuitive GET request. 12 | * Utilize new endpoints to access historical scores and Stamp data. 13 | * Gain access to more data to proactively prevent and resolve misunderstandings. 14 | * Retrieve both binary and numeric scores within the same payload 15 | * Benefit from a more unified API endpoint URI structure. 16 | 17 | If you'd prefer to learn by doing, please visit our [API playground](https://api.passport.xyz/v2/docs) to see the changes in action. 18 | If you'd prefer to learn via our reference docs, please visit our [API reference](api-reference). 19 | 20 | 21 | ## Key changes to address 22 | 1. [The base URL](#the-base-url) 23 | 2. [Simplified score retrieval](#simplified-score-retrieval) 24 | 3. [Updated endpoint URIs](#updated-endpoint-uris) 25 | 4. [Accessing historical data](#accessing-historical-data) 26 | 5. [Unified Scorer types](#unified-scorer-types) 27 | 6. [Additional Stamp data in score payload](#additional-stamp-data-in-score-payload) 28 | 29 | ## The base URL 30 | In August 2024, the Passport workstream spun out of Gitcoin, creating Passport XYZ. 31 | 32 | We have been working on separating our infrastructure from Gitcoin, and the API base URL is finally getting its update. 33 | 34 | * Previous Base URL: https://api.passport.gitcoin.co 35 | * New Base URL: https://api.passport.xyz 36 | 37 | **Action Required:** Update all instances of the base URL in your application to the new URL. 38 | 39 | ## Simplified score retrieval 40 | 41 | ### Background 42 | In V1, retrieving a user's score involved: 43 | * Submitting the Passport for scoring using a POST request. 44 | * Retrieving the score using a GET request. 45 | 46 | This process was counterintuitive and could lead to confusion and stale scores if only the GET endpoint was used. 47 | 48 | ### What's new in v2 49 | * **Single GET Request:** Retrieve the latest score and Stamp data with one GET request. 50 | * **No POST Required:** Eliminates the need to submit the Passport for scoring. 51 | 52 | ### Endpoint changes 53 | * **From V1:** `POST /registry/submit-passport` 54 | * **To V2:** `GET /v2/stamps/{scorer_id}/score/{address}` 55 | 56 | **Action Required:** Replace any `POST /registry/submit-passport` requests with GET requests to the new endpoint. 57 | 58 | 59 | ## Updated endpoint URIs 60 | We've adopted a more consistent, object-oriented design for our API endpoints. 61 | 62 | ### Endpoint mapping 63 | 64 | | From v1 | To v2 | 65 | |----------------------------------------------|-------------------------------------------------------| 66 | | `GET /registry/score/{scorer_id}/{address}` | `GET /v2/stamps/{scorer_id}/score/{address}` | 67 | | *New to v2* | `GET /v2/stamps/{scorer_id}/score/{address}/history` | 68 | | `GET /registry/stamps/{address}` | `GET /v2/stamps/{address}` | 69 | | `GET /registry/stamp-metadata` | `GET /v2/stamps/metadata` | 70 | | `GET /passport/analysis/{address}` | `GET /v2/models/score/{address}` | 71 | 72 | 73 | ## Accessing historical data 74 | 75 | ### New Feature in V2 76 | * **Endpoint:** GET /v2/stamps/{scorer_id}/score/{address}/history 77 | * **Functionality:** Retrieve a user's score and Stamp data from a specific date and time. 78 | 79 | Note: Access to this endpoint requires your API key to be allowlisted. 80 | 81 | **Action Required for use:** 82 | * **Request Access:** Fill out the [access request form](https://forms.gle/4GyicBfhtHW29eEu8) to have your API key allowlisted. 83 | * **Update Implementation:** Incorporate the new endpoint into your application if you need historical data. 84 | 85 | 86 | ## Unified Scorer types 87 | 88 | ### Background 89 | In V1, you had to choose between two Scorer types: 90 | * Unique Humanity 91 | * Unique Humanity: Binary 92 | 93 | This differentiation added complexity and could lead to confusion. 94 | 95 | ### What's New in V2 96 | * **Unified Scoring:** Both numeric and binary scores are included in all payloads. 97 | * **Simplified Choices:** No need to choose a Scorer type; you can use the score that best fits your application. 98 | 99 | ### Example v2 Payload 100 | ```json {3-5} filename="Sample response" 101 | { 102 | "address": "0x9c4de275772297e8fd4c458e6844f4e92ac82b74", 103 | "score": "31.885", 104 | "passing_score": true, 105 | "threshold": "20", 106 | "last_score_timestamp": "2024-12-02T22:21:25.723470+00:00", 107 | "expiration_timestamp": "2025-01-05T20:29:44.441000+00:00", 108 | "error": null, 109 | "stamps": { 110 | "Discord": { 111 | "score": "0", 112 | "dedup": true, 113 | "expiration_date": "2025-2-05T03:25:24.321000+00:00" 114 | }, 115 | "Ens": { 116 | "score": "0.408", 117 | "dedup": false, 118 | "expiration_date": "2025-01-05T20:29:44.441000+00:00" 119 | } 120 | } 121 | } 122 | ``` 123 | 124 | **Action Required:** Adjust your application's logic to handle the new payload structure and use the appropriate score type. 125 | 126 | 127 | ## Additional Stamp data in score payload 128 | 129 | ### Deduplication field 130 | 131 | To prevent multiple Passports from verifying the same credential (enhancing security against Sybil attacks), Stamps are [deduplicated](../major-concepts/deduplicating-stamps) across addresses. 132 | 133 | * **New Field:** `dedup` 134 | * **Purpose:** Indicates whether a Stamp has been deduplicated and thus does not contribute to the score. 135 | 136 | #### Example 137 | 138 | ```json /dedup/ 139 | "stamps": { 140 | "Discord": { 141 | "score": "0", 142 | "dedup": true, 143 | "expiration_date": "" 144 | }, 145 | "Ens": { 146 | "score": "0.408", 147 | "dedup": false, 148 | "expiration_date": "" 149 | } 150 | } 151 | ``` 152 | 153 | In the above example, you'll notice that the Discord Stamp is [deduplicated](/building-with-passport/stamps/major-concepts/deduplicating-stamps), meaning another address has also verified this same credential. As a result, the user received a 0 score for that Stamp. You will also note that a different expiration date returns when `dedup=true`. This date represents when the credential verified by the other address will expire, rather than when this credential will expire. 154 | 155 | You will also see that the ENS Stamp was not deduplicated, meaning the 0.408 score was included in the user's overall unique humanity score. 156 | 157 | **Action Required:** 158 | * **Handle Deduplication:** Update your application to interpret the dedup field and inform users if their Stamps are affected. 159 | * **User Communication:** Consider displaying warnings to users about deduplicated Stamps. 160 | 161 | ### Stamp expiration date 162 | 163 | * **New Field:** `expiration_date` for each credential. 164 | * **Purpose:** Indicates when each specific Stamp will expire. 165 | 166 | **Action required:** 167 | * **Monitor Expirations:** Use the `expiration_date` to notify users about upcoming Stamp expirations. 168 | * **Update Logic:** Ensure your application considers Stamp expiration dates in its functionality. 169 | 170 | 171 | ## Next Steps Checklist 172 | 173 | 1. Update Base URL to https://api.passport.xyz. 174 | 2. Modify all API endpoint URIs to the new V2 structure. 175 | 3. Replace POST requests with GET requests for score retrieval. 176 | 4. Update your data models and logic to accommodate new fields (`passing_score`, `dedup`, `expiration_date`). 177 | 5. If needed, submit the access request form for the historical endpoint and build it into your integration. 178 | 6. Thoroughly test your application to ensure all changes work as expected. 179 | 180 | If you have questions or need support, you can chat with us on our [developer support channel on Telegram](https://t.me/+Mcp9RsRV7tVmYjZh). 181 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/passport-api/quick-start-guide.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Passport API v2 quick start guide 3 | description: Beginner guide covering the basics of the Passport API v2. 4 | --- 5 | import { Callout } from 'nextra/components' 6 | 7 | # Quick Start 8 | 9 | This page will help you make your first API request using the Passport API v2. 10 | 11 | You can also experiment with the Passport API using our [API playground tool](https://api.passport.xyz/v2/docs) and adding your API keys via the 'Authorize' button. 12 | 13 | ## API basics 14 | 15 | Please make sure you have an [API key and Scorer ID](getting-access) before working through this guide. 16 | 17 | The base URL for the API methods we'll be using is `https://api.passport.xyz`. There are several API endpoints that can be accessed by extending this base URL. 18 | 19 | You can browse more specific API details in the [API reference](api-reference). 20 | 21 | ## How to retrieve a score 22 | 23 | There is one basic step to retrieve a user's Passport score and Stamp data. All you have to do is make a request to the following GET endpoint: 24 | 25 | ``` 26 | GET /v2/stamps/{scorer_id}/score/{address} 27 | ``` 28 | 29 | This endpoint requires a `scorer_id` and an `address` to be passed as path parameters. You can see an example of this in the following cURL request, using a scorer ID, `100`; an address, `0x2C1E111d7C3adc823B5fA3af3f07EB62831C3c5`; and a placeholder (`{your-api-key}`) that you need to replace with your API key: 30 | 31 | ```bash filename="Sample request" copy 32 | curl --request GET \ 33 | --url https://api.passport.xyz/v2/stamps/100/score/0x2C1E111d7C3adc823B5fA3af3f07EB62831C3c5 \ 34 | --header 'X-API-KEY: {your-api-key}' 35 | ``` 36 | 37 | An example response might look as follows: 38 | 39 | ```json filename="Sample response" 40 | { 41 | "address": "0x2C1E111d7C3adc823B5fA3af3f07EB62831C3c5", 42 | "score": "33.538", 43 | "passing_score": true, 44 | "last_score_timestamp": "2024-11-17T14:46:22.900951+00:00", 45 | "expiration_timestamp": "2025-02-06T14:28:06.879000+00:00", 46 | "threshold": "20", 47 | "error": null, 48 | "stamp_scores": { 49 | "Discord": "0.516", 50 | "Google": "0.525", 51 | "NFT": "1.032", 52 | "SnapshotProposalsProvider": "0.839", 53 | "zkSyncScore#5": "1.67", 54 | "zkSyncScore#20": "1.67", 55 | "zkSyncScore#50": "1.67", 56 | "ZkSyncEra": "0.606", 57 | "Lens": "0.93", 58 | "ETHGasSpent#0.25": "1.003", 59 | "GuildPassportMember": "0.54", 60 | "CivicUniquenessPass": "6.005", 61 | "TrustaLabs": "0.511", 62 | "BinanceBABT": "16.021" 63 | } 64 | } 65 | ``` 66 | 67 | This response indicates that the address was successfully able to prove their humanity with Passport since their score is above the recommended threshold of 20. 68 | 69 | It's worthwhile to note that you can manually set your own [score threshold](../major-concepts/scoring-thresholds) within your code base based on your ecosystem's unique needs, but a score threshold of 20 is recommended for optimal results. 70 | 71 | 72 | ### Next Steps 73 | 74 | * [Review the API Reference to learn more about the available endpoints](api-reference) 75 | * [Get support via our Telegram channel](https://t.me/+Mcp9RsRV7tVmYjZh) 76 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/passport-api/status-and-error-codes.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Status and error codes 3 | description: Reference documentation for the status and error codes returned from the Passport API. 4 | --- 5 | 6 | # Status and error codes 7 | 8 | ## HTTP Status codes 9 | 10 | | Code | Title | Description | 11 | | ---- | --------------------- | ------------------------------- | 12 | | 200 | OK | The request was successful. | 13 | | 400 | Bad request | Bad request | 14 | | 401 | Unauthorized | Your API key is invalid. | 15 | | 404 | Not found | The resource does not exist. | 16 | | 429 | Too Many Requests | The rate limit was exceeded. | 17 | | 500 | Internal Server Error | An error occurred with our API. | 18 | 19 | 20 | 21 | ## Error types 22 | 23 | All errors are returned in the form of JSON with a detail explaining the error 24 | 25 | > Example error response. 26 | 27 | ```json 28 | { 29 | "detail": "string" 30 | } 31 | ``` 32 | 33 | | Error Detail | Description | 34 | | ------------------------------------------ | -------------------------------------------------------------------------------- | 35 | | Invalid nonce | The `nonce` used in the submit Passport API request could not be verified | 36 | | Address does not match signature | The signer could not be verified | 37 | | Invalid limit | The page limit of the Passport API request is greater than 1000 | 38 | | Unable to get score for provided Scorer ID | Unable to validate that the Scorer ID belongs to the account holding the API key | 39 | | Unauthorized | `X-API-Key` was not specified in the header or an invalid API key was provided | 40 | | Internal Server Error | Something went wrong on our end | 41 | 42 | 43 | --- 44 | 45 | If you have questions about the API, please reach out to us in our [developer support channel](https://t.me/+Mcp9RsRV7tVmYjZh). 46 | 47 | More detailed information about this API's endpoints can be found in the [API reference](../api-reference). -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/passport-embed/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "index": "Introduction", 3 | "getting-access": "Getting access", 4 | "quick-start-guide": "Quick start", 5 | "tutorials": "Tutorials", 6 | "customization": "Customization", 7 | "component-reference": "Component reference" 8 | } -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/passport-embed/customization.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Passport Embed - Customization 3 | description: A guide to customizing Passport Embed. 4 | --- 5 | 6 | import { Callout } from 'nextra/components' 7 | 8 | # Passport Embed - Customization 9 | 10 | The Passport Embed widget is fully themeable, allowing you to match its appearance to your application's design system. You can customize colors, fonts, border radius, padding, transition timing, and z-index positioning. 11 | 12 | ## Collapse Mode 13 | 14 | With Passport Embed, you can control the widget’s **collapsible behavior** and how it is displayed relative to your page layout. 15 | 16 | There are three options for collapse mode: 17 | * **`"shift"`** (default): the widget is embedded in the flow and expanding it will push/shift surrounding content (useful if placing at top of a page, for example). 18 | * **`"overlay"`**: the widget will overlay on top of content when expanded (using CSS `position:absolute` or similar, on top of the page, with an overlay background perhaps – the `overlayZIndex` theme can be used to adjust stacking). 19 | * **`"off"`**: collapse functionality is disabled; the widget is always fully expanded (use this if you want the full widget visible at all times in a particular spot). 20 | 21 | You can experiment with these modes to see which best fits your UI. 22 | 23 | ## Using Built-in Themes 24 | 25 | Passport Embed provides two built-in themes: `DarkTheme` and `LightTheme`. You can import them from the package and pass them directly to the widget’s theme prop. By default, the widget will use `DarkTheme`. 26 | 27 | ```jsx 28 | import { PassportScoreWidget, DarkTheme, LightTheme } from "@human-tech/passport-embed"; 29 | 30 | 36 | ``` 37 | 38 | If your app supports dynamic theming, you can toggle between these based on the user's preference: 39 | 40 | ```jsx 41 | const theme = isDarkMode ? DarkTheme : LightTheme; 42 | ``` 43 | 44 | These built-in themes provide a solid foundation and follow best practices for accessibility and contrast. 45 | 46 | ### Extending or Overriding Theme Properties 47 | 48 | You can also override specific theme values by spreading one of the defaults and replacing the properties you'd like to change: 49 | 50 | ```jsx 51 | const customTheme = { 52 | ...DarkTheme, 53 | colors: { 54 | ...DarkTheme.colors, 55 | primary: "255, 255, 0" 56 | } 57 | }; 58 | ``` 59 | 60 | ### Full Theme Schema 61 | 62 | The PassportWidgetTheme object lets you customize the look and feel of the widget. 63 | 64 | All fields are optional — if a value is not specified, the defaults from the selected base theme (DarkTheme or LightTheme) will be used. 65 | 66 | ```jsx 67 | export type PassportWidgetTheme = { 68 | colors?: { 69 | primary?: string; 70 | secondary?: string; 71 | background?: string; 72 | success?: string; 73 | failure?: string; 74 | }; 75 | padding?: { 76 | widget?: { 77 | x?: string; 78 | y?: string; 79 | }; 80 | }; 81 | radius?: { 82 | widget?: string; 83 | button?: string; 84 | }; 85 | transition?: { 86 | speed?: string; 87 | }; 88 | font?: { 89 | family?: { 90 | body?: string; 91 | heading?: string; 92 | alt?: string; 93 | }; 94 | }; 95 | position?: { 96 | overlayZIndex?: string; 97 | }; 98 | }; 99 | ``` 100 | 101 | ### Tips & Requirements 102 | * `colors.*` must be defined using RGB format — for example: "255, 255, 0" (Hex codes and named colors are not supported) 103 | * Font families must reference fonts that are already loaded on the page, except for the widget defaults 104 | * `overlayZIndex` is only applied when `collapseMode` is set to `overlay` 105 | * Use `transition.speed` to fine-tune widget animation timing (e.g. `0.2s`, `0.5s`) 106 | * All values are optional — anything you omit will fall back to the base theme 107 | 108 | 109 | ### Example 110 | 111 | ```jsx 112 | 123 | ``` 124 | 125 | ## Next Step 126 | 127 | Once your theme is set, head over to the [Component Reference](component-reference) to see all other available props. 128 | 129 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/passport-embed/getting-access.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Getting access to Passport Embed 3 | description: Explainer for how to get access to Passport Embed. 4 | --- 5 | 6 | import { Callout } from 'nextra/components' 7 | 8 | 9 | # Getting Access: Scorer ID and API Key 10 | 11 | Once you have your API key, you need to include it in your integration with Passport Embed. This allows Human Passport to identify your app and verify that you are authorized to access the API. 12 | 13 | 14 | You will need to [reach out to the Passport team](https://tally.so/r/3X81KL) to gain access to the Passport Embed product. 15 | 16 | 17 | 18 | **Please Note:**
19 | You will need to create two API keys to use the Passport Embed product. One will be used for the actual Embed component, while the other will be used to make requests to the Passport API. 20 | 21 | You should only use a single Scorer for both the Embed and the Passport API requests. 22 | 23 | 24 | ### Getting Your API Key 25 | 26 | 1. **Log in to the developer portal:** Go to [developer.passport.xyz](https://developer.passport.xyz) and log in to your account by connecting your wallet. 27 | 2. **Navigate to the API Keys section:** After logging in, go to the "API Keys" section. 28 | 3. **Generate an API key:** Click on the "+ Create a Key" button to generate a unique API key for your account. Make sure to create one for the embed component and another for the Passport API requests. 29 | 4. **Store your API key securely:** Store your API key in a secure place. 30 | 31 | 32 | ### Getting your Scorer ID 33 | A Scorer is an developer element that can be used to organize different use cases. You need to create a Scorer and associated Scorer ID to be able to set up Passport Embed and your Passport API requests. 34 | 35 | 1. **Log in to the Developer Portal:** Go to [developer.passport.xyz](https://developer.passport.xyz) and log in to your account by connecting your wallet. 36 | 2. **Navigate to the Scorer section:** After logging in, go to the "Scorer" section 37 | 3. **Create a Scorer:** Click on the "+ Create a Scorer" button and input a Scorer name, description, and [score threshold](/building-with-passport/stamps/major-concepts/scoring-thresholds) (recommended 20). You will *only need one* for both the embed component and the Passport API. 38 | 4. **Find your Scorer ID:** Once created, you can find your Scorer ID from the main Scorers page in the Developer Portal. 39 | 40 | ## Pricing and Access 41 | 42 | To learn more about accessing the Passport Embed product, please [contact the Human Passport team](https://tally.so/r/3X81KL). 43 | 44 | ### Next step 45 | 46 | * [Quick start guide to Passport Embed](quick-start-guide) 47 | * [Review the Component Reference guide](component-reference) -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/passport-embed/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Passport Embed 3 | description: Passport Embeds is a premium offering that lets websites integrate Human Passport's Stamps-based verification directly on their website or app, eliminating the need for users to be redirected elsewhere. 4 | --- 5 | 6 | import { Callout } from 'nextra/components' 7 | 8 | # Passport Embed 9 | 10 | ## Introduction 11 | 12 | Passport Embeds is a premium offering that lets websites integrate Human Passport's [Stamps-based verification](/building-with-passport/stamps) directly on their website or app, eliminating the need for users to be redirected elsewhere​. In essence, Passport Embeds provides an on-site widget for proof of humanity, ensuring that communities and applications remain Sybil-resistant (protected from fake or duplicate accounts) without adding user friction. 13 | 14 | Core Benefits: 15 | * **Frictionless User Experience:** Users can verify their identity within your app or site (no external redirects), leading to higher conversion and less drop-off​. The verification process is quick and preserves privacy, requiring only a crypto wallet and approved credentials rather than personal data. 16 | * **Powerful Sybil Protection:** Backed by the Human Passport scoring system, it effectively distinguishes real users from bots. You can gate content or features based on Passport scores (for example, only users above a certain score can access an airdrop) to keep out malicious actors​. 17 | * **Targeted for Web3 Communities:** Ideal for dApps, DAOs, forums, or any platform where one-person-one-account is vital. It enables ecosystems to protect and grow their communities organically by ensuring each participant is unique​. 18 | * **Key Differentiators:** Passport Embeds is a privacy-preserving alternative to traditional KYC or CAPTCHA. It uses verifiable credentials (“Stamps”) to calculate a trust score, so site owners never receive sensitive personal info – only a score or pass/fail status. Unlike other solutions, Passport Embeds is decentralized and user-first​, meaning users maintain control over their data and can prove their humanity without sacrificing anonymity. 19 | 20 | Overall, the Passport Embeds widget brings the power of Human Passport’s identity verification directly into your application. It’s designed for both developers and decision-makers who want to boost security and trust in their platform while keeping the user experience seamless and on-brand. 21 | 22 | ## User flow 23 | 24 | The user flow for Passport Embeds is as follows: 25 | 26 | 1. The user visits your website or app and encounters a program that's protected by the Passport Embed widget. 27 | 2. If the user is not connected to a wallet, the widget will prompt them to connect their wallet. 28 | 3. Once connected, the widget will fetch the user's Passport score if they have one. 29 | 4. If the user's score is above a specified threshold (20 by default), the widget will show a success state and inform you that the user is verified. If not, the widget will automatically verify any web3 Stamps that the user qualifies for. 30 | 5. If the user's score is still below the threshold, the widget will walk users through pages of different Stamps that they can verify to build up their score. Once they build up a high enough score, they will be notified that the program is unlocked and they can participate. 31 | 6. [Future optional feature] Once a user builds up a high enough score, they can mint their Passport onchain to one of Passport's supported networks. Once done, they will be notified that the program is unlocked and they can participate. 32 | 33 | ## Customizations 34 | 35 | The widget can be [customized](customization) in a number of ways, including: 36 | 37 | * You can set the theme to dark or light. 38 | * You can additionally adjust several color, font, and spacing options. 39 | * You can set the widget to collapse to a smaller size, and the behavior of surrounding content when it expands. 40 | * [Future customization] You will be able to choose which Stamps display, which order those Stamps are displayed, and what each Stamp's weighting is. 41 | * [Future customization] You will be able to require users to mint their Passport onchain to one of Passport's supported networks. 42 | 43 | ## Pricing and Access 44 | 45 | To learn more about accessing the Passport Embeds product, please [contact the Human Passport team](https://tally.so/r/3X81KL). 46 | 47 | ## Next Steps 48 | 49 | * [Getting access to Passport Embed](getting-access) 50 | * [Quick start guide](quick-start-guide) 51 | * [Tutorial: Protecting Sensitive Programs with Passport Embed](tutorial/protecting-sensitive-programs-with-passport-embed) 52 | * [Component reference](component-reference) -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/passport-embed/quick-start-guide.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Passport Embed - Quick start 3 | description: A quick guide to setting up Passport Embed. 4 | --- 5 | 6 | import { Callout } from 'nextra/components' 7 | 8 | # Passport Embed - Quick Start 9 | 10 | Get up and running with Passport Embed in just a few minutes. This section provides a beginner-friendly setup for both React and non-React environments, covering the essential configuration and a simple integration example. 11 | 12 | ## Obtain Your Credentials 13 | 14 | If you haven't already, please generate an API key and a Scorer ID by following the steps in our [getting access guide](getting-access). You will also need to [reach out to the Passport team](https://tally.so/r/3X81KL) to gain access to the Passport Embed product. 15 | 16 | ## Installing and Importing 17 | 18 | Here's the simplest way to render the widget in a React app. 19 | 20 | **Step 1. Install the NPM package:** 21 | 22 | Add the Passport Embed React package to your project: 23 | 24 | ```bash 25 | npm install @human-tech/passport-embed 26 | # or 27 | yarn add @human-tech/passport-embed 28 | ``` 29 | 30 | **Step 2. Import the component in your React code and render it where appropriate.** 31 | 32 | First we'll provide you a code example, then we'll break down each prop. 33 | 34 | ```jsx 35 | import { PassportScoreWidget, DarkTheme, LightTheme, usePassportScore } from "@passportxyz/passport-embed"; 36 | 37 | const PASSPORT_API_KEY = ""; 38 | const PASSPORT_SCORER_ID=""; 39 | 40 | function MyPage() { 41 | const { passingScore } = usePassportScore({ 42 | apiKey: PASSPORT_API_KEY, 43 | scorerId: PASSPORT_SCORER_ID, 44 | address: userAddress 45 | }); 46 | 47 | const signMessage = async (message: string): Promise => { 48 | const accounts = await window.ethereum.request({ method: "eth_requestAccounts" }); 49 | return await window.ethereum.request({ 50 | method: "personal_sign", 51 | params: [message, accounts[0]] 52 | }); 53 | }; 54 | 55 | return ( 56 | 63 | ); 64 | } 65 | ``` 66 | 67 | This minimal example renders the Passport widget. 68 | 69 | At a minimum, you should pass your `apiKey`, the `scorerId`, the user's `address` (if already known), and a `generateSignatureCallback` function (described below) that will be called to sign any required messages. 70 | 71 | If you don't already have the user's address, you can optionally pass a `connectWalletCallback` function (described below) to prompt the user to connect their wallet via your connection flow. 72 | 73 | You can optionally set a `theme` prop to apply a dark or light theme. 74 | 75 | A final note that we provide a React hook called `usePassportScore()` that fetches the user's score and tells you whether they've passed the threshold — so you can reactively show or hide content in your app. But — frontend values can be spoofed, so don’t trust it for sensitive program protection. Instead, use `passingScore` as a signal to trigger a backend verification request via the [Passport API](/building-with-passport/stamps/passport-api). The Passport API will actually confirm the score server-side, meaning you can confidently unlock protected features based on the user's score. 76 | 77 | 78 | #### Example signature callback for OAuth Stamps 79 | 80 | The Passport Stamps product includes several OAuth-based Stamps (e.g. GitHub, Twitter, Discord) that users can verify to build up their score. 81 | 82 | These Stamps require a signature to confirm that the user completing the OAuth verification also controls the wallet address they’re associating with the Stamp. 83 | 84 | The following function can be included in your code to prompt the user to sign a challenge message with their wallet, proving wallet ownership and allowing the Passport backend to bind the OAuth identity to the correct address. This function should then be passed to the `generateSignatureCallback` prop: 85 | 86 | ```jsx 87 | const signMessage = async (message: string): Promise => { 88 | const accounts = await window.ethereum.request({ method: "eth_requestAccounts" }); 89 | return await window.ethereum.request({ 90 | method: "personal_sign", 91 | params: [message, accounts[0]] 92 | }); 93 | }; 94 | ``` 95 | 96 | #### Example connect wallet callback 97 | 98 | If you don't already have the user's wallet address, you can pass a `connectWalletCallback` function to prompt the user to connect their wallet. 99 | 100 | This is only necessary if: 101 | * You aren't already managing wallet connection elsewhere in your app, and 102 | * You're not using a wallet abstraction like Reown AppKit, which automatically provides the connected wallet address via a hook (e.g. `account?.address`). 103 | 104 | Here's an example of a simple function that could be passed to the `connectWalletCallback` prop: 105 | 106 | ```jsx 107 | const connectWallet = async () => { 108 | const accounts = await window.ethereum.request({ method: "eth_requestAccounts" }); 109 | return accounts[0]; 110 | }; 111 | ``` 112 | 113 | 114 | ## Next step 115 | 116 | * [Tutorial: Protecting Sensitive Programs with Passport Embed](tutorial/protecting-sensitive-programs-with-passport-embed) 117 | * Learn how to [customize Passport Embed](customization) 118 | * Review the [component reference guide](component-reference) 119 | * [Get support via our Telegram channel](https://t.me/+Mcp9RsRV7tVmYjZh) -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/passport-embed/tutorial/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "protecting-sensitive-programs-with-passport-embed": "Protecting sensitive programs with Passport Embed" 3 | } -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/smart-contracts/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "index": "Overview", 3 | "quick-start-guide": "Quick start", 4 | "integrating-onchain-stamp-data": "Tutorial", 5 | "attestation-schema": "Attestation schema", 6 | "onchain-expirations": "Onchain expirations", 7 | "test-mode": "Onchain testing", 8 | "contract-reference": "Contract reference" 9 | } 10 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/smart-contracts/attestation-schema.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Attestation schema 3 | description: Reference documentation for the Attestation schema used in Passport's smart contract stack. 4 | --- 5 | 6 | # Attestation schema 7 | 8 | Onchain Passports use Attestations to verify that a particular address owns specific Stamps. 9 | Ultimately, an Attestation is just a piece of data with a cryptographic signature. 10 | 11 | The data follows a known structure, known as a 'schema'. The schema is critical because it ensures the signing participant 12 | knows what they are signing, and provides a uniform data layout that enables users to decode the Attestations. 13 | 14 | The schema is *the layout of information being attested*. 15 | The signature is the proof that a known, trusted verifier has seen the data and attested that it is truthful. 16 | 17 | There is currently a single attestation written when users mint their Passports onchain, the Human Passport attestation. 18 | 19 | ## Human Passport attestation schema 20 | 21 | [Human Attestation Schema on EAS](https://optimism.easscan.org/schema/view/0xda0257756063c891659fed52fd36ef7557f7b45d66f59645fd3c3b263b747254) 22 | 23 | The raw schema looks as follows: 24 | 25 | ``` 26 | bool passing_score, uint8 score_decimals, uint128 scorer_id, uint32 score, uint32 threshold, tuple(string provider, uint256 score)[] stamps 27 | ``` 28 | 29 | You can see an example Human Passport attestation on the Optimism network by visiting the following link: 30 | 31 | [Example Human Passport attestation on Optimism](https://optimism.easscan.org/attestation/view/0xb6612e9191aaf5741420f4933a509c60f558b6fd2ee769befe3cc07805690a68) 32 | 33 | ### Fields 34 | 35 | The fields in the Human Passport attestation are as follows: 36 | 37 | - `passing_score` (bool): A boolean flag indicating whether the address's score meets or exceeds the threshold value. 38 | - `score_decimals` (uint8): The number of decimal places used for score precision. Set to `4` 39 | - `scorer_id` (uint128): A unique identifier for the scoring algorithm instance. 40 | - `score` (uint32): The raw numerical score calculated for the address. 41 | - `threshold` (uint32): The minimum score required to achieve a passing grade. Default is set to `200000`, the recommendation from the Passport team. However, this can be updated by partners who have set a custom threshold using Custom Passport. 42 | - `stamps` (tuple[]): An array of tuples containing verified credentials and their weights, where each tuple contains: 43 | - A string representing the stamp provider/type (e.g., "CoinbaseDualVerification2", "HolonymGovIdProvider") 44 | - A uint256 representing the weight/score contribution to the overall score 45 | 46 | Example raw data: 47 | ```solidity 48 | { 49 | passing_score: true, 50 | score_decimals: 4, 51 | scorer_id: 335, 52 | score: 922910, 53 | threshold: 200000, 54 | stamps: [ 55 | ["CoinbaseDualVerification2", 100420], 56 | ["HolonymGovIdProvider", 160260], 57 | ["githubContributionActivityGte#60", 18880] 58 | // ... additional stamps 59 | ] 60 | } 61 | ``` 62 | 63 | ## Accessing User Attestation Data 64 | 65 | To access a user's attestation data, please use the decoder contract, which is documented via the [contract reference](/building-with-passport/smart-contracts/contract-reference#decoder-contract) 66 | 67 | 68 | ## Deprecated attestations (as of March 12th, 2025) 69 | 70 | ### Passport (Stamp) attestation schema 71 | 72 | The raw schema looks as follows: 73 | 74 | ``` 75 | uint256[] providers, bytes32[] hashes, uint64[] issuanceDates, uint64[] expirationDates, uint16 providerMapVersion 76 | ``` 77 | 78 | Notice that the types for all these fields are numerical types or raw bytes. 79 | This is because the human-readable information is compressed and encoded before being added to the attestation. 80 | 81 | You can see an example of a Stamp attestation on the Optimism network by visiting the following link: 82 | 83 | [Example Passport (Stamp) attestation on Optimism](https://optimism.easscan.org/attestation/view/0xd53526d72b9e9283a70894ddfba32513b722a939d85c1a6be402416d29cdc0b9) 84 | 85 | #### Fields 86 | 87 | The fields are as follows: 88 | 89 | - `providers`: a u256 that is actually a bitmap where each position maps to a provider name. The mapping is made available offchain. 90 | - `hashes`: an ordered array of elements, with each element being 32 raw bytes. Each element in the array is a 32-byte hash that maps to a known Stamp. A provider might have multiple Stamps that each have a hash. The mapping is made available offchain. 91 | - `issuanceDates`: an ordered array of elements, with each element being 32 raw bytes. Each element represents the UNIX timestamp when the Stamp was verified. 92 | - `expirationDates`: an ordered array of elements, with each element being 32 raw bytes. Each element represents the UNIX timestamp when the Stamp expires. 93 | - `providerMapVersion`: an unsigned integer specifying which version of the `providers` mapping the Attestation conforms to. This allows updates as providers are added and removed from the canonical set. 94 | 95 | 96 | ### Score attestation schema 97 | 98 | The raw schema looks as follows: 99 | 100 | ``` 101 | uint256 score, uint32 scorer_id, uint8 score_decimals 102 | ``` 103 | 104 | You can see an example of a score attestation on the Optimism network by visiting the following link: 105 | 106 | [Example score attestation on Optimism](https://optimism.easscan.org/attestation/view/0x1d7832d2f4e5e71da3d8b0ceee72faf4cd44990057b21a26d9f775b911fe1bfe) 107 | 108 | #### Fields 109 | 110 | The fields are as follows: 111 | 112 | - `score`: the user's Passport score as an unsigned integer 113 | - `scorer_id`: the ID number for the specific Scorer instance that issued the `score` 114 | - `score_decimals`: number of decimals in `score`, similar to how ETH is divided into 1e18 Wei. 115 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/smart-contracts/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Smart Contract Introduction 3 | description: A general overview of Human Passport's onchain technology stack. 4 | --- 5 | 6 | # Onchain Passports 7 | 8 | Human Passport's onchain functionality enables users to store their verified Stamps and scores onchain, and makes this data available via smart contracts. 9 | 10 | We also discuss the onchain use cases in the following resources: 11 | * [Quick start: Get to "Hello World" with the smart contracts](quick-start-guide) 12 | * [Tutorial: Building an app using onchain Passport data](integrating-onchain-stamp-data) 13 | * [Reference: Learn about the available smart contracts and typical onchain developer flow](contract-reference) 14 | 15 | ## Why onchain? 16 | 17 | In addition to accessing Human Passport data offchain using the Passport API, Human Passport has also released a smart contract stack that enables developers to access Passport score and Stamp data directly from the blockchain. 18 | 19 | This onchain Passport data enables partners that want to maintain a decentralized, permissionless backend to engage directly with our smart contracts instead of storing and processing Passport data pulled from our API. 20 | 21 | ## Why not onchain? 22 | 23 | Minting Passports onchain is an optional feature for users. Not all users will add their Passports onchain. Also, onchain Passports may not reflect the most up-to-date data for users, since the onchain mint is point-in-time and users could verify more Stamps or Stamps could expire (note that onchain attestations expire). 24 | 25 | ## Onchain Passport 26 | 27 | Passport data can be converted into onchain attestations that are stored and engaged with via the [Ethereum Attestation Service (EAS)](https://attest.sh/) or [Verax](https://ver.ax/), which make that data accessible to developers via smart contracts. This enables quadratic funding, rewards, governance, access control, and other programs to exist entirely onchain with their Passport integration. 28 | 29 | A simplified onchain Passport data flow follows this process: 30 | 1. A user decides to [mint their Passport onchain](https://support.passport.xyz/passport-knowledge-base/using-passport/onchain-passport) to one of the available networks via the Passport App. 31 | 2. Passport creates a [Stamp (Passport)](https://optimism.easscan.org/schema/view/0xd7b8c4ffa4c9fd1ecb3f6db8201e916a8d7dba11f161c1b0b5ccf44ceb8e2a39) and [score](https://optimism.easscan.org/schema/view/0x6ab5d34260fca0cfcf0e76e96d439cace6aa7c3c019d7c4580ed52c6845e9c89) attestation, and mints them onchain to EAS and other attestation registries, depending on which network they choose. 32 | 3. A developer utilizes our [smart contract stack](/building-with-passport/smart-contracts/contract-reference#how-to-query-for-onchain-passport-data) and users’ wallet addresses to request the Passport data from these onchain attestation registries. 33 | 4. The developer uses this Passport data in their web3 programs to satisfy their [use case](/overview/use-cases). 34 | 35 | Of course, there are some additional complexities to this, including [Stamp expirations](onchain-expirations). 36 | 37 | ## Available networks 38 | 39 | This onchain smart contract stack is currently deployed to the following networks: 40 | 41 | Mainnet 42 | * Arbitrum 43 | * Base 44 | * Linea 45 | * Optimism 46 | * Scroll 47 | * Shape 48 | * ZkSync 49 | 50 | Testnet 51 | * Base Goerli 52 | * Optimism Sepolia 53 | * Scroll Sepolia 54 | * Shape Sepolia 55 | * ZkSync Sepolia 56 | 57 | Please note that you can explore our testnet functionality via the app using [Test Mode](test-mode). 58 | 59 | ## Available registries 60 | 61 | Attestations will be minted to one or two different registries, depending on which network the user chose to push their Passport. 62 | 63 | * All onchain Passports will be minted to EAS, regardless of which network the user selects. 64 | * If the user selects Linea or Linea Goerli, the full attestation will be written to EAS, and a partial attestation will be written to Verax. 65 | 66 | ## Why isn't Human Passport onchain by default? 67 | 68 | Human Passport is entirely opt-in. Users can still use Human Passport without migrating your data onchain. 69 | 70 | While onchain Passports are in their infancy, the offchain Passport is useful as a single source. The offchain infrastructure is also perfectly sufficient for many use cases. 71 | 72 | ## Next steps 73 | 74 | Learn more about onchain Passports: 75 | * [Quick start](quick-start-guide) 76 | * [Tutorial](integrating-onchain-stamp-data) 77 | * [Contract reference](contract-reference) 78 | * [Attestation schema](attestation-schema) 79 | 80 | You can also ask questions about onchain Passports in our [developer support channel on Telegram](https://t.me/+Mcp9RsRV7tVmYjZh) 81 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/smart-contracts/onchain-expirations.md: -------------------------------------------------------------------------------- 1 | # Onchain expirations 2 | 3 | Passport Stamps do not stay valid forever. There is an expiration date after which a Stamp must be reverified in order to keep it valid. This is true for onchain and offchain Stamps. 4 | 5 | ## Passport attestations 6 | 7 | For Passport attestations, there is a key in the schema called `Expiration Dates`. The value associated with this key is an array of hex-encoded dates, each corresponding to a specific Stamp. There is also an equivalent key, `IssuanceDate` whose values encode the date when a particular Stamp was verified. 8 | 9 | New attestations can be issued with updated `IssuanceDate` and `expirationDate` values through the Passport app. 10 | 11 | Here's an example of a [Passport attestation](https://optimism.easscan.org/attestation/view/0x6eefab4afe1610e21c8d7e7cd1d4f4d70fd753fc2bfe6b04ad4bd01dec86c81a) 12 | 13 | ## Score attestations 14 | 15 | Onchain scores do not have an explicit expiry date associated with them. If you are an integrator, you could use the attestation transaction time as a proxy for the issuance date if the age of the score is important for your application. As a rule of thumb, we recommend expiring scores 90 days after it was created. Offchain Stamps also expire after 90 days. 16 | 17 | Here's an example of a [score attestation](https://optimism.easscan.org/attestation/view/0x5beb4300ff732dce2bdec86fb97df3a23787c9f1ff90c06bff6bc86dea74aa6c). 18 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/smart-contracts/quick-start-guide.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Smart contract quick start guide 3 | description: Quick start guide to get you up and running with Human Passport's smart contracts. 4 | --- 5 | 6 | # Smart contract quick start 7 | 8 | The Human Passport smart contracts are deployed on several chains, covering both testnets and live networks. 9 | There are several contracts that interact with each other to provide the Human Passport backend and API. 10 | 11 | This quick start will illustrate different ways that you can quickly test pulling data from the Passport `decoder` contract. 12 | 13 | ## Retrieving data from Block Explorers 14 | 15 | 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. 16 | 17 | 1. Navigate to the `decoder` contract on a [network](../contract-reference#contract-addresses) supported by onchain Passport. In this example, we'll use the [`decoder` deployed to the Optimism Sepolia network](https://sepolia-optimism.etherscan.io/address/0xe53C60F8069C2f0c3a84F9B3DB5cf56f3100ba56). 18 | 2. Make sure the `Read as Proxy` tab is open. This is where you can view the methods exposed by the contract. 19 | 3. Open the `getPassport()` or `getScore()` method. 20 | 4. Enter a ETH wallet address, click `Query`, and view the results. 21 | 22 | Available methods: 23 | * The `getPassport` method will provide the Stamps owned by the given address in the browser. 24 | * 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. 25 | * There are also several lower level functions that give access to encoded data and intermediate values. 26 | 27 | Here's what a response from `getPassport` function on the block explorer looks like: 28 | 29 | ![](public/basescan.png) 30 | 31 | 32 | ## Retrieving data programmatically 33 | 34 | You can also query the API programmatically from the terminal or in an app. 35 | 36 | The steps are: 37 | - 1. instantiate a web3 provider 38 | - 2. instantiate the decoder contract 39 | - 3. call the contract functions 40 | 41 | Here's a minimal example of how to call the `getPassport()` and `getScore()` methods using `Web3js` in a Javascript app: 42 | 43 | ## Instantiate a web3 provider 44 | 45 | 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. 46 | 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. 47 | 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. 48 | 49 | To use an RPC provider: 50 | 51 | ```js 52 | const Web3 = require("web3"); 53 | const rpcUrl = ''; 54 | const web3 = new Web3(new Web3.providers.HttpProvider(rpcUrl)); 55 | ``` 56 | 57 | To use a local node (in this case, Geth using IPC): 58 | 59 | ```js 60 | var web3 = new Web3(new Web3.providers.IpcProvider('/Users/myuser/Library/Ethereum/geth.ipc', net)) 61 | ``` 62 | Now you have a variable, `web3` representing your web3 connection. You can use this to interact with contracts on the blockchain. 63 | 64 | **Note** please ensure your web3 provider is connected to the correct network. 65 | 66 | 67 | ## Instantiate the decoder contract 68 | 69 | Instantiating a contract allows you to interact with a contract deployed on the blockhain as if it were a Javascript object. 70 | This requires you to pass the contract ABI (application Binary Interface) and the address on the blockchain where the contract is deployed. 71 | 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. 72 | The Passport decoder contract ABI can be found on both block explorers and the [Passport Github](https://github.com/passportxyz/eas-proxy/blob/main/deployments/abi/GitcoinPassportDecoder.json). 73 | 74 | ```js 75 | var Contract = require('web3-eth-contract'); 76 | var abi = 77 | 78 | var contract = new Contract(jsonInterface, address); 79 | ``` 80 | 81 | The `contract` variable is a Javascript object exposing the contract methods. 82 | 83 | 84 | ## Call the contract methods 85 | 86 | You can use the contract methods just like Javascript object methods, i.e. `contract.method(args)`. 87 | To call the decoder contract's `getPassport()` method: 88 | 89 | ```js 90 | var passportInfo = contract.getPassport("") 91 | ``` 92 | 93 | To call the contract's `getScore()` method: 94 | 95 | ```js 96 | var score = contract.getScore("") 97 | ``` 98 | 99 | 100 | ## Summary 101 | 102 | This quick start guide demonstrated how to grab information from the Human Passport decoder contract. 103 | You have the option to query the contract using the block explorer UI or programatically using a library such as `web3js`. 104 | There are equivalent libraries in other languages too, such as [`web3py`](https://web3py.readthedocs.io/en/stable/) for Python, [`web3`](https://pkg.go.dev/github.com/gochain/web3) for Go, 105 | and `ethers` for [Rust](https://github.com/gakonst/ethers-rs) and [Javascript](https://docs.ethers.org/v5/). 106 | 107 | 108 | ## Next steps 109 | 110 | Explore our [contract reference page](./contract-reference.mdx) to find all the details about the various Human Passport contract deployments. 111 | Then you could try our more advanced [smart contract app tutorial](./integrating-onchain-stamp-data.md). 112 | 113 | If you have more questions you can chat in our [developer support channel on Telegram](https://t.me/+Mcp9RsRV7tVmYjZh). 114 | -------------------------------------------------------------------------------- /pages/building-with-passport/stamps/smart-contracts/test-mode.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Test mode 3 | description: How to test the onchain infrastructure 4 | --- 5 | 6 | # Testing Onchain Passport 7 | 8 | As developers, we often want to test our apps and integrations on testnets, where there is nothing of real world value at stake, before we go live on a live public mainnet. You can always deploy the Human Passport smart contracts to your own local ephemeral blockchain, but it is also recommended to test your integration on a public testnet too, as this more realistically simulates a mainnet environment. 9 | 10 | For this reason, the Passport team deployed the Passport smart contracts on public testnets, including OP Sepolia and Linea Goerli. 11 | 12 | ## Test mode in the Passport app 13 | 14 | The Passport app can be run in test mode by visitng URL and following the steps below: 15 | 16 | https://app.passport.xyz#/testing/dashboard 17 | 18 | This enables you to write Passport data and scores to the Human Passport smart contracts on several testnets, meaning you can experiment and get comfortable with the flows before trying it out on Mainnet. 19 | 20 | When you sign in to the Passport app, you first have to enable Test Mode. There is a button for this at the top of the page. Enabling Test Mode requires an additional signature from your Ethereum account. 21 | 22 | Once Test Mode is enabled, you can click on `Bring Passport onchain` towards the bottom of the Passport app to view the supported testnets in a panel that pops out from the right-hand side of the page. The app switches over to whichever network you select by clicking on the preferred network in the panel in the app's UI. 23 | 24 | Other than the network selection panel, the behavior of the test app is identical to the real, "live" Passport app. 25 | 26 | 27 | ## Test mode for developers 28 | 29 | Test mode also gives developers the ability to read and write to Passport smart contracts and also develop and test Passport integrations into their own smart contracts. On test networks, this can be done without spending any real ETH on gas fees and without putting any assets at risk from exploits. 30 | 31 | Since the Passport contracts are deployed on public testnets as can be used by anyone, there are proper Passport data and many integrations on these testnets that offer a much more realistic test environment than local, ephemeral blockchains and the Passport contracts are already deployed there and managed by the passport team, easing your development process. 32 | 33 | To work in Test Mode, developers simply have to switch their development environments onto one of the supported test networks and use the appropriate contract addresses for that network. 34 | 35 | 36 | ## Which networks are supported? 37 | 38 | The available test networks are: 39 | 40 | - [Optimism Sepolia](https://sepolia-optimism.etherscan.io/) 41 | - [Linea Goerli](https://docs.linea.build/) 42 | 43 | 44 | ## Testing on mainnet forks 45 | 46 | The Passport smart contracts may sometimes be upgraded after being deployed. If you are testing on a mainnet fork, you must make sure you fork the blockchain at a block *after* the latest contract deployment. Otherwise, the contracts stored in your forked blockchains state will be out of date. The block where the latest version of the contract is deployed is known as the `latest stable block` and you can find out what it is by looking at the contract deployment details on the appropriate block explorer for the network you want to fork. Then, fork the blockchain at a block greater to or equal to the `latest stable block`. 47 | 48 | For example, the latest stable block for OP mainnet is 115525426. Your test network must fork off OP mainnet at a block >= 115525426. 49 | -------------------------------------------------------------------------------- /pages/community/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "getting-involved": "How to Contribute", 3 | "passport-github-projects": "Passport GitHub Projects", 4 | "style-guide": "Style Guide" 5 | } -------------------------------------------------------------------------------- /pages/community/getting-involved.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Getting involved 3 | description: How to contribute to Human Passport 4 | --- 5 | 6 | # How to contribute 7 | 8 | ## Identity Providers 9 | 10 | If you're an identity provider and want to integrate with the Human Passport check out the documentation for Integrating a new stamp into the Passport. 11 | 12 | [Creating a new Stamp](/building-with-passport/stamps/create-a-stamp) 13 | 14 | 15 | ## App Builders 16 | 17 | If you have an app that has integrated the Passport let us know! We're happy to offer support and would love to hear about your experience building with the Passport API. 18 | 19 | Come find us in our [Human Passport Developers Telegram](https://t.me/+Mcp9RsRV7tVmYjZh). 20 | 21 | 22 | ## DevRel and Tech Writers 23 | 24 | If you spot some areas to improve our docs visit our [Github](https://github.com/passportxyz/passport-docs). 25 | 26 | We'd love to get your PRs incorporated and help make this documentation as comprehensive and accessible as possible! 27 | 28 | You can also chat on our [developer support channel on Telegram](https://t.me/+Mcp9RsRV7tVmYjZh). -------------------------------------------------------------------------------- /pages/community/passport-github-projects.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Passport Github projects 3 | description: A collection of projects using Human Passport 4 | --- 5 | 6 | import { Cards, Card } from 'nextra/components' 7 | 8 | 9 | # Human Passport Github Projects 10 | 11 | ## Production Passport Codebase 12 | 13 | 14 | 15 | 16 | 17 | ## Ceramic Nodes 18 | 19 | 20 | 21 | 22 | 23 | -------------------------------------------------------------------------------- /pages/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Human Passport Developer Platform 3 | description: An overview of the developer tools made available by Human Passport. 4 | --- 5 | 6 | import { Cards, Card } from 'nextra/components' 7 | 8 | # Human Passport Docs 9 | 10 | Human Passport is an identity verification application and Sybil resistance protocol. 11 | 12 | Developers can utilize the different Human Passport products and services to build a unique humanity solution for their app or project, enabling more trustworthy and fair participation in their community. Less Sybils and bad actors means higher quality engagements and long-term success. 13 | 14 | These developer docs describe the different Human Passport developer products and services that you can use to protect your community. 15 | 16 | ## Who are you? 17 | 18 | ### Passport user 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | --- 27 | 28 | ### Developer building with Human Passport 29 | 30 | #### Passport Stamps 31 | 32 | Passport Stamps is the core product of Human Passport, and the primary way to verify a user's identity and trustworthiness. 33 | 34 | With Passport Stamps, users can choose how they prove their unique humanity by verifying different Stamps, or verifiable credentials, which represent high human signal activities throughout web3 and web2. Users can choose to verify with KYC, biometrics, web3 activity, web of trust, and web2 activity Stamps to build up a score, which can then be used by builders to protect access or classify addresses. 35 | 36 | Passport Stamps data is made available via the [Passport API](building-with-passport/passport-api). Users can optionally push their Passport Stamps data onchain, which can be accessed by developers using our [smart contracts](building-with-passport/smart-contracts). 37 | 38 | The core Passport Stamps offering is free, but additional premium add-ons ([Custom Passport](building-with-passport/custom-passport) and [Passport Embed](building-with-passport/passport-embed)) can be added to your integration to reduce user friction and customize your unique human verification experience. 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | You can also apply to [become a Stamp provider](/building-with-passport/stamps/create-a-stamp). 48 | 49 | --- 50 | 51 | #### Passport Models 52 | 53 | Passport Models is a real-time verification product that enables you to classify any EVM address as Sybil or human, without requiring users to have a Passport Stamps account. It offers reduced user friction and provides a quick way to verify addresses. 54 | 55 | The model scores made available by the [Models API](building-with-passport/models) are generated using Human Passport's machine learning models that analyze address onchain activity on ETH L1 and several L2s, and compares that activity against the activity of massive lists of known Sybils and humans. 56 | 57 | Passport Models can be used as a quick primary verification method for your community to pass high-quality users. It can also be used alongside Passport Stamps, enabling an frictionless experience to those that pass the Models check, and a secondary verification option with the Stamp-based verification system. 58 | 59 | 60 | 61 | 62 | 63 | --- 64 | 65 | #### Data services 66 | 67 | Human Passport also offers data services to partners who need to better understand whether a list of addresses is Sybil or human. 68 | 69 | These data services include the following types of analyses for each address provided: 70 | * Sybil classification using Passport Models 71 | * Sybil clustering analysis 72 | * Diamond hands analysis 73 | * Custom analysis requested by specific partners 74 | 75 | As part of these engagements, the Passport data team will provide actionable recommendations, as well as embed with your team to make sure you know how to use the data services effectively. 76 | 77 | 78 | 79 | 80 | 81 | --- 82 | 83 | ## Get involved 84 | 85 | 86 | 87 | 88 | 89 | 90 | -------------------------------------------------------------------------------- /pages/overview/_meta.json: -------------------------------------------------------------------------------- 1 | { 2 | "index": "Why Human Passport?", 3 | "use-cases": "Use Cases", 4 | "active-integrations": "Active Integrations", 5 | "key-terms": "Key Terms", 6 | "changelog": "Changelog" 7 | } -------------------------------------------------------------------------------- /pages/overview/active-integrations.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Active integrations 3 | description: A list of partners who have active integrations with Passport, and links to guides. 4 | --- 5 | 6 | import { Cards, Card } from 'nextra/components' 7 | 8 | # Active Passport integrations 9 | 10 | This page contains a condensed list of active integrations that have produced guides detailing how to leverage Passport within each ecosystem. 11 | 12 | To find a complete list of ecosystem partners, please visit the following page: 13 | 14 | 15 | 16 | 17 | 18 | 19 | ## Guild.xyz 20 | 21 | [Guild.xyz](https://guild.xyz/explorer) is a the infrastructure for platformless access management. Create portable memberships, social structures around on- & off-chain requirements and build unique user journeys across apps. 22 | 23 | It's a great tool to gate access to Discord roles, Telegram channels, and more. 24 | 25 | You can use a certain Passport score threshold as a requirement to gain access to your community tools. 26 | 27 | 28 | 29 | 30 | 31 | 32 | ## Snapshot 33 | 34 | Snapshot is a voting platform that allows DAOs, DeFi protocols, or NFT communities to vote easily and without gas fees. 35 | 36 | Snapshot enables you to use Passport in two different ways: Gate access to submitting proposals, and gate access to voting. 37 | 38 | Learn more at the following link: 39 | 40 | 41 | 42 | 43 | 44 | 45 | ## Discourse 46 | 47 | Discourse is an open source Internet forum system that is used as a governance tool for many web3 organizations. 48 | 49 | You've got a few different opportunities to use Passport to assign roles and gate access! 50 | 51 | There are actually two different plugins that you can use with Discourse! We are more impressed with the level of documentation provided by Dappy.lol though. 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | ## Collab.land 60 | 61 | Collab.Land is a community management tool that supports a wide range of projects, including DAOs, NFT communities, brands, and creators of all sizes. 62 | 63 | As with any community management tool, roles are critical for providing different levels of access. The Collab.Land integration allows you to gate access to roles to just those users who can prove their humanity on Passport! 64 | 65 | Learn more here: 66 | 67 | 68 | 69 | 70 | 71 | 72 | ## Missing something? 73 | 74 | While we do list our full list of integration partners on our [ecosystem page](https://passport.human.tech/ecosystem), we want to continue to build out this page with links to partners who have instructions on how to use Passport within their ecosystem. 75 | 76 | If we missed a partner, please feel free to submit an issue or open up a pull request by clicking the "Edit this page" button in the right sidebar! -------------------------------------------------------------------------------- /pages/overview/changelog.mdx: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | ## May 19th, 2025 4 | 5 | We launched a major update to our developer documentation. 6 | 7 | This launch includes a significant overhaul of our product architecture, including the addition of Passport Embeds, and better organizing products into the Passport Stamps, Passport Models, and Data Services groupings. This update coincides with a major update to the Passport website, which also launched earlier this month. 8 | 9 | With any major update to our documentation, we recommend that you review the updated documentation to ensure that you are using the latest features and best practices. We'd also love to hear your feedback! Please feel free to [submit an issue to our GitHub repo](https://github.com/passportxyz/passport-docs/issues/new/choose) if you see anything that doesn't make sense, or any broken redirects. 10 | 11 | ## May 15th, 2025 12 | 13 | We launched a new Stamp to the Passport Stamps product. 14 | 15 | The new Stamp is called Proof of Clean Hands, and it checks to see if a given address and associated government ID is listed on any sanctions lists, including but not limited to the OFAC sanctions list, all US sanctions lists, and specific UN lists. 16 | 17 | you can learn more about this Stamp via our [Proof of Clean Hands documentation](https://support.passport.xyz/passport-knowledge-base/stamps/how-do-i-add-passport-stamps/the-proof-of-clean-hands-stamp). If a user has verified this Stamp, you will be able to see that they verified this Stamp via the [Passport API](/building-with-passport/stamps/passport-api) and [smart contracts](/building-with-passport/stamps/smart-contracts). 18 | 19 | ## May 12th, 2025 20 | 21 | We launched a new version of our Models API aggregate model, as well as a new Base model. 22 | 23 | The new models are available via the `GET /v2/models` endpoint, with the aggregate model being the default and the Base model being available via the `model` query parameter. 24 | 25 | You can learn more about the models in the [Models API documentation](/building-with-passport/models). 26 | 27 | ## March 12th, 2025 28 | 29 | We made several updates to Onchain Passport based on developer feedback. 30 | 31 | - We have reduced the number of onchain attestations that we write for users from two to just one. 32 | - We have updated the [Onchain Passport attestation schema](/building-with-passport/smart-contracts/attestation-schema) to be more developer-friendly. 33 | - We have deprecated the hash that was returned with the decoder contract's `getPassport` method. 34 | - We've introduced a new method, `getScore` (0xdaadd662), which accepts a scorer ID (communityID) and user address, and returns the current score of a user for that scorer. This can be used by partners who are using [custom scores](/building-with-passport/stamps/custom-passport). At this time, there is no way to request Stamp-specific Custom Passport data from onchain. 35 | 36 | ## Context 37 | 38 | We produced the Changelog as part of the March 12th, 2025 release of Passport. We may backfill several product updates in the future. -------------------------------------------------------------------------------- /pages/overview/index.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Why Human Passport 3 | description: A short explanation of why we are building Human Passport. 4 | --- 5 | 6 | # Why Human Passport? 7 | 8 | **Human Passport is a Sybil resistance protocol and identity aggregation dApp built on the Ceramic Network. Users can collect various identity attestations, called "Stamps", from web2 and web3 authenticators all in one place.** 9 | 10 | Many systems, like Gitcoin Grants, assume each participant is a unique human, and offer rewards for these participants. This makes them vulnerable to Sybil attacks, where a bad actor creates a large number of pseudonymous identities to subvert the service’s reputation system, gain a disproportionate amount of influence, and direct rewards towards extractors. 11 | 12 | Credible identity verification and reputation mechanisms are essential to combat this. Applications liked BrightID, ENS, and POAP each help suggest whether an account is associated with a real human, but they are only truly powerful when they compose with each other. 13 | 14 | Projects need a way to evaluate these disparate "identity providers" altogether. 15 | 16 | **That's where Human Passport comes in.** 17 | 18 | We originally created Passport for Gitcoin's needs: to [defend Gitcoin's Grants program from Sybil attacks](https://youtu.be/v1Dm7FI2AdU) so that only real people can help decide which projects receive funds from a shared matching pool. 19 | 20 | One thing we have learned from defending the Gitcoin Grants program is this: Sybil defense is complicated and resource intensive. Yet it is essential for any web3 project that hopes to have longevity, because users will not stick around if your project is filled with scammers. 21 | 22 | As we developed years of in-house expertise in Sybil defense, we saw a responsibility to help other web3 projects protect their communities from bots and bad actors. 23 | 24 | **Because we believe that private identity verification is a public good, we decided to turn Passport into its own product.** 25 | 26 | With dozens of identity providers using Passport to protect their communities, Passport is on track to become the leading, open-source identity verification protocol in the world. 27 | -------------------------------------------------------------------------------- /public/2023-08-04 10-13-01.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/2023-08-04 10-13-01.mp4 -------------------------------------------------------------------------------- /public/Passport Airdrop (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/Passport Airdrop (1).png -------------------------------------------------------------------------------- /public/Passport Airdrop.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/Passport Airdrop.png -------------------------------------------------------------------------------- /public/Screenshot from 2023-08-04 10-17-11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/Screenshot from 2023-08-04 10-17-11.png -------------------------------------------------------------------------------- /public/Screenshot from 2023-08-04 10-17-16.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/Screenshot from 2023-08-04 10-17-16.png -------------------------------------------------------------------------------- /public/Screenshot from 2023-08-04 10-17-19.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/Screenshot from 2023-08-04 10-17-19.png -------------------------------------------------------------------------------- /public/api-key.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/api-key.png -------------------------------------------------------------------------------- /public/app-failure.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/app-failure.png -------------------------------------------------------------------------------- /public/app-success.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/app-success.png -------------------------------------------------------------------------------- /public/bankless.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/bankless.jpg -------------------------------------------------------------------------------- /public/bankless2.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/bankless2.jpg -------------------------------------------------------------------------------- /public/bankless3.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/bankless3.jpg -------------------------------------------------------------------------------- /public/bankless4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/bankless4.png -------------------------------------------------------------------------------- /public/bankless5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/bankless5.png -------------------------------------------------------------------------------- /public/bankless6.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/bankless6.jpg -------------------------------------------------------------------------------- /public/basescan.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/basescan.png -------------------------------------------------------------------------------- /public/custom-scorer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/custom-scorer.png -------------------------------------------------------------------------------- /public/favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/favicon.png -------------------------------------------------------------------------------- /public/favicon.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | -------------------------------------------------------------------------------- /public/improve experience.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/improve experience.png -------------------------------------------------------------------------------- /public/logos/Passport_Lockup_Black.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /public/logos/Passport_Lockup_IceBlue.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /public/logos/Passport_Lockup_Iris.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /public/logos/Passport_Lockup_NightBlue.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /public/logos/Passport_Lockup_SeaFoam.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /public/logos/Passport_Lockup_White.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /public/onchain-stamp-explorer-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/onchain-stamp-explorer-1.png -------------------------------------------------------------------------------- /public/onchain-stamp-explorer-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/onchain-stamp-explorer-2.png -------------------------------------------------------------------------------- /public/onchain-stamp-explorer-3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/onchain-stamp-explorer-3.png -------------------------------------------------------------------------------- /public/passport-app-ethereum-activity.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/passport-app-ethereum-activity.png -------------------------------------------------------------------------------- /public/passport-hero.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/passport-hero.png -------------------------------------------------------------------------------- /public/passport-homepage.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/passport-homepage.png -------------------------------------------------------------------------------- /public/petstore-minimal.json: -------------------------------------------------------------------------------- 1 | { 2 | "swagger": "2.0", 3 | "info": { 4 | "version": "1.0.0", 5 | "title": "Swagger Petstore", 6 | "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", 7 | "termsOfService": "http://swagger.io/terms/", 8 | "contact": { 9 | "name": "Swagger API Team" 10 | }, 11 | "license": { 12 | "name": "MIT" 13 | } 14 | }, 15 | "host": "petstore.swagger.io", 16 | "basePath": "/api", 17 | "schemes": [ 18 | "http" 19 | ], 20 | "consumes": [ 21 | "application/json" 22 | ], 23 | "produces": [ 24 | "application/json" 25 | ], 26 | "paths": { 27 | "/pets": { 28 | "get": { 29 | "description": "Returns all pets from the system that the user has access to", 30 | "produces": [ 31 | "application/json" 32 | ], 33 | "responses": { 34 | "200": { 35 | "description": "A list of pets.", 36 | "schema": { 37 | "type": "array", 38 | "items": { 39 | "$ref": "#/definitions/Pet" 40 | } 41 | } 42 | } 43 | } 44 | } 45 | } 46 | }, 47 | "definitions": { 48 | "Pet": { 49 | "type": "object", 50 | "required": [ 51 | "id", 52 | "name" 53 | ], 54 | "properties": { 55 | "id": { 56 | "type": "integer", 57 | "format": "int64" 58 | }, 59 | "name": { 60 | "type": "string" 61 | }, 62 | "tag": { 63 | "type": "string" 64 | } 65 | } 66 | } 67 | } 68 | } -------------------------------------------------------------------------------- /public/protect-communication.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/protect-communication.png -------------------------------------------------------------------------------- /public/protect-governance.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/protect-governance.png -------------------------------------------------------------------------------- /public/protect-marketplace.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/protect-marketplace.png -------------------------------------------------------------------------------- /public/protect-rewardspng.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/protect-rewardspng.png -------------------------------------------------------------------------------- /public/prove-reputation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/prove-reputation.png -------------------------------------------------------------------------------- /public/quick-start-app (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/quick-start-app (1).png -------------------------------------------------------------------------------- /public/quick-start-app.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/quick-start-app.png -------------------------------------------------------------------------------- /public/robots.txt: -------------------------------------------------------------------------------- 1 | # * 2 | User-agent: * 3 | Allow: / 4 | 5 | # Host 6 | Host: https://docs.passport.xyz 7 | 8 | # Sitemaps 9 | Sitemap: https://docs.passport.xyz/sitemap.xml 10 | -------------------------------------------------------------------------------- /public/scorer-page.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/scorer-page.png -------------------------------------------------------------------------------- /public/scorer-use-case.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/scorer-use-case.png -------------------------------------------------------------------------------- /public/scoring-mechanisms.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/scoring-mechanisms.png -------------------------------------------------------------------------------- /public/sign-in-to-scorer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/sign-in-to-scorer.png -------------------------------------------------------------------------------- /public/sitemap-0.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | https://docs.passport.xyz2023-10-02T02:50:03.379Zdaily0.7 4 | https://docs.passport.xyz/building-with-passport/api-reference2023-10-02T02:50:03.379Zdaily0.7 5 | https://docs.passport.xyz/building-with-passport/contract-reference2023-10-02T02:50:03.379Zdaily0.7 6 | https://docs.passport.xyz/building-with-passport/getting-access2023-10-02T02:50:03.379Zdaily0.7 7 | https://docs.passport.xyz/building-with-passport/introduction2023-10-02T02:50:03.379Zdaily0.7 8 | https://docs.passport.xyz/building-with-passport/major-concepts/data-dictionary2023-10-02T02:50:03.379Zdaily0.7 9 | https://docs.passport.xyz/building-with-passport/major-concepts/deduplicating-stamps2023-10-02T02:50:03.379Zdaily0.7 10 | https://docs.passport.xyz/building-with-passport/major-concepts/onchain-passports2023-10-02T02:50:03.379Zdaily0.7 11 | https://docs.passport.xyz/building-with-passport/major-concepts/platform-integrator-concepts2023-10-02T02:50:03.379Zdaily0.7 12 | https://docs.passport.xyz/building-with-passport/major-concepts/status-and-error-codes2023-10-02T02:50:03.379Zdaily0.7 13 | https://docs.passport.xyz/building-with-passport/quick-start-guide2023-10-02T02:50:03.379Zdaily0.7 14 | https://docs.passport.xyz/building-with-passport/tutorials2023-10-02T02:50:03.379Zdaily0.7 15 | https://docs.passport.xyz/building-with-passport/tutorials/gating-access-with-passport-scores2023-10-02T02:50:03.379Zdaily0.7 16 | https://docs.passport.xyz/building-with-passport/tutorials/integrating-onchain-stamp-data2023-10-02T02:50:03.379Zdaily0.7 17 | https://docs.passport.xyz/building-with-passport/tutorials/integrating-stamps-and-scorers2023-10-02T02:50:03.379Zdaily0.7 18 | https://docs.passport.xyz/building-with-passport/tutorials/requiring-a-passport-score-for-airdrop-claim2023-10-02T02:50:03.379Zdaily0.7 19 | https://docs.passport.xyz/building-with-passport/tutorials/working-with-stamp-metadata2023-10-02T02:50:03.379Zdaily0.7 20 | https://docs.passport.xyz/community/getting-involved2023-10-02T02:50:03.379Zdaily0.7 21 | https://docs.passport.xyz/community/passport-github-projects2023-10-02T02:50:03.379Zdaily0.7 22 | https://docs.passport.xyz/community/style-guide2023-10-02T02:50:03.379Zdaily0.7 23 | https://docs.passport.xyz/overview/key-terms2023-10-02T02:50:03.379Zdaily0.7 24 | https://docs.passport.xyz/overview/use-cases2023-10-02T02:50:03.379Zdaily0.7 25 | https://docs.passport.xyz/overview/why-passport-xyz2023-10-02T02:50:03.379Zdaily0.7 26 | https://docs.passport.xyz/stamps/integrating-a-new-stamp2023-10-02T02:50:03.379Zdaily0.7 27 | -------------------------------------------------------------------------------- /public/sitemap.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | https://docs.passport.xyz/sitemap-0.xml 4 | -------------------------------------------------------------------------------- /public/snapshot.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/snapshot.jpg -------------------------------------------------------------------------------- /public/social-card.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/social-card.png -------------------------------------------------------------------------------- /public/stamp-collector-app-showing-stamps.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/stamp-collector-app-showing-stamps.png -------------------------------------------------------------------------------- /public/stamp-logo-examples.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/stamp-logo-examples.png -------------------------------------------------------------------------------- /public/stamps-page.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/stamps-page.png -------------------------------------------------------------------------------- /public/test-mode-app.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/test-mode-app.png -------------------------------------------------------------------------------- /public/trusted-user-app-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/trusted-user-app-2.png -------------------------------------------------------------------------------- /public/trusted-user-app-pt1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/trusted-user-app-pt1.png -------------------------------------------------------------------------------- /public/trusted-user-app.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/trusted-user-app.png -------------------------------------------------------------------------------- /public/weigh-activities.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/passportxyz/passport-docs/85801989d18c89534737010fa10f94c5ed44b951/public/weigh-activities.png -------------------------------------------------------------------------------- /retired-content/composedb.md: -------------------------------------------------------------------------------- 1 | # ComposeDB - Deprecated 2 | 3 | ComposeDB is a decentralized graph database built on top of Ceramic. 4 | Whereas other databases typically store tables of information, a graph database stores relationships between nodes. 5 | Instead of just storing keys and values, a graph database allows connectioons between values to exist too. 6 | This is very powerful for understanding, for example, user journeys, paths, histories and networks. 7 | 8 | In Compose DB, the nodes of the graph are acounts or documents with a globally unique ID. The relationships between these nodes are known as "edges". You can query nodes and edges. 9 | 10 | Being a product built on top of Ceramic, ComposeDB provides many benefits for web3 native applications including strong Ethereum integrations. There is also a rich, Graph-QL style API that helps developers to construct complex queries. These are very useful features for Human Passport. 11 | 12 | Perhaps more importantly, ComposeDB allows us to create and publish data schemas that work across different tech-stacks, meaning we can deploy apps that work identically across multiple layer-1 blockchains and their layer-2's. Data on ComposeDB is updateable allowing, for example, Stamp expiry and reverification. 13 | 14 | Read more in the [ComposeDB documentation](https://developers.ceramic.network/docs/composedb/getting-started). 15 | 16 | ## Passport on ComposeDB 17 | 18 | The data used by Human Passport fits very well into the graph structure. There are two basic elements that Human Passport considers: user addresses and Stamps. These are nodes. The links between Stamps and users and edges. 19 | 20 | Let's say you want to know who owns a particular Stamp. You would identify the **node** for that Stamp and then query all the **edges** that connect the Stamp to user addresses. 21 | 22 | > **You do not have to construct any of these queries as a Human Passport user! All this logic is handled by the Human Passport app.** 23 | 24 | Nodes can have properties associated with them, such as `isDeleted` or `isRevoked` that clarify something about it. These can be used to filter out edges in the graph (e.g. a query can be used to identify all edges connecting a node to other nodes whose `isRevoked` value is `false`). 25 | 26 | ## Schema 27 | 28 | Here's what a Stamp looks like in JSON format: 29 | 30 | ```json 31 | { 32 | "type": [ 33 | "VerifiableCredential", "GitcoinPassportStamp" 34 | ], 35 | "@context": [ 36 | "https://www.w3.org/2018/credentials/v1", "https://credentials.passport.gitcoin.co/" 37 | ], 38 | "issuer": "...", 39 | "issuanceDate": "2023-10-23T13:32:52.935Z", 40 | "expirationDate": "2024-01-21T13:32:52.935Z", 41 | "credentialSubject": { 42 | "id": "did:pkh:eip155:1:0x0000000000000000000000000000000000000000", 43 | "hash": "v0.0.0:12121212121212121212121212121212121212", 44 | "provider": "MyProvider", 45 | "@context": [...] 46 | }, 47 | "proof": {...} 48 | } 49 | ``` 50 | 51 | and here is what it looks like to create this object in a ComposeDB database: 52 | 53 | ```GraphQL 54 | type GitcoinPassportStamp implements VerifiableCredential 55 | @createModel( 56 | accountRelation: LIST 57 | description: "A Human Passport stamp with a provider and hash" 58 | ) 59 | @createIndex(fields: [{ path: "issuer" }]) 60 | @createIndex(fields: [{ path: "issuanceDate" }]) 61 | @createIndex(fields: [{ path: "expirationDate" }]) { 62 | _context: [String!]! 63 | @string(minLength: 1, maxLength: 1024) 64 | @list(maxLength: 1024) 65 | type: [String!]! @string(minLength: 1, maxLength: 1024) @list(maxLength: 1024) 66 | issuer: String! @string(minLength: 1, maxLength: 1024) 67 | issuanceDate: DateTime! 68 | expirationDate: DateTime 69 | credentialSubject: GitcoinPassportVcCredentialSubject! 70 | proof: GitcoinPassportVcProof! 71 | } 72 | ``` 73 | 74 | You'll notice that the ComposeDB schema definition above uses embedded types and an interface. For brevity we've omitted those above, but you can observe the schema definitions in their entirety in our [passportStamps.graphql](https://github.com/passportxyz/passport/blob/main/schemas/models/passportStamps.graphql) document. 75 | 76 | The fields are as follows: 77 | - `type`: Passport Stamps are always `VerifiableCredentials` 78 | - `context`: an array of strings with lengths between 1 and 1024 bytes to store links to the specifications for verifiable credentials and the Passport credential. 79 | - `issuer`: a string with length 1 to 1024 bytes to store the address issuing the credential. 80 | - `issuanceDate`: A datetime object referencing the time the credential was created. 81 | - `expirationDate`: A datetime object referencing the time the credential will expire. 82 | - `credentialSubject`: An object with the following subfields: 83 | - `id`: A `did` unique identifier for this credential. 84 | - `hash`: A hash of this Stamp object 85 | - `provider`: A hash corresponding to the Stamp provider 86 | - `context`: A string of lenghth 1 - to 1024 bytes for storing additional information about the Stamp. 87 | - `proof`: A hash demonstrating that the Stampo was really attested by a provider. 88 | 89 | ### Syncing Passport Data with Your Ceramic Node 90 | 91 | If you already have a ComposeDB node and you would like to sync and collaborate on Passport data based on the same definitions, you will need to use the same [ComposeDB composite](https://github.com/passportxyz/passport/blob/main/schemas/composites/gitcoin-passport-stamps-composite.json) already deployed onto the Passport ComposeDB node (in order to ensure the same data model references are synced). 92 | 93 | We've put together a simple [repository](https://github.com/Passportxyz/passport-ceramic-deployment) containing a script that automates this for you. 94 | 95 | First, clone the repository and install your dependencies: 96 | 97 | ```bash 98 | git clone https://github.com/Passportxyz/passport-ceramic-deployment && cd eventual-repository-location && npm install 99 | ``` 100 | 101 | This repository has already been pre-loaded with the correct [composite definition](https://github.com/Passportxyz/passport-ceramic-deployment/blob/main/definition.json), so you do not need to edit your definition files. 102 | 103 | Next, follow step #2 in the README (which shows how to enter your node endpoint and corresponding admin seed as arguments). 104 | 105 | Finally, go ahead and deploy: 106 | 107 | ```bash 108 | nvm use 20 109 | npm run deploy 110 | ``` 111 | 112 | Congratulations! Your ComposeDB node is now indexing on the same passport data models. 113 | 114 | Finally, in order to run mutations and read queries against your node corresponding to the passport schema, don't forget to use your [JavaScript Runtime Definition](https://github.com/passportxyz/passport/blob/main/schemas/src/definitions/ts/gitcoin-passport-stamps.ts) when casting these definitions onto your application's ComposeDB client. 115 | 116 | For more information about how this works, visit the [ComposeDB examples](https://developers.ceramic.network/docs/composedb/examples/tutorials-and-examples) documentation, or get in touch with the Ceramic team on their [Official Forum](https://forum.ceramic.network/). 117 | 118 | Here's an example of a query to retrieve 10 Passport Stamps. Users familiar with GraphQL will recognize the syntax. 119 | 120 | ```js 121 | // Read some documents from compose 122 | const m = `query MyQuery { 123 | gitcoinPassportStampIndex( 124 | last: 10 125 | ) { 126 | edges { 127 | node { 128 | credentialSubject { 129 | _id 130 | hash 131 | metaPointer 132 | provider 133 | } 134 | proof { 135 | ...GitcoinPassportStampGitcoinPassportVcProofFragment 136 | } 137 | expirationDate 138 | id 139 | issuanceDate 140 | issuer 141 | } 142 | } 143 | } 144 | } 145 | ``` 146 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "target": "es5", 4 | "lib": ["dom", "dom.iterable", "esnext"], 5 | "allowJs": true, 6 | "skipLibCheck": true, 7 | "strict": false, 8 | "forceConsistentCasingInFileNames": true, 9 | "noEmit": true, 10 | "incremental": true, 11 | "esModuleInterop": true, 12 | "module": "esnext", 13 | "moduleResolution": "node", 14 | "resolveJsonModule": true, 15 | "isolatedModules": true, 16 | "jsx": "preserve" 17 | }, 18 | "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"], 19 | "exclude": ["node_modules"] 20 | } 21 | -------------------------------------------------------------------------------- /utils/data/weights.ts: -------------------------------------------------------------------------------- 1 | export const GITCOIN_PASSPORT_WEIGHTS: Object = { 2 | "BeginnerCommunityStaker": "1.513", 3 | "Brightid": "0.802", 4 | "CivicCaptchaPass": "1.014", 5 | "CivicLivenessPass": "3.004", 6 | "CivicUniquenessPass": "6.005", 7 | "CoinbaseDualVerification": "16.042", 8 | "Discord": "0.516", 9 | "Ens": "0.408", 10 | "ETHDaysActive#50": "0.507", 11 | "ETHGasSpent#0.25": "1.003", 12 | "ETHnumTransactions#100": "0.51", 13 | "ETHScore#50": "10.012", 14 | "ETHScore#75": "2.001", 15 | "ETHScore#90": "2.009", 16 | "ExperiencedCommunityStaker": "2.515", 17 | "GitcoinContributorStatistics#totalContributionAmountGte#1000": "5.018", 18 | "GitcoinContributorStatistics#totalContributionAmountGte#100": "2.017", 19 | "GitcoinContributorStatistics#totalContributionAmountGte#10": "0.523", 20 | "githubContributionActivityGte#120": "3.019", 21 | "githubContributionActivityGte#30": "2.020", 22 | "githubContributionActivityGte#60": "2.021", 23 | "GnosisSafe": "0.822", 24 | "Google": "0.525", 25 | "GuildAdmin": "0.724", 26 | "GuildPassportMember": "0.54", 27 | "HolonymGovIdProvider": "16.026", 28 | "IdenaState#Human": "2.027", 29 | "IdenaState#Newbie": "6.028", 30 | "IdenaState#Verified": "2.029", 31 | "Lens": "0.93", 32 | "Linkedin": "1.531", 33 | "NFT": "1.032", 34 | "NFTScore#50": "10.033", 35 | "NFTScore#75": "2.034", 36 | "NFTScore#90": "2.035", 37 | "SelfStakingBronze": "1.036", 38 | "SelfStakingGold": "3.037", 39 | "SelfStakingSilver": "2.038", 40 | "SnapshotProposalsProvider": "0.839", 41 | "TrustaLabs": "0.511", 42 | "TrustedCitizen": "4.041", 43 | "ZkSyncEra": "0.606", 44 | "zkSyncScore#20": "1.67", 45 | "zkSyncScore#50": "1.67", 46 | "zkSyncScore#5": "1.67", 47 | } 48 | --------------------------------------------------------------------------------