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.

Contract	Address
AttestationStore	0xa116261Ed3a848A9E1cd34923D5A0442D1455F71
ComplianceGate	0x01BEEA13A485c7bAD58f926E345325e9e3773bEe

Fuji Testnet

Full read/write environment — this is where the KYC flow at kumply.xyz/verify issues attestations.

Contract	Address
AttestationStore	0xa3Bc5564A18e107807aF41fF2a5215Db050b22dD
ComplianceGate	0xcFDdeA5482baE9A6733B58F6a39FC36BCe6164cF
KumplyValidatorSetManager	0x935114966Ac6CB6Ec569c8C6959aDF5Ceb9E6f64

⚡ 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.

1. Users/Businesses/Agents complete identity verification via our certified KYC provider (Sumsub).
2. 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.
3. 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

Document	What it covers
LITEPAPER.md	Problem, architecture, tiers, business model, roadmap
L1.md	KUMPLY Compliance L1 design and deployment path
docs/diagrams/architecture.md	Mermaid architecture diagrams
contracts/l1/README.md	L1 genesis and node operation
packages/sdk/README.md	SDK API reference
apps/api/openapi.yaml	OpenAPI 3.0 spec for the REST API
docs/audits/avalanche-ecosystem-audit-2026-08-17.md	Our own review of the contracts and docs against official Avalanche tooling (not a formal third-party audit)
docs/AI-USAGE.md	AI-assistance disclosure
CONTRIBUTING.md	Setup, tests, commit style, PRs
SECURITY.md	How to report a vulnerability privately
CODE_OF_CONDUCT.md	Contributor Covenant 2.1

Links

• Website: kumply.xyz. Docs: kumply.xyz/docs. Developers: kumply.xyz/developers. Tiers: kumply.xyz/tiers
• SDK on npm: @kumply/sdk (1.3.0 adds isPersonAtLeast / isBusiness / isAgent; tiers 1-3 are a ladder for people, 4 and 5 are separate categories)
• X: @kumplyavax

🚀 Getting Started

Prerequisites

• Node.js >= 20.0.0
• pnpm >= 10.0.0

Installation

1. Clone the repository:

   git clone https://github.com/kumplyprotocol/Kumply.git
   cd Kumply

2. Install dependencies:

   pnpm install

3. Setup environment variables:

   cp .env.example .env
   # Add your specific keys (WalletConnect ID, Sumsub credentials if running locally)

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

• Architecture & Ecosystem: Avalanche Network, Developer Hub, Primary Network & Consensus
• Nodes & Validation: Run a Node, Staking for Institutions, Subnet-EVM Configs
• Avalanche L1s (Subnets): L1 Nodes, L1 Architecture
• Interoperability (ICM/Warp): Avalanche Interchain Messaging, Warp Building & Parsing
• Data API: Avalanche Data API
• Smart Contract Verification: Verify on Snowtrace, Hardhat Integration
• Implemented ACPs:
  • ACP-99: ValidatorSetManager Contract
  • ACP-77: Reinventing Subnets
  • ACP-30: Avalanche Warp X EVM

🤝 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.