> For the complete documentation index, see [llms.txt](https://docs.humanity.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.humanity.org/build-with-humanity/build-on-chain/on-chain-quickstart.md).
# On-Chain QuickStart
**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](https://metamask.io/) 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.
{% embed url="" %}
### 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:
{% embed url="" %}
Get testnet tokens from the faucet:
{% embed url="" %}
> ℹ️ 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:
```bash
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:
```bash
corepack enable
corepack prepare yarn@stable --activate
```
If prompted to confirm a download, type `y`.
### Install dependencies
```bash
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:
```bash
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):
```bash
# 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:
{% embed url="" %}
***
## 5. Import Your Deployer Key
The scaffold encrypts your private key at rest. Run the import script from the hardhat package:
```bash
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.
```bash
cd ../..
```
***
## 6. Deploy `HumanityVerifier`
From the repo root, run:
```bash
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:
```bash
🚀 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](https://humanity-testnet.explorer.alchemy.com/address/0x1a247b7d7076e4c4D97D87c62947Ab5495C13423?tab=read_write_proxy).
***
## 7. Verify a Wallet
Start the front end:
```bash
npm run start
# or yarn start
```
Then open 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](https://app.sandbox.humanity.org/). |
| No testnet tokens | Use the [Humanity testnet faucet](https://www.alchemy.com/faucets/humanity-testnet). |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.humanity.org/build-with-humanity/build-on-chain/on-chain-quickstart.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.