@umpledger/sdk 2.0.0-alpha.1

package/examples/multi-agent-marketplace.ts

@@ -0,0 +1,140 @@
+/**
+ * UMP v2.0 — Multi-Agent Marketplace Example
+ *
+ * Demonstrates the AI Agent API Marketplace use case from the spec:
+ * A coding agent discovers a security-review agent, negotiates pricing,
+ * submits work, verifies outcomes, and settles payment — all autonomously.
+ *
+ * Run: npx tsx examples/multi-agent-marketplace.ts
+ */
+import { UMP, PricingTemplates } from '../src';
+
+async function main() {
+  const ump = new UMP({
+    apiKey: 'ump_sk_marketplace_demo',
+    onAudit: (r) => console.log(`  [AUDIT] ${r.what.operation}: $${r.what.amount ?? 0}`),
+  });
+
+  console.log('═══ Multi-Agent Marketplace Demo ═══\n');
+
+  // ── 1. Set up the enterprise org ──
+  const acmeOrg = ump.registerAgent({
+    name: 'Acme Corp',
+    type: 'ORGANIZATION',
+    authority: { maxPerTransaction: '$500', maxPerDay: '$5000', maxPerMonth: '$50000' },
+  });
+  acmeOrg.wallet.fund({ amount: '$10000' });
+  console.log(`✓ Org registered: ${acmeOrg.id} (balance: $${acmeOrg.wallet.balance()})`);
+
+  // ── 2. Org creates an AI coding agent ──
+  const codingAgent = ump.registerAgent({
+    name: 'acme-coding-agent',
+    type: 'AI_AGENT',
+    capabilities: ['code_generation', 'refactoring'],
+    authority: {
+      maxPerTransaction: '$100',
+      maxPerDay: '$1000',
+    },
+  });
+  codingAgent.wallet.fund({ amount: '$500' });
+
+  // ── 3. Security review service registers ──
+  const securityAgent = ump.registerAgent({
+    name: 'security-review-service',
+    type: 'SERVICE',
+    capabilities: ['security_review', 'vulnerability_scan'],
+    authority: {
+      maxPerTransaction: '$200',
+      maxPerDay: '$10000',
+    },
+  });
+  console.log(`✓ Security service: ${securityAgent.id}`);
+
+  // ── 4. Dynamic contract negotiation ──
+  console.log('\n── Contract Negotiation ──');
+
+  // Coding agent proposes
+  const proposal = ump.contracts.propose(codingAgent.id, {
+    targetAgentId: securityAgent.id,
+    pricingRules: [{
+      name: 'Per-file static analysis',
+      primitive: 'UNIT_RATE',
+      rate: 0.05,
+      unit: 'FILE',
+    } as any],
+  });
+  console.log(`  Proposal: $0.05/file (status: ${proposal.status})`);
+
+  // Security agent counters with tiered pricing
+  const counter = ump.contracts.counter(proposal.contractId, securityAgent.id, [{
+    name: 'Deep review tiered',
+    primitive: 'TIERED',
+    mode: 'GRADUATED',
+    tiers: [
+      { from: 0, to: 50, rate: 0.50 },
+      { from: 50, to: 200, rate: 0.35 },
+      { from: 200, to: null, rate: 0.20 },
+    ],
+  } as any]);
+  console.log(`  Counter: $0.50/file (first 50), $0.35 (50-200), $0.20 (200+) (status: ${counter.status})`);
+
+  // Coding agent accepts
+  const accepted = ump.contracts.accept(counter.contractId);
+  console.log(`  ✓ Contract accepted: ${accepted.contractId}\n`);
+
+  // ── 5. Create escrow for 94 files ──
+  console.log('── Escrow & Execution ──');
+  const fileCount = 94;
+  const estimatedCost = 50 * 0.50 + 44 * 0.35; // $25 + $15.40 = $40.40
+  console.log(`  Estimated cost for ${fileCount} files: $${estimatedCost.toFixed(2)}`);
+
+  const escrowId = ump.settlement.createEscrow(
+    codingAgent.id,
+    securityAgent.id,
+    estimatedCost,
+    'txn_security_review_1',
+  );
+  console.log(`  ✓ Escrow created: ${escrowId}`);
+  console.log(`  Buyer balance: $${codingAgent.wallet.balance()} (${estimatedCost} reserved)`);
+
+  // ── 6. Simulate execution — meter per-file events ──
+  for (let i = 0; i < fileCount; i++) {
+    ump.metering.record({
+      sourceAgentId: codingAgent.id,
+      targetAgentId: securityAgent.id,
+      contractId: accepted.contractId,
+      serviceId: 'deep_security_review',
+      quantity: 1,
+      unit: 'FILE',
+      dimensions: { filename: `src/file_${i}.ts`, severity_findings: Math.floor(Math.random() * 3) },
+    });
+  }
+  console.log(`  ✓ Metered ${fileCount} file review events`);
+
+  // ── 7. Release escrow upon verified outcome ──
+  const outcome = ump.metering.attestOutcome({
+    outcomeType: 'TASK_COMPLETION',
+    claimedBy: securityAgent.id,
+    evidence: [
+      { type: 'LOG', uri: 'ump://evidence/scan_report_001', hash: 'sha256:abc123', description: '94 files reviewed' },
+      { type: 'METRIC', uri: 'ump://evidence/findings_summary', hash: 'sha256:def456', description: '12 critical, 23 warnings' },
+    ],
+    verificationMethod: 'BILATERAL_AGREEMENT',
+    confidenceScore: 0.95,
+  });
+  console.log(`  ✓ Outcome attested: ${outcome.outcomeId} (confidence: ${outcome.confidenceScore})`);
+
+  const { settlement } = ump.settlement.releaseEscrow(escrowId, estimatedCost);
+  console.log(`  ✓ Settlement complete: $${settlement.totalAmount.toFixed(2)} released to security agent`);
+
+  // ── 8. Final state ──
+  console.log('\n── Final State ──');
+  console.log(`  Coding agent balance:  $${codingAgent.wallet.balance().toFixed(2)}`);
+  console.log(`  Security agent balance: $${securityAgent.wallet.balance().toFixed(2)}`);
+  console.log(`  Audit records: ${ump.audit.count()}`);
+  console.log(`  Usage events: ${ump.metering.getByAgent(codingAgent.id).length}`);
+
+  console.log('\n✓ Multi-agent marketplace demo complete!');
+}
+
+main().catch(console.error);

package/examples/quickstart.ts

@@ -0,0 +1,107 @@
+/**
+ * UMP v2.0 — Quick Start Example
+ *
+ * This example demonstrates the core flow:
+ * Register agents → Fund wallets → Create contracts → Transact
+ *
+ * Run: npx tsx examples/quickstart.ts
+ */
+import { UMP, PricingTemplates } from '../src';
+
+async function main() {
+  // ── 1. Initialize UMP ──
+  const ump = new UMP({
+    apiKey: 'ump_sk_demo_123',
+    onAudit: (record) => {
+      console.log(`[AUDIT] ${record.what.operation}: $${record.what.amount ?? 0}`);
+    },
+  });
+
+  // ── 2. Register your AI agent with spending limits ──
+  const codingAgent = ump.registerAgent({
+    name: 'my-coding-agent',
+    type: 'AI_AGENT',
+    capabilities: ['code_review', 'refactoring', 'testing'],
+    authority: {
+      maxPerTransaction: '$50',
+      maxPerDay: '$500',
+      maxPerMonth: '$5000',
+    },
+  });
+
+  console.log(`✓ Registered agent: ${codingAgent.id}`);
+
+  // ── 3. Register the service agent ──
+  const reviewService = ump.registerAgent({
+    name: 'code-review-service',
+    type: 'SERVICE',
+    capabilities: ['security_review', 'performance_review'],
+    authority: {
+      maxPerTransaction: '$100',
+      maxPerDay: '$10000',
+    },
+  });
+
+  console.log(`✓ Registered service: ${reviewService.id}`);
+
+  // ── 4. Fund the agent's wallet ──
+  codingAgent.wallet.fund({ amount: '$100' });
+  console.log(`✓ Funded wallet: $${codingAgent.wallet.balance()}`);
+
+  // ── 5. Create a contract with pricing rules ──
+  const contract = ump.contracts.create(codingAgent.id, {
+    targetAgentId: reviewService.id,
+    pricingRules: [
+      PricingTemplates.agentTask(0.50, 1.00), // $0.50/task + $1.00 bonus on success
+    ],
+  });
+
+  console.log(`✓ Contract created: ${contract.contractId}`);
+
+  // ── 6. Execute a transaction ──
+  const result = await ump.transact({
+    from: codingAgent.id,
+    to: reviewService.id,
+    service: 'code_review',
+    payload: {
+      repo: 'github.com/acme/app',
+      pr: 42,
+      files: ['src/auth.ts', 'src/payments.ts'],
+    },
+  });
+
+  console.log(`\n═══ Transaction Result ═══`);
+  console.log(`  Cost:    $${result.cost}`);
+  console.log(`  Audit:   ${result.auditId}`);
+  console.log(`  Speed:   ${result.duration}ms`);
+  console.log(`  Balance: $${codingAgent.wallet.balance()}`);
+
+  // ── 7. Check the ledger ──
+  const wallet = ump.wallets.getByAgent(codingAgent.id);
+  const ledger = ump.wallets.getLedger(wallet.walletId);
+  console.log(`\n═══ Spending Ledger (${ledger.length} entries) ═══`);
+  for (const entry of ledger) {
+    console.log(`  ${entry.type.padEnd(8)} $${entry.amount.toFixed(2).padStart(8)}  ${entry.description}`);
+  }
+
+  // ── 8. Simulate pricing scenarios ──
+  const perTokenRule = PricingTemplates.perToken(30, 60);
+  console.log(`\n═══ Pricing Simulation ═══`);
+  console.log(`  1M input tokens:  $${ump.pricing.simulate(perTokenRule, 1_000_000, { direction: 'input' })}`);
+  console.log(`  1M output tokens: $${ump.pricing.simulate(perTokenRule, 1_000_000, { direction: 'output' })}`);
+
+  const hybridRule = PricingTemplates.subscriptionPlusUsage(99, 1000, 0.05);
+  console.log(`  500 calls (sub):  $${ump.pricing.simulate(hybridRule, 500)}`);
+  console.log(`  2000 calls (sub): $${ump.pricing.simulate(hybridRule, 2000)}`);
+
+  // ── 9. Query audit trail ──
+  const audits = ump.audit.query({ agentId: codingAgent.id });
+  console.log(`\n═══ Audit Trail (${audits.length} records) ═══`);
+  for (const a of audits) {
+    console.log(`  [${a.when.toISOString()}] ${a.what.operation} - ${a.result.status}`);
+  }
+
+  console.log(`\n✓ Done! UMP v2.0 Quick Start complete.`);
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@umpledger/sdk",
+  "version": "2.0.0-alpha.1",
+  "description": "Universal Monetization Protocol SDK — The payment rail for the autonomous economy",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "module": "dist/index.mjs",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./pricing": {
+      "import": "./dist/pricing/index.mjs",
+      "require": "./dist/pricing/index.js",
+      "types": "./dist/pricing/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/ --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
+  },
+  "keywords": [
+    "monetization",
+    "ai-agents",
+    "billing",
+    "pricing",
+    "settlement",
+    "agent-commerce",
+    "protocol"
+  ],
+  "author": "UMPLedger",
+  "license": "Apache-2.0",
+  "homepage": "https://umpledger.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/umpledger/ump-protocol"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "uuid": "^9.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.37",
+    "@types/uuid": "^9.0.8",
+    "eslint": "^8.50.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^1.0.0"
+  }
+}

package/src/core/agent-manager.ts

@@ -0,0 +1,200 @@
+import type {
+  AgentIdentity, AgentStatus, AgentType, AuthorityScope,
+  CreateAgentOptions, VerificationProof,
+} from '../types';
+import { generateId, parseMoney, hrTimestamp } from '../utils/id';
+import { AgentNotFoundError, AgentRevokedError } from '../utils/errors';
+import crypto from 'crypto';
+
+/**
+ * AgentManager — Layer 1 primitive
+ *
+ * Manages Agent Identity lifecycle: creation, verification,
+ * authority scope enforcement, hierarchical revocation.
+ */
+export class AgentManager {
+  private agents: Map<string, AgentIdentity> = new Map();
+
+  /**
+   * Register a new Agent Identity with authority scope.
+   */
+  create(options: CreateAgentOptions): AgentIdentity {
+    const agentId = generateId('agt');
+    const now = hrTimestamp();
+
+    // Generate ephemeral keypair for this agent
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+    const pubKeyHex = publicKey.export({ type: 'spki', format: 'der' }).toString('hex');
+
+    // Normalize authority scope — parse "$50" strings into numbers
+    const authority: AuthorityScope = {
+      maxPerTransaction: parseMoney(options.authority.maxPerTransaction),
+      maxPerDay: parseMoney(options.authority.maxPerDay),
+      maxPerMonth: options.authority.maxPerMonth
+        ? parseMoney(options.authority.maxPerMonth)
+        : parseMoney(options.authority.maxPerDay) * 30,
+      allowedServices: options.authority.allowedServices,
+      allowedCounterparties: options.authority.allowedCounterparties,
+      requiresApprovalAbove: options.authority.requiresApprovalAbove,
+      autoRevokeAfter: options.authority.autoRevokeAfter,
+    };
+
+    // If parent exists, child authority cannot exceed parent's
+    if (options.parentId) {
+      const parent = this.get(options.parentId);
+      authority.maxPerTransaction = Math.min(authority.maxPerTransaction, parent.authorityScope.maxPerTransaction);
+      authority.maxPerDay = Math.min(authority.maxPerDay, parent.authorityScope.maxPerDay);
+      authority.maxPerMonth = Math.min(authority.maxPerMonth, parent.authorityScope.maxPerMonth);
+    }
+
+    const verification: VerificationProof = {
+      publicKey: pubKeyHex,
+      issuingAuthority: 'ump-sdk-local',
+      expiresAt: new Date(now.getTime() + (options.authority.autoRevokeAfter || 365 * 24 * 60 * 60 * 1000)),
+    };
+
+    const agent: AgentIdentity = {
+      agentId,
+      agentType: options.type,
+      parentId: options.parentId || null,
+      displayName: options.name,
+      capabilities: options.capabilities || [],
+      authorityScope: authority,
+      verification,
+      metadata: {
+        ...options.metadata,
+        _privateKey: privateKey.export({ type: 'pkcs8', format: 'der' }).toString('hex'),
+      },
+      status: 'ACTIVE',
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    this.agents.set(agentId, agent);
+
+    // Schedule auto-revoke if set
+    if (options.authority.autoRevokeAfter) {
+      setTimeout(() => this.revoke(agentId), options.authority.autoRevokeAfter);
+    }
+
+    return agent;
+  }
+
+  /**
+   * Retrieve an agent by ID.
+   */
+  get(agentId: string): AgentIdentity {
+    const agent = this.agents.get(agentId);
+    if (!agent) throw new AgentNotFoundError(agentId);
+    return agent;
+  }
+
+  /**
+   * Update authority scope (tightening is always allowed; loosening requires parent).
+   */
+  updateAuthority(agentId: string, newScope: Partial<AuthorityScope>): AgentIdentity {
+    const agent = this.get(agentId);
+    if (agent.status !== 'ACTIVE') throw new AgentRevokedError(agentId);
+
+    const updated: AgentIdentity = {
+      ...agent,
+      authorityScope: { ...agent.authorityScope, ...newScope },
+      updatedAt: hrTimestamp(),
+    };
+
+    this.agents.set(agentId, updated);
+    return updated;
+  }
+
+  /**
+   * Revoke an agent and cascade to all children.
+   */
+  revoke(agentId: string): string[] {
+    const revoked: string[] = [];
+    const agent = this.agents.get(agentId);
+    if (!agent) return revoked;
+
+    agent.status = 'REVOKED';
+    agent.updatedAt = hrTimestamp();
+    revoked.push(agentId);
+
+    // Cascade: revoke all children
+    for (const [id, a] of this.agents) {
+      if (a.parentId === agentId && a.status === 'ACTIVE') {
+        revoked.push(...this.revoke(id));
+      }
+    }
+
+    return revoked;
+  }
+
+  /**
+   * Verify that an agent's identity is valid and active.
+   */
+  verify(agentId: string): { valid: boolean; reason?: string } {
+    const agent = this.agents.get(agentId);
+    if (!agent) return { valid: false, reason: 'Agent not found' };
+    if (agent.status !== 'ACTIVE') return { valid: false, reason: `Agent status: ${agent.status}` };
+    if (agent.verification.expiresAt < new Date()) {
+      agent.status = 'EXPIRED';
+      return { valid: false, reason: 'Verification expired' };
+    }
+    return { valid: true };
+  }
+
+  /**
+   * Check if a transaction amount is within the agent's authority scope.
+   */
+  checkAuthority(
+    agentId: string,
+    amount: number,
+    counterpartyId?: string,
+    serviceId?: string
+  ): { allowed: boolean; reason?: string; requiresApproval?: boolean } {
+    const agent = this.get(agentId);
+    const scope = agent.authorityScope;
+
+    if (agent.status !== 'ACTIVE') {
+      return { allowed: false, reason: `Agent status: ${agent.status}` };
+    }
+
+    if (amount > scope.maxPerTransaction) {
+      return { allowed: false, reason: `Exceeds per-transaction limit of ${scope.maxPerTransaction}` };
+    }
+
+    if (scope.allowedCounterparties && counterpartyId) {
+      const allowed = scope.allowedCounterparties.some(pattern => {
+        if (pattern.endsWith('*')) {
+          return counterpartyId.startsWith(pattern.slice(0, -1));
+        }
+        return counterpartyId === pattern;
+      });
+      if (!allowed) {
+        return { allowed: false, reason: `Counterparty ${counterpartyId} not in allowlist` };
+      }
+    }
+
+    if (scope.allowedServices && serviceId) {
+      if (!scope.allowedServices.includes(serviceId)) {
+        return { allowed: false, reason: `Service ${serviceId} not in allowlist` };
+      }
+    }
+
+    if (scope.requiresApprovalAbove && amount > scope.requiresApprovalAbove) {
+      return { allowed: true, requiresApproval: true };
+    }
+
+    return { allowed: true };
+  }
+
+  /**
+   * List all agents, optionally filtered.
+   */
+  list(filter?: { parentId?: string; type?: AgentType; status?: AgentStatus }): AgentIdentity[] {
+    let results = Array.from(this.agents.values());
+    if (filter?.parentId) results = results.filter(a => a.parentId === filter.parentId);
+    if (filter?.type) results = results.filter(a => a.agentType === filter.type);
+    if (filter?.status) results = results.filter(a => a.status === filter.status);
+    return results;
+  }
+}

package/src/core/audit-trail.ts

@@ -0,0 +1,91 @@
+import type { AuditRecord } from '../types';
+import { generateId, hrTimestamp } from '../utils/id';
+
+/**
+ * AuditTrail — Layer 3 primitive
+ *
+ * Immutable append-only log of every UMP operation.
+ * Captures 6 dimensions: WHAT, WHO, WHEN, WHY, HOW, RESULT.
+ */
+export class AuditTrail {
+  private records: AuditRecord[] = [];
+  private onAudit?: (record: AuditRecord) => void;
+
+  constructor(onAudit?: (record: AuditRecord) => void) {
+    this.onAudit = onAudit;
+  }
+
+  /**
+   * Record an audit entry. Returns the audit ID.
+   */
+  record(data: Omit<AuditRecord, 'auditId' | 'when'>): string {
+    const auditId = generateId('aud');
+    const record: AuditRecord = {
+      auditId,
+      when: hrTimestamp(),
+      ...data,
+    };
+    this.records.push(record);
+
+    // Fire callback if registered (for real-time dashboards, etc.)
+    if (this.onAudit) {
+      this.onAudit(record);
+    }
+
+    return auditId;
+  }
+
+  /**
+   * Query audit records with filters.
+   */
+  query(filters?: {
+    agentId?: string;
+    operation?: string;
+    fromDate?: Date;
+    toDate?: Date;
+    minAmount?: number;
+    contractId?: string;
+  }, limit = 100, offset = 0): AuditRecord[] {
+    let results = this.records;
+
+    if (filters) {
+      if (filters.agentId) {
+        results = results.filter(r =>
+          r.who.sourceAgentId === filters.agentId ||
+          r.who.targetAgentId === filters.agentId
+        );
+      }
+      if (filters.operation) {
+        results = results.filter(r => r.what.operation === filters.operation);
+      }
+      if (filters.fromDate) {
+        results = results.filter(r => r.when >= filters.fromDate!);
+      }
+      if (filters.toDate) {
+        results = results.filter(r => r.when <= filters.toDate!);
+      }
+      if (filters.minAmount !== undefined) {
+        results = results.filter(r => (r.what.amount || 0) >= filters.minAmount!);
+      }
+      if (filters.contractId) {
+        results = results.filter(r => r.why.contractId === filters.contractId);
+      }
+    }
+
+    return results.slice(offset, offset + limit);
+  }
+
+  /**
+   * Get a specific audit record by ID.
+   */
+  get(auditId: string): AuditRecord | undefined {
+    return this.records.find(r => r.auditId === auditId);
+  }
+
+  /**
+   * Get total count of records.
+   */
+  count(): number {
+    return this.records.length;
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,3 @@
+export { AgentManager } from './agent-manager';
+export { WalletManager } from './wallet-manager';
+export { AuditTrail } from './audit-trail';