brainchain-verify 0.5.1 → 0.7.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 +144 -7
- package/dist/cli.js +201 -24
- package/dist/verify.d.ts +151 -3
- package/dist/verify.js +979 -29
- package/package.json +1 -1
package/dist/verify.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { type PublicClient } from "viem";
|
|
1
|
+
import { type Address, type Hex, type PublicClient } from "viem";
|
|
2
2
|
import type { ContractSet, Network } from "./deployments.js";
|
|
3
3
|
/** `error` is a check that could not complete, such as a record host that did not answer. */
|
|
4
4
|
export type Status = "ok" | "fail" | "skip" | "error";
|
|
@@ -8,6 +8,24 @@ export interface Check {
|
|
|
8
8
|
status: Status;
|
|
9
9
|
message: string;
|
|
10
10
|
}
|
|
11
|
+
/** The sandbox's run of a brief's checks after the delivered code. */
|
|
12
|
+
export interface Run {
|
|
13
|
+
language: "python" | "javascript";
|
|
14
|
+
outcome: "passed" | "failed" | "timed out";
|
|
15
|
+
}
|
|
16
|
+
/** A grade or ruling decided by a panel, as its record states it. */
|
|
17
|
+
export interface PanelReport {
|
|
18
|
+
rule: string;
|
|
19
|
+
/** Every member that answered, Jev first, with its probability of paying. */
|
|
20
|
+
judges: {
|
|
21
|
+
model: string;
|
|
22
|
+
paid: number;
|
|
23
|
+
}[];
|
|
24
|
+
degraded: boolean;
|
|
25
|
+
/** When degraded: the members the panel decided without, and what it then had to put on paying to pay. */
|
|
26
|
+
missing?: string[];
|
|
27
|
+
bar?: number;
|
|
28
|
+
}
|
|
11
29
|
export interface DecisionReport {
|
|
12
30
|
id: number;
|
|
13
31
|
kind?: string;
|
|
@@ -16,17 +34,53 @@ export interface DecisionReport {
|
|
|
16
34
|
outside?: boolean;
|
|
17
35
|
/** Served without the work, as the chain shows it may be, so its hashes could not be checked. */
|
|
18
36
|
withheld?: boolean;
|
|
37
|
+
/** On a grade or ruling whose request holds one. */
|
|
38
|
+
run?: Run;
|
|
39
|
+
panel?: PanelReport;
|
|
19
40
|
block?: number;
|
|
20
41
|
recordedAt?: string;
|
|
21
42
|
confidenceBps?: number;
|
|
22
43
|
payloadURI?: string;
|
|
44
|
+
/** The evidence hash the decision's Recorded event carries in payloadURI, once the record matched it. */
|
|
45
|
+
evidence?: Hex;
|
|
46
|
+
/** The receipt checked for the paid job this decision settled, with the job and outcome it states. */
|
|
47
|
+
receipt?: {
|
|
48
|
+
from: string;
|
|
49
|
+
job?: string;
|
|
50
|
+
outcome?: string;
|
|
51
|
+
};
|
|
23
52
|
checks: Check[];
|
|
24
53
|
}
|
|
54
|
+
/** A payment behind the job a decision is about, as its record and its receipt state it. */
|
|
55
|
+
export interface Payment {
|
|
56
|
+
/** CAIP-2, such as eip155:8453. */
|
|
57
|
+
network: string;
|
|
58
|
+
asset: string;
|
|
59
|
+
/** In the asset's smallest units. */
|
|
60
|
+
amount: string;
|
|
61
|
+
payer: string;
|
|
62
|
+
transaction: string;
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* How a transaction changed each owner's balance of `asset`, by owner, in
|
|
66
|
+
* lowercase on EVM networks. Undefined when it is not on `network` or did not
|
|
67
|
+
* succeed.
|
|
68
|
+
*/
|
|
69
|
+
export type Balances = (network: string, transaction: string, asset: string) => Promise<Map<string, bigint> | undefined>;
|
|
25
70
|
export interface Context {
|
|
26
71
|
client: PublicClient;
|
|
27
72
|
network: Network;
|
|
28
73
|
set: ContractSet;
|
|
29
74
|
briefs: Map<bigint, Promise<Brief>>;
|
|
75
|
+
/** Reads payment transactions; public RPCs for Base, Robinhood Chain and Solana when absent. */
|
|
76
|
+
balances?: Balances;
|
|
77
|
+
/** Fetches no receipt from the brain host, so only one given to verifyDecision is checked. */
|
|
78
|
+
offline?: boolean;
|
|
79
|
+
}
|
|
80
|
+
/** A receipt as an agent kept it, and where it was read. */
|
|
81
|
+
export interface GivenReceipt {
|
|
82
|
+
from: string;
|
|
83
|
+
value: unknown;
|
|
30
84
|
}
|
|
31
85
|
interface Brief {
|
|
32
86
|
title: string;
|
|
@@ -40,10 +94,104 @@ export declare const clean: (text: string) => string;
|
|
|
40
94
|
export declare function errorMessage(error: unknown): string;
|
|
41
95
|
/** Decision ids about one task on the set's board, oldest first. */
|
|
42
96
|
export declare function decisionsOf({ client, network, set }: Context, task: bigint): Promise<bigint[]>;
|
|
43
|
-
|
|
97
|
+
/** `receipt` is one the caller kept. Without it, the receipt of a paid grade or ruling is fetched from the host that serves its record, unless the context is offline. */
|
|
98
|
+
export declare function verifyDecision(ctx: Context, id: bigint, receipt?: GivenReceipt): Promise<DecisionReport>;
|
|
99
|
+
/** Reads a receipt from a file or an http(s) URL: the receipt itself, or a reply that carries it as `receipt`. */
|
|
100
|
+
export declare function readReceipt(client: PublicClient, source: string): Promise<GivenReceipt>;
|
|
101
|
+
/** The decision and log a BrainChain receipt names. The x402 extension's receipt names neither. */
|
|
102
|
+
export declare function receiptDecision(value: unknown): {
|
|
103
|
+
decision: string;
|
|
104
|
+
decisionLog: Address;
|
|
105
|
+
} | undefined;
|
|
44
106
|
export type Outcome = "match" | "withheld" | "unverified" | "mismatch";
|
|
45
107
|
/** Disagreement first, then what could not be read. A withheld record never reads as a match: its hashes were not checked. */
|
|
46
|
-
export declare function outcomeOf(reports: DecisionReport[]): Outcome;
|
|
108
|
+
export declare function outcomeOf(reports: Pick<DecisionReport, "checks" | "withheld">[]): Outcome;
|
|
47
109
|
/** What a withheld copy leaves unchecked. A grade of outside work has no task here, so nothing on chain backs its brief or levels. */
|
|
48
110
|
export declare function withheldNotChecked(reports: DecisionReport[]): string;
|
|
111
|
+
/** Where BrainChain records each task that settles for an ERC-8004 agent, and whom its entries name. */
|
|
112
|
+
export interface Registry {
|
|
113
|
+
/** Reads the chain the registries are on. */
|
|
114
|
+
client: PublicClient;
|
|
115
|
+
chainId: number;
|
|
116
|
+
/** The ERC-8004 reputation registry. */
|
|
117
|
+
address: Address;
|
|
118
|
+
/** The ERC-8004 identity registry, which says who held an agent and when. */
|
|
119
|
+
identity: Address;
|
|
120
|
+
/** The addresses BrainChain writes entries from, the one it writes from now first. Anyone can write under its tag, so only these count. */
|
|
121
|
+
writers: readonly Address[];
|
|
122
|
+
/** The block of BrainChain's first entry. */
|
|
123
|
+
fromBlock: bigint;
|
|
124
|
+
/** BrainChain's house workers: the model name the board hires each agent id by. */
|
|
125
|
+
house: Readonly<Record<string, string>>;
|
|
126
|
+
}
|
|
127
|
+
/** BrainChain mainnet's: the registries on Robinhood Chain, and the addresses and agents its docs list (workers#erc-8004-identity). */
|
|
128
|
+
export declare const REPUTATION: {
|
|
129
|
+
readonly network: 274663;
|
|
130
|
+
readonly chainId: 4663;
|
|
131
|
+
readonly rpc: "https://rpc.mainnet.chain.robinhood.com";
|
|
132
|
+
readonly address: "0x8004BAa17C55a88189AE136b182e5fdA19dE9b63";
|
|
133
|
+
readonly identity: "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432";
|
|
134
|
+
readonly writers: readonly ["0x97D558417c3D61f1074422AD843e1Db1E565b952", "0xafB0C4Ef895D4895040cdC6435B96D3EE8350c6E"];
|
|
135
|
+
readonly fromBlock: 103375137n;
|
|
136
|
+
readonly house: {
|
|
137
|
+
readonly 20424: "claude";
|
|
138
|
+
readonly 20425: "gpt";
|
|
139
|
+
readonly 20426: "gemini";
|
|
140
|
+
readonly 20427: "grok";
|
|
141
|
+
readonly 20428: "deepseek";
|
|
142
|
+
};
|
|
143
|
+
};
|
|
144
|
+
/** An entry as its NewFeedback event states it. The registry names it by agent, writer and index. */
|
|
145
|
+
export interface Feedback {
|
|
146
|
+
agentId: bigint;
|
|
147
|
+
clientAddress: Address;
|
|
148
|
+
/** From 1 for each agent and writer. */
|
|
149
|
+
feedbackIndex: bigint;
|
|
150
|
+
value: bigint;
|
|
151
|
+
valueDecimals: number;
|
|
152
|
+
tag1: string;
|
|
153
|
+
tag2: string;
|
|
154
|
+
endpoint: string;
|
|
155
|
+
feedbackURI: string;
|
|
156
|
+
feedbackHash: Hex;
|
|
157
|
+
block: bigint;
|
|
158
|
+
transaction: Hex;
|
|
159
|
+
}
|
|
160
|
+
export interface EntryReport {
|
|
161
|
+
/** As --entry takes it: the agent and the index, with the writer between them unless it is the one BrainChain writes from now. */
|
|
162
|
+
entry: string;
|
|
163
|
+
agentId: string;
|
|
164
|
+
clientAddress: Address;
|
|
165
|
+
feedbackIndex: number;
|
|
166
|
+
value: number;
|
|
167
|
+
block: number;
|
|
168
|
+
transaction: Hex;
|
|
169
|
+
endpoint: string;
|
|
170
|
+
feedbackURI: string;
|
|
171
|
+
feedbackHash: Hex;
|
|
172
|
+
/** The task the endpoint names, and its board and contract set where it names one the tool carries. */
|
|
173
|
+
task?: number;
|
|
174
|
+
board?: Address;
|
|
175
|
+
set?: string;
|
|
176
|
+
/** The decision the entry's receipt names, checked with the receipt. Its checks are among the entry's. */
|
|
177
|
+
decision?: DecisionReport & {
|
|
178
|
+
set: string;
|
|
179
|
+
};
|
|
180
|
+
/** That decision's record was served without the work, so its hashes could not be checked. */
|
|
181
|
+
withheld?: boolean;
|
|
182
|
+
checks: Check[];
|
|
183
|
+
}
|
|
184
|
+
export declare const entryName: (registry: Registry, f: Pick<Feedback, "agentId" | "clientAddress" | "feedbackIndex">) => string;
|
|
185
|
+
/** Every entry BrainChain wrote for an agent, from the writers given or all of its own, oldest first. */
|
|
186
|
+
export declare function entriesOf(registry: Registry, agentId: bigint, writers?: readonly Address[]): Promise<Feedback[]>;
|
|
187
|
+
/**
|
|
188
|
+
* One entry, end to end: as the registry holds it, the task its endpoint
|
|
189
|
+
* names, the receipt its feedbackHash commits to, the decision and payment
|
|
190
|
+
* that receipt names, and the board's settlement and hire behind its value
|
|
191
|
+
* and its agent.
|
|
192
|
+
*/
|
|
193
|
+
export declare function verifyEntry(ctx: Context, registry: Registry, f: Feedback): Promise<EntryReport>;
|
|
194
|
+
export type EntryOutcome = Outcome | "no-receipt";
|
|
195
|
+
/** As for decisions, and `no-receipt` when everything passed and no entry had a receipt to check. */
|
|
196
|
+
export declare function entryOutcome(reports: EntryReport[]): EntryOutcome;
|
|
49
197
|
export {};
|