arl-protocol-sdk 0.1.0 → 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 +22 -2
- package/package.json +5 -5
- 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/{index.d.ts → sdk/src/index.d.ts} +2 -0
- package/{index.js → sdk/src/index.js} +3 -0
- package/{jobs.d.ts → sdk/src/jobs.d.ts} +2 -2
- package/{jobs.js → sdk/src/jobs.js} +7 -2
- package/sdk/src/openTask.d.ts +23 -0
- package/sdk/src/openTask.js +116 -0
- package/{verified.d.ts → sdk/src/verified.d.ts} +6 -2
- package/{verified.js → sdk/src/verified.js} +3 -3
- /package/{abi.d.ts → sdk/src/abi.d.ts} +0 -0
- /package/{abi.js → sdk/src/abi.js} +0 -0
- /package/{acquireArl.d.ts → sdk/src/acquireArl.d.ts} +0 -0
- /package/{acquireArl.js → sdk/src/acquireArl.js} +0 -0
- /package/{escrowProvider.d.ts → sdk/src/escrowProvider.d.ts} +0 -0
- /package/{escrowProvider.js → sdk/src/escrowProvider.js} +0 -0
- /package/{payVerified.d.ts → sdk/src/payVerified.d.ts} +0 -0
- /package/{payVerified.js → sdk/src/payVerified.js} +0 -0
- /package/{streaming.d.ts → sdk/src/streaming.d.ts} +0 -0
- /package/{streaming.js → sdk/src/streaming.js} +0 -0
package/README.md
CHANGED
|
@@ -35,6 +35,26 @@ await settleJob(clients, ESCROWS.ARL, BigInt(jobId), "complete", "checked"); //
|
|
|
35
35
|
`ESCROWS.USDC` does the same in USDC. `settleJob(…, "reject")` refunds the client, and after the
|
|
36
36
|
deadline `settleJob(…, "claimRefund")` returns an unfinished job's escrow. `getJob` reads a job.
|
|
37
37
|
|
|
38
|
+
## Open a verified task (arl-task/1)
|
|
39
|
+
|
|
40
|
+
An [`arl-task/1`](https://github.com/armanalabsai/arlcoin.io/tree/main/spec/arl-task/v0.1.0)
|
|
41
|
+
document says what the work is, how it is accepted, paid and checked. `openTask` validates it,
|
|
42
|
+
checks it against its verification policy, and only then creates, configures and funds the job:
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
import { openTask } from "arl-protocol-sdk";
|
|
46
|
+
|
|
47
|
+
const { jobId, taskHash } = await openTask(clients, task, {
|
|
48
|
+
taskUri: "https://example.com/task.json", // where validators fetch the task
|
|
49
|
+
provider: "0xProviderAddress",
|
|
50
|
+
committee: ["0xValidator1", "0xValidator2", "0xValidator3"],
|
|
51
|
+
});
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
A task that fails validation sends no transaction. `prepareTask` and `fundingTransactions` return
|
|
55
|
+
the same calls unsigned, for wallets that sign elsewhere. `parseTask`, `taskHash`,
|
|
56
|
+
`checkTaskAgainstPolicy` and the other protocol functions are exported too.
|
|
57
|
+
|
|
38
58
|
## Also in the SDK
|
|
39
59
|
|
|
40
60
|
| Function | What it does |
|
|
@@ -49,8 +69,8 @@ deadline `settleJob(…, "claimRefund")` returns an unfinished job's escrow. `ge
|
|
|
49
69
|
| Contract | Address |
|
|
50
70
|
| ------------------ | -------------------------------------------- |
|
|
51
71
|
| ARL token | `0xde91E6f39D50bBd875f831dcc1134A3D7f3aaDb4` |
|
|
52
|
-
| Jobs escrow (ARL) | `
|
|
53
|
-
| Jobs escrow (USDC) | `
|
|
72
|
+
| Jobs escrow (ARL) | `0x9aE99bF9a59aF47E81346B7c0b93Cd2B610455fC` |
|
|
73
|
+
| Jobs escrow (USDC) | `0xE3eA0EAEc3Cf9DA2d0856A0f784A4B1671AeFD04` |
|
|
54
74
|
| Compute payment | `0x1bFE932896fdd32175836a7364dcaf53d49EE464` |
|
|
55
75
|
|
|
56
76
|
Use a dedicated wallet that holds only what your app needs. No-code? Use the n8n node
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "arl-protocol-sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
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",
|
|
@@ -20,12 +20,12 @@
|
|
|
20
20
|
"directory": "packages/sdk"
|
|
21
21
|
},
|
|
22
22
|
"type": "module",
|
|
23
|
-
"main": "./index.js",
|
|
24
|
-
"types": "./index.d.ts",
|
|
23
|
+
"main": "./sdk/src/index.js",
|
|
24
|
+
"types": "./sdk/src/index.d.ts",
|
|
25
25
|
"exports": {
|
|
26
26
|
".": {
|
|
27
|
-
"types": "./index.d.ts",
|
|
28
|
-
"default": "./index.js"
|
|
27
|
+
"types": "./sdk/src/index.d.ts",
|
|
28
|
+
"default": "./sdk/src/index.js"
|
|
29
29
|
}
|
|
30
30
|
},
|
|
31
31
|
"dependencies": {
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import { type Hex } from "viem";
|
|
2
|
+
export declare class CanonicalError extends Error {
|
|
3
|
+
name: string;
|
|
4
|
+
}
|
|
5
|
+
export declare function canonicalize(value: unknown): string;
|
|
6
|
+
/** keccak256 of the UTF-8 bytes of the canonical JSON. */
|
|
7
|
+
export declare function canonicalHash(value: unknown): Hex;
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
// Canonical JSON for hashing ARL protocol documents (arl-task/1 and later specs). The same rules as
|
|
2
|
+
// `@arl/verifier` (canonical.ts) so a document hashes identically everywhere: object keys sorted
|
|
3
|
+
// by UTF-16 code units, no whitespace, strings escaped as ECMAScript JSON.stringify does, safe
|
|
4
|
+
// integers only. Anything else is refused rather than silently normalized.
|
|
5
|
+
import { keccak256, stringToBytes } from "viem";
|
|
6
|
+
export class CanonicalError extends Error {
|
|
7
|
+
name = "CanonicalError";
|
|
8
|
+
}
|
|
9
|
+
export function canonicalize(value) {
|
|
10
|
+
if (value === null || typeof value === "boolean")
|
|
11
|
+
return JSON.stringify(value);
|
|
12
|
+
if (typeof value === "string")
|
|
13
|
+
return JSON.stringify(value);
|
|
14
|
+
if (typeof value === "number") {
|
|
15
|
+
if (!Number.isSafeInteger(value))
|
|
16
|
+
throw new CanonicalError(`not a safe integer: ${value}`);
|
|
17
|
+
return JSON.stringify(value);
|
|
18
|
+
}
|
|
19
|
+
if (Array.isArray(value))
|
|
20
|
+
return `[${value.map(canonicalize).join(",")}]`;
|
|
21
|
+
if (typeof value === "object") {
|
|
22
|
+
const proto = Object.getPrototypeOf(value);
|
|
23
|
+
if (proto !== Object.prototype && proto !== null) {
|
|
24
|
+
throw new CanonicalError("only plain objects can be canonicalized");
|
|
25
|
+
}
|
|
26
|
+
const entries = Object.entries(value).filter(([, v]) => v !== undefined);
|
|
27
|
+
entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
|
|
28
|
+
return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalize(v)}`).join(",")}}`;
|
|
29
|
+
}
|
|
30
|
+
throw new CanonicalError(`cannot canonicalize a ${typeof value}`);
|
|
31
|
+
}
|
|
32
|
+
/** keccak256 of the UTF-8 bytes of the canonical JSON. */
|
|
33
|
+
export function canonicalHash(value) {
|
|
34
|
+
return keccak256(stringToBytes(canonicalize(value)));
|
|
35
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import type { Address } from "viem";
|
|
2
|
+
import type { Token } from "./task.ts";
|
|
3
|
+
export interface TaskDeployment {
|
|
4
|
+
chainId: number;
|
|
5
|
+
/** The token the escrow is paid in. */
|
|
6
|
+
token: Address;
|
|
7
|
+
/** ARLJobs paid in `token`. */
|
|
8
|
+
jobs: Address;
|
|
9
|
+
/** ARLVerifiedEvaluator bound to `jobs`. */
|
|
10
|
+
evaluator: Address;
|
|
11
|
+
/** The evaluator's arbiter (the Arbiter Safe); it may not be client, provider or member. */
|
|
12
|
+
arbiter: Address;
|
|
13
|
+
}
|
|
14
|
+
/** Base Mainnet: escrows v2 (nonces 22 and 23) and evaluators v4 (nonces 29 and 30). */
|
|
15
|
+
export declare const BASE_MAINNET_TASK_DEPLOYMENTS: Record<Token, TaskDeployment>;
|
|
16
|
+
/** The deployment a task paid in `token` uses on `chainId`, or undefined (local chains). */
|
|
17
|
+
export declare function taskDeployment(chainId: number, token: Token): TaskDeployment | undefined;
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
// Where an arl-task/1 task is opened: the jobs escrow and verified evaluator for each payment token
|
|
2
|
+
// on Base Mainnet (docs/mainnet-services.md). One place to change when the escrows are redeployed.
|
|
3
|
+
const ARBITER_SAFE = "0x8FF6c3aD0991Ac848BFf5d0acD78BBc5e190466f";
|
|
4
|
+
/** Base Mainnet: escrows v2 (nonces 22 and 23) and evaluators v4 (nonces 29 and 30). */
|
|
5
|
+
export const BASE_MAINNET_TASK_DEPLOYMENTS = {
|
|
6
|
+
ARL: {
|
|
7
|
+
chainId: 8453,
|
|
8
|
+
token: "0xde91E6f39D50bBd875f831dcc1134A3D7f3aaDb4",
|
|
9
|
+
jobs: "0x9aE99bF9a59aF47E81346B7c0b93Cd2B610455fC",
|
|
10
|
+
evaluator: "0x6648e141cb7473822ddBd8bC039b91e5af3259B4",
|
|
11
|
+
arbiter: ARBITER_SAFE,
|
|
12
|
+
},
|
|
13
|
+
USDC: {
|
|
14
|
+
chainId: 8453,
|
|
15
|
+
token: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
|
|
16
|
+
jobs: "0xE3eA0EAEc3Cf9DA2d0856A0f784A4B1671AeFD04",
|
|
17
|
+
evaluator: "0x6bFfdEace7d0B2F7711f604F0A5D2545be2961AF",
|
|
18
|
+
arbiter: ARBITER_SAFE,
|
|
19
|
+
},
|
|
20
|
+
};
|
|
21
|
+
/** The deployment a task paid in `token` uses on `chainId`, or undefined (local chains). */
|
|
22
|
+
export function taskDeployment(chainId, token) {
|
|
23
|
+
return chainId === 8453 ? BASE_MAINNET_TASK_DEPLOYMENTS[token] : undefined;
|
|
24
|
+
}
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
import type { Address, Hex } from "viem";
|
|
2
|
+
export declare const EVIDENCE_VERSION = "arl-evidence/2";
|
|
3
|
+
interface EventRef {
|
|
4
|
+
block: string;
|
|
5
|
+
tx: Hex;
|
|
6
|
+
}
|
|
7
|
+
/** arl-evidence/1, as produced by `arl-verifier bundle` (packages/verifier/src/bundle.ts). */
|
|
8
|
+
export interface SettlementRecord {
|
|
9
|
+
version: "arl-evidence/1";
|
|
10
|
+
chainId: number;
|
|
11
|
+
jobs: Address;
|
|
12
|
+
evaluator: Address;
|
|
13
|
+
jobId: string;
|
|
14
|
+
job: {
|
|
15
|
+
client: Address;
|
|
16
|
+
provider: Address;
|
|
17
|
+
budget: string;
|
|
18
|
+
status: number;
|
|
19
|
+
description: string;
|
|
20
|
+
};
|
|
21
|
+
config: {
|
|
22
|
+
tier: number;
|
|
23
|
+
threshold: number;
|
|
24
|
+
specHash: Hex;
|
|
25
|
+
committee: Address[];
|
|
26
|
+
};
|
|
27
|
+
submitted: (EventRef & {
|
|
28
|
+
deliverable: Hex;
|
|
29
|
+
}) | null;
|
|
30
|
+
votes: (EventRef & {
|
|
31
|
+
validator: Address;
|
|
32
|
+
approve: boolean;
|
|
33
|
+
deliverable: Hex;
|
|
34
|
+
evidence: Hex;
|
|
35
|
+
})[];
|
|
36
|
+
decided: (EventRef & {
|
|
37
|
+
approved: boolean;
|
|
38
|
+
}) | null;
|
|
39
|
+
finalized: (EventRef & {
|
|
40
|
+
approved: boolean;
|
|
41
|
+
voteHash: Hex;
|
|
42
|
+
}) | null;
|
|
43
|
+
settlement: (EventRef & {
|
|
44
|
+
outcome: "completed" | "rejected";
|
|
45
|
+
}) | null;
|
|
46
|
+
}
|
|
47
|
+
export interface EvidenceV2 {
|
|
48
|
+
version: typeof EVIDENCE_VERSION;
|
|
49
|
+
settlement: SettlementRecord;
|
|
50
|
+
task: unknown;
|
|
51
|
+
proof: unknown;
|
|
52
|
+
policy: unknown;
|
|
53
|
+
/** keccak256 of the canonical policy, so a reader can pin the exact policy text. */
|
|
54
|
+
policy_hash: Hex;
|
|
55
|
+
}
|
|
56
|
+
export declare class EvidenceError extends Error {
|
|
57
|
+
name: string;
|
|
58
|
+
}
|
|
59
|
+
export interface EvidenceResult {
|
|
60
|
+
outcome: "completed" | "rejected" | "pending";
|
|
61
|
+
approvals: number;
|
|
62
|
+
rejections: number;
|
|
63
|
+
/** The settlement differs from the committee's decision (a dispute was ruled). */
|
|
64
|
+
overturned: boolean;
|
|
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
|
+
export declare function checkEvidence(raw: EvidenceV2): EvidenceResult;
|
|
72
|
+
export {};
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
// arl-evidence/2: a portable, independently verifiable package for one task (spec/arl-evidence/
|
|
2
|
+
// v0.2.0). It wraps the on-chain settlement record of arl-evidence/1 (built and re-checked
|
|
3
|
+
// against any RPC by `arl-verifier bundle` / `verify-bundle`) together with the documents that
|
|
4
|
+
// give it meaning: the arl-task/1 task, the arl-proof/1 proof and the arl-policy/1 policy.
|
|
5
|
+
// `checkEvidence` checks, offline, that all four agree with each other.
|
|
6
|
+
import { parsePolicy, policyHash, checkTaskAgainstPolicy, POLICY_VERSION } from "./policy.js";
|
|
7
|
+
import { checkProofAgainstTask, parseProof, submittedDeliverable } from "./proof.js";
|
|
8
|
+
import { committedSpecHash, parseTask, taskHash } from "./task.js";
|
|
9
|
+
export const EVIDENCE_VERSION = "arl-evidence/2";
|
|
10
|
+
export class EvidenceError extends Error {
|
|
11
|
+
name = "EvidenceError";
|
|
12
|
+
}
|
|
13
|
+
const TIER_INDEX = { fallback: 0, reexecution: 1, attested: 2 };
|
|
14
|
+
/**
|
|
15
|
+
* Checks that the settlement record, task, proof and policy describe the same job and agree.
|
|
16
|
+
* Throws EvidenceError (or the document's own error) on the first inconsistency. It does not
|
|
17
|
+
* re-read the chain: run `arl-verifier verify-bundle` on `settlement` for that.
|
|
18
|
+
*/
|
|
19
|
+
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
|
+
throw new EvidenceError("version must be arl-evidence/2");
|
|
24
|
+
if (versions.settlement.version !== "arl-evidence/1") {
|
|
25
|
+
throw new EvidenceError("settlement must be arl-evidence/1");
|
|
26
|
+
}
|
|
27
|
+
const s = raw.settlement;
|
|
28
|
+
const task = parseTask(raw.task);
|
|
29
|
+
const proof = parseProof(raw.proof);
|
|
30
|
+
const policy = parsePolicy(raw.policy);
|
|
31
|
+
if (policyHash(policy) !== raw.policy_hash)
|
|
32
|
+
throw new EvidenceError("policy_hash does not match the policy");
|
|
33
|
+
if (task.verification.policy !== `${POLICY_VERSION}:${policy.id}`) {
|
|
34
|
+
throw new EvidenceError("the task names another policy");
|
|
35
|
+
}
|
|
36
|
+
checkTaskAgainstPolicy(task, policy);
|
|
37
|
+
checkProofAgainstTask(task, proof);
|
|
38
|
+
// The proof names this job.
|
|
39
|
+
if (proof.chain_id !== s.chainId)
|
|
40
|
+
throw new EvidenceError("proof chain differs from the settlement");
|
|
41
|
+
if (proof.jobs.toLowerCase() !== s.jobs.toLowerCase())
|
|
42
|
+
throw new EvidenceError("proof escrow differs");
|
|
43
|
+
if (proof.job_id !== s.jobId)
|
|
44
|
+
throw new EvidenceError("proof job id differs");
|
|
45
|
+
// The job on chain was opened for this task.
|
|
46
|
+
const th = taskHash(task);
|
|
47
|
+
if (!s.job.description.startsWith(`arl-task:${th} `)) {
|
|
48
|
+
throw new EvidenceError("the on-chain description does not name this task");
|
|
49
|
+
}
|
|
50
|
+
if (s.job.budget !== task.payment.budget)
|
|
51
|
+
throw new EvidenceError("on-chain budget differs from the task");
|
|
52
|
+
if (s.config.specHash !== committedSpecHash(task)) {
|
|
53
|
+
throw new EvidenceError("on-chain specHash differs from the task's committed spec hash");
|
|
54
|
+
}
|
|
55
|
+
if (s.config.tier !== TIER_INDEX[task.verification.tier])
|
|
56
|
+
throw new EvidenceError("on-chain tier differs");
|
|
57
|
+
if (s.config.threshold !== task.verification.threshold)
|
|
58
|
+
throw new EvidenceError("on-chain threshold differs");
|
|
59
|
+
if (s.config.committee.length !== task.verification.committee_size) {
|
|
60
|
+
throw new EvidenceError("on-chain committee size differs");
|
|
61
|
+
}
|
|
62
|
+
// The submitted deliverable is this proof's.
|
|
63
|
+
const deliverable = submittedDeliverable(proof);
|
|
64
|
+
if (s.submitted === null)
|
|
65
|
+
throw new EvidenceError("nothing was submitted for this job");
|
|
66
|
+
if (s.submitted.deliverable !== deliverable) {
|
|
67
|
+
throw new EvidenceError("the submitted deliverable is not this proof's");
|
|
68
|
+
}
|
|
69
|
+
// Votes: committee members only, once each; approvals name the submitted deliverable.
|
|
70
|
+
const committee = new Set(s.config.committee.map((a) => a.toLowerCase()));
|
|
71
|
+
const voted = new Set();
|
|
72
|
+
let approvals = 0;
|
|
73
|
+
let rejections = 0;
|
|
74
|
+
for (const v of s.votes) {
|
|
75
|
+
const who = v.validator.toLowerCase();
|
|
76
|
+
if (!committee.has(who))
|
|
77
|
+
throw new EvidenceError(`vote from outside the committee: ${v.validator}`);
|
|
78
|
+
if (voted.has(who))
|
|
79
|
+
throw new EvidenceError(`double vote: ${v.validator}`);
|
|
80
|
+
voted.add(who);
|
|
81
|
+
if (v.approve) {
|
|
82
|
+
if (v.deliverable !== deliverable)
|
|
83
|
+
throw new EvidenceError("an approval names another deliverable");
|
|
84
|
+
approvals += 1;
|
|
85
|
+
}
|
|
86
|
+
else
|
|
87
|
+
rejections += 1;
|
|
88
|
+
}
|
|
89
|
+
// A committee approval needs the threshold of approvals naming the deliverable.
|
|
90
|
+
if (s.decided?.approved === true && approvals < task.verification.threshold) {
|
|
91
|
+
throw new EvidenceError("decided approved without enough approvals");
|
|
92
|
+
}
|
|
93
|
+
if (s.settlement === null)
|
|
94
|
+
return { outcome: "pending", approvals, rejections, overturned: false };
|
|
95
|
+
// On chain a provider is paid only through the evaluator's settlement, which always follows a
|
|
96
|
+
// committee decision and emits Finalized: a "completed" record without both is not one any
|
|
97
|
+
// chain can produce.
|
|
98
|
+
if (s.settlement.outcome === "completed" && (s.decided === null || s.finalized === null)) {
|
|
99
|
+
throw new EvidenceError("a completed settlement needs a decision and a finalization");
|
|
100
|
+
}
|
|
101
|
+
if (s.finalized !== null && s.finalized.approved !== (s.settlement.outcome === "completed")) {
|
|
102
|
+
throw new EvidenceError("finalization and settlement disagree");
|
|
103
|
+
}
|
|
104
|
+
// A settlement that differs from the committee's decision can only come from a ruled dispute.
|
|
105
|
+
const overturned = s.decided !== null && s.decided.approved !== (s.settlement.outcome === "completed");
|
|
106
|
+
return { outcome: s.settlement.outcome, approvals, rejections, overturned };
|
|
107
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
export { CanonicalError, canonicalHash, canonicalize } from "./canonical.ts";
|
|
2
|
+
export { BOUNDS, EVIDENCE_KINDS, TASK_VERSION, TIERS, TOKENS, TaskError, WORKLOAD_CLASSES, committedSpecHash, jobDescription, onchainTerms, parseTask, taskHash, } from "./task.ts";
|
|
3
|
+
export type { AcceptanceRule, EvidenceKind, OnchainTerms, Payment, Task, Tier, Token, Verification, Workload, WorkloadClass, } from "./task.ts";
|
|
4
|
+
export { PROOF_VERSION, ProofError, REEXEC_RESULT_VERSION, checkProofAgainstTask, parseProof, proofHash, submittedDeliverable, } from "./proof.ts";
|
|
5
|
+
export type { ContentRef, EvidenceItem, ModelRef, Proof, ReexecResult } from "./proof.ts";
|
|
6
|
+
export { POLICY_VERSION, PolicyError, checkTaskAgainstPolicy, decideVote, effectiveBond, parsePolicy, policyHash, } from "./policy.ts";
|
|
7
|
+
export type { ModelAllowance, Policy, RuleOutcome, VoteDecision } from "./policy.ts";
|
|
8
|
+
export { DEFAULT_PARAMS, REPUTATION_VERSION, ReputationError, reputationScore, } from "./reputation.ts";
|
|
9
|
+
export type { Outcome, OutcomeKind, Score, ScoreParams } from "./reputation.ts";
|
|
10
|
+
export { EVIDENCE_VERSION, EvidenceError, checkEvidence } from "./evidence.ts";
|
|
11
|
+
export type { EvidenceResult, EvidenceV2, SettlementRecord } from "./evidence.ts";
|
|
12
|
+
export { BASE_MAINNET_TASK_DEPLOYMENTS, taskDeployment, type TaskDeployment, } from "./deployments.ts";
|
|
13
|
+
export { BUILTIN_POLICIES, builtinPolicy } from "./policies.ts";
|
|
14
|
+
export { fundingTransactions, openTaskAbi, prepareTask, type OpenStep, type PrepareTaskInput, type PreparedTask, type UnsignedTx, } from "./prepare.ts";
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
export { CanonicalError, canonicalHash, canonicalize } from "./canonical.js";
|
|
2
|
+
export { BOUNDS, EVIDENCE_KINDS, TASK_VERSION, TIERS, TOKENS, TaskError, WORKLOAD_CLASSES, committedSpecHash, jobDescription, onchainTerms, parseTask, taskHash, } from "./task.js";
|
|
3
|
+
export { PROOF_VERSION, ProofError, REEXEC_RESULT_VERSION, checkProofAgainstTask, parseProof, proofHash, submittedDeliverable, } from "./proof.js";
|
|
4
|
+
export { POLICY_VERSION, PolicyError, checkTaskAgainstPolicy, decideVote, effectiveBond, parsePolicy, policyHash, } from "./policy.js";
|
|
5
|
+
export { DEFAULT_PARAMS, REPUTATION_VERSION, ReputationError, reputationScore, } from "./reputation.js";
|
|
6
|
+
export { EVIDENCE_VERSION, EvidenceError, checkEvidence } from "./evidence.js";
|
|
7
|
+
export { BASE_MAINNET_TASK_DEPLOYMENTS, taskDeployment, } from "./deployments.js";
|
|
8
|
+
export { BUILTIN_POLICIES, builtinPolicy } from "./policies.js";
|
|
9
|
+
export { fundingTransactions, openTaskAbi, prepareTask, } from "./prepare.js";
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import { type Policy } from "./policy.ts";
|
|
2
|
+
/** The built-in policies, validated, by id. */
|
|
3
|
+
export declare const BUILTIN_POLICIES: ReadonlyMap<string, Policy>;
|
|
4
|
+
/** The built-in policy a task names (`arl-policy/1:<id>`), or undefined. */
|
|
5
|
+
export declare function builtinPolicy(ref: string): Policy | undefined;
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
// The built-in arl-policy/1 documents (spec/arl-policy/v0.1.0/policies). Kept here as data so the
|
|
2
|
+
// SDK, the read API and the MCP server carry them without reading files; a test checks that they
|
|
3
|
+
// equal the spec's JSON files.
|
|
4
|
+
import { POLICY_VERSION, parsePolicy } from "./policy.js";
|
|
5
|
+
const ARL_100 = "100000000000000000000";
|
|
6
|
+
const RAW = [
|
|
7
|
+
{
|
|
8
|
+
version: POLICY_VERSION,
|
|
9
|
+
id: "reexec-standard",
|
|
10
|
+
workload_classes: ["reexec"],
|
|
11
|
+
tiers: ["reexecution"],
|
|
12
|
+
committee: { min_size: 3, max_size: 7 },
|
|
13
|
+
vote_window_seconds: [3600, 86400],
|
|
14
|
+
challenge_window_seconds: [86400, 259200],
|
|
15
|
+
min_bond_floor: ARL_100,
|
|
16
|
+
bond_covers_budget: true,
|
|
17
|
+
required_evidence: ["result-manifest"],
|
|
18
|
+
model: { allowed: false, max_budget: {}, models: [] },
|
|
19
|
+
},
|
|
20
|
+
{
|
|
21
|
+
version: POLICY_VERSION,
|
|
22
|
+
id: "fallback-review",
|
|
23
|
+
workload_classes: ["review"],
|
|
24
|
+
tiers: ["fallback"],
|
|
25
|
+
committee: { min_size: 1, max_size: 1 },
|
|
26
|
+
vote_window_seconds: [600, 86400],
|
|
27
|
+
challenge_window_seconds: [86400, 172800],
|
|
28
|
+
min_bond_floor: ARL_100,
|
|
29
|
+
bond_covers_budget: true,
|
|
30
|
+
required_evidence: ["artifact"],
|
|
31
|
+
model: { allowed: false, max_budget: {}, models: [] },
|
|
32
|
+
},
|
|
33
|
+
{
|
|
34
|
+
version: POLICY_VERSION,
|
|
35
|
+
id: "model-assisted-review",
|
|
36
|
+
workload_classes: ["model-assisted"],
|
|
37
|
+
tiers: ["attested"],
|
|
38
|
+
committee: { min_size: 3, max_size: 7 },
|
|
39
|
+
vote_window_seconds: [3600, 172800],
|
|
40
|
+
challenge_window_seconds: [86400, 259200],
|
|
41
|
+
min_bond_floor: ARL_100,
|
|
42
|
+
bond_covers_budget: true,
|
|
43
|
+
required_evidence: ["artifact", "model-verdict"],
|
|
44
|
+
model: { allowed: true, max_budget: { ARL: ARL_100, USDC: "100000000" }, models: [] },
|
|
45
|
+
},
|
|
46
|
+
];
|
|
47
|
+
/** The built-in policies, validated, by id. */
|
|
48
|
+
export const BUILTIN_POLICIES = new Map(RAW.map((r) => {
|
|
49
|
+
const p = parsePolicy(r);
|
|
50
|
+
return [p.id, p];
|
|
51
|
+
}));
|
|
52
|
+
/** The built-in policy a task names (`arl-policy/1:<id>`), or undefined. */
|
|
53
|
+
export function builtinPolicy(ref) {
|
|
54
|
+
const prefix = `${POLICY_VERSION}:`;
|
|
55
|
+
return ref.startsWith(prefix) ? BUILTIN_POLICIES.get(ref.slice(prefix.length)) : undefined;
|
|
56
|
+
}
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
import type { Hex } from "viem";
|
|
2
|
+
import { type EvidenceKind, type Task, type Tier, type Token, type WorkloadClass } from "./task.ts";
|
|
3
|
+
export declare const POLICY_VERSION = "arl-policy/1";
|
|
4
|
+
export interface ModelAllowance {
|
|
5
|
+
/** Whether a model verdict may decide a rule (still as a validator's vote). */
|
|
6
|
+
allowed: boolean;
|
|
7
|
+
/** Highest budget, per token in base units, for which a model verdict may decide a rule. */
|
|
8
|
+
max_budget: Partial<Record<Token, string>>;
|
|
9
|
+
/** Models a validator may use: name and SHA-256 of the weights. Empty: any pinned model. */
|
|
10
|
+
models: {
|
|
11
|
+
name: string;
|
|
12
|
+
weights_sha256: string;
|
|
13
|
+
}[];
|
|
14
|
+
}
|
|
15
|
+
export interface Policy {
|
|
16
|
+
version: typeof POLICY_VERSION;
|
|
17
|
+
id: string;
|
|
18
|
+
workload_classes: WorkloadClass[];
|
|
19
|
+
tiers: Tier[];
|
|
20
|
+
committee: {
|
|
21
|
+
min_size: number;
|
|
22
|
+
max_size: number;
|
|
23
|
+
};
|
|
24
|
+
vote_window_seconds: [number, number];
|
|
25
|
+
challenge_window_seconds: [number, number];
|
|
26
|
+
/** Minimum bond floor, per token the task is paid in, in ARL base units. */
|
|
27
|
+
min_bond_floor: string;
|
|
28
|
+
/**
|
|
29
|
+
* ARL tasks only: the committee's total bond at risk (threshold × max(floor, budget / 10)) must
|
|
30
|
+
* cover the budget. USDC tasks are bonded in ARL, so the rule needs a price and is not applied.
|
|
31
|
+
*/
|
|
32
|
+
bond_covers_budget: boolean;
|
|
33
|
+
required_evidence: EvidenceKind[];
|
|
34
|
+
model: ModelAllowance;
|
|
35
|
+
}
|
|
36
|
+
export declare class PolicyError extends Error {
|
|
37
|
+
name: string;
|
|
38
|
+
}
|
|
39
|
+
/** Validates an untrusted policy document. Unknown fields are refused. */
|
|
40
|
+
export declare function parsePolicy(raw: unknown): Policy;
|
|
41
|
+
export declare function policyHash(policy: Policy): Hex;
|
|
42
|
+
/** The bond each accepted member locks: ARLVerifiedEvaluator takes max(floor, budget / 10). */
|
|
43
|
+
export declare function effectiveBond(task: Task): bigint;
|
|
44
|
+
/** Checks that a task follows the policy it names. Throws PolicyError with the first violation. */
|
|
45
|
+
export declare function checkTaskAgainstPolicy(task: Task, policy: Policy): void;
|
|
46
|
+
/** How a validator established one acceptance rule. */
|
|
47
|
+
export interface RuleOutcome {
|
|
48
|
+
id: string;
|
|
49
|
+
passed: boolean;
|
|
50
|
+
/** "check": the validator's own deterministic check or review; "model": a model verdict. */
|
|
51
|
+
by: "check" | "model";
|
|
52
|
+
/** For "model": the SHA-256 of the weights used. */
|
|
53
|
+
weights_sha256?: string;
|
|
54
|
+
}
|
|
55
|
+
export interface VoteDecision {
|
|
56
|
+
approve: boolean;
|
|
57
|
+
reason: string;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Turns a validator's outcomes into its vote. Approve only if every acceptance rule of the task
|
|
61
|
+
* has an admissible passing outcome. A model outcome is admissible only if the policy allows
|
|
62
|
+
* models, the budget is within the policy's cap for the token, and (when the policy lists models)
|
|
63
|
+
* the weights are listed. Anything missing or inadmissible is a reject, never an approve.
|
|
64
|
+
*/
|
|
65
|
+
export declare function decideVote(task: Task, policy: Policy, outcomes: RuleOutcome[]): VoteDecision;
|