arl-protocol-sdk 0.0.0-stage → 0.2.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 +79 -2
- package/package.json +32 -4
- package/protocol/src/canonical.d.ts +7 -0
- package/protocol/src/canonical.js +35 -0
- package/protocol/src/deployments.d.ts +17 -0
- package/protocol/src/deployments.js +24 -0
- package/protocol/src/evidence.d.ts +72 -0
- package/protocol/src/evidence.js +107 -0
- package/protocol/src/index.d.ts +14 -0
- package/protocol/src/index.js +9 -0
- package/protocol/src/policies.d.ts +5 -0
- package/protocol/src/policies.js +56 -0
- package/protocol/src/policy.d.ts +65 -0
- package/protocol/src/policy.js +202 -0
- package/protocol/src/prepare.d.ts +176 -0
- package/protocol/src/prepare.js +104 -0
- package/protocol/src/proof.d.ts +70 -0
- package/protocol/src/proof.js +239 -0
- package/protocol/src/reputation.d.ts +47 -0
- package/protocol/src/reputation.js +74 -0
- package/protocol/src/task.d.ts +121 -0
- package/protocol/src/task.js +322 -0
- package/sdk/src/abi.d.ts +358 -0
- package/sdk/src/abi.js +465 -0
- package/sdk/src/acquireArl.d.ts +34 -0
- package/sdk/src/acquireArl.js +126 -0
- package/sdk/src/escrowProvider.d.ts +73 -0
- package/sdk/src/escrowProvider.js +169 -0
- package/sdk/src/index.d.ts +9 -0
- package/sdk/src/index.js +10 -0
- package/sdk/src/jobs.d.ts +278 -0
- package/sdk/src/jobs.js +220 -0
- package/sdk/src/openTask.d.ts +23 -0
- package/sdk/src/openTask.js +116 -0
- package/sdk/src/payVerified.d.ts +45 -0
- package/sdk/src/payVerified.js +147 -0
- package/sdk/src/streaming.d.ts +80 -0
- package/sdk/src/streaming.js +229 -0
- package/sdk/src/verified.d.ts +229 -0
- package/sdk/src/verified.js +220 -0
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
// arl-policy/1: verification policies (spec/arl-policy/v0.1.0). A policy fixes, per workload
|
|
2
|
+
// class, how a task is checked: tier and committee shape, windows, bond sizing, required evidence,
|
|
3
|
+
// whether a model verdict is admissible and up to which budget, and how a validator turns its own
|
|
4
|
+
// checks into a vote. Contract-enforced bounds stay in the contract; the rest is validator duty,
|
|
5
|
+
// backed by bonds and disputes.
|
|
6
|
+
import { canonicalHash } from "./canonical.js";
|
|
7
|
+
import { BOUNDS, EVIDENCE_KINDS, TIERS, TOKENS, WORKLOAD_CLASSES, } from "./task.js";
|
|
8
|
+
export const POLICY_VERSION = "arl-policy/1";
|
|
9
|
+
export class PolicyError extends Error {
|
|
10
|
+
name = "PolicyError";
|
|
11
|
+
}
|
|
12
|
+
const ID = /^[a-z0-9][a-z0-9-]{0,47}$/;
|
|
13
|
+
const DIGITS = /^(0|[1-9][0-9]*)$/;
|
|
14
|
+
const SHA256 = /^[0-9a-f]{64}$/;
|
|
15
|
+
function isRecord(v) {
|
|
16
|
+
return typeof v === "object" && v !== null && !Array.isArray(v);
|
|
17
|
+
}
|
|
18
|
+
function onlyKeys(v, allowed, what) {
|
|
19
|
+
for (const k of Object.keys(v)) {
|
|
20
|
+
if (!allowed.includes(k))
|
|
21
|
+
throw new PolicyError(`${what}: unknown field ${k}`);
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
function list(v, values, what, nonEmpty = true) {
|
|
25
|
+
if (!Array.isArray(v) || (nonEmpty && v.length === 0)) {
|
|
26
|
+
throw new PolicyError(`${what} must be a${nonEmpty ? " non-empty" : "n"} array`);
|
|
27
|
+
}
|
|
28
|
+
const out = v.map((x, i) => {
|
|
29
|
+
if (typeof x !== "string" || !values.includes(x)) {
|
|
30
|
+
throw new PolicyError(`${what}[${i}] must be one of ${values.join(", ")}`);
|
|
31
|
+
}
|
|
32
|
+
return x;
|
|
33
|
+
});
|
|
34
|
+
if (new Set(out).size !== out.length)
|
|
35
|
+
throw new PolicyError(`${what} repeats a value`);
|
|
36
|
+
return out;
|
|
37
|
+
}
|
|
38
|
+
function range(v, [lo, hi], what) {
|
|
39
|
+
if (!Array.isArray(v) ||
|
|
40
|
+
v.length !== 2 ||
|
|
41
|
+
!v.every((x) => typeof x === "number" && Number.isSafeInteger(x)) ||
|
|
42
|
+
v[0] < lo ||
|
|
43
|
+
v[1] > hi ||
|
|
44
|
+
v[0] > v[1]) {
|
|
45
|
+
throw new PolicyError(`${what} must be [min, max] within ${lo}..${hi}`);
|
|
46
|
+
}
|
|
47
|
+
return [v[0], v[1]];
|
|
48
|
+
}
|
|
49
|
+
function digits(v, what) {
|
|
50
|
+
if (typeof v !== "string" || !DIGITS.test(v))
|
|
51
|
+
throw new PolicyError(`${what} must be a decimal string`);
|
|
52
|
+
return v;
|
|
53
|
+
}
|
|
54
|
+
/** Validates an untrusted policy document. Unknown fields are refused. */
|
|
55
|
+
export function parsePolicy(raw) {
|
|
56
|
+
if (!isRecord(raw))
|
|
57
|
+
throw new PolicyError("policy must be an object");
|
|
58
|
+
onlyKeys(raw, [
|
|
59
|
+
"version",
|
|
60
|
+
"id",
|
|
61
|
+
"workload_classes",
|
|
62
|
+
"tiers",
|
|
63
|
+
"committee",
|
|
64
|
+
"vote_window_seconds",
|
|
65
|
+
"challenge_window_seconds",
|
|
66
|
+
"min_bond_floor",
|
|
67
|
+
"bond_covers_budget",
|
|
68
|
+
"required_evidence",
|
|
69
|
+
"model",
|
|
70
|
+
], "policy");
|
|
71
|
+
if (raw.version !== POLICY_VERSION)
|
|
72
|
+
throw new PolicyError(`version must be ${POLICY_VERSION}`);
|
|
73
|
+
if (typeof raw.id !== "string" || !ID.test(raw.id))
|
|
74
|
+
throw new PolicyError("id must be lowercase letters, digits and dashes");
|
|
75
|
+
const classes = list(raw.workload_classes, WORKLOAD_CLASSES, "workload_classes");
|
|
76
|
+
const tiers = list(raw.tiers, TIERS, "tiers");
|
|
77
|
+
if (!isRecord(raw.committee))
|
|
78
|
+
throw new PolicyError("committee must be an object");
|
|
79
|
+
onlyKeys(raw.committee, ["min_size", "max_size"], "committee");
|
|
80
|
+
const [minSize, maxSize] = range([raw.committee.min_size, raw.committee.max_size], BOUNDS.committeeSize, "committee");
|
|
81
|
+
if (typeof raw.bond_covers_budget !== "boolean")
|
|
82
|
+
throw new PolicyError("bond_covers_budget must be a boolean");
|
|
83
|
+
if (!isRecord(raw.model))
|
|
84
|
+
throw new PolicyError("model must be an object");
|
|
85
|
+
onlyKeys(raw.model, ["allowed", "max_budget", "models"], "model");
|
|
86
|
+
if (typeof raw.model.allowed !== "boolean")
|
|
87
|
+
throw new PolicyError("model.allowed must be a boolean");
|
|
88
|
+
if (!isRecord(raw.model.max_budget))
|
|
89
|
+
throw new PolicyError("model.max_budget must be an object");
|
|
90
|
+
const maxBudget = {};
|
|
91
|
+
for (const [k, v] of Object.entries(raw.model.max_budget)) {
|
|
92
|
+
if (!TOKENS.includes(k))
|
|
93
|
+
throw new PolicyError(`model.max_budget: unknown token ${k}`);
|
|
94
|
+
maxBudget[k] = digits(v, `model.max_budget.${k}`);
|
|
95
|
+
}
|
|
96
|
+
if (!Array.isArray(raw.model.models))
|
|
97
|
+
throw new PolicyError("model.models must be an array");
|
|
98
|
+
const models = raw.model.models.map((m, i) => {
|
|
99
|
+
if (!isRecord(m))
|
|
100
|
+
throw new PolicyError(`model.models[${i}] must be an object`);
|
|
101
|
+
onlyKeys(m, ["name", "weights_sha256"], `model.models[${i}]`);
|
|
102
|
+
if (typeof m.name !== "string" || m.name.trim() === "")
|
|
103
|
+
throw new PolicyError(`model.models[${i}].name must be a string`);
|
|
104
|
+
if (typeof m.weights_sha256 !== "string" || !SHA256.test(m.weights_sha256)) {
|
|
105
|
+
throw new PolicyError(`model.models[${i}].weights_sha256 must be 64 lowercase hex`);
|
|
106
|
+
}
|
|
107
|
+
return { name: m.name, weights_sha256: m.weights_sha256 };
|
|
108
|
+
});
|
|
109
|
+
if (raw.model.allowed && Object.keys(maxBudget).length === 0) {
|
|
110
|
+
throw new PolicyError("a policy that allows model verdicts must cap the budget");
|
|
111
|
+
}
|
|
112
|
+
if (classes.includes("reexec") && raw.model.allowed) {
|
|
113
|
+
throw new PolicyError("reexec policies decide by re-execution, not by a model");
|
|
114
|
+
}
|
|
115
|
+
return {
|
|
116
|
+
version: POLICY_VERSION,
|
|
117
|
+
id: raw.id,
|
|
118
|
+
workload_classes: classes,
|
|
119
|
+
tiers,
|
|
120
|
+
committee: { min_size: minSize, max_size: maxSize },
|
|
121
|
+
vote_window_seconds: range(raw.vote_window_seconds, BOUNDS.voteWindowSeconds, "vote_window_seconds"),
|
|
122
|
+
challenge_window_seconds: range(raw.challenge_window_seconds, BOUNDS.challengeWindowSeconds, "challenge_window_seconds"),
|
|
123
|
+
min_bond_floor: digits(raw.min_bond_floor, "min_bond_floor"),
|
|
124
|
+
bond_covers_budget: raw.bond_covers_budget,
|
|
125
|
+
required_evidence: list(raw.required_evidence, EVIDENCE_KINDS, "required_evidence", false),
|
|
126
|
+
model: { allowed: raw.model.allowed, max_budget: maxBudget, models },
|
|
127
|
+
};
|
|
128
|
+
}
|
|
129
|
+
export function policyHash(policy) {
|
|
130
|
+
return canonicalHash(policy);
|
|
131
|
+
}
|
|
132
|
+
/** The bond each accepted member locks: ARLVerifiedEvaluator takes max(floor, budget / 10). */
|
|
133
|
+
export function effectiveBond(task) {
|
|
134
|
+
const floor = BigInt(task.verification.bond_floor);
|
|
135
|
+
const tenth = BigInt(task.payment.budget) / 10n;
|
|
136
|
+
return floor > tenth ? floor : tenth;
|
|
137
|
+
}
|
|
138
|
+
/** Checks that a task follows the policy it names. Throws PolicyError with the first violation. */
|
|
139
|
+
export function checkTaskAgainstPolicy(task, policy) {
|
|
140
|
+
const v = task.verification;
|
|
141
|
+
if (v.policy !== `${POLICY_VERSION}:${policy.id}`)
|
|
142
|
+
throw new PolicyError("the task names another policy");
|
|
143
|
+
if (!policy.workload_classes.includes(task.workload.class)) {
|
|
144
|
+
throw new PolicyError(`workload class ${task.workload.class} is not covered by this policy`);
|
|
145
|
+
}
|
|
146
|
+
if (!policy.tiers.includes(v.tier))
|
|
147
|
+
throw new PolicyError(`tier ${v.tier} is not allowed by this policy`);
|
|
148
|
+
if (v.committee_size < policy.committee.min_size ||
|
|
149
|
+
v.committee_size > policy.committee.max_size) {
|
|
150
|
+
throw new PolicyError(`committee size must be ${policy.committee.min_size} to ${policy.committee.max_size}`);
|
|
151
|
+
}
|
|
152
|
+
const [vlo, vhi] = policy.vote_window_seconds;
|
|
153
|
+
if (v.vote_window_seconds < vlo || v.vote_window_seconds > vhi)
|
|
154
|
+
throw new PolicyError("vote window outside the policy");
|
|
155
|
+
const [clo, chi] = policy.challenge_window_seconds;
|
|
156
|
+
if (v.challenge_window_seconds < clo || v.challenge_window_seconds > chi) {
|
|
157
|
+
throw new PolicyError("challenge window outside the policy");
|
|
158
|
+
}
|
|
159
|
+
if (BigInt(v.bond_floor) < BigInt(policy.min_bond_floor))
|
|
160
|
+
throw new PolicyError("bond floor below the policy minimum");
|
|
161
|
+
if (policy.bond_covers_budget && task.payment.token === "ARL") {
|
|
162
|
+
if (BigInt(v.threshold) * effectiveBond(task) < BigInt(task.payment.budget)) {
|
|
163
|
+
throw new PolicyError("threshold × bond does not cover the budget");
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
for (const k of policy.required_evidence) {
|
|
167
|
+
if (!task.evidence.includes(k))
|
|
168
|
+
throw new PolicyError(`the policy requires ${k} evidence`);
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
/**
|
|
172
|
+
* Turns a validator's outcomes into its vote. Approve only if every acceptance rule of the task
|
|
173
|
+
* has an admissible passing outcome. A model outcome is admissible only if the policy allows
|
|
174
|
+
* models, the budget is within the policy's cap for the token, and (when the policy lists models)
|
|
175
|
+
* the weights are listed. Anything missing or inadmissible is a reject, never an approve.
|
|
176
|
+
*/
|
|
177
|
+
export function decideVote(task, policy, outcomes) {
|
|
178
|
+
const byId = new Map(outcomes.map((o) => [o.id, o]));
|
|
179
|
+
for (const rule of task.acceptance) {
|
|
180
|
+
const o = byId.get(rule.id);
|
|
181
|
+
if (o === undefined)
|
|
182
|
+
return { approve: false, reason: `no outcome for rule ${rule.id}` };
|
|
183
|
+
if (o.by === "model") {
|
|
184
|
+
if (!policy.model.allowed)
|
|
185
|
+
return { approve: false, reason: `rule ${rule.id}: model verdicts are not admissible` };
|
|
186
|
+
const cap = policy.model.max_budget[task.payment.token];
|
|
187
|
+
if (cap === undefined || BigInt(task.payment.budget) > BigInt(cap)) {
|
|
188
|
+
return { approve: false, reason: `rule ${rule.id}: budget above the model cap` };
|
|
189
|
+
}
|
|
190
|
+
if (policy.model.models.length > 0 &&
|
|
191
|
+
!policy.model.models.some((m) => m.weights_sha256 === o.weights_sha256)) {
|
|
192
|
+
return {
|
|
193
|
+
approve: false,
|
|
194
|
+
reason: `rule ${rule.id}: model weights not allowed by the policy`,
|
|
195
|
+
};
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
if (!o.passed)
|
|
199
|
+
return { approve: false, reason: `rule ${rule.id} failed` };
|
|
200
|
+
}
|
|
201
|
+
return { approve: true, reason: "every acceptance rule passed" };
|
|
202
|
+
}
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
import { type Address, type Hex } from "viem";
|
|
2
|
+
import type { TaskDeployment } from "./deployments.ts";
|
|
3
|
+
import { type Policy } from "./policy.ts";
|
|
4
|
+
import { type OnchainTerms, type Task } from "./task.ts";
|
|
5
|
+
export declare const openTaskAbi: readonly [{
|
|
6
|
+
readonly name: "createJob";
|
|
7
|
+
readonly type: "function";
|
|
8
|
+
readonly stateMutability: "nonpayable";
|
|
9
|
+
readonly inputs: readonly [{
|
|
10
|
+
readonly type: "address";
|
|
11
|
+
readonly name: "provider";
|
|
12
|
+
}, {
|
|
13
|
+
readonly type: "address";
|
|
14
|
+
readonly name: "evaluator";
|
|
15
|
+
}, {
|
|
16
|
+
readonly type: "uint256";
|
|
17
|
+
readonly name: "expiredAt";
|
|
18
|
+
}, {
|
|
19
|
+
readonly type: "string";
|
|
20
|
+
readonly name: "description";
|
|
21
|
+
}, {
|
|
22
|
+
readonly type: "address";
|
|
23
|
+
readonly name: "hook";
|
|
24
|
+
}];
|
|
25
|
+
readonly outputs: readonly [{
|
|
26
|
+
readonly type: "uint256";
|
|
27
|
+
}];
|
|
28
|
+
}, {
|
|
29
|
+
readonly name: "setBudget";
|
|
30
|
+
readonly type: "function";
|
|
31
|
+
readonly stateMutability: "nonpayable";
|
|
32
|
+
readonly inputs: readonly [{
|
|
33
|
+
readonly type: "uint256";
|
|
34
|
+
readonly name: "jobId";
|
|
35
|
+
}, {
|
|
36
|
+
readonly type: "uint256";
|
|
37
|
+
readonly name: "amount";
|
|
38
|
+
}, {
|
|
39
|
+
readonly type: "bytes";
|
|
40
|
+
readonly name: "optParams";
|
|
41
|
+
}];
|
|
42
|
+
readonly outputs: readonly [];
|
|
43
|
+
}, {
|
|
44
|
+
readonly name: "fund";
|
|
45
|
+
readonly type: "function";
|
|
46
|
+
readonly stateMutability: "nonpayable";
|
|
47
|
+
readonly inputs: readonly [{
|
|
48
|
+
readonly type: "uint256";
|
|
49
|
+
readonly name: "jobId";
|
|
50
|
+
}, {
|
|
51
|
+
readonly type: "uint256";
|
|
52
|
+
readonly name: "expectedBudget";
|
|
53
|
+
}, {
|
|
54
|
+
readonly type: "bytes";
|
|
55
|
+
readonly name: "optParams";
|
|
56
|
+
}];
|
|
57
|
+
readonly outputs: readonly [];
|
|
58
|
+
}, {
|
|
59
|
+
readonly name: "approve";
|
|
60
|
+
readonly type: "function";
|
|
61
|
+
readonly stateMutability: "nonpayable";
|
|
62
|
+
readonly inputs: readonly [{
|
|
63
|
+
readonly type: "address";
|
|
64
|
+
readonly name: "spender";
|
|
65
|
+
}, {
|
|
66
|
+
readonly type: "uint256";
|
|
67
|
+
readonly name: "amount";
|
|
68
|
+
}];
|
|
69
|
+
readonly outputs: readonly [{
|
|
70
|
+
readonly type: "bool";
|
|
71
|
+
}];
|
|
72
|
+
}, {
|
|
73
|
+
readonly name: "configure";
|
|
74
|
+
readonly type: "function";
|
|
75
|
+
readonly stateMutability: "nonpayable";
|
|
76
|
+
readonly inputs: readonly [{
|
|
77
|
+
readonly type: "uint256";
|
|
78
|
+
readonly name: "jobId";
|
|
79
|
+
}, {
|
|
80
|
+
readonly type: "tuple";
|
|
81
|
+
readonly components: readonly [{
|
|
82
|
+
readonly type: "uint8";
|
|
83
|
+
readonly name: "tier";
|
|
84
|
+
}, {
|
|
85
|
+
readonly type: "uint8";
|
|
86
|
+
readonly name: "threshold";
|
|
87
|
+
}, {
|
|
88
|
+
readonly type: "uint64";
|
|
89
|
+
readonly name: "voteWindow";
|
|
90
|
+
}, {
|
|
91
|
+
readonly type: "uint64";
|
|
92
|
+
readonly name: "challengeWindow";
|
|
93
|
+
}, {
|
|
94
|
+
readonly type: "uint96";
|
|
95
|
+
readonly name: "bond";
|
|
96
|
+
}, {
|
|
97
|
+
readonly type: "uint256";
|
|
98
|
+
readonly name: "providerAgentId";
|
|
99
|
+
}, {
|
|
100
|
+
readonly type: "bytes32";
|
|
101
|
+
readonly name: "specHash";
|
|
102
|
+
}, {
|
|
103
|
+
readonly type: "address[]";
|
|
104
|
+
readonly name: "committee";
|
|
105
|
+
}];
|
|
106
|
+
readonly name: "cfg";
|
|
107
|
+
}];
|
|
108
|
+
readonly outputs: readonly [];
|
|
109
|
+
}, {
|
|
110
|
+
readonly name: "JobCreated";
|
|
111
|
+
readonly type: "event";
|
|
112
|
+
readonly inputs: readonly [{
|
|
113
|
+
readonly type: "uint256";
|
|
114
|
+
readonly name: "jobId";
|
|
115
|
+
readonly indexed: true;
|
|
116
|
+
}, {
|
|
117
|
+
readonly type: "address";
|
|
118
|
+
readonly name: "client";
|
|
119
|
+
readonly indexed: true;
|
|
120
|
+
}, {
|
|
121
|
+
readonly type: "address";
|
|
122
|
+
readonly name: "provider";
|
|
123
|
+
readonly indexed: true;
|
|
124
|
+
}, {
|
|
125
|
+
readonly type: "address";
|
|
126
|
+
readonly name: "evaluator";
|
|
127
|
+
}, {
|
|
128
|
+
readonly type: "uint256";
|
|
129
|
+
readonly name: "expiredAt";
|
|
130
|
+
}, {
|
|
131
|
+
readonly type: "address";
|
|
132
|
+
readonly name: "hook";
|
|
133
|
+
}];
|
|
134
|
+
}];
|
|
135
|
+
export type OpenStep = "createJob" | "configure" | "setBudget" | "approve" | "fund";
|
|
136
|
+
/** One transaction for the client's wallet: send `data` to `to` with no value. */
|
|
137
|
+
export interface UnsignedTx {
|
|
138
|
+
step: OpenStep;
|
|
139
|
+
to: Address;
|
|
140
|
+
data: Hex;
|
|
141
|
+
value: "0";
|
|
142
|
+
}
|
|
143
|
+
export interface PrepareTaskInput {
|
|
144
|
+
/** The task document (untrusted: it is validated here). */
|
|
145
|
+
task: unknown;
|
|
146
|
+
/** Where anyone can fetch the task (https or ipfs); goes into the on-chain description. */
|
|
147
|
+
taskUri: string;
|
|
148
|
+
/** The wallet that signs and pays: the job's client. */
|
|
149
|
+
client: Address;
|
|
150
|
+
provider: Address;
|
|
151
|
+
/** Staked validators, as many as the task's committee_size. */
|
|
152
|
+
committee: Address[];
|
|
153
|
+
/** The escrow and evaluator for the task's payment token. */
|
|
154
|
+
deployment: TaskDeployment;
|
|
155
|
+
/** Chain time in seconds (latest block). */
|
|
156
|
+
now: bigint;
|
|
157
|
+
/** The policy the task names; the built-in policies are used when it is omitted. */
|
|
158
|
+
policy?: Policy;
|
|
159
|
+
providerAgentId?: bigint;
|
|
160
|
+
}
|
|
161
|
+
export interface PreparedTask {
|
|
162
|
+
task: Task;
|
|
163
|
+
taskHash: Hex;
|
|
164
|
+
policy: Policy;
|
|
165
|
+
terms: OnchainTerms;
|
|
166
|
+
deployment: TaskDeployment;
|
|
167
|
+
/** Step 1. */
|
|
168
|
+
create: UnsignedTx;
|
|
169
|
+
}
|
|
170
|
+
/**
|
|
171
|
+
* Validates the task, checks it against its policy and against the deployment's arbiter, and
|
|
172
|
+
* returns the terms and the createJob transaction. Throws TaskError or PolicyError.
|
|
173
|
+
*/
|
|
174
|
+
export declare function prepareTask(input: PrepareTaskInput): PreparedTask;
|
|
175
|
+
/** Step 2, once createJob is mined and its JobCreated event gave `jobId`. */
|
|
176
|
+
export declare function fundingTransactions(prepared: PreparedTask, jobId: bigint): UnsignedTx[];
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
// Turns an arl-task/1 task into the unsigned transactions that open it on chain, for the client's
|
|
2
|
+
// own wallet to sign (SDK openTask, the MCP server, AgentKit). Pure: no chain access, no keys.
|
|
3
|
+
//
|
|
4
|
+
// 1. createJob on the jobs escrow (the job id comes from its JobCreated event), then
|
|
5
|
+
// 2. configure on the evaluator, setBudget, approve the escrow for the budget, and fund.
|
|
6
|
+
//
|
|
7
|
+
// The provider then approves the committee (approveCommittee) and the members accept.
|
|
8
|
+
import { encodeFunctionData, parseAbi } from "viem";
|
|
9
|
+
import { builtinPolicy } from "./policies.js";
|
|
10
|
+
import { checkTaskAgainstPolicy } from "./policy.js";
|
|
11
|
+
import { TaskError, onchainTerms, parseTask, taskHash, } from "./task.js";
|
|
12
|
+
export const openTaskAbi = parseAbi([
|
|
13
|
+
"function createJob(address provider, address evaluator, uint256 expiredAt, string description, address hook) returns (uint256)",
|
|
14
|
+
"function setBudget(uint256 jobId, uint256 amount, bytes optParams)",
|
|
15
|
+
"function fund(uint256 jobId, uint256 expectedBudget, bytes optParams)",
|
|
16
|
+
"function approve(address spender, uint256 amount) returns (bool)",
|
|
17
|
+
"struct Config { uint8 tier; uint8 threshold; uint64 voteWindow; uint64 challengeWindow; uint96 bond; uint256 providerAgentId; bytes32 specHash; address[] committee; }",
|
|
18
|
+
"function configure(uint256 jobId, Config cfg)",
|
|
19
|
+
"event JobCreated(uint256 indexed jobId, address indexed client, address indexed provider, address evaluator, uint256 expiredAt, address hook)",
|
|
20
|
+
]);
|
|
21
|
+
const same = (a, b) => a.toLowerCase() === b.toLowerCase();
|
|
22
|
+
/**
|
|
23
|
+
* Validates the task, checks it against its policy and against the deployment's arbiter, and
|
|
24
|
+
* returns the terms and the createJob transaction. Throws TaskError or PolicyError.
|
|
25
|
+
*/
|
|
26
|
+
export function prepareTask(input) {
|
|
27
|
+
const task = parseTask(input.task);
|
|
28
|
+
const policy = input.policy ?? builtinPolicy(task.verification.policy);
|
|
29
|
+
if (!policy) {
|
|
30
|
+
throw new TaskError(`unknown policy ${task.verification.policy}: pass the policy document`);
|
|
31
|
+
}
|
|
32
|
+
checkTaskAgainstPolicy(task, policy);
|
|
33
|
+
const d = input.deployment;
|
|
34
|
+
// ARLVerifiedEvaluator refuses these (ConflictOfInterest); checking first avoids a created job
|
|
35
|
+
// that can never be configured.
|
|
36
|
+
const arbiter = d.arbiter;
|
|
37
|
+
if (same(input.client, arbiter) || same(input.provider, arbiter)) {
|
|
38
|
+
throw new TaskError("the arbiter cannot be the client or the provider");
|
|
39
|
+
}
|
|
40
|
+
if (input.committee.some((m) => same(m, arbiter))) {
|
|
41
|
+
throw new TaskError("the arbiter cannot be a committee member");
|
|
42
|
+
}
|
|
43
|
+
if (same(input.client, input.provider))
|
|
44
|
+
throw new TaskError("the client cannot be the provider");
|
|
45
|
+
const terms = onchainTerms(task, {
|
|
46
|
+
client: input.client,
|
|
47
|
+
provider: input.provider,
|
|
48
|
+
evaluator: d.evaluator,
|
|
49
|
+
committee: input.committee,
|
|
50
|
+
taskUri: input.taskUri,
|
|
51
|
+
now: input.now,
|
|
52
|
+
...(input.providerAgentId === undefined ? {} : { providerAgentId: input.providerAgentId }),
|
|
53
|
+
});
|
|
54
|
+
const c = terms.createJob;
|
|
55
|
+
return {
|
|
56
|
+
task,
|
|
57
|
+
taskHash: taskHash(task),
|
|
58
|
+
policy,
|
|
59
|
+
terms,
|
|
60
|
+
deployment: d,
|
|
61
|
+
create: {
|
|
62
|
+
step: "createJob",
|
|
63
|
+
to: d.jobs,
|
|
64
|
+
data: encodeFunctionData({
|
|
65
|
+
abi: openTaskAbi,
|
|
66
|
+
functionName: "createJob",
|
|
67
|
+
args: [c.provider, c.evaluator, c.expiredAt, c.description, c.hook],
|
|
68
|
+
}),
|
|
69
|
+
value: "0",
|
|
70
|
+
},
|
|
71
|
+
};
|
|
72
|
+
}
|
|
73
|
+
/** Step 2, once createJob is mined and its JobCreated event gave `jobId`. */
|
|
74
|
+
export function fundingTransactions(prepared, jobId) {
|
|
75
|
+
const { terms, deployment: d } = prepared;
|
|
76
|
+
const tx = (step, to, data) => ({
|
|
77
|
+
step,
|
|
78
|
+
to,
|
|
79
|
+
data,
|
|
80
|
+
value: "0",
|
|
81
|
+
});
|
|
82
|
+
return [
|
|
83
|
+
tx("configure", d.evaluator, encodeFunctionData({
|
|
84
|
+
abi: openTaskAbi,
|
|
85
|
+
functionName: "configure",
|
|
86
|
+
args: [jobId, terms.configure],
|
|
87
|
+
})),
|
|
88
|
+
tx("setBudget", d.jobs, encodeFunctionData({
|
|
89
|
+
abi: openTaskAbi,
|
|
90
|
+
functionName: "setBudget",
|
|
91
|
+
args: [jobId, terms.budget, "0x"],
|
|
92
|
+
})),
|
|
93
|
+
tx("approve", d.token, encodeFunctionData({
|
|
94
|
+
abi: openTaskAbi,
|
|
95
|
+
functionName: "approve",
|
|
96
|
+
args: [d.jobs, terms.budget],
|
|
97
|
+
})),
|
|
98
|
+
tx("fund", d.jobs, encodeFunctionData({
|
|
99
|
+
abi: openTaskAbi,
|
|
100
|
+
functionName: "fund",
|
|
101
|
+
args: [jobId, terms.budget, "0x"],
|
|
102
|
+
})),
|
|
103
|
+
];
|
|
104
|
+
}
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
import type { Address, Hex } from "viem";
|
|
2
|
+
import { type EvidenceKind, type Task } from "./task.ts";
|
|
3
|
+
export declare const PROOF_VERSION = "arl-proof/1";
|
|
4
|
+
export declare const REEXEC_RESULT_VERSION = "arl-reexec-result/1";
|
|
5
|
+
export interface ContentRef {
|
|
6
|
+
/** Where the content lives: https:// or ipfs://. */
|
|
7
|
+
uri: string;
|
|
8
|
+
/** SHA-256 of the content bytes, lowercase hex (no prefix). */
|
|
9
|
+
sha256: string;
|
|
10
|
+
media_type: string;
|
|
11
|
+
bytes: number;
|
|
12
|
+
}
|
|
13
|
+
export interface ModelRef {
|
|
14
|
+
/** Model name as published, for example an open Nemotron checkpoint. */
|
|
15
|
+
name: string;
|
|
16
|
+
/** SHA-256 of the weights archive the verdict was produced with, lowercase hex. */
|
|
17
|
+
weights_sha256: string;
|
|
18
|
+
/** Inference runtime and version, for example "vllm/0.x". */
|
|
19
|
+
runtime: string;
|
|
20
|
+
}
|
|
21
|
+
export interface EvidenceItem {
|
|
22
|
+
kind: EvidenceKind;
|
|
23
|
+
uri: string;
|
|
24
|
+
sha256: string;
|
|
25
|
+
media_type: string;
|
|
26
|
+
/** Required for model-verdict evidence. */
|
|
27
|
+
model?: ModelRef;
|
|
28
|
+
}
|
|
29
|
+
/** arl-reexec-result/1, as produced by `arl-verifier run` (packages/verifier/src/result.ts). */
|
|
30
|
+
export interface ReexecResult {
|
|
31
|
+
version: typeof REEXEC_RESULT_VERSION;
|
|
32
|
+
spec_hash: Hex;
|
|
33
|
+
exit_code: number | null;
|
|
34
|
+
timed_out: boolean;
|
|
35
|
+
outputs: {
|
|
36
|
+
path: string;
|
|
37
|
+
sha256: string | null;
|
|
38
|
+
}[];
|
|
39
|
+
}
|
|
40
|
+
export interface Proof {
|
|
41
|
+
version: typeof PROOF_VERSION;
|
|
42
|
+
task_hash: Hex;
|
|
43
|
+
chain_id: number;
|
|
44
|
+
jobs: Address;
|
|
45
|
+
/** ARLJobs job id, decimal string. */
|
|
46
|
+
job_id: string;
|
|
47
|
+
deliverable: ContentRef;
|
|
48
|
+
/** Required for reexec tasks; its hash is the on-chain deliverable. */
|
|
49
|
+
result_manifest?: ReexecResult;
|
|
50
|
+
evidence: EvidenceItem[];
|
|
51
|
+
}
|
|
52
|
+
export declare class ProofError extends Error {
|
|
53
|
+
name: string;
|
|
54
|
+
}
|
|
55
|
+
/** Validates an untrusted proof document and returns it typed. Unknown fields are refused. */
|
|
56
|
+
export declare function parseProof(raw: unknown): Proof;
|
|
57
|
+
/** keccak256 of the canonical proof. */
|
|
58
|
+
export declare function proofHash(proof: Proof): Hex;
|
|
59
|
+
/**
|
|
60
|
+
* The bytes32 the provider passes to `ARLJobs.submit`: for a reexec task the hash of the
|
|
61
|
+
* arl-reexec-result/1 manifest (what `arl-verifier` recomputes, unchanged), otherwise the proof
|
|
62
|
+
* hash.
|
|
63
|
+
*/
|
|
64
|
+
export declare function submittedDeliverable(proof: Proof): Hex;
|
|
65
|
+
/**
|
|
66
|
+
* Structural checks of a proof against its task (no network, no chain): the hashes bind, the
|
|
67
|
+
* required evidence is present, the deliverable fits. Passing this is the precondition for
|
|
68
|
+
* verification, not verification itself.
|
|
69
|
+
*/
|
|
70
|
+
export declare function checkProofAgainstTask(task: Task, proof: Proof): void;
|