@paypol-protocol/aps-1 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +337 -0
- package/dist/aps1-agent.d.ts +88 -0
- package/dist/aps1-agent.js +218 -0
- package/dist/aps1-client.d.ts +64 -0
- package/dist/aps1-client.js +188 -0
- package/dist/index.d.ts +59 -0
- package/dist/index.js +58 -0
- package/dist/types.d.ts +246 -0
- package/dist/types.js +31 -0
- package/dist/validator.d.ts +534 -0
- package/dist/validator.js +164 -0
- package/package.json +40 -0
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* APS-1 Reference Client
|
|
3
|
+
*
|
|
4
|
+
* A client that follows the full APS-1 protocol flow:
|
|
5
|
+
* 1. Discover agent via manifest
|
|
6
|
+
* 2. Optionally negotiate price
|
|
7
|
+
* 3. Lock funds in escrow (NexusV2 or StreamV1)
|
|
8
|
+
* 4. Send execution envelope to agent
|
|
9
|
+
* 5. Receive and validate result
|
|
10
|
+
* 6. Settle escrow
|
|
11
|
+
*
|
|
12
|
+
* Usage:
|
|
13
|
+
* const client = new APS1Client({ agentServiceUrl: 'http://localhost:3001' });
|
|
14
|
+
* const manifest = await client.discover('token-transfer');
|
|
15
|
+
* const result = await client.execute('token-transfer', 'Send 100 AlphaUSD to 0x...', '0xMyWallet');
|
|
16
|
+
*/
|
|
17
|
+
import type { APS1Manifest, APS1Result, APS1EscrowParams, APS1NegotiationMessage } from './types';
|
|
18
|
+
export interface APS1ClientConfig {
|
|
19
|
+
/** Base URL of the agent service (e.g. http://localhost:3001) */
|
|
20
|
+
agentServiceUrl: string;
|
|
21
|
+
/** Optional marketplace URL for discovery */
|
|
22
|
+
marketplaceUrl?: string;
|
|
23
|
+
/** Request timeout in ms (default: 120000) */
|
|
24
|
+
timeoutMs?: number;
|
|
25
|
+
}
|
|
26
|
+
export declare class APS1Client {
|
|
27
|
+
private config;
|
|
28
|
+
constructor(config: APS1ClientConfig);
|
|
29
|
+
/**
|
|
30
|
+
* Discover an agent's capabilities via its APS-1 manifest.
|
|
31
|
+
*/
|
|
32
|
+
discover(agentId: string): Promise<APS1Manifest>;
|
|
33
|
+
/**
|
|
34
|
+
* List all available agents from the marketplace.
|
|
35
|
+
*/
|
|
36
|
+
listAgents(): Promise<APS1Manifest[]>;
|
|
37
|
+
/**
|
|
38
|
+
* Search agents by category or capability.
|
|
39
|
+
*/
|
|
40
|
+
searchAgents(query: {
|
|
41
|
+
category?: string;
|
|
42
|
+
maxPrice?: number;
|
|
43
|
+
capability?: string;
|
|
44
|
+
}): Promise<APS1Manifest[]>;
|
|
45
|
+
/**
|
|
46
|
+
* Propose a price for a job (optional - only if agent supports negotiation).
|
|
47
|
+
*/
|
|
48
|
+
negotiate(agentId: string, message: APS1NegotiationMessage): Promise<APS1NegotiationMessage>;
|
|
49
|
+
/**
|
|
50
|
+
* Execute a job on an agent following APS-1 protocol.
|
|
51
|
+
* This is the main entry point for hiring an agent.
|
|
52
|
+
*/
|
|
53
|
+
execute(agentId: string, prompt: string, callerWallet: string, options?: {
|
|
54
|
+
payload?: Record<string, unknown>;
|
|
55
|
+
jobId?: string;
|
|
56
|
+
}): Promise<APS1Result>;
|
|
57
|
+
/**
|
|
58
|
+
* Execute with full escrow flow (for integration with on-chain escrow).
|
|
59
|
+
*/
|
|
60
|
+
executeWithEscrow(agentId: string, prompt: string, callerWallet: string, escrowParams: APS1EscrowParams): Promise<APS1Result>;
|
|
61
|
+
private fetch;
|
|
62
|
+
private toAPS1Manifest;
|
|
63
|
+
private toAPS1Result;
|
|
64
|
+
}
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* APS-1 Reference Client
|
|
3
|
+
*
|
|
4
|
+
* A client that follows the full APS-1 protocol flow:
|
|
5
|
+
* 1. Discover agent via manifest
|
|
6
|
+
* 2. Optionally negotiate price
|
|
7
|
+
* 3. Lock funds in escrow (NexusV2 or StreamV1)
|
|
8
|
+
* 4. Send execution envelope to agent
|
|
9
|
+
* 5. Receive and validate result
|
|
10
|
+
* 6. Settle escrow
|
|
11
|
+
*
|
|
12
|
+
* Usage:
|
|
13
|
+
* const client = new APS1Client({ agentServiceUrl: 'http://localhost:3001' });
|
|
14
|
+
* const manifest = await client.discover('token-transfer');
|
|
15
|
+
* const result = await client.execute('token-transfer', 'Send 100 AlphaUSD to 0x...', '0xMyWallet');
|
|
16
|
+
*/
|
|
17
|
+
import { APS1_VERSION } from './types';
|
|
18
|
+
export class APS1Client {
|
|
19
|
+
config;
|
|
20
|
+
constructor(config) {
|
|
21
|
+
this.config = {
|
|
22
|
+
agentServiceUrl: config.agentServiceUrl.replace(/\/$/, ''),
|
|
23
|
+
marketplaceUrl: config.marketplaceUrl ?? config.agentServiceUrl.replace(/\/$/, ''),
|
|
24
|
+
timeoutMs: config.timeoutMs ?? 120000,
|
|
25
|
+
};
|
|
26
|
+
}
|
|
27
|
+
// ── Phase 1: Discovery ─────────────────────────────────
|
|
28
|
+
/**
|
|
29
|
+
* Discover an agent's capabilities via its APS-1 manifest.
|
|
30
|
+
*/
|
|
31
|
+
async discover(agentId) {
|
|
32
|
+
const res = await this.fetch(`${this.config.agentServiceUrl}/agents/${agentId}`);
|
|
33
|
+
const data = await res.json();
|
|
34
|
+
// Wrap existing manifests in APS-1 format
|
|
35
|
+
return this.toAPS1Manifest(data, agentId);
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* List all available agents from the marketplace.
|
|
39
|
+
*/
|
|
40
|
+
async listAgents() {
|
|
41
|
+
const res = await this.fetch(`${this.config.agentServiceUrl}/agents`);
|
|
42
|
+
const agents = await res.json();
|
|
43
|
+
return (Array.isArray(agents) ? agents : []).map((a) => this.toAPS1Manifest(a, a.id));
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* Search agents by category or capability.
|
|
47
|
+
*/
|
|
48
|
+
async searchAgents(query) {
|
|
49
|
+
const all = await this.listAgents();
|
|
50
|
+
return all.filter(a => {
|
|
51
|
+
if (query.category && a.category !== query.category)
|
|
52
|
+
return false;
|
|
53
|
+
if (query.maxPrice && a.pricing.basePrice > query.maxPrice)
|
|
54
|
+
return false;
|
|
55
|
+
if (query.capability && !a.capabilities.includes(query.capability))
|
|
56
|
+
return false;
|
|
57
|
+
return true;
|
|
58
|
+
});
|
|
59
|
+
}
|
|
60
|
+
// ── Phase 2: Negotiation ───────────────────────────────
|
|
61
|
+
/**
|
|
62
|
+
* Propose a price for a job (optional - only if agent supports negotiation).
|
|
63
|
+
*/
|
|
64
|
+
async negotiate(agentId, message) {
|
|
65
|
+
const manifest = await this.discover(agentId);
|
|
66
|
+
if (!manifest.endpoints.negotiate) {
|
|
67
|
+
throw new Error(`Agent ${agentId} does not support negotiation`);
|
|
68
|
+
}
|
|
69
|
+
const res = await this.fetch(manifest.endpoints.negotiate, {
|
|
70
|
+
method: 'POST',
|
|
71
|
+
body: JSON.stringify(message),
|
|
72
|
+
});
|
|
73
|
+
return res.json();
|
|
74
|
+
}
|
|
75
|
+
// ── Phase 4: Execution ─────────────────────────────────
|
|
76
|
+
/**
|
|
77
|
+
* Execute a job on an agent following APS-1 protocol.
|
|
78
|
+
* This is the main entry point for hiring an agent.
|
|
79
|
+
*/
|
|
80
|
+
async execute(agentId, prompt, callerWallet, options) {
|
|
81
|
+
const jobId = options?.jobId ?? `aps1-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
|
|
82
|
+
const envelope = {
|
|
83
|
+
jobId,
|
|
84
|
+
agentId,
|
|
85
|
+
prompt,
|
|
86
|
+
payload: options?.payload,
|
|
87
|
+
callerWallet,
|
|
88
|
+
timestamp: new Date().toISOString(),
|
|
89
|
+
};
|
|
90
|
+
const res = await this.fetch(`${this.config.agentServiceUrl}/agents/${agentId}/execute`, {
|
|
91
|
+
method: 'POST',
|
|
92
|
+
body: JSON.stringify({
|
|
93
|
+
jobId: envelope.jobId,
|
|
94
|
+
prompt: envelope.prompt,
|
|
95
|
+
payload: envelope.payload,
|
|
96
|
+
callerWallet: envelope.callerWallet,
|
|
97
|
+
}),
|
|
98
|
+
});
|
|
99
|
+
const result = await res.json();
|
|
100
|
+
// Normalize to APS-1 result format
|
|
101
|
+
return this.toAPS1Result(result, jobId, agentId);
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* Execute with full escrow flow (for integration with on-chain escrow).
|
|
105
|
+
*/
|
|
106
|
+
async executeWithEscrow(agentId, prompt, callerWallet, escrowParams) {
|
|
107
|
+
// In production, this would:
|
|
108
|
+
// 1. Create escrow on-chain (NexusV2.createJob or StreamV1.createStream)
|
|
109
|
+
// 2. Wait for confirmation
|
|
110
|
+
// 3. Include escrow info in envelope
|
|
111
|
+
// 4. Execute agent
|
|
112
|
+
// 5. Settle escrow based on result
|
|
113
|
+
// For now, execute directly (escrow handled by marketplace backend)
|
|
114
|
+
return this.execute(agentId, prompt, callerWallet);
|
|
115
|
+
}
|
|
116
|
+
// ── Helpers ────────────────────────────────────────────
|
|
117
|
+
async fetch(url, init) {
|
|
118
|
+
const controller = new AbortController();
|
|
119
|
+
const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
|
|
120
|
+
try {
|
|
121
|
+
const res = await globalThis.fetch(url, {
|
|
122
|
+
...init,
|
|
123
|
+
headers: {
|
|
124
|
+
'Content-Type': 'application/json',
|
|
125
|
+
'X-APS-Version': APS1_VERSION,
|
|
126
|
+
...init?.headers,
|
|
127
|
+
},
|
|
128
|
+
signal: controller.signal,
|
|
129
|
+
});
|
|
130
|
+
if (!res.ok) {
|
|
131
|
+
throw new Error(`APS-1 request failed: ${res.status} ${res.statusText}`);
|
|
132
|
+
}
|
|
133
|
+
return res;
|
|
134
|
+
}
|
|
135
|
+
finally {
|
|
136
|
+
clearTimeout(timeout);
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
toAPS1Manifest(data, agentId) {
|
|
140
|
+
return {
|
|
141
|
+
aps: '1.0',
|
|
142
|
+
id: data.id ?? agentId,
|
|
143
|
+
name: data.name ?? agentId,
|
|
144
|
+
description: data.description ?? '',
|
|
145
|
+
category: data.category ?? 'analytics',
|
|
146
|
+
version: data.version ?? '1.0.0',
|
|
147
|
+
pricing: {
|
|
148
|
+
basePrice: data.price ?? data.pricing?.basePrice ?? 0,
|
|
149
|
+
currency: 'USD',
|
|
150
|
+
negotiable: data.pricing?.negotiable ?? false,
|
|
151
|
+
},
|
|
152
|
+
capabilities: data.capabilities ?? data.skills ?? [],
|
|
153
|
+
paymentMethods: ['nexus-escrow', 'stream-milestone', 'direct-transfer'],
|
|
154
|
+
supportedTokens: [
|
|
155
|
+
{ symbol: 'AlphaUSD', address: '0x20c0000000000000000000000000000000000001', decimals: 6 },
|
|
156
|
+
],
|
|
157
|
+
proofEnabled: data.proofEnabled ?? true,
|
|
158
|
+
walletAddress: data.walletAddress ?? '0x33F7E5da060A7FEE31AB4C7a5B27F4cC3B020793',
|
|
159
|
+
endpoints: {
|
|
160
|
+
manifest: `${this.config.agentServiceUrl}/agents/${agentId}`,
|
|
161
|
+
execute: `${this.config.agentServiceUrl}/agents/${agentId}/execute`,
|
|
162
|
+
},
|
|
163
|
+
};
|
|
164
|
+
}
|
|
165
|
+
toAPS1Result(data, jobId, agentId) {
|
|
166
|
+
return {
|
|
167
|
+
jobId: data.jobId ?? jobId,
|
|
168
|
+
agentId: data.agentId ?? agentId,
|
|
169
|
+
status: data.status ?? 'error',
|
|
170
|
+
result: data.result,
|
|
171
|
+
error: data.error,
|
|
172
|
+
onChain: data.onChain ?? data.transaction ? {
|
|
173
|
+
executed: true,
|
|
174
|
+
transactions: data.transaction ? [{
|
|
175
|
+
hash: data.transaction.hash,
|
|
176
|
+
blockNumber: data.transaction.blockNumber ?? 0,
|
|
177
|
+
gasUsed: data.transaction.gasUsed ?? '0',
|
|
178
|
+
explorerUrl: data.transaction.explorerUrl ?? '',
|
|
179
|
+
}] : [],
|
|
180
|
+
network: data.network ?? 'Tempo L1 Moderato',
|
|
181
|
+
chainId: data.chainId ?? 42431,
|
|
182
|
+
} : undefined,
|
|
183
|
+
proof: data.proof,
|
|
184
|
+
executionTimeMs: data.executionTimeMs ?? 0,
|
|
185
|
+
timestamp: new Date().toISOString(),
|
|
186
|
+
};
|
|
187
|
+
}
|
|
188
|
+
}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @paypol-protocol/aps-1 - Agent Payment Standard v1.0
|
|
3
|
+
*
|
|
4
|
+
* The open protocol standard for AI agent payments on Tempo L1.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```typescript
|
|
8
|
+
* // Build an APS-1 compliant agent
|
|
9
|
+
* import { APS1Agent } from '@paypol-protocol/aps-1';
|
|
10
|
+
*
|
|
11
|
+
* const agent = new APS1Agent({
|
|
12
|
+
* id: 'my-agent',
|
|
13
|
+
* name: 'My Agent',
|
|
14
|
+
* description: 'Does amazing things',
|
|
15
|
+
* category: 'analytics',
|
|
16
|
+
* version: '1.0.0',
|
|
17
|
+
* pricing: { basePrice: 5, currency: 'USD', negotiable: false },
|
|
18
|
+
* capabilities: ['analyze'],
|
|
19
|
+
* walletAddress: '0x...',
|
|
20
|
+
* });
|
|
21
|
+
*
|
|
22
|
+
* agent.onExecute(async (envelope) => {
|
|
23
|
+
* return { status: 'success', result: { answer: 42 } };
|
|
24
|
+
* });
|
|
25
|
+
*
|
|
26
|
+
* agent.listen(3002);
|
|
27
|
+
* ```
|
|
28
|
+
*
|
|
29
|
+
* @example
|
|
30
|
+
* ```typescript
|
|
31
|
+
* // Hire an APS-1 agent
|
|
32
|
+
* import { APS1Client } from '@paypol-protocol/aps-1';
|
|
33
|
+
*
|
|
34
|
+
* const client = new APS1Client({ agentServiceUrl: 'https://paypol.xyz' });
|
|
35
|
+
* const agents = await client.listAgents();
|
|
36
|
+
* const result = await client.execute('my-agent', 'Analyze this data', '0xMyWallet');
|
|
37
|
+
* ```
|
|
38
|
+
*
|
|
39
|
+
* @example
|
|
40
|
+
* ```typescript
|
|
41
|
+
* // Validate APS-1 data
|
|
42
|
+
* import { validateManifest, validateResult } from '@paypol-protocol/aps-1';
|
|
43
|
+
*
|
|
44
|
+
* const valid = validateManifest(someData);
|
|
45
|
+
* if (valid.success) {
|
|
46
|
+
* console.log('Valid manifest:', valid.data);
|
|
47
|
+
* } else {
|
|
48
|
+
* console.error('Invalid:', valid.errors);
|
|
49
|
+
* }
|
|
50
|
+
* ```
|
|
51
|
+
*/
|
|
52
|
+
export type { APS1Manifest, APS1Category, APS1Pricing, APS1PaymentMethod, APS1TokenConfig, APS1Endpoints, APS1NegotiationMessage, APS1EscrowParams, APS1Milestone, APS1ExecutionEnvelope, APS1Result, APS1Transaction, APS1Settlement, } from './types';
|
|
53
|
+
export { APS1_VERSION, APS1_CHAIN_ID, APS1_NETWORK, APS1_PLATFORM_FEE_BPS, APS1_DEFAULT_TOKENS, APS1_CONTRACTS, } from './types';
|
|
54
|
+
export { validateManifest, validateEnvelope, validateResult, validateEscrowParams, validateNegotiation, validateSettlement, } from './validator';
|
|
55
|
+
export type { ValidationResult } from './validator';
|
|
56
|
+
export { APS1Agent } from './aps1-agent';
|
|
57
|
+
export type { APS1AgentConfig, APS1ExecuteHandler, APS1NegotiateHandler } from './aps1-agent';
|
|
58
|
+
export { APS1Client } from './aps1-client';
|
|
59
|
+
export type { APS1ClientConfig } from './aps1-client';
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @paypol-protocol/aps-1 - Agent Payment Standard v1.0
|
|
3
|
+
*
|
|
4
|
+
* The open protocol standard for AI agent payments on Tempo L1.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```typescript
|
|
8
|
+
* // Build an APS-1 compliant agent
|
|
9
|
+
* import { APS1Agent } from '@paypol-protocol/aps-1';
|
|
10
|
+
*
|
|
11
|
+
* const agent = new APS1Agent({
|
|
12
|
+
* id: 'my-agent',
|
|
13
|
+
* name: 'My Agent',
|
|
14
|
+
* description: 'Does amazing things',
|
|
15
|
+
* category: 'analytics',
|
|
16
|
+
* version: '1.0.0',
|
|
17
|
+
* pricing: { basePrice: 5, currency: 'USD', negotiable: false },
|
|
18
|
+
* capabilities: ['analyze'],
|
|
19
|
+
* walletAddress: '0x...',
|
|
20
|
+
* });
|
|
21
|
+
*
|
|
22
|
+
* agent.onExecute(async (envelope) => {
|
|
23
|
+
* return { status: 'success', result: { answer: 42 } };
|
|
24
|
+
* });
|
|
25
|
+
*
|
|
26
|
+
* agent.listen(3002);
|
|
27
|
+
* ```
|
|
28
|
+
*
|
|
29
|
+
* @example
|
|
30
|
+
* ```typescript
|
|
31
|
+
* // Hire an APS-1 agent
|
|
32
|
+
* import { APS1Client } from '@paypol-protocol/aps-1';
|
|
33
|
+
*
|
|
34
|
+
* const client = new APS1Client({ agentServiceUrl: 'https://paypol.xyz' });
|
|
35
|
+
* const agents = await client.listAgents();
|
|
36
|
+
* const result = await client.execute('my-agent', 'Analyze this data', '0xMyWallet');
|
|
37
|
+
* ```
|
|
38
|
+
*
|
|
39
|
+
* @example
|
|
40
|
+
* ```typescript
|
|
41
|
+
* // Validate APS-1 data
|
|
42
|
+
* import { validateManifest, validateResult } from '@paypol-protocol/aps-1';
|
|
43
|
+
*
|
|
44
|
+
* const valid = validateManifest(someData);
|
|
45
|
+
* if (valid.success) {
|
|
46
|
+
* console.log('Valid manifest:', valid.data);
|
|
47
|
+
* } else {
|
|
48
|
+
* console.error('Invalid:', valid.errors);
|
|
49
|
+
* }
|
|
50
|
+
* ```
|
|
51
|
+
*/
|
|
52
|
+
// ── Constants ─────────────────────────────────────────────
|
|
53
|
+
export { APS1_VERSION, APS1_CHAIN_ID, APS1_NETWORK, APS1_PLATFORM_FEE_BPS, APS1_DEFAULT_TOKENS, APS1_CONTRACTS, } from './types';
|
|
54
|
+
// ── Validation ────────────────────────────────────────────
|
|
55
|
+
export { validateManifest, validateEnvelope, validateResult, validateEscrowParams, validateNegotiation, validateSettlement, } from './validator';
|
|
56
|
+
// ── Reference Implementations ─────────────────────────────
|
|
57
|
+
export { APS1Agent } from './aps1-agent';
|
|
58
|
+
export { APS1Client } from './aps1-client';
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* APS-1: Agent Payment Standard v1.0
|
|
3
|
+
*
|
|
4
|
+
* Core type definitions for the PayPol Agent Payment Standard.
|
|
5
|
+
* These interfaces define the protocol for how AI agents discover,
|
|
6
|
+
* negotiate, escrow, execute, verify, and settle payments.
|
|
7
|
+
*
|
|
8
|
+
* Framework-agnostic - works with OpenAI, Anthropic, LangChain,
|
|
9
|
+
* CrewAI, MCP, Eliza, or any HTTP-based agent.
|
|
10
|
+
*/
|
|
11
|
+
/**
|
|
12
|
+
* APS-1 Agent Manifest - the identity card of every APS-1 compliant agent.
|
|
13
|
+
* Served at GET /manifest endpoint.
|
|
14
|
+
*/
|
|
15
|
+
export interface APS1Manifest {
|
|
16
|
+
/** Protocol version identifier */
|
|
17
|
+
aps: '1.0';
|
|
18
|
+
/** Unique agent identifier (kebab-case, e.g. "contract-auditor") */
|
|
19
|
+
id: string;
|
|
20
|
+
/** Human-readable agent name */
|
|
21
|
+
name: string;
|
|
22
|
+
/** What the agent does (1-3 sentences) */
|
|
23
|
+
description: string;
|
|
24
|
+
/** Agent category */
|
|
25
|
+
category: APS1Category;
|
|
26
|
+
/** Semantic version (semver) */
|
|
27
|
+
version: string;
|
|
28
|
+
/** Pricing configuration */
|
|
29
|
+
pricing: APS1Pricing;
|
|
30
|
+
/** List of capabilities/skills */
|
|
31
|
+
capabilities: string[];
|
|
32
|
+
/** Supported payment methods */
|
|
33
|
+
paymentMethods: APS1PaymentMethod[];
|
|
34
|
+
/** ERC20 token addresses the agent accepts */
|
|
35
|
+
supportedTokens: APS1TokenConfig[];
|
|
36
|
+
/** Whether the agent uses AIProofRegistry for verifiable execution */
|
|
37
|
+
proofEnabled: boolean;
|
|
38
|
+
/** Agent's reputation score (0-10000, from ReputationRegistry) */
|
|
39
|
+
reputationScore?: number;
|
|
40
|
+
/** Agent's wallet address on Tempo L1 */
|
|
41
|
+
walletAddress: string;
|
|
42
|
+
/** HTTP endpoints */
|
|
43
|
+
endpoints: APS1Endpoints;
|
|
44
|
+
/** Optional metadata */
|
|
45
|
+
metadata?: Record<string, unknown>;
|
|
46
|
+
}
|
|
47
|
+
export type APS1Category = 'security' | 'escrow' | 'payments' | 'streams' | 'analytics' | 'deployment' | 'privacy' | 'verification' | 'orchestration' | 'payroll' | 'admin';
|
|
48
|
+
export interface APS1Pricing {
|
|
49
|
+
/** Base price in USD */
|
|
50
|
+
basePrice: number;
|
|
51
|
+
/** Currency (always USD in v1) */
|
|
52
|
+
currency: 'USD';
|
|
53
|
+
/** Whether the agent accepts price negotiation */
|
|
54
|
+
negotiable: boolean;
|
|
55
|
+
/** Minimum acceptable price (if negotiable) */
|
|
56
|
+
minPrice?: number;
|
|
57
|
+
/** Maximum price (if negotiable) */
|
|
58
|
+
maxPrice?: number;
|
|
59
|
+
}
|
|
60
|
+
export type APS1PaymentMethod = 'nexus-escrow' | 'stream-milestone' | 'direct-transfer';
|
|
61
|
+
export interface APS1TokenConfig {
|
|
62
|
+
/** Token symbol (e.g. "AlphaUSD") */
|
|
63
|
+
symbol: string;
|
|
64
|
+
/** ERC20 contract address on Tempo L1 */
|
|
65
|
+
address: string;
|
|
66
|
+
/** Token decimals */
|
|
67
|
+
decimals: number;
|
|
68
|
+
}
|
|
69
|
+
export interface APS1Endpoints {
|
|
70
|
+
/** GET /manifest - returns APS1Manifest */
|
|
71
|
+
manifest: string;
|
|
72
|
+
/** POST /execute - executes a job */
|
|
73
|
+
execute: string;
|
|
74
|
+
/** POST /negotiate - optional price negotiation */
|
|
75
|
+
negotiate?: string;
|
|
76
|
+
/** GET /status/:jobId - check job status */
|
|
77
|
+
status?: string;
|
|
78
|
+
/** GET /health - health check */
|
|
79
|
+
health?: string;
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* APS-1 Negotiation Message - for optional price negotiation between
|
|
83
|
+
* client and agent before escrow lockup.
|
|
84
|
+
*/
|
|
85
|
+
export interface APS1NegotiationMessage {
|
|
86
|
+
/** Message type in the negotiation flow */
|
|
87
|
+
type: 'propose' | 'counter' | 'accept' | 'reject';
|
|
88
|
+
/** Job ID this negotiation is for */
|
|
89
|
+
jobId: string;
|
|
90
|
+
/** Proposed/countered price in USD */
|
|
91
|
+
price: number;
|
|
92
|
+
/** Currency */
|
|
93
|
+
currency: 'USD';
|
|
94
|
+
/** Optional human-readable message */
|
|
95
|
+
message?: string;
|
|
96
|
+
/** ISO timestamp */
|
|
97
|
+
timestamp: string;
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* APS-1 Escrow Parameters - defines how funds are locked before execution.
|
|
101
|
+
*/
|
|
102
|
+
export interface APS1EscrowParams {
|
|
103
|
+
/** Which payment method to use */
|
|
104
|
+
method: APS1PaymentMethod;
|
|
105
|
+
/** ERC20 token address */
|
|
106
|
+
token: string;
|
|
107
|
+
/** Amount to lock (in token's smallest unit) */
|
|
108
|
+
amount: string;
|
|
109
|
+
/** Amount in USD (for display) */
|
|
110
|
+
amountUSD: number;
|
|
111
|
+
/** Deadline in seconds from now */
|
|
112
|
+
deadlineSeconds: number;
|
|
113
|
+
/** Worker (agent) wallet address */
|
|
114
|
+
workerWallet: string;
|
|
115
|
+
/** Judge wallet address (for NexusV2 disputes) */
|
|
116
|
+
judgeWallet?: string;
|
|
117
|
+
/** Milestones (for stream-milestone method) */
|
|
118
|
+
milestones?: APS1Milestone[];
|
|
119
|
+
}
|
|
120
|
+
export interface APS1Milestone {
|
|
121
|
+
/** Amount for this milestone (in token's smallest unit) */
|
|
122
|
+
amount: string;
|
|
123
|
+
/** Description of the deliverable */
|
|
124
|
+
deliverable: string;
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* APS-1 Execution Envelope - the standardized job request sent to an agent.
|
|
128
|
+
* This is what gets POSTed to the agent's /execute endpoint.
|
|
129
|
+
*/
|
|
130
|
+
export interface APS1ExecutionEnvelope {
|
|
131
|
+
/** Unique job identifier */
|
|
132
|
+
jobId: string;
|
|
133
|
+
/** Agent identifier */
|
|
134
|
+
agentId: string;
|
|
135
|
+
/** Natural language prompt describing the task */
|
|
136
|
+
prompt: string;
|
|
137
|
+
/** Optional structured payload */
|
|
138
|
+
payload?: Record<string, unknown>;
|
|
139
|
+
/** Client's wallet address */
|
|
140
|
+
callerWallet: string;
|
|
141
|
+
/** Escrow information (if funds are locked) */
|
|
142
|
+
escrow?: {
|
|
143
|
+
/** Smart contract address holding the funds */
|
|
144
|
+
contractAddress: string;
|
|
145
|
+
/** On-chain job/stream ID */
|
|
146
|
+
onChainId: number;
|
|
147
|
+
/** Transaction hash of the escrow creation */
|
|
148
|
+
txHash: string;
|
|
149
|
+
/** Payment method used */
|
|
150
|
+
method: APS1PaymentMethod;
|
|
151
|
+
};
|
|
152
|
+
/** AI Proof commitment (if proofEnabled) */
|
|
153
|
+
proof?: {
|
|
154
|
+
/** keccak256 hash of the agent's planned approach */
|
|
155
|
+
planHash: string;
|
|
156
|
+
/** Commitment ID from AIProofRegistry */
|
|
157
|
+
commitmentId: string;
|
|
158
|
+
/** Transaction hash of the commit() call */
|
|
159
|
+
commitTxHash: string;
|
|
160
|
+
};
|
|
161
|
+
/** ISO timestamp */
|
|
162
|
+
timestamp: string;
|
|
163
|
+
}
|
|
164
|
+
/**
|
|
165
|
+
* APS-1 Execution Result - the standardized response from an agent.
|
|
166
|
+
*/
|
|
167
|
+
export interface APS1Result {
|
|
168
|
+
/** Job identifier (matches envelope.jobId) */
|
|
169
|
+
jobId: string;
|
|
170
|
+
/** Agent identifier */
|
|
171
|
+
agentId: string;
|
|
172
|
+
/** Execution status */
|
|
173
|
+
status: 'success' | 'error' | 'pending';
|
|
174
|
+
/** Result data (agent-specific) */
|
|
175
|
+
result?: unknown;
|
|
176
|
+
/** Error message (if status === 'error') */
|
|
177
|
+
error?: string;
|
|
178
|
+
/** On-chain execution details */
|
|
179
|
+
onChain?: {
|
|
180
|
+
/** Whether real on-chain transactions were executed */
|
|
181
|
+
executed: boolean;
|
|
182
|
+
/** Transaction hashes */
|
|
183
|
+
transactions: APS1Transaction[];
|
|
184
|
+
/** Network identifier */
|
|
185
|
+
network: string;
|
|
186
|
+
/** Chain ID */
|
|
187
|
+
chainId: number;
|
|
188
|
+
};
|
|
189
|
+
/** AI Proof verification (if proofEnabled) */
|
|
190
|
+
proof?: {
|
|
191
|
+
/** keccak256 hash of the actual execution result */
|
|
192
|
+
resultHash: string;
|
|
193
|
+
/** Transaction hash of the verify() call */
|
|
194
|
+
verifyTxHash: string;
|
|
195
|
+
/** Whether plan hash matched result hash */
|
|
196
|
+
matched: boolean;
|
|
197
|
+
};
|
|
198
|
+
/** Execution time in milliseconds */
|
|
199
|
+
executionTimeMs: number;
|
|
200
|
+
/** ISO timestamp */
|
|
201
|
+
timestamp: string;
|
|
202
|
+
}
|
|
203
|
+
export interface APS1Transaction {
|
|
204
|
+
/** Transaction hash */
|
|
205
|
+
hash: string;
|
|
206
|
+
/** Block number */
|
|
207
|
+
blockNumber: number;
|
|
208
|
+
/** Gas used */
|
|
209
|
+
gasUsed: string;
|
|
210
|
+
/** Tempo Explorer URL */
|
|
211
|
+
explorerUrl: string;
|
|
212
|
+
/** Description of what this TX did */
|
|
213
|
+
description?: string;
|
|
214
|
+
}
|
|
215
|
+
/**
|
|
216
|
+
* APS-1 Settlement Event - emitted when escrow is settled.
|
|
217
|
+
*/
|
|
218
|
+
export interface APS1Settlement {
|
|
219
|
+
/** Job identifier */
|
|
220
|
+
jobId: string;
|
|
221
|
+
/** Settlement type */
|
|
222
|
+
type: 'settle' | 'refund' | 'dispute';
|
|
223
|
+
/** Amount paid to agent (after fee deduction) */
|
|
224
|
+
agentPayout: string;
|
|
225
|
+
/** Platform fee amount */
|
|
226
|
+
platformFee: string;
|
|
227
|
+
/** Settlement transaction hash */
|
|
228
|
+
txHash: string;
|
|
229
|
+
/** ISO timestamp */
|
|
230
|
+
timestamp: string;
|
|
231
|
+
}
|
|
232
|
+
export declare const APS1_VERSION: "1.0";
|
|
233
|
+
export declare const APS1_CHAIN_ID = 42431;
|
|
234
|
+
export declare const APS1_NETWORK = "Tempo L1 Moderato";
|
|
235
|
+
export declare const APS1_PLATFORM_FEE_BPS = 800;
|
|
236
|
+
/** Default supported tokens on Tempo L1 */
|
|
237
|
+
export declare const APS1_DEFAULT_TOKENS: APS1TokenConfig[];
|
|
238
|
+
/** PayPol smart contract addresses on Tempo L1 */
|
|
239
|
+
export declare const APS1_CONTRACTS: {
|
|
240
|
+
readonly NexusV2: "0x6A467Cd4156093bB528e448C04366586a1052Fab";
|
|
241
|
+
readonly ShieldVaultV2: "0x3B4b47971B61cB502DD97eAD9cAF0552ffae0055";
|
|
242
|
+
readonly MultisendV2: "0x25f4d3f12C579002681a52821F3a6251c46D4575";
|
|
243
|
+
readonly AIProofRegistry: "0x8fDB8E871c9eaF2955009566F41490Bbb128a014";
|
|
244
|
+
readonly StreamV1: "0x4fE37c46E3D442129c2319de3D24c21A6cbfa36C";
|
|
245
|
+
readonly Reputation: "0x9332c1B2bb94C96DA2D729423f345c76dB3494D0";
|
|
246
|
+
};
|
package/dist/types.js
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* APS-1: Agent Payment Standard v1.0
|
|
3
|
+
*
|
|
4
|
+
* Core type definitions for the PayPol Agent Payment Standard.
|
|
5
|
+
* These interfaces define the protocol for how AI agents discover,
|
|
6
|
+
* negotiate, escrow, execute, verify, and settle payments.
|
|
7
|
+
*
|
|
8
|
+
* Framework-agnostic - works with OpenAI, Anthropic, LangChain,
|
|
9
|
+
* CrewAI, MCP, Eliza, or any HTTP-based agent.
|
|
10
|
+
*/
|
|
11
|
+
// ── Protocol Constants ─────────────────────────────────────
|
|
12
|
+
export const APS1_VERSION = '1.0';
|
|
13
|
+
export const APS1_CHAIN_ID = 42431;
|
|
14
|
+
export const APS1_NETWORK = 'Tempo L1 Moderato';
|
|
15
|
+
export const APS1_PLATFORM_FEE_BPS = 800; // 8%
|
|
16
|
+
/** Default supported tokens on Tempo L1 */
|
|
17
|
+
export const APS1_DEFAULT_TOKENS = [
|
|
18
|
+
{ symbol: 'AlphaUSD', address: '0x20c0000000000000000000000000000000000001', decimals: 6 },
|
|
19
|
+
{ symbol: 'pathUSD', address: '0x20c0000000000000000000000000000000000000', decimals: 6 },
|
|
20
|
+
{ symbol: 'BetaUSD', address: '0x20c0000000000000000000000000000000000002', decimals: 6 },
|
|
21
|
+
{ symbol: 'ThetaUSD', address: '0x20c0000000000000000000000000000000000003', decimals: 6 },
|
|
22
|
+
];
|
|
23
|
+
/** PayPol smart contract addresses on Tempo L1 */
|
|
24
|
+
export const APS1_CONTRACTS = {
|
|
25
|
+
NexusV2: '0x6A467Cd4156093bB528e448C04366586a1052Fab',
|
|
26
|
+
ShieldVaultV2: '0x3B4b47971B61cB502DD97eAD9cAF0552ffae0055',
|
|
27
|
+
MultisendV2: '0x25f4d3f12C579002681a52821F3a6251c46D4575',
|
|
28
|
+
AIProofRegistry: '0x8fDB8E871c9eaF2955009566F41490Bbb128a014',
|
|
29
|
+
StreamV1: '0x4fE37c46E3D442129c2319de3D24c21A6cbfa36C',
|
|
30
|
+
Reputation: '0x9332c1B2bb94C96DA2D729423f345c76dB3494D0',
|
|
31
|
+
};
|