Know Your Agent
An on-chain identity standard for autonomous AI agents built on the Ethereum Attestation Service
Problem • Quick Start • Architecture • Schemas • Packages • Development • Docs
Note KYA is live on Base Sepolia testnet. Schema definitions and SDK interfaces are stabilizing but may still change before mainnet. Feedback welcome.
AI agents are transacting at unprecedented scale — yet they remain "unbanked ghosts" with no way to prove who they are, what they're authorized to do, or who's accountable when they fail.
Humans have KYC. Agents need KYA.
npm install @kya/sdk ethersimport { KYA } from "@kya/sdk";
import { ethers } from "ethers";
const provider = new ethers.JsonRpcProvider("https://sepolia.base.org");
const signer = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
const kya = new KYA({ network: "base-sepolia", signer });
// Register agent identity (on-chain attestation)
const identityUID = await kya.createIdentity({
agentAddress: "0xAgent...",
ownerAddress: "0xHuman...", // accountability anchor
displayName: "TradingBot Alpha",
description: "Autonomous market-making agent",
});
// Grant capabilities with permission bitmasks
const capUID = await kya.createCapability({
parentIdentityUID: identityUID,
permissions: KYA.Permissions.TRANSACT | KYA.Permissions.SIGN,
expiresAt: Math.floor(Date.now() / 1000) + 86400 * 30, // 30 days
});
// Verify any attestation
const result = await kya.verify(identityUID);
console.log(result.valid); // true// EIP-712 signed attestation — no gas cost
const offchain = await kya.createIdentityOffchain({
agentAddress: "0xAgent...",
ownerAddress: "0xHuman...",
displayName: "TradingBot Alpha",
});const provenanceUID = await kya.createProvenance({
parentIdentityUID: identityUID,
sourceCodeHash: KYA.hashString("https://github.com/org/agent@v1.2.0"),
provenanceType: 1, // source code
});const delegationUID = await kya.createDelegation({
parentIdentityUID: identityUID,
delegator: "0xHuman...",
delegatee: "0xSubAgent...",
scope: "trade:execute",
expiresAt: Math.floor(Date.now() / 1000) + 86400 * 7, // 7 days
});KYA provides four composable attestation schemas built on EAS:
┌──────────────────────────────────────────────────────────────────┐
│ KYA TRUST CHAIN │
├──────────────────────────────────────────────────────────────────┤
│ │
│ IDENTITY ────► CAPABILITY ────► DELEGATION ────► PROVENANCE │
│ "Who?" "What?" "By whom?" "From where?" │
│ │
│ Every chain terminates at a human. Always. │
│ │
└──────────────────────────────────────────────────────────────────┘
Two custom resolver contracts enforce on-chain invariants:
| Contract | Enforces |
|---|---|
KYAIdentityResolver |
One identity per agent address, non-zero owner/agent validation, optional attester whitelist, 2-step admin transfer |
KYACapabilityResolver |
Parent identity must exist, not be revoked, and not be expired |
| Schema | Purpose | Resolver | Fields |
|---|---|---|---|
| KYA-Identity | Agent passport — one per agent address | KYAIdentityResolver |
agentDID, agentAddress, ownerAddress, displayNameHash, descriptionHash, createdAt, version, metadataURI |
| KYA-Capability | Permission grants tied to an identity | KYACapabilityResolver |
capabilityId, permissions, targetContract, grantedAt, expiresAt, conditionsHash, trustLevel |
| KYA-Provenance | Code lineage and audit trail | None (v1) | sourceCodeHash, modelHash, buildHash, builderAddress, auditReportHash, buildTimestamp, previousVersionUID, provenanceType |
| KYA-Delegation | Authorization chains between agents | None (v1) | delegator, delegatee, scope, constraints, delegatedAt, expiresAt, depth |
Capabilities use a bitmask system for fine-grained permission control:
| Permission | Bit | Value | Description |
|---|---|---|---|
TRANSACT |
0 | 1 |
Execute transactions |
SIGN |
1 | 2 |
Sign messages |
DEPLOY |
2 | 4 |
Deploy contracts |
ADMIN |
3 | 8 |
Administrative operations |
READ_PRIVATE |
4 | 16 |
Access private data |
DELEGATE |
5 | 32 |
Delegate to sub-agents |
CROSS_CHAIN |
6 | 64 |
Cross-chain operations |
// Compose permissions with bitwise OR
const permissions = KYA.Permissions.TRANSACT | KYA.Permissions.SIGN | KYA.Permissions.DELEGATE;kya-protocol/
├── packages/
│ ├── contracts/ # Hardhat — Solidity resolvers, tests, deploy script
│ └── sdk/ # @kya/sdk — TypeScript SDK
├── docs/ # Specification, whitepaper, explainer
├── examples/ # Runnable examples
└── package.json # npm workspaces root
| Package | Description | Tests |
|---|---|---|
@kya/contracts |
Solidity resolver contracts, Hardhat tests, deployment script | 11 |
@kya/sdk |
TypeScript SDK — identity, capability, provenance, delegation, verification, off-chain support | 7 |
- Node.js >= 18
- npm >= 9
# Install all workspace dependencies
npm install
# Compile contracts
cd packages/contracts && npx hardhat compile
# Run contract tests (11 tests)
npx hardhat test
# Build SDK
cd ../sdk && npm run build
# Run SDK tests (7 tests)
npm testOr from the repo root:
npm run build # compile contracts + build SDK
npm test # run all 18 tests across both packages# 1. Configure environment
cp .env.example .env
# Set BASE_SEPOLIA_RPC_URL and DEPLOYER_PRIVATE_KEY in .env
# 2. Deploy resolvers and register schemas
cd packages/contracts
npm run deploy:base-sepoliaThe deploy script will:
- Deploy
KYAIdentityResolver(whitelist enabled, deployer added as first attester) - Register the Identity schema with the resolver
- Deploy
KYACapabilityResolver(linked to the Identity schema UID) - Register the Capability schema with the resolver
- Register the Provenance and Delegation schemas (no resolvers)
- Write all addresses and schema UIDs to
deployments/base-sepolia.json
| Address | |
|---|---|
| Network | Base Sepolia (chain ID 84532) |
| EAS | 0x4200000000000000000000000000000000000021 |
| SchemaRegistry | 0x4200000000000000000000000000000000000020 |
- One identity per agent — the resolver enforces a unique mapping from agent address to identity UID
- Non-zero validation — both agent and owner addresses must be non-zero
- Attester whitelist — optional access control for who can create attestations
- 2-step admin transfer — admin privileges require
transferAdmin+acceptAdminto prevent accidental transfers - Parent validation — capabilities are rejected if the referenced identity is revoked or expired
When whitelistEnabled=false on the KYAIdentityResolver, anyone can create identity attestations. This permissionless mode carries important risks:
Risks:
- Spam attestations — Malicious actors can flood the system with garbage attestations, consuming on-chain storage and indexer resources
- Agent address squatting — Bad actors may claim agent addresses before legitimate owners, blocking future registrations (since one identity per agent is enforced)
- DoS via mapping pollution — Excessive attestations can degrade lookup performance and increase costs for legitimate users
Mitigations:
- Keep
whitelistEnabled=truefor production deployments - Only whitelist trusted attesters who have been vetted
- Implement rate limiting at the application layer (e.g., in your backend or SDK wrapper)
- Monitor attestation patterns for suspicious activity
Recommendation: Always enable the attester whitelist for mainnet deployments. Permissionless mode should only be used for testing or controlled environments.
This is alpha software. Do not use in production.
To report security issues, please email security@edgeoftrust.com.
| Document | Description |
|---|---|
| SPECIFICATION.md | Full technical spec — schemas, resolvers, integration patterns |
| WHITEPAPER.md | Market context, protocol landscape, adoption pathways |
| EXPLAINER.md | Visual explainer with diagrams |
See CONTRIBUTING.md for guidelines.
MIT — See LICENSE
The agents are coming. It's time to know who they are.
Built by Edge of Trust