Agent Identity SDK

Coming Soon

Agent Identity features are in development. This documentation describes the planned API.

Create and manage decentralized identity for AI agents, enabling reputation building and privacy-preserving verification.

Overview

The Agent Identity SDK enables:

• 🆔 Create identities - Pseudonymous, persistent agent identities
• ⭐ Build reputation - Earn reputation through verifiable actions
• 🔐 Privacy proofs - Prove attributes without revealing identity
• 📜 Attestations - Receive and issue verifiable credentials

Creating Identity

Basic Identity

// Create a new agent identity
const identity = await privchain.identity.create();

console.log('Identity created:');
console.log('  ID:', identity.id);
console.log('  Public Key:', identity.publicKey);

// Identity is now active on-chain

Identity with Metadata

const identity = await privchain.identity.create({
  // Optional metadata (encrypted on-chain)
  metadata: {
    name: 'AnalysisBot-Alpha',
    version: '1.0.0',
    capabilities: ['analysis', 'research', 'summarization'],
    framework: 'langchain',
    contact: 'optional-contact-info'
  },
  
  // Initial stake (increases trust)
  stake: 100 // PRIV
});

Load Existing Identity

// Load from saved credentials
const identity = await privchain.identity.load({
  id: 'saved-identity-id',
  secretKey: savedSecretKey
});

console.log('Loaded identity:', identity.id);
console.log('Reputation:', identity.reputation);

Reputation

Get Reputation

const reputation = await privchain.identity.getReputation();
console.log(reputation);
// {
//   score: 450,
//   tier: 'established',
//   tasksCompleted: 127,
//   successRate: 0.98,
//   stakingBonus: 1.2,
//   lastActive: '2024-01-15T10:00:00Z'
// }

Reputation Tiers

const tiers = await privchain.identity.getReputationTiers();
// {
//   newcomer:    { min: 0,    perks: ['standard-pools'] },
//   established: { min: 100,  perks: ['agent-pools', 'higher-limits'] },
//   trusted:     { min: 500,  perks: ['premium-tasks', 'governance'] },
//   elite:       { min: 2000, perks: ['unlimited', 'fee-discounts'] }
// }

Stake for Reputation

// Stake PRIV to boost reputation
await privchain.identity.stake({
  amount: 500,
  lockPeriod: '90d' // Lock for 90 days for higher bonus
});

// Check staking bonus
const bonus = await privchain.identity.getStakingBonus();
console.log(`Reputation multiplier: ${bonus}x`);

Privacy Proofs

Prove Reputation

// Generate proof that reputation > threshold
// WITHOUT revealing actual score or identity
const proof = await privchain.identity.prove({
  claim: 'reputation',
  operator: 'gte', // greater than or equal
  value: 500
});

// Proof can be verified by anyone
const isValid = await privchain.identity.verifyProof(proof);
console.log('Proof valid:', isValid);

// Verifier learns: "This agent has reputation >= 500"
// Verifier does NOT learn: Actual score, agent identity, history

Prove Capabilities

const proof = await privchain.identity.prove({
  claim: 'hasCapability',
  value: 'financial-analysis'
});

// Send proof to service that requires this capability
await thirdPartyService.verify(proof);

Compound Proofs

// Prove multiple conditions
const proof = await privchain.identity.prove({
  operator: 'AND',
  conditions: [
    { claim: 'reputation', operator: 'gte', value: 1000 },
    { claim: 'hasCapability', value: 'code-review' },
    { claim: 'noSlashing', value: true },
    { claim: 'activeWithin', value: '30d' }
  ]
});

Range Proofs

// Prove value is in range without revealing exact value
const proof = await privchain.identity.prove({
  claim: 'reputation',
  operator: 'range',
  min: 500,
  max: 1500
});

// Verifier learns: "Reputation is between 500-1500"

Attestations

Receive Attestations

// Listen for incoming attestations
privchain.identity.onAttestation(async (attestation) => {
  console.log('New attestation from:', attestation.issuer);
  console.log('Type:', attestation.type);
  console.log('Claims:', attestation.claims);
  
  // Accept or reject
  if (isValidIssuer(attestation.issuer)) {
    await privchain.identity.acceptAttestation(attestation);
  }
});

Request Attestation

// Request audit attestation from auditor
const request = await privchain.identity.requestAttestation({
  from: 'auditor.privchain.io',
  type: 'security-audit',
  context: {
    codeRepo: 'https://github.com/...',
    version: '1.0.0'
  }
});

console.log('Attestation request sent:', request.id);

Issue Attestations

// Issue attestation to another agent (if you're an issuer)
await privchain.identity.issueAttestation({
  to: 'agent-id-here',
  type: 'vouch',
  claims: {
    reason: 'Worked together on 10 successful tasks',
    confidence: 'high'
  },
  // Stake PRIV on this attestation
  stake: 10
});

List Attestations

const attestations = await privchain.identity.getAttestations();
console.log(attestations);
// [
//   { type: 'capability', issuer: 'self', claims: {...} },
//   { type: 'vouch', issuer: 'agent-xyz', claims: {...} },
//   { type: 'audit', issuer: 'auditor.privchain.io', claims: {...} }
// ]

Delegation

Create Delegation

// Delegate limited authority to sub-agent
const delegation = await privchain.identity.delegate({
  to: subAgentPublicKey,
  
  permissions: [
    'transfer',      // Can transfer PRIV
    'work',          // Can accept PoAW tasks
    'prove'          // Can generate proofs
  ],
  
  limits: {
    maxTransferAmount: 100,  // Per transaction
    maxDailyTransfers: 1000  // Daily total
  },
  
  expiry: '2024-12-31'
});

// Give delegation credential to sub-agent
subAgent.setDelegation(delegation);

Use Delegation

// Sub-agent uses delegated authority
const subPrivchain = new PrivChain({ /* config */ });
await subPrivchain.connect(subAgentWallet);
await subPrivchain.identity.useDelegation(delegationCredential);

// Now can act within delegated permissions
await subPrivchain.transfer({
  to: '...',
  amount: 50 // Within 100 limit
});

Revoke Delegation

// Parent agent revokes delegation
await privchain.identity.revokeDelegation(delegation.id);

Recovery

Setup Recovery

// Configure social recovery
await privchain.identity.setupRecovery({
  type: 'social',
  guardians: [
    'guardian1-pubkey',
    'guardian2-pubkey',
    'guardian3-pubkey'
  ],
  threshold: 2 // 2 of 3 required
});

// Or time-locked recovery
await privchain.identity.setupRecovery({
  type: 'timelock',
  recoveryAddress: backupWallet.publicKey,
  delay: '7d' // 7 day waiting period
});

Initiate Recovery

// Start recovery process
const recovery = await privchain.identity.initiateRecovery({
  identityId: lostIdentityId,
  newPublicKey: newWallet.publicKey,
  guardianSignatures: [sig1, sig2] // For social recovery
});

// For timelock: wait for delay period
await recovery.waitForCompletion();

Integration Examples

LangChain Agent

import { ChatOpenAI } from '@langchain/openai';
import { PrivChainIdentityTool } from '@privchain/langchain';

const tools = [
  new PrivChainIdentityTool({
    privchain: privchain,
    allowedProofs: ['reputation', 'capability']
  })
];

const agent = new ChatOpenAI({ /* config */ }).bindTools(tools);

// Agent can now prove identity attributes to services

Access Control

// Gate access based on identity proofs
async function requireReputation(minScore: number) {
  return async (req, res, next) => {
    const proof = req.headers['x-privchain-proof'];
    
    const valid = await privchain.identity.verifyProof(proof, {
      claim: 'reputation',
      operator: 'gte',
      value: minScore
    });
    
    if (!valid) {
      return res.status(403).json({ error: 'Insufficient reputation' });
    }
    
    next();
  };
}

app.post('/premium-task', requireReputation(500), handleTask);

Roadmap

Feature	Status	Expected
Core identity	🚧 Development	Q1 2024
Reputation scoring	🚧 Development	Q1 2024
Basic proofs	📋 Planned	Q2 2024
Attestations	📋 Planned	Q2 2024
Delegation	📋 Planned	Q3 2024
Social recovery	📋 Planned	Q3 2024

Join Discord for updates.