@paypol-protocol/aps-1 1.0.0

package/README.md

@@ -0,0 +1,337 @@
+# APS-1: Agent Payment Standard v1.0
+
+> The open protocol standard for AI agent payments on blockchain.
+
+**APS-1** defines how AI agents discover, negotiate, escrow, execute, verify, and settle payments - providing a universal interface for the AI agent economy.
+
+## Why APS-1?
+
+Today, every AI agent platform has its own payment mechanism. APS-1 standardizes this into a single protocol that works across frameworks (OpenAI, Anthropic, LangChain, CrewAI, MCP, Eliza) and chains.
+
+| Before APS-1 | After APS-1 |
+|---|---|
+| Every platform = custom integration | One standard, every framework |
+| Trust the agent blindly | Verifiable execution proofs |
+| Pay upfront, hope for the best | Escrow-protected payments |
+| No reputation portability | On-chain reputation scores |
+
+## Protocol Overview
+
+APS-1 defines a 6-phase lifecycle for agent payments:
+
+```
+┌─────────────────────────────────────────────────────┐
+│                  APS-1 Protocol Flow                │
+│                                                     │
+│  1. DISCOVER  ──→  GET /manifest                    │
+│                    Returns APS1Manifest              │
+│                                                     │
+│  2. NEGOTIATE ──→  POST /negotiate  (optional)      │
+│                    Price negotiation messages         │
+│                                                     │
+│  3. ESCROW    ──→  Lock funds on-chain              │
+│                    NexusV2 | StreamV1 | Direct       │
+│                                                     │
+│  4. EXECUTE   ──→  POST /execute                    │
+│                    Send APS1ExecutionEnvelope         │
+│                    Receive APS1Result                 │
+│                                                     │
+│  5. VERIFY    ──→  AIProofRegistry verification     │
+│                    planHash vs resultHash matching    │
+│                                                     │
+│  6. SETTLE    ──→  Release escrow payment            │
+│                    Agent payout - platform fee        │
+└─────────────────────────────────────────────────────┘
+```
+
+## Installation
+
+```bash
+npm install @paypol-protocol/aps-1
+```
+
+## Quick Start
+
+### Build an APS-1 Agent
+
+```typescript
+import { APS1Agent } from '@paypol-protocol/aps-1';
+
+const agent = new APS1Agent({
+  id: 'data-analyzer',
+  name: 'Data Analyzer',
+  description: 'Analyzes on-chain data and generates reports',
+  category: 'analytics',
+  version: '1.0.0',
+  pricing: { basePrice: 5, currency: 'USD', negotiable: true, minPrice: 2 },
+  capabilities: ['analyze-transactions', 'generate-report', 'trend-detection'],
+  walletAddress: '0xYourAgentWallet',
+});
+
+agent.onExecute(async (envelope) => {
+  // Your agent logic here
+  const analysis = await analyzeData(envelope.prompt, envelope.payload);
+
+  return {
+    status: 'success',
+    result: analysis,
+    onChain: {
+      executed: true,
+      transactions: [{ hash: '0x...', blockNumber: 1234, gasUsed: '21000', explorerUrl: '...' }],
+      network: 'Tempo L1 Moderato',
+      chainId: 42431,
+    },
+  };
+});
+
+// Optional: support price negotiation
+agent.onNegotiate(async (message) => {
+  if (message.type === 'propose' && message.price >= 3) {
+    return { type: 'accept', jobId: message.jobId, price: message.price, currency: 'USD', timestamp: new Date().toISOString() };
+  }
+  return { type: 'counter', jobId: message.jobId, price: 4, currency: 'USD', message: 'Minimum $4 for this task', timestamp: new Date().toISOString() };
+});
+
+agent.listen(3002);
+```
+
+### Hire an APS-1 Agent
+
+```typescript
+import { APS1Client } from '@paypol-protocol/aps-1';
+
+const client = new APS1Client({
+  agentServiceUrl: 'https://paypol.xyz',
+});
+
+// Discover available agents
+const agents = await client.listAgents();
+const analytics = await client.searchAgents({ category: 'analytics', maxPrice: 10 });
+
+// Execute a job
+const result = await client.execute(
+  'data-analyzer',
+  'Analyze top 100 transactions on Tempo L1 this week',
+  '0xMyWallet',
+);
+
+console.log(result.status);  // 'success'
+console.log(result.result);  // { analysis: ... }
+```
+
+### Validate APS-1 Data
+
+```typescript
+import { validateManifest, validateResult } from '@paypol-protocol/aps-1';
+
+// Validate a manifest
+const manifestCheck = validateManifest(someData);
+if (!manifestCheck.success) {
+  console.error('Invalid manifest:', manifestCheck.errors);
+}
+
+// Validate a result
+const resultCheck = validateResult(someResult);
+if (resultCheck.success) {
+  console.log('Valid result:', resultCheck.data);
+}
+```
+
+## Specification
+
+### Phase 1: Discovery
+
+Every APS-1 agent MUST serve a manifest at `GET /manifest`:
+
+```json
+{
+  "aps": "1.0",
+  "id": "data-analyzer",
+  "name": "Data Analyzer",
+  "description": "Analyzes on-chain data and generates reports",
+  "category": "analytics",
+  "version": "1.0.0",
+  "pricing": {
+    "basePrice": 5.00,
+    "currency": "USD",
+    "negotiable": true,
+    "minPrice": 2.00
+  },
+  "capabilities": ["analyze-transactions", "generate-report"],
+  "paymentMethods": ["nexus-escrow", "stream-milestone", "direct-transfer"],
+  "supportedTokens": [
+    { "symbol": "AlphaUSD", "address": "0x20c0...0001", "decimals": 6 }
+  ],
+  "proofEnabled": true,
+  "walletAddress": "0xAgentWallet",
+  "endpoints": {
+    "manifest": "https://agent.example.com/manifest",
+    "execute": "https://agent.example.com/execute",
+    "negotiate": "https://agent.example.com/negotiate",
+    "status": "https://agent.example.com/status",
+    "health": "https://agent.example.com/health"
+  }
+}
+```
+
+### Phase 2: Negotiation (Optional)
+
+If `pricing.negotiable` is `true`, clients MAY negotiate price via `POST /negotiate`:
+
+```json
+// Client proposes
+{ "type": "propose", "jobId": "job-123", "price": 3.00, "currency": "USD" }
+
+// Agent counters
+{ "type": "counter", "jobId": "job-123", "price": 4.00, "currency": "USD", "message": "Minimum $4" }
+
+// Client accepts
+{ "type": "accept", "jobId": "job-123", "price": 4.00, "currency": "USD" }
+```
+
+### Phase 3: Escrow
+
+Before execution, the client locks funds using one of three methods:
+
+| Method | Contract | Use Case |
+|--------|----------|----------|
+| `nexus-escrow` | NexusV2 | Single job with dispute resolution |
+| `stream-milestone` | PayPolStreamV1 | Multi-milestone projects |
+| `direct-transfer` | ERC20 transfer | Trusted agents, small amounts |
+
+### Phase 4: Execution
+
+Client sends an `APS1ExecutionEnvelope` to `POST /execute`:
+
+```json
+{
+  "jobId": "job-123",
+  "agentId": "data-analyzer",
+  "prompt": "Analyze top 100 transactions",
+  "callerWallet": "0xClientWallet",
+  "escrow": {
+    "contractAddress": "0x6A467Cd4156093bB528e448C04366586a1052Fab",
+    "onChainId": 42,
+    "txHash": "0xabc...",
+    "method": "nexus-escrow"
+  },
+  "proof": {
+    "planHash": "0xdef...",
+    "commitmentId": "proof-42",
+    "commitTxHash": "0x789..."
+  },
+  "timestamp": "2025-01-15T10:30:00Z"
+}
+```
+
+Agent returns an `APS1Result`:
+
+```json
+{
+  "jobId": "job-123",
+  "agentId": "data-analyzer",
+  "status": "success",
+  "result": { "analysis": "...", "topTransactions": [...] },
+  "onChain": {
+    "executed": true,
+    "transactions": [
+      { "hash": "0x...", "blockNumber": 54321, "gasUsed": "150000", "explorerUrl": "https://explore.tempo.xyz/tx/0x..." }
+    ],
+    "network": "Tempo L1 Moderato",
+    "chainId": 42431
+  },
+  "proof": {
+    "resultHash": "0xabc...",
+    "verifyTxHash": "0xdef...",
+    "matched": true
+  },
+  "executionTimeMs": 4520,
+  "timestamp": "2025-01-15T10:30:04Z"
+}
+```
+
+### Phase 5: Verification
+
+If `proofEnabled` is `true`, the agent's execution is verified via `AIProofRegistry`:
+
+1. **Commit**: Before execution, agent commits `planHash` on-chain
+2. **Execute**: Agent performs the work
+3. **Verify**: After execution, agent submits `resultHash` for verification
+4. **Match**: `planHash === resultHash` → proof of honest execution
+
+### Phase 6: Settlement
+
+After successful execution and verification:
+
+- **Success**: Escrow releases payment to agent (minus platform fee)
+- **Failure**: Client can dispute via NexusV2 judge mechanism
+- **Timeout**: If agent doesn't deliver within deadline, client gets refund
+
+```json
+{
+  "jobId": "job-123",
+  "type": "settle",
+  "agentPayout": "4600000",
+  "platformFee": "400000",
+  "txHash": "0x...",
+  "timestamp": "2025-01-15T10:31:00Z"
+}
+```
+
+## Protocol Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `APS1_VERSION` | `1.0` | Protocol version |
+| `APS1_CHAIN_ID` | `42431` | Tempo L1 Moderato |
+| `APS1_PLATFORM_FEE_BPS` | `800` | 8% platform fee |
+| `APS1_NETWORK` | `Tempo L1 Moderato` | Network name |
+
+## Smart Contracts
+
+| Contract | Address | Purpose |
+|----------|---------|---------|
+| NexusV2 | `0x6A467Cd4156093bB528e448C04366586a1052Fab` | Escrow + dispute |
+| PayPolStreamV1 | `0x4fE37c46E3D442129c2319de3D24c21A6cbfa36C` | Milestone streams |
+| AIProofRegistry | `0x8fDB8E871c9eaF2955009566F41490Bbb128a014` | Execution proofs |
+| ReputationRegistry | `0x9332c1B2bb94C96DA2D729423f345c76dB3494D0` | Agent reputation |
+| ShieldVaultV2 | `0x3B4b47971B61cB502DD97eAD9cAF0552ffae0055` | Privacy payments |
+| MultisendV2 | `0x25f4d3f12C579002681a52821F3a6251c46D4575` | Batch payments |
+
+## Supported Tokens
+
+| Token | Address | Decimals |
+|-------|---------|----------|
+| AlphaUSD | `0x20c0000000000000000000000000000000000001` | 6 |
+| pathUSD | `0x20c0000000000000000000000000000000000000` | 6 |
+| BetaUSD | `0x20c0000000000000000000000000000000000002` | 6 |
+| ThetaUSD | `0x20c0000000000000000000000000000000000003` | 6 |
+
+## Framework Compatibility
+
+APS-1 is framework-agnostic. Use the `paypol-sdk` adapters:
+
+```typescript
+// OpenAI function-calling
+import { toOpenAITools } from 'paypol-sdk/openai';
+
+// Anthropic tool-use
+import { toAnthropicTools } from 'paypol-sdk/anthropic';
+
+// LangChain
+import { PayPolToolkit } from 'paypol-sdk/langchain';
+
+// CrewAI
+import { PayPolCrewAITool } from 'paypol-sdk/crewai';
+
+// MCP
+import { PayPolMCPServer } from 'paypol-sdk/mcp';
+```
+
+## Contributing
+
+Want to build APS-1 compliant agents? See the [Contributing Guide](../../CONTRIBUTING.md).
+
+## License
+
+MIT

package/dist/aps1-agent.d.ts

@@ -0,0 +1,88 @@
+/**
+ * APS-1 Reference Agent
+ *
+ * An Express-based agent server that implements the full APS-1 protocol.
+ * Extends the standard PayPolAgent pattern with:
+ *   - APS-1 manifest endpoint
+ *   - Optional negotiation endpoint
+ *   - Job status tracking
+ *   - Structured APS-1 result format
+ *
+ * Usage:
+ *   const agent = new APS1Agent({
+ *     id: 'my-agent',
+ *     name: 'My Agent',
+ *     description: 'Does amazing things',
+ *     category: 'analytics',
+ *     version: '1.0.0',
+ *     pricing: { basePrice: 5, currency: 'USD', negotiable: false },
+ *     capabilities: ['analyze', 'report'],
+ *     walletAddress: '0x...',
+ *   });
+ *
+ *   agent.onExecute(async (envelope) => {
+ *     return { status: 'success', result: { ... } };
+ *   });
+ *
+ *   agent.listen(3002);
+ */
+import express from 'express';
+import type { APS1Manifest, APS1ExecutionEnvelope, APS1Result, APS1NegotiationMessage, APS1Category, APS1Pricing, APS1PaymentMethod, APS1TokenConfig } from './types';
+export interface APS1AgentConfig {
+    /** Unique agent ID (kebab-case) */
+    id: string;
+    /** Human-readable agent name */
+    name: string;
+    /** What the agent does */
+    description: string;
+    /** Agent category */
+    category: APS1Category;
+    /** Semantic version */
+    version: string;
+    /** Pricing configuration */
+    pricing: APS1Pricing;
+    /** List of capabilities */
+    capabilities: string[];
+    /** Agent's wallet address on Tempo L1 */
+    walletAddress: string;
+    /** Accepted payment methods (default: all) */
+    paymentMethods?: APS1PaymentMethod[];
+    /** Accepted tokens (default: APS1_DEFAULT_TOKENS) */
+    supportedTokens?: APS1TokenConfig[];
+    /** Whether AIProofRegistry is used (default: true) */
+    proofEnabled?: boolean;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+export type APS1ExecuteHandler = (envelope: APS1ExecutionEnvelope) => Promise<Partial<APS1Result>>;
+export type APS1NegotiateHandler = (message: APS1NegotiationMessage) => Promise<APS1NegotiationMessage>;
+export declare class APS1Agent {
+    private config;
+    private app;
+    private executeHandler?;
+    private negotiateHandler?;
+    private baseUrl;
+    /** In-memory job status tracking */
+    private jobs;
+    constructor(config: APS1AgentConfig);
+    /**
+     * Register the handler called for every APS-1 execution envelope.
+     * Return a partial APS1Result - jobId, agentId, executionTimeMs, timestamp
+     * are filled in automatically.
+     */
+    onExecute(handler: APS1ExecuteHandler): this;
+    /**
+     * Register an optional negotiation handler.
+     * If not registered, the /negotiate endpoint will return 404.
+     */
+    onNegotiate(handler: APS1NegotiateHandler): this;
+    /** Start the HTTP server. */
+    listen(port: number, cb?: () => void): void;
+    /** Generate the APS-1 manifest. */
+    toManifest(): APS1Manifest;
+    /** Get a tracked job result by ID. */
+    getJob(jobId: string): APS1Result | undefined;
+    /** Access the underlying Express app (for custom middleware). */
+    getExpressApp(): express.Application;
+    private _registerRoutes;
+}

package/dist/aps1-agent.js

@@ -0,0 +1,218 @@
+/**
+ * APS-1 Reference Agent
+ *
+ * An Express-based agent server that implements the full APS-1 protocol.
+ * Extends the standard PayPolAgent pattern with:
+ *   - APS-1 manifest endpoint
+ *   - Optional negotiation endpoint
+ *   - Job status tracking
+ *   - Structured APS-1 result format
+ *
+ * Usage:
+ *   const agent = new APS1Agent({
+ *     id: 'my-agent',
+ *     name: 'My Agent',
+ *     description: 'Does amazing things',
+ *     category: 'analytics',
+ *     version: '1.0.0',
+ *     pricing: { basePrice: 5, currency: 'USD', negotiable: false },
+ *     capabilities: ['analyze', 'report'],
+ *     walletAddress: '0x...',
+ *   });
+ *
+ *   agent.onExecute(async (envelope) => {
+ *     return { status: 'success', result: { ... } };
+ *   });
+ *
+ *   agent.listen(3002);
+ */
+import express from 'express';
+import { APS1_VERSION, APS1_DEFAULT_TOKENS, APS1_NETWORK, APS1_CHAIN_ID, } from './types';
+// ── APS-1 Agent Server ──────────────────────────────────
+export class APS1Agent {
+    config;
+    app = express();
+    executeHandler;
+    negotiateHandler;
+    baseUrl = '';
+    /** In-memory job status tracking */
+    jobs = new Map();
+    constructor(config) {
+        this.config = config;
+        this.app.use(express.json());
+        this._registerRoutes();
+    }
+    // ── Public API ──────────────────────────────────────
+    /**
+     * Register the handler called for every APS-1 execution envelope.
+     * Return a partial APS1Result - jobId, agentId, executionTimeMs, timestamp
+     * are filled in automatically.
+     */
+    onExecute(handler) {
+        this.executeHandler = handler;
+        return this;
+    }
+    /**
+     * Register an optional negotiation handler.
+     * If not registered, the /negotiate endpoint will return 404.
+     */
+    onNegotiate(handler) {
+        this.negotiateHandler = handler;
+        return this;
+    }
+    /** Start the HTTP server. */
+    listen(port, cb) {
+        this.baseUrl = `http://localhost:${port}`;
+        this.app.listen(port, () => {
+            console.log(`[APS-1] ${this.config.name} listening on port ${port}`);
+            console.log(`[APS-1] Manifest: ${this.baseUrl}/manifest`);
+            console.log(`[APS-1] Execute:  POST ${this.baseUrl}/execute`);
+            cb?.();
+        });
+    }
+    /** Generate the APS-1 manifest. */
+    toManifest() {
+        const base = this.baseUrl || 'http://localhost:3000';
+        return {
+            aps: '1.0',
+            id: this.config.id,
+            name: this.config.name,
+            description: this.config.description,
+            category: this.config.category,
+            version: this.config.version,
+            pricing: this.config.pricing,
+            capabilities: this.config.capabilities,
+            paymentMethods: this.config.paymentMethods ?? ['nexus-escrow', 'stream-milestone', 'direct-transfer'],
+            supportedTokens: this.config.supportedTokens ?? APS1_DEFAULT_TOKENS,
+            proofEnabled: this.config.proofEnabled ?? true,
+            walletAddress: this.config.walletAddress,
+            endpoints: {
+                manifest: `${base}/manifest`,
+                execute: `${base}/execute`,
+                negotiate: this.negotiateHandler ? `${base}/negotiate` : undefined,
+                status: `${base}/status`,
+                health: `${base}/health`,
+            },
+            metadata: this.config.metadata,
+        };
+    }
+    /** Get a tracked job result by ID. */
+    getJob(jobId) {
+        return this.jobs.get(jobId);
+    }
+    /** Access the underlying Express app (for custom middleware). */
+    getExpressApp() {
+        return this.app;
+    }
+    // ── Routes ──────────────────────────────────────────
+    _registerRoutes() {
+        // GET /manifest - APS-1 manifest
+        this.app.get('/manifest', (_req, res) => {
+            res.json(this.toManifest());
+        });
+        // POST /execute - APS-1 execution
+        this.app.post('/execute', async (req, res) => {
+            if (!this.executeHandler) {
+                return res.status(501).json({
+                    error: 'No execute handler registered',
+                    aps: APS1_VERSION,
+                });
+            }
+            const jobId = req.body.jobId ?? `aps1-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            const envelope = {
+                jobId,
+                agentId: this.config.id,
+                prompt: req.body.prompt ?? '',
+                payload: req.body.payload,
+                callerWallet: req.body.callerWallet ?? '',
+                escrow: req.body.escrow,
+                proof: req.body.proof,
+                timestamp: new Date().toISOString(),
+            };
+            const start = Date.now();
+            try {
+                const partial = await this.executeHandler(envelope);
+                const result = {
+                    jobId,
+                    agentId: this.config.id,
+                    status: partial.status ?? 'success',
+                    result: partial.result,
+                    error: partial.error,
+                    onChain: partial.onChain ?? {
+                        executed: false,
+                        transactions: [],
+                        network: APS1_NETWORK,
+                        chainId: APS1_CHAIN_ID,
+                    },
+                    proof: partial.proof,
+                    executionTimeMs: Date.now() - start,
+                    timestamp: new Date().toISOString(),
+                };
+                // Track the job
+                this.jobs.set(jobId, result);
+                res.json(result);
+            }
+            catch (err) {
+                const errorResult = {
+                    jobId,
+                    agentId: this.config.id,
+                    status: 'error',
+                    error: err.message ?? String(err),
+                    executionTimeMs: Date.now() - start,
+                    timestamp: new Date().toISOString(),
+                };
+                this.jobs.set(jobId, errorResult);
+                res.status(500).json(errorResult);
+            }
+        });
+        // POST /negotiate - optional price negotiation
+        this.app.post('/negotiate', async (req, res) => {
+            if (!this.negotiateHandler) {
+                return res.status(404).json({
+                    error: 'This agent does not support negotiation',
+                    aps: APS1_VERSION,
+                });
+            }
+            try {
+                const message = {
+                    type: req.body.type,
+                    jobId: req.body.jobId,
+                    price: req.body.price,
+                    currency: req.body.currency ?? 'USD',
+                    message: req.body.message,
+                    timestamp: new Date().toISOString(),
+                };
+                const response = await this.negotiateHandler(message);
+                res.json(response);
+            }
+            catch (err) {
+                res.status(500).json({
+                    error: err.message ?? String(err),
+                    aps: APS1_VERSION,
+                });
+            }
+        });
+        // GET /status/:jobId - job status
+        this.app.get('/status/:jobId', (req, res) => {
+            const job = this.jobs.get(req.params.jobId);
+            if (!job) {
+                return res.status(404).json({
+                    error: 'Job not found',
+                    aps: APS1_VERSION,
+                });
+            }
+            res.json(job);
+        });
+        // GET /health - health check
+        this.app.get('/health', (_req, res) => {
+            res.json({
+                status: 'ok',
+                aps: APS1_VERSION,
+                agent: this.config.id,
+                name: this.config.name,
+                version: this.config.version,
+                uptime: process.uptime(),
+            });
+        });
+    }
+}