arl-protocol-sdk 0.2.0 → 0.2.2

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 CHANGED
@@ -61,7 +61,7 @@ the same calls unsigned, for wallets that sign elsewhere. `parseTask`, `taskHash
61
61
  | ------------------------------------------ | ------------------------------------------------------------------------- |
62
62
  | `streamComputePayment`, `stopComputeStream` | Pay a compute provider per second (`COMPUTE_PAYMENT` on Base Mainnet) |
63
63
  | `quoteArl`, `acquireArl` | Buy exact ARL in the official Uniswap v3 pools, paying USDC, USDT or ETH |
64
- | `openVerifiedJob`, `getVerdict`, `finalizeJob` | Verified jobs: a committee of staked ARL validators checks the work |
64
+ | `openVerifiedJob`, `getVerdict`, `getOutcomes`, `finalizeJob` | Verified jobs: a committee of staked ARL validators checks the work, and `getOutcomes` reads an agent's verified `outcomesOf` counts |
65
65
  | `payVerified` | Pay a service that answers HTTP 402 with an ARL escrow offer |
66
66
 
67
67
  ## Contracts on Base Mainnet
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "arl-protocol-sdk",
3
- "version": "0.2.0",
3
+ "version": "0.2.2",
4
4
  "description": "ARL Protocol SDK: escrowed and verified jobs for AI agents, compute payments and ARL purchase on Base Mainnet",
5
5
  "keywords": [
6
6
  "arl",
@@ -7,14 +7,14 @@ export const BASE_MAINNET_TASK_DEPLOYMENTS = {
7
7
  chainId: 8453,
8
8
  token: "0xde91E6f39D50bBd875f831dcc1134A3D7f3aaDb4",
9
9
  jobs: "0x9aE99bF9a59aF47E81346B7c0b93Cd2B610455fC",
10
- evaluator: "0x6648e141cb7473822ddBd8bC039b91e5af3259B4",
10
+ evaluator: "0x0D160C869bd2a7AaEDd29e11fc60fdAEf21c3E28",
11
11
  arbiter: ARBITER_SAFE,
12
12
  },
13
13
  USDC: {
14
14
  chainId: 8453,
15
15
  token: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
16
16
  jobs: "0xE3eA0EAEc3Cf9DA2d0856A0f784A4B1671AeFD04",
17
- evaluator: "0x6bFfdEace7d0B2F7711f604F0A5D2545be2961AF",
17
+ evaluator: "0x7A00D45598Da7C13feEA8962fc1110FC4Db4D850",
18
18
  arbiter: ARBITER_SAFE,
19
19
  },
20
20
  };
@@ -63,10 +63,5 @@ export interface EvidenceResult {
63
63
  /** The settlement differs from the committee's decision (a dispute was ruled). */
64
64
  overturned: boolean;
65
65
  }
66
- /**
67
- * Checks that the settlement record, task, proof and policy describe the same job and agree.
68
- * Throws EvidenceError (or the document's own error) on the first inconsistency. It does not
69
- * re-read the chain: run `arl-verifier verify-bundle` on `settlement` for that.
70
- */
71
66
  export declare function checkEvidence(raw: EvidenceV2): EvidenceResult;
72
67
  export {};
@@ -16,14 +16,25 @@ const TIER_INDEX = { fallback: 0, reexecution: 1, attested: 2 };
16
16
  * Throws EvidenceError (or the document's own error) on the first inconsistency. It does not
17
17
  * re-read the chain: run `arl-verifier verify-bundle` on `settlement` for that.
18
18
  */
19
+ function isObject(v) {
20
+ return typeof v === "object" && v !== null && !Array.isArray(v);
21
+ }
19
22
  export function checkEvidence(raw) {
20
- // The bundle is untrusted input: check the versions as plain values.
21
- const versions = raw;
22
- if (versions.version !== EVIDENCE_VERSION)
23
+ // The bundle is untrusted input: check its shape before reading it (security report
24
+ // 2026-11-17: a missing field must be the caller's EvidenceError, not a TypeError).
25
+ const doc = raw;
26
+ if (!isObject(doc) || doc.version !== EVIDENCE_VERSION)
23
27
  throw new EvidenceError("version must be arl-evidence/2");
24
- if (versions.settlement.version !== "arl-evidence/1") {
28
+ const record = doc.settlement;
29
+ if (!isObject(record) || record.version !== "arl-evidence/1") {
25
30
  throw new EvidenceError("settlement must be arl-evidence/1");
26
31
  }
32
+ if (!isObject(record.job) ||
33
+ !isObject(record.config) ||
34
+ !Array.isArray(record.config.committee) ||
35
+ !Array.isArray(record.votes)) {
36
+ throw new EvidenceError("settlement record is incomplete");
37
+ }
27
38
  const s = raw.settlement;
28
39
  const task = parseTask(raw.task);
29
40
  const proof = parseProof(raw.proof);
@@ -90,6 +101,11 @@ export function checkEvidence(raw) {
90
101
  if (s.decided?.approved === true && approvals < task.verification.threshold) {
91
102
  throw new EvidenceError("decided approved without enough approvals");
92
103
  }
104
+ // A committee rejection happens only once no deliverable can reach the threshold.
105
+ const open = s.config.committee.length - approvals - rejections;
106
+ if (s.decided?.approved === false && approvals + open >= task.verification.threshold) {
107
+ throw new EvidenceError("decided rejected while the threshold was still reachable");
108
+ }
93
109
  if (s.settlement === null)
94
110
  return { outcome: "pending", approvals, rejections, overturned: false };
95
111
  // On chain a provider is paid only through the evaluator's settlement, which always follows a
@@ -43,6 +43,60 @@ const RAW = [
43
43
  required_evidence: ["artifact", "model-verdict"],
44
44
  model: { allowed: true, max_budget: { ARL: ARL_100, USDC: "100000000" }, models: [] },
45
45
  },
46
+ // Job-type policies: one per common kind of agent work, each paired with a task template in
47
+ // spec/arl-policy/v0.1.0/templates and a validator checklist in the spec README.
48
+ {
49
+ version: POLICY_VERSION,
50
+ id: "code-tests",
51
+ workload_classes: ["reexec"],
52
+ tiers: ["reexecution"],
53
+ committee: { min_size: 3, max_size: 7 },
54
+ vote_window_seconds: [3600, 86400],
55
+ challenge_window_seconds: [86400, 259200],
56
+ min_bond_floor: ARL_100,
57
+ bond_covers_budget: true,
58
+ required_evidence: ["result-manifest", "logs"],
59
+ model: { allowed: false, max_budget: {}, models: [] },
60
+ },
61
+ {
62
+ version: POLICY_VERSION,
63
+ id: "data-recompute",
64
+ workload_classes: ["reexec"],
65
+ tiers: ["reexecution"],
66
+ committee: { min_size: 3, max_size: 7 },
67
+ vote_window_seconds: [3600, 86400],
68
+ challenge_window_seconds: [86400, 259200],
69
+ min_bond_floor: ARL_100,
70
+ bond_covers_budget: true,
71
+ required_evidence: ["result-manifest", "artifact"],
72
+ model: { allowed: false, max_budget: {}, models: [] },
73
+ },
74
+ {
75
+ version: POLICY_VERSION,
76
+ id: "gpu-inference",
77
+ workload_classes: ["attested"],
78
+ tiers: ["attested"],
79
+ committee: { min_size: 3, max_size: 7 },
80
+ vote_window_seconds: [3600, 172800],
81
+ challenge_window_seconds: [86400, 259200],
82
+ min_bond_floor: ARL_100,
83
+ bond_covers_budget: true,
84
+ required_evidence: ["attestation", "result-manifest", "logs"],
85
+ model: { allowed: false, max_budget: {}, models: [] },
86
+ },
87
+ {
88
+ version: POLICY_VERSION,
89
+ id: "research-sources",
90
+ workload_classes: ["model-assisted"],
91
+ tiers: ["attested"],
92
+ committee: { min_size: 3, max_size: 7 },
93
+ vote_window_seconds: [3600, 172800],
94
+ challenge_window_seconds: [86400, 259200],
95
+ min_bond_floor: ARL_100,
96
+ bond_covers_budget: true,
97
+ required_evidence: ["artifact", "model-verdict", "logs"],
98
+ model: { allowed: true, max_budget: { ARL: ARL_100, USDC: "100000000" }, models: [] },
99
+ },
46
100
  ];
47
101
  /** The built-in policies, validated, by id. */
48
102
  export const BUILTIN_POLICIES = new Map(RAW.map((r) => {
@@ -1,6 +1,6 @@
1
1
  export { computePaymentAbi } from "./abi.ts";
2
2
  export { BASE_MAINNET_CHAIN_ID, COMPUTE_PAYMENT, MAX_STREAM_DURATION_SECONDS, StreamingError, planStream, stopComputeStream, streamComputePayment, type ComputeStream, type StopComputeStreamParams, type StreamComputePaymentParams, type StreamSettlement, type StreamingClients, type StreamingErrorCode, } from "./streaming.ts";
3
- export { BASE_MAINNET_VERIFIED, VERDICT_PHASES, VerifiedJobError, checkEvaluationFits, checkOpenParams, checkVerifiedChain, finalizeJob, getVerdict, openVerifiedJob, verifiedEvaluatorAbi, verifiedDeployment, verifiedJobsAbi, walletAccount, type OpenVerifiedJobParams, type VerifiedClients, } from "./verified.ts";
3
+ export { BASE_MAINNET_VERIFIED, VERDICT_PHASES, VerifiedJobError, checkEvaluationFits, checkOpenParams, checkVerifiedChain, finalizeJob, getOutcomes, getVerdict, openVerifiedJob, defaultWindows, verifiedEvaluatorAbi, verifiedDeployment, verifiedJobsAbi, walletAccount, type AgentOutcomes, type OpenVerifiedJobParams, type VerifiedClients, } from "./verified.ts";
4
4
  export { ESCROW_SCHEME, JOB_HEADER, fundVerifiedJob, parseEscrowOffer, payVerified, type EscrowOffer, type PayVerifiedOptions, } from "./payVerified.ts";
5
5
  export { ARL_SWAP, acquireArl, quoteArl, type AcquireArlParams, type ArlQuoteToken, } from "./acquireArl.ts";
6
6
  export { acceptedCount, approveCommittee, buildEscrowOffer, checkFundedJob, submitDeliverable, waitForAcceptance, type EscrowOfferInput, } from "./escrowProvider.ts";
package/sdk/src/index.js CHANGED
@@ -1,6 +1,6 @@
1
1
  export { computePaymentAbi } from "./abi.js";
2
2
  export { BASE_MAINNET_CHAIN_ID, COMPUTE_PAYMENT, MAX_STREAM_DURATION_SECONDS, StreamingError, planStream, stopComputeStream, streamComputePayment, } from "./streaming.js";
3
- export { BASE_MAINNET_VERIFIED, VERDICT_PHASES, VerifiedJobError, checkEvaluationFits, checkOpenParams, checkVerifiedChain, finalizeJob, getVerdict, openVerifiedJob, verifiedEvaluatorAbi, verifiedDeployment, verifiedJobsAbi, walletAccount, } from "./verified.js";
3
+ export { BASE_MAINNET_VERIFIED, VERDICT_PHASES, VerifiedJobError, checkEvaluationFits, checkOpenParams, checkVerifiedChain, finalizeJob, getOutcomes, getVerdict, openVerifiedJob, defaultWindows, verifiedEvaluatorAbi, verifiedDeployment, verifiedJobsAbi, walletAccount, } from "./verified.js";
4
4
  export { ESCROW_SCHEME, JOB_HEADER, fundVerifiedJob, parseEscrowOffer, payVerified, } from "./payVerified.js";
5
5
  export { ARL_SWAP, acquireArl, quoteArl, } from "./acquireArl.js";
6
6
  export { acceptedCount, approveCommittee, buildEscrowOffer, checkFundedJob, submitDeliverable, waitForAcceptance, } from "./escrowProvider.js";
@@ -10,7 +10,7 @@ export declare const BASE_MAINNET_VERIFIED: {
10
10
  readonly chainId: 8453;
11
11
  readonly token: "0xde91E6f39D50bBd875f831dcc1134A3D7f3aaDb4";
12
12
  readonly jobs: "0x9aE99bF9a59aF47E81346B7c0b93Cd2B610455fC";
13
- readonly evaluator: "0x6648e141cb7473822ddBd8bC039b91e5af3259B4";
13
+ readonly evaluator: "0x0D160C869bd2a7AaEDd29e11fc60fdAEf21c3E28";
14
14
  readonly arbiterSafe: "0x8FF6c3aD0991Ac848BFf5d0acD78BBc5e190466f";
15
15
  };
16
16
  /** The jobs escrow and evaluator of a chain, or undefined on the local chain. */
@@ -149,6 +149,21 @@ export declare const verifiedEvaluatorAbi: readonly [{
149
149
  readonly name: "voteHash";
150
150
  }];
151
151
  }];
152
+ }, {
153
+ readonly name: "outcomesOf";
154
+ readonly type: "function";
155
+ readonly stateMutability: "view";
156
+ readonly inputs: readonly [{
157
+ readonly type: "uint256";
158
+ readonly name: "agentId";
159
+ }];
160
+ readonly outputs: readonly [{
161
+ readonly type: "uint64";
162
+ readonly name: "approved";
163
+ }, {
164
+ readonly type: "uint64";
165
+ readonly name: "rejected";
166
+ }];
152
167
  }, {
153
168
  readonly name: "finalize";
154
169
  readonly type: "function";
@@ -158,6 +173,14 @@ export declare const verifiedEvaluatorAbi: readonly [{
158
173
  readonly name: "jobId";
159
174
  }];
160
175
  readonly outputs: readonly [];
176
+ }, {
177
+ readonly name: "minChallengeWindow";
178
+ readonly type: "function";
179
+ readonly stateMutability: "view";
180
+ readonly inputs: readonly [];
181
+ readonly outputs: readonly [{
182
+ readonly type: "uint64";
183
+ }];
161
184
  }];
162
185
  /** ARLVerifiedEvaluator.Phase, by index. */
163
186
  export declare const VERDICT_PHASES: readonly ["None", "Configured", "Approved", "Rejected", "Disputed", "Finalized", "Released", "Failed"];
@@ -201,6 +224,21 @@ export declare function checkVerifiedChain(client: PublicClient): Promise<number
201
224
  export declare function walletAccount(wallet: VerifiedClients["walletClient"]): Account;
202
225
  /** Checks the parameters the evaluator would reject, before any transaction is sent. */
203
226
  export declare function checkOpenParams(p: OpenVerifiedJobParams): void;
227
+ /**
228
+ * The windows and lifetime openVerifiedJob uses when the caller gives none. The challenge window
229
+ * defaults to the evaluator's minimum (one day on Base Mainnet) and the job lives long enough for
230
+ * the evaluator's own check at configure and at voting start (`_checkFits`: the vote window plus
231
+ * two challenge windows), with a day to spare for the committee to accept.
232
+ */
233
+ export declare function defaultWindows(minChallengeWindow: bigint, p: {
234
+ voteWindow?: bigint;
235
+ challengeWindow?: bigint;
236
+ expiresIn?: bigint;
237
+ }): {
238
+ voteWindow: bigint;
239
+ challengeWindow: bigint;
240
+ expiresIn: bigint;
241
+ };
204
242
  /**
205
243
  * Creates the job (the caller is its client) and configures the committee in two transactions.
206
244
  * The provider then approves the committee and sets the budget; the client funds the job.
@@ -225,5 +263,15 @@ export declare function getVerdict(publicClient: PublicClient, jobId: bigint, ev
225
263
  deliverable: `0x${string}`;
226
264
  voteHash: `0x${string}`;
227
265
  }>;
266
+ export interface AgentOutcomes {
267
+ approved: bigint;
268
+ rejected: bigint;
269
+ }
270
+ /**
271
+ * Approved and rejected job counts recorded by `ARLVerifiedEvaluator` for an ERC-8004 agent.
272
+ * Accepts either `(publicClient, evaluator, agentId)` or `(publicClient, agentId, evaluator?)`.
273
+ */
274
+ export declare function getOutcomes(publicClient: PublicClient, evaluator: Address, agentId: bigint): Promise<AgentOutcomes>;
275
+ export declare function getOutcomes(publicClient: PublicClient, agentId: bigint, evaluator?: Address): Promise<AgentOutcomes>;
228
276
  /** Pays out after the challenge window: anyone may call it. */
229
277
  export declare function finalizeJob({ publicClient, walletClient }: VerifiedClients, jobId: bigint, evaluator?: Address): Promise<Hash>;
@@ -19,7 +19,7 @@ export const BASE_MAINNET_VERIFIED = {
19
19
  chainId: 8453,
20
20
  token: "0xde91E6f39D50bBd875f831dcc1134A3D7f3aaDb4",
21
21
  jobs: "0x9aE99bF9a59aF47E81346B7c0b93Cd2B610455fC",
22
- evaluator: "0x6648e141cb7473822ddBd8bC039b91e5af3259B4",
22
+ evaluator: "0x0D160C869bd2a7AaEDd29e11fc60fdAEf21c3E28",
23
23
  arbiterSafe: "0x8FF6c3aD0991Ac848BFf5d0acD78BBc5e190466f",
24
24
  };
25
25
  const ALLOWED = [8453, 31_337];
@@ -44,7 +44,9 @@ export const verifiedEvaluatorAbi = parseAbi([
44
44
  "struct Verdict { uint8 phase; bool providerApproved; uint8 approvals; uint8 rejections; uint8 topApprovals; uint64 voteEnds; uint64 challengeEnds; address challenger; uint256 bond; bytes32 deliverable; bytes32 voteHash; }",
45
45
  "function configure(uint256 jobId, Config cfg)",
46
46
  "function getVerdict(uint256 jobId) view returns (Verdict)",
47
+ "function outcomesOf(uint256 agentId) view returns (uint64 approved, uint64 rejected)",
47
48
  "function finalize(uint256 jobId)",
49
+ "function minChallengeWindow() view returns (uint64)",
48
50
  ]);
49
51
  /** ARLVerifiedEvaluator.Phase, by index. */
50
52
  export const VERDICT_PHASES = [
@@ -116,6 +118,21 @@ export function checkOpenParams(p) {
116
118
  if (!/^0x[0-9a-fA-F]{64}$/.test(p.specHash))
117
119
  throw new VerifiedJobError("specHash must be 32 bytes");
118
120
  }
121
+ /** Time left after the windows for the committee to accept before voting starts (one day). */
122
+ const ACCEPT_SLACK = 86400n;
123
+ /**
124
+ * The windows and lifetime openVerifiedJob uses when the caller gives none. The challenge window
125
+ * defaults to the evaluator's minimum (one day on Base Mainnet) and the job lives long enough for
126
+ * the evaluator's own check at configure and at voting start (`_checkFits`: the vote window plus
127
+ * two challenge windows), with a day to spare for the committee to accept.
128
+ */
129
+ export function defaultWindows(minChallengeWindow, p) {
130
+ const voteWindow = p.voteWindow ?? 3600n;
131
+ const challengeWindow = p.challengeWindow ?? (minChallengeWindow > 3600n ? minChallengeWindow : 3600n);
132
+ const needed = voteWindow + 2n * challengeWindow + ACCEPT_SLACK;
133
+ const expiresIn = p.expiresIn ?? (needed > 86400n ? needed : 86400n);
134
+ return { voteWindow, challengeWindow, expiresIn };
135
+ }
119
136
  /**
120
137
  * Creates the job (the caller is its client) and configures the committee in two transactions.
121
138
  * The provider then approves the committee and sets the budget; the client funds the job.
@@ -130,10 +147,14 @@ export async function openVerifiedJob({ publicClient, walletClient }, p) {
130
147
  throw new VerifiedJobError("jobs and evaluator are required locally");
131
148
  await requireCode(publicClient, jobs, "jobs escrow");
132
149
  await requireCode(publicClient, evaluator, "evaluator");
133
- const voteWindow = p.voteWindow ?? 3600n;
134
- const challengeWindow = p.challengeWindow ?? 3600n;
150
+ const minChallengeWindow = await publicClient.readContract({
151
+ address: evaluator,
152
+ abi: verifiedEvaluatorAbi,
153
+ functionName: "minChallengeWindow",
154
+ });
155
+ const { voteWindow, challengeWindow, expiresIn } = defaultWindows(minChallengeWindow, p);
135
156
  const { timestamp } = await publicClient.getBlock();
136
- const expiredAt = timestamp + (p.expiresIn ?? 86400n);
157
+ const expiredAt = timestamp + expiresIn;
137
158
  const from = walletAccount(walletClient);
138
159
  const createTx = await walletClient.writeContract({
139
160
  account: from,
@@ -199,6 +220,25 @@ export async function getVerdict(publicClient, jobId, evaluator) {
199
220
  });
200
221
  return { ...v, phaseName: VERDICT_PHASES[v.phase] ?? `Phase ${String(v.phase)}` };
201
222
  }
223
+ export async function getOutcomes(publicClient, evaluatorOrAgentId, agentIdOrEvaluator) {
224
+ const chainId = await checkVerifiedChain(publicClient);
225
+ const [evaluator, agentId] = typeof evaluatorOrAgentId === "bigint"
226
+ ? [agentIdOrEvaluator, evaluatorOrAgentId]
227
+ : [evaluatorOrAgentId, agentIdOrEvaluator];
228
+ if (typeof agentId !== "bigint" || agentId < 0n) {
229
+ throw new VerifiedJobError("agentId must be a non-negative bigint");
230
+ }
231
+ const address = evaluator ?? verifiedDeployment(chainId)?.evaluator;
232
+ if (!address)
233
+ throw new VerifiedJobError("evaluator is required locally");
234
+ const [approved, rejected] = await publicClient.readContract({
235
+ address,
236
+ abi: verifiedEvaluatorAbi,
237
+ functionName: "outcomesOf",
238
+ args: [agentId],
239
+ });
240
+ return { approved, rejected };
241
+ }
202
242
  /** Pays out after the challenge window: anyone may call it. */
203
243
  export async function finalizeJob({ publicClient, walletClient }, jobId, evaluator) {
204
244
  const chainId = await checkVerifiedChain(publicClient);