Ctrlk
ExplorerFaucetBridgeDeveloper PortalWhitepaperDashboard
For the complete documentation index, see llms.txt. This page is also available as Markdown.

On-Chain QuickStart

Get your first Humanity on-chain integration. Clone the scaffold, deploy a verification contract to Humanity testnet, and confirm a wallet is linked to a verified human.

This guide walks you through a complete on-chain integration using the testnet environment.

ℹ️ The testnet is a safe development environment that behaves the same as mainnet but uses test tokens and sandbox credentials instead of real assets and real biometric data. Your contract runs on Humanity's testnet chain and connects to the live Verification Oracle on that network.

How this Quickstart Works

Here's the flow you are about to implement:

  1. Generate a sandbox credential.

  2. Clone and configure the Humanity Scaffold.

  3. Deploy HumanityVerifier to Humanity testnet.

  4. Run the front end and verify a connected wallet against the oracle.

You'll complete this loop in less than 10 minutes.

Prerequisites

Before you begin, make sure you have the following installed:

  • Node.js >= 20.18.3

  • Git

  • MetaMask browser extension with a dedicated test wallet

⚠️ Always use a dedicated test wallet for development — never use a wallet that holds real assets.

1. Generate a Sandbox Credential

The Humanity Verification Oracle checks whether a wallet address is linked to a verified human. For the oracle to return a positive result during development, your test wallet needs a sandbox credential registered against it.

LogoHumanity Protocolapp.sandbox.humanity.org

Steps to follow

  • Log in to the account with the linked wallet you plan to use for testing.

  • Generate a credential — choose either Palm Print or Palm Vein biometric type.

  • Once created, the credential is registered in the sandbox and the oracle will return verified = true for that wallet address.

2. Configure MetaMask and Get Testnet Tokens

Before deploying, connect MetaMask to the Humanity testnet and fund your wallet with test tokens.

Testnet Network Details

The quickest way to add the network is via ChainList:

LogoHumanity Protocol testnet RPC and Chain settings | ChainListchainlist.org

Get testnet tokens from the faucet:

LogoHumanity Testnet Faucet | Get tHP TokensAlchemy

ℹ️ You'll need at least 0.1 tHP to cover the FeeEscrow deposit made during deployment. The scaffold defaults to exactly this amount.

3. Project Setup

Clone the scaffold and enable the correct package manager:

Enable Yarn via Corepack

This project uses Yarn 3.2.3 via Corepack. Run the following to activate it:

If prompted to confirm a download, type y.

Install dependencies

⚠️ This repo is Yarn 3.2.3. Do not run npm install — it will cause dependency resolution issues.

4. Configure Environment

Copy the example env file for the Hardhat package:

Open packages/hardhat/.env. It ships pre-filled with the correct testnet defaults — the only values you need to provide are your Alchemy API key and your deployer private key (added in the next step):

To get your Alchemy API key, follow the instructions here:

LogoHow To Create a New Alchemy API Key?Alchemy

5. Import Your Deployer Key

The scaffold encrypts your private key at rest. Run the import script from the hardhat package:

You'll be prompted to enter your private key and choose a password. Save this password — you'll need it every time you deploy.

The script writes the encrypted key to DEPLOYER_PRIVATE_KEY_ENCRYPTED in your .env automatically.

6. Deploy HumanityVerifier

From the repo root, run:

You'll be prompted for the password you set in step 5. Expected output:

ℹ️ FeeEscrow — prepaid model

Humanity Protocol uses a prepaid fee model. Your dApp deposits tHP into the FeeEscrow once. Verification fees are deducted automatically per successful verification. Users never pay fees directly. The deploy script handles the initial deposit for you.

You can top up at any time by calling deposit(dapp) on the FeeEscrow contract.

7. Verify a Wallet

Start the front end:

Then open http://localhost:3000 in your browser.

  1. Connect the same test wallet you used in step 1 (the one with the sandbox credential).

  2. Click Verify Wallet.

  3. Sign the permission message when your wallet prompts — this authorises the oracle to check your credentials.

  4. Wait for the oracle callback. The status will update to Success or Failed.

ℹ️ The oracle processes verification requests asynchronously. The callback typically arrives within a few seconds on testnet. The front end polls for status updates automatically.

Troubleshooting

Issue
Solution

yarn install fails

Ensure you ran corepack enable and accepted the Yarn download prompt.

Deployment fails at key decryption

Double-check the password you set during yarn account:import.

Verification stays Pending indefinitely

Check that your FeeEscrow balance is above zero using getEscrowAvailable().

Oracle returns Failed

Confirm your wallet has a sandbox credential at app.sandbox.humanity.org.

No testnet tokens

Use the Humanity testnet faucet.

Last updated