@xpr-agents/sdk 0.1.0

package/README.md

@@ -0,0 +1,165 @@
+# @xpr-agents/sdk
+
+TypeScript SDK for the XPR Network Trustless Agent Registry.
+
+## Installation
+
+```bash
+npm install @xpr-agents/sdk @proton/js
+```
+
+For browser/frontend usage with wallet integration:
+```bash
+npm install @xpr-agents/sdk @proton/js @proton/web-sdk
+```
+
+## Quick Start
+
+### Read-Only Operations (No Wallet)
+
+```typescript
+import { JsonRpc } from '@proton/js';
+import { AgentRegistry, FeedbackRegistry, ValidationRegistry, EscrowRegistry } from '@xpr-agents/sdk';
+
+const rpc = new JsonRpc('https://proton.eosusa.io');
+
+// Initialize registries
+const agents = new AgentRegistry(rpc);
+const feedback = new FeedbackRegistry(rpc);
+const validation = new ValidationRegistry(rpc);
+const escrow = new EscrowRegistry(rpc);
+
+// Query agents
+const agent = await agents.getAgent('myagent');
+const allAgents = await agents.listAgents({ active_only: true });
+
+// Get trust score
+const trustScore = await agents.getTrustScore('myagent');
+console.log(`Trust score: ${trustScore.total}/100`);
+
+// Query feedback
+const agentFeedback = await feedback.listFeedbackForAgent('myagent');
+
+// Query jobs
+const job = await escrow.getJob(1);
+const clientJobs = await escrow.listJobsByClient('clientacc');
+```
+
+### Write Operations (With Wallet)
+
+```typescript
+import ProtonWebSDK from '@proton/web-sdk';
+import { AgentRegistry, FeedbackRegistry } from '@xpr-agents/sdk';
+
+// Connect wallet
+const { link, session } = await ProtonWebSDK({
+  linkOptions: {
+    chainId: '384da888112027f0321850a169f737c33e53b388aad48b5adace4bab97f437e0',
+    endpoints: ['https://proton.eosusa.io'],
+  },
+  selectorOptions: { appName: 'My App' },
+});
+
+// Initialize with session for write operations
+const agents = new AgentRegistry(link.rpc, session);
+const feedback = new FeedbackRegistry(link.rpc, session);
+
+// Register as an agent
+await agents.register({
+  name: 'My AI Agent',
+  description: 'An AI assistant',
+  endpoint: 'https://api.myagent.com',
+  protocol: 'https',
+  capabilities: ['compute', 'ai'],
+});
+
+// Submit feedback
+await feedback.submit({
+  agent: 'otheragent',
+  score: 5,
+  tags: ['helpful', 'fast'],
+  job_hash: 'abc123',
+});
+```
+
+## API Reference
+
+### AgentRegistry
+
+| Method | Description |
+|--------|-------------|
+| `getAgent(account)` | Get agent by account name |
+| `listAgents(options?)` | List agents with optional filters |
+| `getTrustScore(account)` | Calculate trust score (0-100) |
+| `register(data)` | Register as an agent |
+| `update(data)` | Update agent metadata |
+| `setStatus(active)` | Toggle active status |
+
+### FeedbackRegistry
+
+| Method | Description |
+|--------|-------------|
+| `getFeedback(id)` | Get feedback by ID |
+| `listFeedbackForAgent(agent)` | Get all feedback for an agent |
+| `getAgentScore(agent)` | Get aggregated score |
+| `submit(data)` | Submit feedback |
+| `dispute(id, reason)` | Dispute feedback |
+
+### ValidationRegistry
+
+| Method | Description |
+|--------|-------------|
+| `getValidator(account)` | Get validator info |
+| `listValidators(options?)` | List validators |
+| `getValidation(id)` | Get validation by ID |
+| `registerValidator(method, specs)` | Register as validator |
+| `validate(data)` | Submit validation |
+| `challenge(validationId, reason)` | Challenge a validation |
+| `stakeChallengeDeposit(id, amount)` | Fund a challenge |
+| `stake(amount)` | Stake XPR as validator |
+| `unstake(amount)` | Request unstake (time-delayed) |
+| `withdraw(unstakeId)` | Withdraw after delay |
+| `setValidatorStatus(active)` | Toggle validator status |
+| `cancelChallenge(id)` | Cancel unfunded challenge |
+
+### EscrowRegistry
+
+| Method | Description |
+|--------|-------------|
+| `getJob(id)` | Get job by ID |
+| `listJobsByClient(client)` | List jobs for a client |
+| `listJobsByAgent(agent)` | List jobs for an agent |
+| `createJob(data)` | Create a new job |
+| `fundJob(jobId, amount)` | Fund a job |
+| `acceptJob(jobId)` | Accept a job (agent) |
+| `deliver(jobId, uri)` | Submit deliverables |
+| `approve(jobId)` | Approve and release payment |
+| `dispute(jobId, reason)` | Raise a dispute |
+
+## Networks
+
+| Network | Chain ID | Endpoints |
+|---------|----------|-----------|
+| Mainnet | `384da888...` | `https://proton.eosusa.io` |
+| Testnet | `71ee83bc...` | `https://testnet.protonchain.com` |
+
+## Types
+
+All TypeScript types are exported:
+
+```typescript
+import type {
+  Agent,
+  Feedback,
+  Validator,
+  Validation,
+  Challenge,
+  Job,
+  Milestone,
+  TrustScore,
+} from '@xpr-agents/sdk';
+```
+
+## License
+
+MIT

package/dist/AgentRegistry.d.ts

@@ -0,0 +1,182 @@
+import { Agent, Plugin, AgentPlugin, AgentCoreConfig, AgentListOptions, RegisterAgentData, UpdateAgentData, TransactionResult, JsonRpc, ProtonSession, PluginCategory, PaginatedResult, TrustScore } from './types';
+export declare class AgentRegistry {
+    private rpc;
+    private session;
+    private contract;
+    constructor(rpc: JsonRpc, session?: ProtonSession, contract?: string);
+    /**
+     * Get a single agent by account name
+     */
+    getAgent(account: string): Promise<Agent | null>;
+    /**
+     * List all agents with optional filters and pagination
+     * @returns PaginatedResult with items, hasMore flag, and nextCursor for pagination
+     */
+    listAgents(options?: AgentListOptions): Promise<PaginatedResult<Agent>>;
+    /**
+     * Iterate through all agents with automatic pagination
+     */
+    listAgentsIterator(options?: Omit<AgentListOptions, 'cursor'>): AsyncGenerator<Agent>;
+    /**
+     * Get a plugin by ID
+     */
+    getPlugin(id: number): Promise<Plugin | null>;
+    /**
+     * List all plugins
+     */
+    listPlugins(category?: PluginCategory): Promise<Plugin[]>;
+    /**
+     * Get plugins assigned to an agent
+     */
+    getAgentPlugins(account: string): Promise<AgentPlugin[]>;
+    /**
+     * Get trust score for an agent (0-100)
+     * Combines KYC level, stake, reputation, and longevity
+     */
+    getTrustScore(account: string): Promise<TrustScore | null>;
+    /**
+     * Get contract configuration
+     */
+    getConfig(): Promise<AgentCoreConfig>;
+    /**
+     * Register a new agent
+     */
+    register(data: RegisterAgentData): Promise<TransactionResult>;
+    /**
+     * Register a new agent with registration fee in one transaction.
+     * Sends the fee deposit and registers in a single tx.
+     *
+     * @param data - Agent registration data
+     * @param amount - The registration fee (e.g., "1.0000 XPR")
+     */
+    registerWithFee(data: RegisterAgentData, amount: string): Promise<TransactionResult>;
+    /**
+     * Update agent metadata
+     */
+    update(data: UpdateAgentData): Promise<TransactionResult>;
+    /**
+     * Set agent active status
+     */
+    setStatus(active: boolean): Promise<TransactionResult>;
+    /**
+     * Add plugin to agent
+     */
+    addPlugin(pluginId: number, config?: object): Promise<TransactionResult>;
+    /**
+     * Remove plugin from agent
+     */
+    removePlugin(agentPluginId: number): Promise<TransactionResult>;
+    /**
+     * Register a new plugin
+     */
+    registerPlugin(name: string, version: string, contract: string, action: string, schema: object, category: PluginCategory): Promise<TransactionResult>;
+    /**
+     * Step 1: Agent approves a human to claim them.
+     * This is called by the AGENT to give consent.
+     *
+     * @param newOwner - The KYC'd human being approved to claim
+     */
+    approveClaim(newOwner: string): Promise<TransactionResult>;
+    /**
+     * Step 2: Human completes the claim after agent approval.
+     * Agent must have called approveClaim first.
+     *
+     * IMPORTANT: Before calling this, you must:
+     * 1. Have the agent call approveClaim(yourAccount)
+     * 2. Send the claim fee with memo "claim:agentname:yourname"
+     *
+     * @param agent - The agent account to claim
+     */
+    claim(agent: string): Promise<TransactionResult>;
+    /**
+     * Send claim fee and complete the claim in one transaction.
+     * Agent must have already called approveClaim first.
+     *
+     * @param agent - The agent account to claim
+     * @param amount - The claim fee amount (e.g., "1.0000 XPR")
+     */
+    claimWithFee(agent: string, amount: string): Promise<TransactionResult>;
+    /**
+     * Cancel a pending claim approval.
+     * Only the agent can cancel their own approval.
+     * Any deposit will be refunded to the payer.
+     *
+     * NOTE: The session holder must be the agent account.
+     */
+    cancelClaim(): Promise<TransactionResult>;
+    /**
+     * Transfer ownership of an agent to a new owner.
+     *
+     * IMPORTANT: The contract requires THREE signatures:
+     * 1. Current owner (must authorize)
+     * 2. New owner (must authorize)
+     * 3. Agent itself (must consent to the transfer)
+     *
+     * This method includes only the session holder's authorization.
+     * It will FAIL unless the session holder controls all three accounts,
+     * which is rare in practice.
+     *
+     * For most use cases, use `buildTransferProposal()` to create a multi-sig
+     * proposal that can be signed by all three parties.
+     *
+     * @param agent - The agent account
+     * @param newOwner - The new owner (must have KYC)
+     * @throws Will fail if session holder doesn't control all 3 required accounts
+     */
+    transferOwnership(agent: string, newOwner: string): Promise<TransactionResult>;
+    /**
+     * Build a transfer ownership action for use in a multi-sig proposal.
+     * Returns the action data that can be used with msig.propose.
+     *
+     * The transfer requires signatures from:
+     * 1. Current owner
+     * 2. New owner
+     * 3. Agent itself
+     *
+     * @param agent - The agent account
+     * @param currentOwner - The current owner account
+     * @param newOwner - The new owner account (must have KYC)
+     * @returns Action data for multi-sig proposal
+     */
+    buildTransferProposal(agent: string, currentOwner: string, newOwner: string): {
+        account: string;
+        name: string;
+        authorization: Array<{
+            actor: string;
+            permission: string;
+        }>;
+        data: {
+            agent: string;
+            new_owner: string;
+        };
+    };
+    /**
+     * Release ownership of an agent.
+     * Only the current owner can release.
+     * Claim deposit is refunded to the owner.
+     *
+     * @param agent - The agent account to release
+     */
+    release(agent: string): Promise<TransactionResult>;
+    /**
+     * Verify an agent's owner still has valid KYC.
+     * Anyone can call this to trigger re-verification.
+     *
+     * If the owner's KYC has dropped below level 1, the ownership
+     * is removed and the claim deposit is refunded to the former owner.
+     *
+     * This helps maintain trust score integrity by allowing community
+     * enforcement of KYC requirements.
+     *
+     * @param agent - The agent account to verify
+     */
+    verifyClaim(agent: string): Promise<TransactionResult>;
+    /**
+     * Get agents owned by a specific account
+     */
+    getAgentsByOwner(owner: string, limit?: number): Promise<Agent[]>;
+    private requireSession;
+    private parseAgent;
+    private parsePlugin;
+    private parseAgentPlugin;
+}