arl-protocol-sdk 0.3.1 → 0.3.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 +1 -0
- package/package.json +1 -1
- package/sdk/src/index.d.ts +1 -0
- package/sdk/src/index.js +1 -0
- package/sdk/src/receipt.d.ts +58 -0
- package/sdk/src/receipt.js +157 -0
package/README.md
CHANGED
|
@@ -100,6 +100,7 @@ database or KV store. On runtimes that stop work when the response ends, pass `w
|
|
|
100
100
|
| `getJobAudit` | Every on-chain event of a verified job in order: who acted, when, with what hashes |
|
|
101
101
|
| `getAgentPassport` | An agent's ERC-8004 identity and its verified record in one answer |
|
|
102
102
|
| `getValidators` | Every validator that staked: stake, locked bonds, jobs accepted, votes and slashes |
|
|
103
|
+
| `getJobReceipt` | A finalized job's portable receipt and the unsigned EAS `attest` call that records it |
|
|
103
104
|
| `getTrustGraph` | Every agent with a verified outcome, its score, and an edge per client and agent |
|
|
104
105
|
|
|
105
106
|
## Contracts on Base Mainnet
|
package/package.json
CHANGED
package/sdk/src/index.d.ts
CHANGED
|
@@ -12,3 +12,4 @@ export { REPUTATION_REGISTRY, VERIFIED_EVALUATORS, getAgentScore, getTrustGraph,
|
|
|
12
12
|
export { getJobAudit, type AuditEntry, type AuditValue, type JobAudit } from "./audit.ts";
|
|
13
13
|
export { IDENTITY_REGISTRY, getAgentPassport, type AgentPassport } from "./passport.ts";
|
|
14
14
|
export { getValidators, type ValidatorRecord, type Validators } from "./validators.ts";
|
|
15
|
+
export { EAS, EAS_SCHEMA_REGISTRY, RECEIPT_SCHEMA, encodeReceipt, getJobReceipt, prepareReceiptAttestation, prepareReceiptSchemaRegistration, receiptFromAudit, receiptSchemaUid, type JobReceipt, type JobReceiptAnswer, type PreparedCall, } from "./receipt.ts";
|
package/sdk/src/index.js
CHANGED
|
@@ -13,3 +13,4 @@ export { REPUTATION_REGISTRY, VERIFIED_EVALUATORS, getAgentScore, getTrustGraph,
|
|
|
13
13
|
export { getJobAudit } from "./audit.js";
|
|
14
14
|
export { IDENTITY_REGISTRY, getAgentPassport } from "./passport.js";
|
|
15
15
|
export { getValidators } from "./validators.js";
|
|
16
|
+
export { EAS, EAS_SCHEMA_REGISTRY, RECEIPT_SCHEMA, encodeReceipt, getJobReceipt, prepareReceiptAttestation, prepareReceiptSchemaRegistration, receiptFromAudit, receiptSchemaUid, } from "./receipt.js";
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import { type Address, type Hex, type PublicClient } from "viem";
|
|
2
|
+
import type { HistoryOptions } from "./agentScore.ts";
|
|
3
|
+
import { type JobAudit } from "./audit.ts";
|
|
4
|
+
/** EAS and its SchemaRegistry on Base (OP Stack predeploys). */
|
|
5
|
+
export declare const EAS: Address;
|
|
6
|
+
export declare const EAS_SCHEMA_REGISTRY: Address;
|
|
7
|
+
/** The receipt's EAS schema. Field order and types are part of the schema's identity. */
|
|
8
|
+
export declare const RECEIPT_SCHEMA = "uint256 chainId,address escrow,uint256 jobId,address client,address provider,uint256 providerAgentId,bool approved,bytes32 deliverable,bytes32 specHash,bytes32 voteHash,uint64 finalizedAt";
|
|
9
|
+
/** The schema's UID: no resolver, not revocable (a settled job does not change). */
|
|
10
|
+
export declare function receiptSchemaUid(): Hex;
|
|
11
|
+
export interface JobReceipt {
|
|
12
|
+
chainId: number;
|
|
13
|
+
escrow: Address;
|
|
14
|
+
jobId: bigint;
|
|
15
|
+
client: Address;
|
|
16
|
+
provider: Address;
|
|
17
|
+
providerAgentId: bigint;
|
|
18
|
+
/** The committee's verdict as finalized: true paid the provider, false refunded the client. */
|
|
19
|
+
approved: boolean;
|
|
20
|
+
deliverable: Hex;
|
|
21
|
+
specHash: Hex;
|
|
22
|
+
voteHash: Hex;
|
|
23
|
+
/** Unix seconds of the Finalized event. */
|
|
24
|
+
finalizedAt: number;
|
|
25
|
+
}
|
|
26
|
+
/** An unsigned transaction, for the caller's own wallet. */
|
|
27
|
+
export interface PreparedCall {
|
|
28
|
+
to: Address;
|
|
29
|
+
data: Hex;
|
|
30
|
+
value: "0";
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* The receipt of a job, from its audit trail. Null while the job is not finalized, or when the
|
|
34
|
+
* trail lacks an event the receipt needs (it is then not a job of the verified evaluator).
|
|
35
|
+
*/
|
|
36
|
+
export declare function receiptFromAudit(audit: JobAudit, chainId?: number): JobReceipt | null;
|
|
37
|
+
/** The receipt as EAS attestation data, in the schema's field order. */
|
|
38
|
+
export declare function encodeReceipt(r: JobReceipt): Hex;
|
|
39
|
+
/** The unsigned EAS `attest` call for a receipt: recipient is the provider, never expires. */
|
|
40
|
+
export declare function prepareReceiptAttestation(r: JobReceipt): PreparedCall;
|
|
41
|
+
/** The unsigned call that registers the receipt schema; needed once, by anyone. */
|
|
42
|
+
export declare function prepareReceiptSchemaRegistration(): PreparedCall;
|
|
43
|
+
export interface JobReceiptAnswer {
|
|
44
|
+
/** The block the job was read at. */
|
|
45
|
+
block: bigint;
|
|
46
|
+
/** Null while the job is not finalized. */
|
|
47
|
+
receipt: JobReceipt | null;
|
|
48
|
+
schema: string;
|
|
49
|
+
schemaUid: Hex;
|
|
50
|
+
/** Whether the schema is registered on EAS yet; an attestation needs it. */
|
|
51
|
+
schemaRegistered: boolean;
|
|
52
|
+
/** The unsigned `attest` call, when there is a receipt. */
|
|
53
|
+
attest?: PreparedCall;
|
|
54
|
+
/** The unsigned `register` call, while the schema is not registered. */
|
|
55
|
+
registerSchema?: PreparedCall;
|
|
56
|
+
}
|
|
57
|
+
/** Reads a job's receipt and prepares the calls that put it on EAS. */
|
|
58
|
+
export declare function getJobReceipt(client: PublicClient, token: "ARL" | "USDC", jobId: bigint, opts?: HistoryOptions): Promise<JobReceiptAnswer>;
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
// A portable receipt for a finalized verified job, as an Ethereum Attestation Service (EAS)
|
|
2
|
+
// attestation on Base. The receipt restates what the escrow and the evaluator already recorded
|
|
3
|
+
// (who, what was delivered, what the committee decided), in one record another platform can read
|
|
4
|
+
// without knowing ARL's contracts.
|
|
5
|
+
//
|
|
6
|
+
// Nothing here signs or sends. The SDK builds the receipt from the job's audit trail and prepares
|
|
7
|
+
// the unsigned `attest` transaction; whoever wants the receipt on EAS (usually the provider, whose
|
|
8
|
+
// record it is) sends it from their own wallet. A receipt is only as true as the job it names:
|
|
9
|
+
// anyone can check it against the audit trail, and this module's `receiptFromAudit` is that check.
|
|
10
|
+
import { encodeAbiParameters, encodeFunctionData, encodePacked, keccak256, parseAbi, } from "viem";
|
|
11
|
+
import { getJobAudit } from "./audit.js";
|
|
12
|
+
/** EAS and its SchemaRegistry on Base (OP Stack predeploys). */
|
|
13
|
+
export const EAS = "0x4200000000000000000000000000000000000021";
|
|
14
|
+
export const EAS_SCHEMA_REGISTRY = "0x4200000000000000000000000000000000000020";
|
|
15
|
+
/** The receipt's EAS schema. Field order and types are part of the schema's identity. */
|
|
16
|
+
export const RECEIPT_SCHEMA = "uint256 chainId,address escrow,uint256 jobId,address client,address provider,uint256 providerAgentId,bool approved,bytes32 deliverable,bytes32 specHash,bytes32 voteHash,uint64 finalizedAt";
|
|
17
|
+
const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
|
|
18
|
+
const ZERO_BYTES32 = `0x${"00".repeat(32)}`;
|
|
19
|
+
const easAbi = parseAbi([
|
|
20
|
+
"struct AttestationRequestData { address recipient; uint64 expirationTime; bool revocable; bytes32 refUID; bytes data; uint256 value; }",
|
|
21
|
+
"struct AttestationRequest { bytes32 schema; AttestationRequestData data; }",
|
|
22
|
+
"function attest(AttestationRequest request) payable returns (bytes32)",
|
|
23
|
+
]);
|
|
24
|
+
const registryAbi = parseAbi([
|
|
25
|
+
"struct SchemaRecord { bytes32 uid; address resolver; bool revocable; string schema; }",
|
|
26
|
+
"function register(string schema, address resolver, bool revocable) returns (bytes32)",
|
|
27
|
+
"function getSchema(bytes32 uid) view returns (SchemaRecord)",
|
|
28
|
+
]);
|
|
29
|
+
/** The schema's UID: no resolver, not revocable (a settled job does not change). */
|
|
30
|
+
export function receiptSchemaUid() {
|
|
31
|
+
return keccak256(encodePacked(["string", "address", "bool"], [RECEIPT_SCHEMA, ZERO_ADDRESS, false]));
|
|
32
|
+
}
|
|
33
|
+
const bytes32 = (v) => typeof v === "string" && /^0x[0-9a-fA-F]{64}$/.test(v) ? v : null;
|
|
34
|
+
/**
|
|
35
|
+
* The receipt of a job, from its audit trail. Null while the job is not finalized, or when the
|
|
36
|
+
* trail lacks an event the receipt needs (it is then not a job of the verified evaluator).
|
|
37
|
+
*/
|
|
38
|
+
export function receiptFromAudit(audit, chainId = 8453) {
|
|
39
|
+
const last = (event) => audit.entries.filter((e) => e.event === event).at(-1);
|
|
40
|
+
const created = last("JobCreated");
|
|
41
|
+
const configured = last("Configured");
|
|
42
|
+
const submitted = last("JobSubmitted");
|
|
43
|
+
const finalized = last("Finalized");
|
|
44
|
+
if (!created?.actor || !configured || !finalized)
|
|
45
|
+
return null;
|
|
46
|
+
const provider = created.detail.provider;
|
|
47
|
+
const agent = configured.detail.providerAgentId;
|
|
48
|
+
const specHash = bytes32(configured.detail.specHash);
|
|
49
|
+
const voteHash = bytes32(finalized.detail.voteHash);
|
|
50
|
+
if (typeof provider !== "string" ||
|
|
51
|
+
typeof agent !== "string" ||
|
|
52
|
+
typeof finalized.detail.approved !== "boolean" ||
|
|
53
|
+
!specHash ||
|
|
54
|
+
!voteHash)
|
|
55
|
+
return null;
|
|
56
|
+
return {
|
|
57
|
+
chainId,
|
|
58
|
+
escrow: audit.escrow,
|
|
59
|
+
jobId: audit.jobId,
|
|
60
|
+
client: created.actor,
|
|
61
|
+
provider: provider,
|
|
62
|
+
providerAgentId: BigInt(agent),
|
|
63
|
+
approved: finalized.detail.approved,
|
|
64
|
+
// A job rejected before any delivery has no deliverable.
|
|
65
|
+
deliverable: bytes32(submitted?.detail.deliverable) ?? ZERO_BYTES32,
|
|
66
|
+
specHash,
|
|
67
|
+
voteHash,
|
|
68
|
+
finalizedAt: finalized.at,
|
|
69
|
+
};
|
|
70
|
+
}
|
|
71
|
+
/** The receipt as EAS attestation data, in the schema's field order. */
|
|
72
|
+
export function encodeReceipt(r) {
|
|
73
|
+
return encodeAbiParameters([
|
|
74
|
+
{ type: "uint256" },
|
|
75
|
+
{ type: "address" },
|
|
76
|
+
{ type: "uint256" },
|
|
77
|
+
{ type: "address" },
|
|
78
|
+
{ type: "address" },
|
|
79
|
+
{ type: "uint256" },
|
|
80
|
+
{ type: "bool" },
|
|
81
|
+
{ type: "bytes32" },
|
|
82
|
+
{ type: "bytes32" },
|
|
83
|
+
{ type: "bytes32" },
|
|
84
|
+
{ type: "uint64" },
|
|
85
|
+
], [
|
|
86
|
+
BigInt(r.chainId),
|
|
87
|
+
r.escrow,
|
|
88
|
+
r.jobId,
|
|
89
|
+
r.client,
|
|
90
|
+
r.provider,
|
|
91
|
+
r.providerAgentId,
|
|
92
|
+
r.approved,
|
|
93
|
+
r.deliverable,
|
|
94
|
+
r.specHash,
|
|
95
|
+
r.voteHash,
|
|
96
|
+
BigInt(r.finalizedAt),
|
|
97
|
+
]);
|
|
98
|
+
}
|
|
99
|
+
/** The unsigned EAS `attest` call for a receipt: recipient is the provider, never expires. */
|
|
100
|
+
export function prepareReceiptAttestation(r) {
|
|
101
|
+
return {
|
|
102
|
+
to: EAS,
|
|
103
|
+
data: encodeFunctionData({
|
|
104
|
+
abi: easAbi,
|
|
105
|
+
functionName: "attest",
|
|
106
|
+
args: [
|
|
107
|
+
{
|
|
108
|
+
schema: receiptSchemaUid(),
|
|
109
|
+
data: {
|
|
110
|
+
recipient: r.provider,
|
|
111
|
+
expirationTime: 0n,
|
|
112
|
+
revocable: false,
|
|
113
|
+
refUID: ZERO_BYTES32,
|
|
114
|
+
data: encodeReceipt(r),
|
|
115
|
+
value: 0n,
|
|
116
|
+
},
|
|
117
|
+
},
|
|
118
|
+
],
|
|
119
|
+
}),
|
|
120
|
+
value: "0",
|
|
121
|
+
};
|
|
122
|
+
}
|
|
123
|
+
/** The unsigned call that registers the receipt schema; needed once, by anyone. */
|
|
124
|
+
export function prepareReceiptSchemaRegistration() {
|
|
125
|
+
return {
|
|
126
|
+
to: EAS_SCHEMA_REGISTRY,
|
|
127
|
+
data: encodeFunctionData({
|
|
128
|
+
abi: registryAbi,
|
|
129
|
+
functionName: "register",
|
|
130
|
+
args: [RECEIPT_SCHEMA, ZERO_ADDRESS, false],
|
|
131
|
+
}),
|
|
132
|
+
value: "0",
|
|
133
|
+
};
|
|
134
|
+
}
|
|
135
|
+
/** Reads a job's receipt and prepares the calls that put it on EAS. */
|
|
136
|
+
export async function getJobReceipt(client, token, jobId, opts = {}) {
|
|
137
|
+
const audit = await getJobAudit(client, token, jobId, opts);
|
|
138
|
+
const receipt = receiptFromAudit(audit);
|
|
139
|
+
const schemaUid = receiptSchemaUid();
|
|
140
|
+
const record = await client.readContract({
|
|
141
|
+
address: EAS_SCHEMA_REGISTRY,
|
|
142
|
+
abi: registryAbi,
|
|
143
|
+
functionName: "getSchema",
|
|
144
|
+
args: [schemaUid],
|
|
145
|
+
blockNumber: audit.block,
|
|
146
|
+
});
|
|
147
|
+
const schemaRegistered = record.uid.toLowerCase() === schemaUid.toLowerCase();
|
|
148
|
+
return {
|
|
149
|
+
block: audit.block,
|
|
150
|
+
receipt,
|
|
151
|
+
schema: RECEIPT_SCHEMA,
|
|
152
|
+
schemaUid,
|
|
153
|
+
schemaRegistered,
|
|
154
|
+
...(receipt ? { attest: prepareReceiptAttestation(receipt) } : {}),
|
|
155
|
+
...(schemaRegistered ? {} : { registerSchema: prepareReceiptSchemaRegistration() }),
|
|
156
|
+
};
|
|
157
|
+
}
|