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.

Humanity 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:

Humanity Protocol testnet RPC and Chain settings | ChainListchainlist.org

Get testnet tokens from the faucet:

Faucet - Humanity Testnet | AlchemyAlchemy

ℹ️ 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:

git clone https://github.com/humanity-org/scaffold-humanity.git
cd scaffold-humanity

Enable Yarn via Corepack

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

corepack enable
corepack prepare yarn@stable --activate

If prompted to confirm a download, type y.

Install dependencies

yarn install

⚠️ 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:

cp packages/hardhat/.env.example packages/hardhat/.env

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

# Filled in by yarn account:import — do not edit manually
DEPLOYER_PRIVATE_KEY_ENCRYPTED=

# Get a free key at https://dashboard.alchemy.com/
ALCHEMY_API_KEY=

# Humanity Testnet defaults — no changes needed
VERIFICATION_ORACLE_CONTRACT=0x67c0A5cA2Fb19E8E0Ff008d727aff5f128b00E09
FEE_ESCROW_CONTRACT=0x1a247b7d7076e4c4D97D87c62947Ab5495C13423
REQUIRED_CLAIMS=humanity_identity
MAX_VERIFICATION_AGE_SECONDS=2592000

# Auto-funds FeeEscrow after deployment (0.1 tHP)
FEE_ESCROW_FUNDING_WEI=100000000000000000

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

How To Create a New Alchemy API Key?www.alchemy.com

---

5. Import Your Deployer Key

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

cd packages/hardhat
yarn account:import

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.

cd ../..

---

6. Deploy HumanityVerifier

From the repo root, run:

npm run deploy
#or for specific tests yarn workspace @se-2/hardhat deploy --network humanityTestnet --tags HumanityVerifier

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

🚀 Deploying HumanityVerifier contract...
📡 Network: humanityTestnet
👤 Deployer: 0xYourAddress...
🔎 Oracle: 0x67c0A5cA2Fb19E8E0Ff008d727aff5f128b00E09
🏦 FeeEscrow: 0x1a247b7d7076e4c4D97D87c62947Ab5495C13423
🧾 Claims: humanity_identity
⏱️ Max Age (s): 2592000
✅ HumanityVerifier deployed at 0xABC123...
💸 Funding FeeEscrow for 0xABC123... with 100000000000000000 wei...
✅ FeeEscrow funded (tx: 0xDEF456...)

ℹ️ 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:

npm run start
# or yarn start

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.