@vouch-protocol/sdk 0.1.0

package/src/registry.ts

@@ -0,0 +1,287 @@
+import { Program, AnchorProvider, BN } from "@coral-xyz/anchor";
+import { PublicKey, SystemProgram } from "@solana/web3.js";
+import { Kya } from "../../target/types/kya";
+import { SEEDS, VOUCH_PROGRAM_ID } from "./constants";
+import type { VouchConfig, AgentIdentity } from "./types";
+import { deriveAgentDid, parseDid, generateDidDocument } from "./did";
+import type { DidDocument } from "./did";
+
+export class RegistryClient {
+  constructor(
+    public readonly program: Program<Kya>,
+    public readonly provider: AnchorProvider
+  ) {}
+
+  // ── PDA derivation ──
+
+  static findConfigPda(
+    programId: PublicKey = VOUCH_PROGRAM_ID
+  ): [PublicKey, number] {
+    return PublicKey.findProgramAddressSync([SEEDS.VOUCH_CONFIG], programId);
+  }
+
+  static findAgentPda(
+    owner: PublicKey,
+    programId: PublicKey = VOUCH_PROGRAM_ID
+  ): [PublicKey, number] {
+    return PublicKey.findProgramAddressSync(
+      [SEEDS.AGENT, owner.toBuffer()],
+      programId
+    );
+  }
+
+  static findDeactivationRecordPda(
+    owner: PublicKey,
+    programId: PublicKey = VOUCH_PROGRAM_ID
+  ): [PublicKey, number] {
+    return PublicKey.findProgramAddressSync(
+      [SEEDS.DEACTIVATED, owner.toBuffer()],
+      programId
+    );
+  }
+
+  // ── Instructions (agent owner operations) ──
+
+  async registerAgent(params: {
+    owner: PublicKey;
+    name: string;
+    serviceCategory: Record<string, Record<string, never>>;
+    agentCardUrl: string;
+    agentCardHash: number[] | Uint8Array;
+  }) {
+    const [configPda] = RegistryClient.findConfigPda(this.program.programId);
+    const [agentPda] = RegistryClient.findAgentPda(
+      params.owner,
+      this.program.programId
+    );
+
+    return this.program.methods
+      .registerAgent(
+        params.name,
+        params.serviceCategory as any,
+        params.agentCardUrl,
+        Array.from(params.agentCardHash),
+      )
+      .accounts({
+        owner: params.owner,
+        config: configPda,
+        agent: agentPda,
+        deactivationRecord: PublicKey.findProgramAddressSync(
+          [SEEDS.DEACTIVATED, params.owner.toBuffer()],
+          this.program.programId,
+        )[0],
+        systemProgram: SystemProgram.programId,
+      } as any)
+      .rpc();
+  }
+
+  async updateAgent(params: {
+    owner: PublicKey;
+    agentPda: PublicKey;
+    newCapabilities?: BN | number | null;
+    newName?: string | null;
+    newServiceCategory?: Record<string, Record<string, never>> | null;
+    newVersion?: string | null;
+    newAgentCardUrl?: string | null;
+    newAgentCardHash?: number[] | Uint8Array | null;
+  }) {
+    const [configPda] = RegistryClient.findConfigPda(this.program.programId);
+
+    return this.program.methods
+      .updateAgent(
+        params.newCapabilities !== undefined && params.newCapabilities !== null
+          ? new BN(params.newCapabilities) : null,
+        params.newName ?? null,
+        (params.newServiceCategory as any) ?? null,
+        params.newVersion ?? null,
+        params.newAgentCardUrl ?? null,
+        params.newAgentCardHash ? Array.from(params.newAgentCardHash) : null,
+      )
+      .accounts({
+        owner: params.owner,
+        config: configPda,
+        agent: params.agentPda,
+      } as any)
+      .rpc();
+  }
+
+  async deactivateAgent(params: {
+    owner: PublicKey;
+    agentPda: PublicKey;
+  }) {
+    const [configPda] = RegistryClient.findConfigPda(this.program.programId);
+
+    return this.program.methods
+      .deactivateAgent()
+      .accounts({
+        owner: params.owner,
+        config: configPda,
+        agent: params.agentPda,
+        deactivationRecord: PublicKey.findProgramAddressSync(
+          [SEEDS.DEACTIVATED, params.owner.toBuffer()],
+          this.program.programId,
+        )[0],
+        systemProgram: SystemProgram.programId,
+      } as any)
+      .rpc();
+  }
+
+  async closeAgent(params: {
+    owner: PublicKey;
+    agentPda: PublicKey;
+  }) {
+    // V6-M10: Include stake_account PDA required by on-chain CloseAgent
+    const [stakePda] = PublicKey.findProgramAddressSync(
+      [SEEDS.STAKE, params.agentPda.toBuffer()],
+      this.program.programId,
+    );
+    const [configPda] = RegistryClient.findConfigPda(this.program.programId);
+
+    return this.program.methods
+      .closeAgent()
+      .accounts({
+        owner: params.owner,
+        config: configPda,
+        agent: params.agentPda,
+        stakeAccount: stakePda,
+      } as any)
+      .rpc();
+  }
+
+  async suspendAgent(params: {
+    authority: PublicKey;
+    agentPda: PublicKey;
+  }) {
+    const [configPda] = RegistryClient.findConfigPda(this.program.programId);
+
+    return this.program.methods
+      .suspendAgent()
+      .accounts({
+        authority: params.authority,
+        config: configPda,
+        agent: params.agentPda,
+      } as any)
+      .rpc();
+  }
+
+  async reactivateAgent(params: {
+    authority: PublicKey;
+    agentPda: PublicKey;
+  }) {
+    const [configPda] = RegistryClient.findConfigPda(this.program.programId);
+
+    return this.program.methods
+      .reactivateAgent()
+      .accounts({
+        authority: params.authority,
+        config: configPda,
+        agent: params.agentPda,
+      } as any)
+      .rpc();
+  }
+
+  async closeDeactivationRecord(params: {
+    owner: PublicKey;
+  }) {
+    const [configPda] = RegistryClient.findConfigPda(this.program.programId);
+    const [deactivationRecordPda] = PublicKey.findProgramAddressSync(
+      [SEEDS.DEACTIVATED, params.owner.toBuffer()],
+      this.program.programId,
+    );
+
+    return this.program.methods
+      .closeDeactivationRecord()
+      .accounts({
+        owner: params.owner,
+        config: configPda,
+        deactivationRecord: deactivationRecordPda,
+      } as any)
+      .rpc();
+  }
+
+  async checkAgentEligibility(agentPda: PublicKey) {
+    const [configPda] = RegistryClient.findConfigPda(this.program.programId);
+
+    return this.program.methods
+      .checkAgentEligibility()
+      .accounts({
+        agent: agentPda,
+        config: configPda,
+      } as any)
+      .rpc();
+  }
+
+  async verifyAgent(agentPda: PublicKey) {
+    const [configPda] = RegistryClient.findConfigPda(this.program.programId);
+
+    return this.program.methods
+      .verifyAgent()
+      .accounts({
+        agent: agentPda,
+        config: configPda,
+      } as any)
+      .rpc();
+  }
+
+  // ── Fetchers ──
+
+  async fetchConfig(): Promise<VouchConfig> {
+    const [configPda] = RegistryClient.findConfigPda(this.program.programId);
+    return this.program.account.vouchConfig.fetch(configPda) as Promise<any>;
+  }
+
+  async fetchAgent(agentPda: PublicKey): Promise<AgentIdentity> {
+    return this.program.account.agentIdentity.fetch(agentPda) as Promise<any>;
+  }
+
+  async fetchAgentByOwner(owner: PublicKey): Promise<AgentIdentity> {
+    const [agentPda] = RegistryClient.findAgentPda(
+      owner,
+      this.program.programId
+    );
+    return this.fetchAgent(agentPda);
+  }
+
+  async fetchDeactivationRecord(owner: PublicKey): Promise<any> {
+    const [pda] = RegistryClient.findDeactivationRecordPda(
+      owner,
+      this.program.programId
+    );
+    return this.program.account.deactivationRecord.fetch(pda);
+  }
+
+  // ── DID Resolution ──
+
+  /**
+   * Derive the W3C DID (did:sol:<base58>) for an agent owner.
+   */
+  static deriveAgentDid(owner: PublicKey): string {
+    return deriveAgentDid(owner);
+  }
+
+  /**
+   * Resolve a did:sol URI to the on-chain AgentIdentity.
+   * Returns null if the DID is invalid or the agent doesn't exist.
+   */
+  async resolveAgentByDid(did: string): Promise<AgentIdentity | null> {
+    const owner = parseDid(did);
+    if (!owner) return null;
+    try {
+      return await this.fetchAgentByOwner(owner);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Generate a W3C DID Document for a Vouch-registered agent.
+   */
+  async generateDidDocument(owner: PublicKey): Promise<DidDocument> {
+    const [agentPda] = RegistryClient.findAgentPda(
+      owner,
+      this.program.programId
+    );
+    const agent = await this.fetchAgent(agentPda);
+    return generateDidDocument({ owner, agentPda, agent });
+  }
+}

package/src/types.ts

@@ -0,0 +1,129 @@
+import { PublicKey } from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+
+// ── Enums ──
+
+export enum AgentTier {
+  Observer = "observer",
+  Basic = "basic",
+  Standard = "standard",
+  Premium = "premium",
+}
+
+export enum AgentStatus {
+  Active = "active",
+  Suspended = "suspended",
+  Deactivated = "deactivated",
+}
+
+export enum ServiceCategory {
+  Commerce = "commerce",
+  DataAnalysis = "dataAnalysis",
+  ContentCreation = "contentCreation",
+  CustomerService = "customerService",
+  Financial = "financial",
+  Logistics = "logistics",
+  Development = "development",
+  Research = "research",
+  Other = "other",
+}
+
+// ── Account types ──
+
+export interface VouchConfig {
+  admin: PublicKey;
+  pendingAdmin: PublicKey | null;
+  paused: boolean;
+  treasury: PublicKey;
+  usdcMint: PublicKey;
+  tierThresholds: [BN, BN, BN, BN];
+  cooldownPeriod: BN;
+  stakeToTxRatio: number;
+  bump: number;
+}
+
+export interface AgentIdentity {
+  owner: PublicKey;
+  tier: { [key in AgentTier]?: {} };
+  capabilities: BN;
+  name: string;
+  serviceCategory: { [key in ServiceCategory]?: {} };
+  version: string;
+  agentCardUrl: string;
+  agentCardHash: number[];
+  status: { [key in AgentStatus]?: {} };
+  createdAt: BN;
+  updatedAt: BN;
+  bump: number;
+  reputationScore: number;
+  reputationUpdatedAt: BN;
+  reputationChangeToday: number;
+  reputationDayStart: BN;
+  tierEffectiveAt: BN;
+  suspendedBy: PublicKey | null;
+}
+
+export interface StakeAccount {
+  agent: PublicKey;
+  owner: PublicKey;
+  depositedAmount: BN;
+  lockedAmount: BN;
+  pendingWithdrawal: BN;
+  bump: number;
+}
+
+export interface WithdrawalRequest {
+  stakeAccount: PublicKey;
+  owner: PublicKey;
+  amount: BN;
+  unlockAt: BN;
+  createdAt: BN;
+  bump: number;
+}
+
+export interface PendingConfigChange {
+  proposer: PublicKey;
+  proposedAt: BN;
+  executableAt: BN;
+  newTierThresholds: [BN, BN, BN, BN] | null;
+  newCooldownPeriod: BN | null;
+  newTreasury: PublicKey | null;
+  newStakeToTxRatio: number | null;
+  bump: number;
+}
+
+export interface DeactivationRecord {
+  owner: PublicKey;
+  deactivatedAt: BN;
+  finalReputationScore: number;
+  bump: number;
+}
+
+export interface ReputationReporter {
+  authority: PublicKey;
+  registeredBy: PublicKey;
+  label: string;
+  weight: number;
+  totalReports: BN;
+  lastReportSlot: BN;
+  isActive: boolean;
+  bump: number;
+}
+
+// ── Helper for parsing Anchor enum variants ──
+
+export function parseEnum<T extends string>(
+  enumObj: { [key: string]: {} | undefined } | null | undefined,
+  enumType: Record<string, T>
+): T | null {
+  if (!enumObj) return null;
+  const objKey = Object.keys(enumObj)[0];
+  if (!objKey) return null;
+  const lowerKey = objKey.toLowerCase();
+  for (const [enumKey, enumValue] of Object.entries(enumType)) {
+    if (enumKey.toLowerCase() === lowerKey) {
+      return enumValue;
+    }
+  }
+  return null;
+}

package/src/vault.ts

@@ -0,0 +1,208 @@
+import { Program, AnchorProvider, BN } from "@coral-xyz/anchor";
+import { PublicKey, SystemProgram } from "@solana/web3.js";
+import { TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID, getAssociatedTokenAddressSync } from "@solana/spl-token";
+import { Kya } from "../../target/types/kya";
+import { SEEDS, VOUCH_PROGRAM_ID } from "./constants";
+import type { StakeAccount, WithdrawalRequest } from "./types";
+
+export class VaultClient {
+  constructor(
+    public readonly program: Program<Kya>,
+    public readonly provider: AnchorProvider
+  ) {}
+
+  // ── PDA derivation ──
+
+  static findConfigPda(
+    programId: PublicKey = VOUCH_PROGRAM_ID
+  ): [PublicKey, number] {
+    return PublicKey.findProgramAddressSync([SEEDS.VOUCH_CONFIG], programId);
+  }
+
+  static findStakePda(
+    agentPda: PublicKey,
+    programId: PublicKey = VOUCH_PROGRAM_ID
+  ): [PublicKey, number] {
+    return PublicKey.findProgramAddressSync(
+      [SEEDS.STAKE, agentPda.toBuffer()],
+      programId
+    );
+  }
+
+  static findWithdrawalPda(
+    stakeAccountPda: PublicKey,
+    programId: PublicKey = VOUCH_PROGRAM_ID
+  ): [PublicKey, number] {
+    return PublicKey.findProgramAddressSync(
+      [SEEDS.WITHDRAWAL, stakeAccountPda.toBuffer()],
+      programId
+    );
+  }
+
+  /**
+   * V6-M04: Derive the canonical vault token account (ATA of config PDA for USDC mint).
+   * This is the only vault address accepted by the on-chain program.
+   */
+  static findVaultTokenAccount(usdcMint: PublicKey, programId: PublicKey = VOUCH_PROGRAM_ID): PublicKey {
+    const [configPda] = VaultClient.findConfigPda(programId);
+    return getAssociatedTokenAddressSync(usdcMint, configPda, true);
+  }
+
+  // ── Instructions (agent owner / user operations) ──
+
+  async deposit(params: {
+    owner: PublicKey;
+    agentPda: PublicKey;
+    ownerTokenAccount: PublicKey;
+    vaultTokenAccount: PublicKey;
+    amount: BN | number;
+  }) {
+    const [configPda] = VaultClient.findConfigPda(this.program.programId);
+    const [stakePda] = VaultClient.findStakePda(
+      params.agentPda,
+      this.program.programId
+    );
+
+    return this.program.methods
+      .deposit(new BN(params.amount))
+      .accounts({
+        owner: params.owner,
+        config: configPda,
+        agent: params.agentPda,
+        stakeAccount: stakePda,
+        ownerTokenAccount: params.ownerTokenAccount,
+        vaultTokenAccount: params.vaultTokenAccount,
+        tokenProgram: TOKEN_PROGRAM_ID,
+        systemProgram: SystemProgram.programId,
+      } as any)
+      .rpc();
+  }
+
+  async requestWithdrawal(params: {
+    owner: PublicKey;
+    agentPda: PublicKey;
+    stakeAccountPda: PublicKey;
+    amount: BN | number;
+  }) {
+    const [configPda] = VaultClient.findConfigPda(this.program.programId);
+    const [withdrawalPda] = VaultClient.findWithdrawalPda(
+      params.stakeAccountPda,
+      this.program.programId
+    );
+
+    return this.program.methods
+      .requestWithdrawal(new BN(params.amount))
+      .accounts({
+        owner: params.owner,
+        config: configPda,
+        agent: params.agentPda,
+        stakeAccount: params.stakeAccountPda,
+        withdrawalRequest: withdrawalPda,
+        systemProgram: SystemProgram.programId,
+      } as any)
+      .rpc();
+  }
+
+  async completeWithdrawal(params: {
+    owner: PublicKey;
+    stakeAccountPda: PublicKey;
+    agentPda: PublicKey;
+    vaultTokenAccount: PublicKey;
+    ownerTokenAccount: PublicKey;
+  }) {
+    const [configPda] = VaultClient.findConfigPda(this.program.programId);
+    const [withdrawalPda] = VaultClient.findWithdrawalPda(
+      params.stakeAccountPda,
+      this.program.programId
+    );
+
+    return this.program.methods
+      .completeWithdrawal()
+      .accounts({
+        owner: params.owner,
+        config: configPda,
+        agent: params.agentPda,
+        stakeAccount: params.stakeAccountPda,
+        withdrawalRequest: withdrawalPda,
+        vaultTokenAccount: params.vaultTokenAccount,
+        ownerTokenAccount: params.ownerTokenAccount,
+        tokenProgram: TOKEN_PROGRAM_ID,
+        systemProgram: SystemProgram.programId,
+      } as any)
+      .rpc();
+  }
+
+  async cancelWithdrawal(params: {
+    owner: PublicKey;
+    agentPda: PublicKey;
+    stakeAccountPda: PublicKey;
+  }) {
+    const [configPda] = VaultClient.findConfigPda(this.program.programId);
+    const [withdrawalPda] = VaultClient.findWithdrawalPda(
+      params.stakeAccountPda,
+      this.program.programId
+    );
+
+    return this.program.methods
+      .cancelWithdrawal()
+      .accounts({
+        owner: params.owner,
+        config: configPda,
+        agent: params.agentPda,
+        stakeAccount: params.stakeAccountPda,
+        withdrawalRequest: withdrawalPda,
+      } as any)
+      .rpc();
+  }
+
+  // ── Instructions (owner cleanup operations) ──
+
+  async closeStake(params: {
+    owner: PublicKey;
+    agentPda: PublicKey;
+  }) {
+    const [configPda] = VaultClient.findConfigPda(this.program.programId);
+    const [stakePda] = VaultClient.findStakePda(params.agentPda, this.program.programId);
+
+    return this.program.methods
+      .closeStake()
+      .accounts({
+        owner: params.owner,
+        config: configPda,
+        agent: params.agentPda,
+        stakeAccount: stakePda,
+      } as any)
+      .rpc();
+  }
+
+  // ── Fetchers ──
+
+  async fetchConfig(): Promise<any> {
+    const [configPda] = VaultClient.findConfigPda(this.program.programId);
+    return this.program.account.vouchConfig.fetch(configPda) as Promise<any>;
+  }
+
+  async fetchStakeAccount(stakePda: PublicKey): Promise<StakeAccount> {
+    return this.program.account.stakeAccount.fetch(stakePda) as Promise<any>;
+  }
+
+  async fetchStakeByAgent(agentPda: PublicKey): Promise<StakeAccount> {
+    const [stakePda] = VaultClient.findStakePda(
+      agentPda,
+      this.program.programId
+    );
+    return this.fetchStakeAccount(stakePda);
+  }
+
+  async fetchWithdrawalRequest(
+    stakeAccountPda: PublicKey
+  ): Promise<WithdrawalRequest> {
+    const [withdrawalPda] = VaultClient.findWithdrawalPda(
+      stakeAccountPda,
+      this.program.programId
+    );
+    return this.program.account.withdrawalRequest.fetch(
+      withdrawalPda
+    ) as Promise<any>;
+  }
+}