KUMPLY 🛡️
KYC, KYB, and KYA (AI agent verification) in one on-chain attestation layer for AVALANCHE®
KUMPLY provides non-custodial, on-chain identity verification (KYC/KYB/KYA) for the AVALANCHE® network. By bridging real-world regulatory compliance with DeFi anonymity, we empower institutions, exchanges, and autonomous AI agents to operate seamlessly across the C-Chain and custom AVALANCHE® L1s without compromising user privacy.
Live on the AVALANCHE® Fuji Testnet, with a read-only beta on Mainnet C-Chain.
Trademark Notice: The AVALANCHE® and AVAX® trademarks are owned by Ava Labs, Inc. KUMPLY is an independent project — not endorsed by, sponsored by, or affiliated with Ava Labs, Inc. or the Avalanche Foundation.
🌐 Live Contracts
All contracts are deployed and verified. The full test suite (contracts, SDK, API) runs on every push.
Mainnet C-Chain (read-only beta)
The read layer is live on mainnet. verificationFee is currently 0, so compliance reads and the SDK are free. Paid queries are enabled in a later milestone — see the litepaper roadmap.
Fuji Testnet
Full read/write environment — this is where the KYC flow at kumply.xyz/verify issues attestations.
⚡ The Problem
As DeFi scales and institutions enter the Avalanche ecosystem, a massive friction point exists: Compliance.
DApps must enforce KYC/AML laws, but forcing users to verify their identity on every single DApp destroys UX and creates dangerous data honeypots. Furthermore, the rise of Autonomous AI Agents trading on-chain brings a new question: Who is legally responsible for this agent's actions?
💡 The Solution
KUMPLY is a "Verify Once, Use Everywhere" protocol.
- Users/Businesses/Agents complete identity verification via our certified KYC provider (Sumsub).
- We issue an on-chain attestation credential to their wallet. The credential holds only
(address, tier, issue time, expiry, verifier) and is public; revoking it deletes the record. No personal data is ever written on-chain. Documents stay with Sumsub; KUMPLY never stores them.
- Avalanche Smart Contracts can check a user's compliance Tier (
1-5) natively via our AttestationStore or ComplianceGate without touching personal data.
Verification Tiers
- Tier 1 (Basic): Email & Phone Verification
- Tier 2 (Standard): Government ID + Liveness Check (KYC)
- Tier 3 (Enhanced): Proof of Address + Source of Funds
- Tier 4 (Business): Corporate Verification (KYB) + UBO Disclosure
- Tier 5 (Agentic): AI Agent Verification (KYA) - Linking autonomous software to verified owners.
Note: "KYA" here is KUMPLY's own tier name (Know Your Agent). It's a different, unrelated thing from KYA-OS, the DIF-governed identity protocol for MCP agents — same acronym, different standard, no relationship between the two.
🏗️ Architecture
KUMPLY is built entirely around the Avalanche technical stack.
- Software-Only Protocol (shipped): We never store user documents. Data is processed by Sumsub, while KUMPLY exclusively handles the cryptographic on-chain proofs. No custody, no financial intermediation.
- PII-free attestations (shipped):
AttestationStore records only tier, expiry, issuer and revocation status against an address. Reads are public and free.
- Avalanche L1 Interoperability via ICM (designed, not yet shipped): The architecture targets Interchain Messaging so a credential issued on C-Chain can be read from any Avalanche L1 without a bridge.
AttestationStoreL1.sol (the ICM-mirrored reader) is on the Q3 2026 roadmap — today, cross-chain reads are not yet live.
- Encrypted ERC (eERC) (Phase 2, not yet shipped):
AttestationStore exposes an admin-only setEercToken() hook so encrypted credentials can be added once AvaCloud's EncryptedERC integration lands. In Phase 1 this is set to address(0) — attestations today are plaintext tier records, not encrypted tokens.
We list roadmap items explicitly as roadmap. If it says shipped, you can verify it on Snowtrace or in the test suite right now.
⛓️ KUMPLY Compliance L1 (Registered on Fuji — Activation Pending)
We are building an Avalanche L1 where validators must hold a KUMPLY attestation to register: Tier 4 (KYB) or higher in the deployed manager. A fix that restricts registration to exactly Tier 4 is already in the code and ships with the manager's redeploy before the L1 is activated. The L1 is not activated yet and has no validators.
- Validator Architecture (ACP-77 + ACP-99): Uses
KumplyValidatorSetManager.sol to require a valid attestation of Tier 4 (KYB) or higher as a prerequisite for registering a validator.
- Sub-Cent Compliance Reads: Predictable, near-zero fees for compliance lookups at institutional scale.
- Cross-L1 via Warp + ICM (planned, not shipped): Attestations would propagate natively without bridges or third-party trust assumptions.
- Permissionless Validator Purge: If a validator's attestation expires or is revoked, anyone can call
disableExpiredValidator() to start its removal, no admin needed. It is not automatic: someone has to make the call.
L1 Network Details (Fuji — chain registered, validator activation pending)
- Network Name: KUMPLY Compliance L1
- RPC URL:
https://subnets.avax.network/2pyvAQK1WQ318yHtnv4ZQeL9hWeJmmgMp9MEHqpJnDYttQEL6b/rpc
- Chain ID:
43210
- Currency Symbol:
KMP
- Subnet ID:
2buHAwNvaybnQ6vQYRS4TeXizZhAo33bhpnonAJu21CKYLZoST
- Blockchain ID:
2pyvAQK1WQ318yHtnv4ZQeL9hWeJmmgMp9MEHqpJnDYttQEL6b
- Validator Set Manager:
0x935114966Ac6CB6Ec569c8C6959aDF5Ceb9E6f64
💻 Tech Stack
- Smart Contracts: Solidity 0.8.28, Hardhat, OpenZeppelin
- Frontend: Next.js 16 (App Router), React 19, Vanilla CSS (custom design system)
- Web3 Interaction: Wagmi v3, Viem v2, MetaMask / Core Wallet
- API: Express + TypeScript, Zod validation, HMAC-SHA256 webhooks
- SDK:
@kumply/sdk (TypeScript package for DApps)
📦 Monorepo Layout
pnpm workspaces. Each package is independently testable and CI-gated.
kumply/
├── contracts/ # @kumply/contracts — Solidity 0.8.28 + Hardhat
│ ├── contracts/ # AttestationStore · ComplianceGate · KumplyValidatorSetManager
│ └── l1/ # KUMPLY Compliance L1: genesis, ACP-77 config, validator node
├── packages/sdk/ # @kumply/sdk — TypeScript SDK (viem-based), published to npm
├── apps/
│ ├── api/ # @kumply/api — Express API (Sumsub token proxy + webhook)
│ └── web/ # Next.js 16 frontend — kumply.xyz (EN/ES via next-intl)
└── docs/diagrams/ # Architecture diagrams (Mermaid)
🧪 Tests
pnpm test # everything: contracts, SDK, API
pnpm --filter @kumply/contracts test # Hardhat + Chai
pnpm --filter @kumply/sdk test # Vitest
pnpm --filter @kumply/api test # Vitest + Supertest
Contract coverage includes roles and access control, pausability, the five tiers, revocation and expiry, the fee/subscription billing paths, and a bit-exact Avalanche-codec round-trip for the ACP-99 Warp payloads.
🔍 Security & Engineering Rigor
Before attempting to activate KUMPLY's L1 on Fuji, we audited KumplyValidatorSetManager against the real source of ava-labs/icm-contracts , not just its documentation. We found that our port of ValidatorMessages.computeConversionID was missing the 4-byte length prefix the real P-Chain wire format requires: the hash it computed would never have matched the conversionID the network actually signs, so initializeValidatorSet would have reverted every time. The existing 27 tests didn't catch this because the Warp mock reimplemented the same error as the contract. Fixed, redeployed, and re-verified on Fuji (0x935114966Ac6CB6Ec569c8C6959aDF5Ceb9E6f64), with a test that now exercises the real P-Chain format.
The same audit, over three passes, also verified and filed real gaps upstream in AVAXSKILLS (a community skills package for Avalanche), none of them KUMPLY's own bugs:
| Where | What | Status |
|---|
| avaxskills#2 | subnet-deployment skill documents CLI commands (platform subnet create, and others) that don't exist in the real ava-labs/avalanche-cli | PR #5 open |
| avaxskills#2 (comment) | validator-management skill: same issue, avalanche primaryNetwork addValidator / avalanche subnet addValidator don't exist | PR #5 open |
| avaxskills#2 (comment) | custom-vm skill: same issue again, avalanche subnet create/deploy | PR #5 open |
| avaxskills#3 | precompiles skill: wrong genesis key for TxAllowList (transactionAllowListConfig vs. the real txAllowListConfig), confirmed against ava-labs/subnet-evm source | PR #6 open |
| avaxskills#4 | wagmi skill: claims v2 is latest (v3 has shipped) and its example uses useAccount, deprecated in wagmi's own types in favor of useConnection | PR #7 open |
Also checked, with nothing genuine to report: kyc-aml-integration, subnet-governance, security, audit, contract-verification, viem, OpenZeppelin contracts, and ava-labs/precompile-evm. "Nothing found" was treated as a valid, honest result throughout, not a gap to force-fill.
Full writeup: docs/audits/avalanche-ecosystem-audit-2026-08-17.md. AI-assistance disclosure: docs/AI-USAGE.md.
📖 Documentation
Links
🚀 Getting Started
Prerequisites
- Node.js >= 20.0.0
- pnpm >= 10.0.0
Installation
-
Clone the repository:
git clone https://github.com/kumplyprotocol/Kumply.git
cd Kumply
-
Install dependencies:
pnpm install
-
Setup environment variables:
cp .env.example .env
# Add your specific keys (WalletConnect ID, Sumsub credentials if running locally)
-
Run the development server:
pnpm dev
The frontend will be available at http://localhost:3000
🔐 For Developers: Using the Kumply SDK
Integrating KUMPLY into your DApp is incredibly simple:
pnpm add @kumply/sdk # or npm / yarn
import { KumplyClient, DEPLOYMENTS, TIER } from '@kumply/sdk';
// `contractAddress` is required — use DEPLOYMENTS for the canonical addresses.
const client = new KumplyClient({
network: 'mainnet',
contractAddress: DEPLOYMENTS.mainnet.attestationStore,
});
// Tiers 1-3 are a ladder for people; 4 (business) and 5 (agent) are separate categories.
if (await client.isPersonAtLeast('0xUserAddress', TIER.STANDARD)) {
// A person with Standard (2) or Enhanced (3) KYC: allow deposit
} else {
// Block action
}
Reads are free while verificationFee is 0. Swap network: 'fuji' with DEPLOYMENTS.fuji.attestationStore to target testnet.
Or enforce it directly in your Solidity contracts:
interface IAttestationStore {
function verify(address subject) external view returns (
bool verified, uint32 tier, uint64 timestamp, uint64 expiry
);
}
contract MyDeFiVault {
IAttestationStore public immutable kumply;
constructor(address _attestationStore) {
kumply = IAttestationStore(_attestationStore);
}
// verify() is free and returns verified == false once expired or revoked.
// Tiers 1-3: a ladder for people. 4: business (KYB). 5: agent (KYA).
function deposit() external {
(bool ok, uint32 tier, , ) = kumply.verify(msg.sender);
require(ok && tier >= 2 && tier <= 3, "person KYC required");
// ... execute deposit
}
}
About the deployed ComplianceGate. The ComplianceGate contracts in the tables above (Fuji and Mainnet C-Chain) check tier >= requiredTier with requiredTier = 2. That is the old single-ladder rule, so a Tier 4 business or a Tier 5 agent passes them. They are immutable. A category-aware gate is planned for mainnet hardening.
📜 Compliance & Brand Alignment
KUMPLY rigorously adheres to the May 2026 Ava Labs Trademark Usage Policy and AVALANCHE® ecosystem guidelines:
- ✅ Uses AVALANCHE® and AVAX® as adjectives (never as nouns or verbs)
- ✅ Uses the official "AVALANCHE® L1" nomenclature (not "Subnets")
- ✅ Stores no personal data on-chain — attestations are tier records, documents stay with Sumsub
- 🔜 eERC (Encrypted ERC) integration hook in place for Phase 2 — not yet active
- ✅ Categorizes autonomous actors as "AI Agents" with KYA verification
- ✅ Follows responsible disclosure practices for security vulnerabilities
- ✅ Operates as Software-Only infrastructure — non-custodial, no financial intermediation
- ✅ Published under the Apache License 2.0 — permissive, with an explicit patent grant and no trademark license
📚 Official Avalanche Resources & References
The architecture and implementation of KUMPLY were built strictly following the official Avalanche documentation and ACPs (Avalanche Community Proposals):
🤝 Program Participation
KUMPLY's application to Avalanche's Team1 Mini Grants program went in
through a real channel: the founding team includes an official Team1 LatAm
collaborator. Applied, decision still pending — not claimed as an award
here.
📄 License
This project is licensed under the Apache License 2.0 — see LICENSE and NOTICE.
Apache 2.0 was chosen over MIT deliberately: it carries an express patent grant (important for institutional adopters integrating a compliance primitive) and explicitly does not license trademarks.
Note on already-deployed contracts: the contracts currently live on Fuji and Mainnet C-Chain were compiled and verified on Snowtrace under MIT, and remain verified as such. The license change affects only the Solidity SPDX identifier, which lives in contract metadata — it does not alter executable logic (verified: recompiling changes only the 86-byte CBOR metadata trailer, 99.24% of the bytecode is byte-identical). The next deployment will carry Apache 2.0 end to end.
Built with ❤️ for the AVALANCHE® ecosystem.
The AVALANCHE® and AVAX® trademarks are owned by Ava Labs, Inc. KUMPLY is not endorsed by, sponsored by, or affiliated with Ava Labs, Inc.
