brainchain-verify 0.6.0 → 0.7.1

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/dist/verify.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { type Address, type Hex, type PublicClient } from "viem";
1
+ import { type Address, type Hex, type HttpTransport, 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";
@@ -30,6 +30,8 @@ export interface DecisionReport {
30
30
  id: number;
31
31
  kind?: string;
32
32
  task?: number;
33
+ /** The task's brief by its title, or its first line, cut to 100 characters. Set once the brief committed on chain was read. */
34
+ title?: string;
33
35
  /** A grade of work delivered outside BrainChain, so no task here. */
34
36
  outside?: boolean;
35
37
  /** Served without the work, as the chain shows it may be, so its hashes could not be checked. */
@@ -63,8 +65,9 @@ export interface Payment {
63
65
  }
64
66
  /**
65
67
  * 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
+ * lowercase on EVM networks. Undefined when it did not succeed, or cannot be on
69
+ * `network`. Throws when the network's RPC does not find it, which a lagging
70
+ * node can explain.
68
71
  */
69
72
  export type Balances = (network: string, transaction: string, asset: string) => Promise<Map<string, bigint> | undefined>;
70
73
  export interface Context {
@@ -72,7 +75,7 @@ export interface Context {
72
75
  network: Network;
73
76
  set: ContractSet;
74
77
  briefs: Map<bigint, Promise<Brief>>;
75
- /** Reads payment transactions; public RPCs for Base, Robinhood Chain and Solana when absent. */
78
+ /** Reads payment transactions; public RPCs for Base, Robinhood Chain and Solana when absent. balancesFrom builds one from other RPCs. */
76
79
  balances?: Balances;
77
80
  /** Fetches no receipt from the brain host, so only one given to verifyDecision is checked. */
78
81
  offline?: boolean;
@@ -92,20 +95,124 @@ interface Brief {
92
95
  }
93
96
  export declare const clean: (text: string) => string;
94
97
  export declare function errorMessage(error: unknown): string;
98
+ /** An http transport for one RPC, with two tries of 8 seconds, whose errors say which RPC failed: `name` is its chain, as in "BrainChain RPC <origin>". */
99
+ export declare function rpcTransport(name: string, url: string): HttpTransport;
95
100
  /** Decision ids about one task on the set's board, oldest first. */
96
101
  export declare function decisionsOf({ client, network, set }: Context, task: bigint): Promise<bigint[]>;
97
102
  /** `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
103
  export declare function verifyDecision(ctx: Context, id: bigint, receipt?: GivenReceipt): Promise<DecisionReport>;
99
104
  /** Reads a receipt from a file or an http(s) URL: the receipt itself, or a reply that carries it as `receipt`. */
100
105
  export declare function readReceipt(client: PublicClient, source: string): Promise<GivenReceipt>;
106
+ /** Whether a value is a receipt as BrainChain or the x402 extension signs one. */
107
+ export declare const isReceipt: (value: unknown) => boolean;
101
108
  /** The decision and log a BrainChain receipt names. The x402 extension's receipt names neither. */
102
109
  export declare function receiptDecision(value: unknown): {
103
110
  decision: string;
104
111
  decisionLog: Address;
105
112
  } | undefined;
113
+ /** Reads payment transactions from the RPC given for each CAIP-2 network, such as eip155:8453. */
114
+ export declare function balancesFrom(rpcs: Readonly<Record<string, string>>): Balances;
106
115
  export type Outcome = "match" | "withheld" | "unverified" | "mismatch";
107
116
  /** Disagreement first, then what could not be read. A withheld record never reads as a match: its hashes were not checked. */
108
- export declare function outcomeOf(reports: DecisionReport[]): Outcome;
117
+ export declare function outcomeOf(reports: Pick<DecisionReport, "checks" | "withheld">[]): Outcome;
109
118
  /** What a withheld copy leaves unchecked. A grade of outside work has no task here, so nothing on chain backs its brief or levels. */
110
119
  export declare function withheldNotChecked(reports: DecisionReport[]): string;
120
+ /** Where BrainChain records each task that settles for an ERC-8004 agent, and whom its entries name. */
121
+ export interface Registry {
122
+ /** Reads the chain the registries are on. */
123
+ client: PublicClient;
124
+ chainId: number;
125
+ /** The ERC-8004 reputation registry. */
126
+ address: Address;
127
+ /** The ERC-8004 identity registry, which says who held an agent and when. */
128
+ identity: Address;
129
+ /** The addresses BrainChain writes entries from, the one it writes from now first. Anyone can write under its tag, so only these count. */
130
+ writers: readonly Address[];
131
+ /** The block of BrainChain's first entry. */
132
+ fromBlock: bigint;
133
+ /** BrainChain's house workers: the model name the board hires each agent id by. */
134
+ house: Readonly<Record<string, string>>;
135
+ }
136
+ /** BrainChain mainnet's: the registries on Robinhood Chain, and the addresses and agents its docs list (workers#erc-8004-identity). */
137
+ export declare const REPUTATION: {
138
+ readonly network: 274663;
139
+ readonly chainId: 4663;
140
+ readonly rpc: "https://rpc.mainnet.chain.robinhood.com";
141
+ readonly address: "0x8004BAa17C55a88189AE136b182e5fdA19dE9b63";
142
+ readonly identity: "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432";
143
+ readonly writers: readonly ["0x97D558417c3D61f1074422AD843e1Db1E565b952", "0xafB0C4Ef895D4895040cdC6435B96D3EE8350c6E"];
144
+ readonly fromBlock: 103375137n;
145
+ readonly house: {
146
+ readonly 20424: "claude";
147
+ readonly 20425: "gpt";
148
+ readonly 20426: "gemini";
149
+ readonly 20427: "grok";
150
+ readonly 20428: "deepseek";
151
+ };
152
+ };
153
+ /** An entry as its NewFeedback event states it. The registry names it by agent, writer and index. */
154
+ export interface Feedback {
155
+ agentId: bigint;
156
+ clientAddress: Address;
157
+ /** From 1 for each agent and writer. */
158
+ feedbackIndex: bigint;
159
+ value: bigint;
160
+ valueDecimals: number;
161
+ tag1: string;
162
+ tag2: string;
163
+ endpoint: string;
164
+ feedbackURI: string;
165
+ feedbackHash: Hex;
166
+ block: bigint;
167
+ transaction: Hex;
168
+ }
169
+ export interface EntryReport {
170
+ /** As --entry takes it: the agent and the index, with the writer between them unless it is the one BrainChain writes from now. */
171
+ entry: string;
172
+ agentId: string;
173
+ clientAddress: Address;
174
+ feedbackIndex: number;
175
+ value: number;
176
+ block: number;
177
+ transaction: Hex;
178
+ endpoint: string;
179
+ feedbackURI: string;
180
+ feedbackHash: Hex;
181
+ /** The task the endpoint names, and its board and contract set where it names one the tool carries. */
182
+ task?: number;
183
+ board?: Address;
184
+ set?: string;
185
+ /** The decision the entry's receipt names, checked with the receipt. Its checks are among the entry's. */
186
+ decision?: DecisionReport & {
187
+ set: string;
188
+ };
189
+ /** That decision's record was served without the work, so its hashes could not be checked. */
190
+ withheld?: boolean;
191
+ checks: Check[];
192
+ }
193
+ export declare const entryName: (registry: Registry, f: Pick<Feedback, "agentId" | "clientAddress" | "feedbackIndex">) => string;
194
+ /** An entry as its NewFeedback event states it, with `checks` as its own. */
195
+ export declare function entryReport(registry: Registry, f: Feedback, checks: Check[]): EntryReport;
196
+ /** Every entry BrainChain wrote for an agent, from the writers given or all of its own, oldest first. */
197
+ export declare function entriesOf(registry: Registry, agentId: bigint, writers?: readonly Address[]): Promise<Feedback[]>;
198
+ /**
199
+ * One entry, end to end: as the registry holds it, the task its endpoint
200
+ * names, the receipt its feedbackHash commits to, the decision and payment
201
+ * that receipt names, and the board's settlement and hire behind its value
202
+ * and its agent.
203
+ */
204
+ export declare function verifyEntry(ctx: Context, registry: Registry, f: Feedback): Promise<EntryReport>;
205
+ export type EntryOutcome = Outcome | "no-receipt";
206
+ /** As for decisions, and `no-receipt` when everything passed and no entry had a receipt to check. */
207
+ export declare function entryOutcome(reports: EntryReport[]): EntryOutcome;
208
+ export interface EntrySummary {
209
+ entries: number;
210
+ withReceipt: number;
211
+ /** Entries whose receipt and decision fully matched. A copy served without the work never does. */
212
+ verified: number;
213
+ withheld: number;
214
+ failed: number;
215
+ unverified: number;
216
+ }
217
+ export declare function entrySummary(reports: EntryReport[]): EntrySummary;
111
218
  export {};