@0gfoundation/0g-agentdna 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.
Files changed (206) hide show
  1. package/GUIDE.md +975 -0
  2. package/LICENSE +21 -0
  3. package/MIGRATION.md +84 -0
  4. package/MIGRATION.zh.md +70 -0
  5. package/PROVIDERS.md +273 -0
  6. package/PROVIDERS.zh.md +234 -0
  7. package/README.md +334 -2
  8. package/dist/AgentClient.d.ts +312 -0
  9. package/dist/AgentClient.d.ts.map +1 -0
  10. package/dist/AgentClient.js +715 -0
  11. package/dist/AgentClient.js.map +1 -0
  12. package/dist/AgenticID.d.ts +823 -0
  13. package/dist/AgenticID.d.ts.map +1 -0
  14. package/dist/AgenticID.js +1188 -0
  15. package/dist/AgenticID.js.map +1 -0
  16. package/dist/AgenticIDClient.d.ts +68 -0
  17. package/dist/AgenticIDClient.d.ts.map +1 -0
  18. package/dist/AgenticIDClient.js +198 -0
  19. package/dist/AgenticIDClient.js.map +1 -0
  20. package/dist/AttestorClient.d.ts +465 -0
  21. package/dist/AttestorClient.d.ts.map +1 -0
  22. package/dist/AttestorClient.js +1030 -0
  23. package/dist/AttestorClient.js.map +1 -0
  24. package/dist/Providers.d.ts +72 -0
  25. package/dist/Providers.d.ts.map +1 -0
  26. package/dist/Providers.js +182 -0
  27. package/dist/Providers.js.map +1 -0
  28. package/dist/ReputationClient.d.ts +213 -0
  29. package/dist/ReputationClient.d.ts.map +1 -0
  30. package/dist/ReputationClient.js +708 -0
  31. package/dist/ReputationClient.js.map +1 -0
  32. package/dist/SandboxClient.d.ts +107 -0
  33. package/dist/SandboxClient.d.ts.map +1 -0
  34. package/dist/SandboxClient.js +200 -0
  35. package/dist/SandboxClient.js.map +1 -0
  36. package/dist/ServeProof.d.ts +161 -0
  37. package/dist/ServeProof.d.ts.map +1 -0
  38. package/dist/ServeProof.js +230 -0
  39. package/dist/ServeProof.js.map +1 -0
  40. package/dist/ServeSession.d.ts +180 -0
  41. package/dist/ServeSession.d.ts.map +1 -0
  42. package/dist/ServeSession.js +336 -0
  43. package/dist/ServeSession.js.map +1 -0
  44. package/dist/Settings.d.ts +179 -0
  45. package/dist/Settings.d.ts.map +1 -0
  46. package/dist/Settings.js +247 -0
  47. package/dist/Settings.js.map +1 -0
  48. package/dist/abi.d.ts +2216 -0
  49. package/dist/abi.d.ts.map +1 -0
  50. package/dist/abi.js +1248 -0
  51. package/dist/abi.js.map +1 -0
  52. package/dist/cli/commands/cells.d.ts +34 -0
  53. package/dist/cli/commands/cells.d.ts.map +1 -0
  54. package/dist/cli/commands/cells.js +66 -0
  55. package/dist/cli/commands/cells.js.map +1 -0
  56. package/dist/cli/commands/doctor.d.ts +15 -0
  57. package/dist/cli/commands/doctor.d.ts.map +1 -0
  58. package/dist/cli/commands/doctor.js +236 -0
  59. package/dist/cli/commands/doctor.js.map +1 -0
  60. package/dist/cli/commands/interactive.d.ts +107 -0
  61. package/dist/cli/commands/interactive.d.ts.map +1 -0
  62. package/dist/cli/commands/interactive.js +3034 -0
  63. package/dist/cli/commands/interactive.js.map +1 -0
  64. package/dist/cli/commands/list.d.ts +31 -0
  65. package/dist/cli/commands/list.d.ts.map +1 -0
  66. package/dist/cli/commands/list.js +115 -0
  67. package/dist/cli/commands/list.js.map +1 -0
  68. package/dist/cli/commands/providers.d.ts +3 -0
  69. package/dist/cli/commands/providers.d.ts.map +1 -0
  70. package/dist/cli/commands/providers.js +21 -0
  71. package/dist/cli/commands/providers.js.map +1 -0
  72. package/dist/cli/commands/settings.d.ts +22 -0
  73. package/dist/cli/commands/settings.d.ts.map +1 -0
  74. package/dist/cli/commands/settings.js +188 -0
  75. package/dist/cli/commands/settings.js.map +1 -0
  76. package/dist/cli/commands/status.d.ts +16 -0
  77. package/dist/cli/commands/status.d.ts.map +1 -0
  78. package/dist/cli/commands/status.js +148 -0
  79. package/dist/cli/commands/status.js.map +1 -0
  80. package/dist/cli/commands/update.d.ts +21 -0
  81. package/dist/cli/commands/update.d.ts.map +1 -0
  82. package/dist/cli/commands/update.js +95 -0
  83. package/dist/cli/commands/update.js.map +1 -0
  84. package/dist/cli/config.d.ts +73 -0
  85. package/dist/cli/config.d.ts.map +1 -0
  86. package/dist/cli/config.js +239 -0
  87. package/dist/cli/config.js.map +1 -0
  88. package/dist/cli/env.d.ts +36 -0
  89. package/dist/cli/env.d.ts.map +1 -0
  90. package/dist/cli/env.js +74 -0
  91. package/dist/cli/env.js.map +1 -0
  92. package/dist/cli/envelope.d.ts +33 -0
  93. package/dist/cli/envelope.d.ts.map +1 -0
  94. package/dist/cli/envelope.js +62 -0
  95. package/dist/cli/envelope.js.map +1 -0
  96. package/dist/cli/errors.d.ts +48 -0
  97. package/dist/cli/errors.d.ts.map +1 -0
  98. package/dist/cli/errors.js +81 -0
  99. package/dist/cli/errors.js.map +1 -0
  100. package/dist/cli/inference.d.ts +21 -0
  101. package/dist/cli/inference.d.ts.map +1 -0
  102. package/dist/cli/inference.js +60 -0
  103. package/dist/cli/inference.js.map +1 -0
  104. package/dist/cli/logo.d.ts +21 -0
  105. package/dist/cli/logo.d.ts.map +1 -0
  106. package/dist/cli/logo.js +131 -0
  107. package/dist/cli/logo.js.map +1 -0
  108. package/dist/cli/main.d.ts +14 -0
  109. package/dist/cli/main.d.ts.map +1 -0
  110. package/dist/cli/main.js +223 -0
  111. package/dist/cli/main.js.map +1 -0
  112. package/dist/cli/proofs.d.ts +67 -0
  113. package/dist/cli/proofs.d.ts.map +1 -0
  114. package/dist/cli/proofs.js +133 -0
  115. package/dist/cli/proofs.js.map +1 -0
  116. package/dist/cli/ref.d.ts +39 -0
  117. package/dist/cli/ref.d.ts.map +1 -0
  118. package/dist/cli/ref.js +48 -0
  119. package/dist/cli/ref.js.map +1 -0
  120. package/dist/cli/sdk.d.ts +24 -0
  121. package/dist/cli/sdk.d.ts.map +1 -0
  122. package/dist/cli/sdk.js +65 -0
  123. package/dist/cli/sdk.js.map +1 -0
  124. package/dist/cli/settings.d.ts +66 -0
  125. package/dist/cli/settings.d.ts.map +1 -0
  126. package/dist/cli/settings.js +137 -0
  127. package/dist/cli/settings.js.map +1 -0
  128. package/dist/cli/tokenize.d.ts +61 -0
  129. package/dist/cli/tokenize.d.ts.map +1 -0
  130. package/dist/cli/tokenize.js +157 -0
  131. package/dist/cli/tokenize.js.map +1 -0
  132. package/dist/cli/types.d.ts +25 -0
  133. package/dist/cli/types.d.ts.map +1 -0
  134. package/dist/cli/types.js +8 -0
  135. package/dist/cli/types.js.map +1 -0
  136. package/dist/constants.d.ts +107 -0
  137. package/dist/constants.d.ts.map +1 -0
  138. package/dist/constants.js +74 -0
  139. package/dist/constants.js.map +1 -0
  140. package/dist/context.d.ts +108 -0
  141. package/dist/context.d.ts.map +1 -0
  142. package/dist/context.js +64 -0
  143. package/dist/context.js.map +1 -0
  144. package/dist/index.d.ts +45 -0
  145. package/dist/index.d.ts.map +1 -0
  146. package/dist/index.js +118 -0
  147. package/dist/index.js.map +1 -0
  148. package/dist/provider-catalog.json +23 -0
  149. package/dist/seal.d.ts +47 -0
  150. package/dist/seal.d.ts.map +1 -0
  151. package/dist/seal.js +145 -0
  152. package/dist/seal.js.map +1 -0
  153. package/dist/secretEnv.d.ts +119 -0
  154. package/dist/secretEnv.d.ts.map +1 -0
  155. package/dist/secretEnv.js +199 -0
  156. package/dist/secretEnv.js.map +1 -0
  157. package/dist/taskHash.d.ts +39 -0
  158. package/dist/taskHash.d.ts.map +1 -0
  159. package/dist/taskHash.js +119 -0
  160. package/dist/taskHash.js.map +1 -0
  161. package/dist/types.d.ts +336 -0
  162. package/dist/types.d.ts.map +1 -0
  163. package/dist/types.js +19 -0
  164. package/dist/types.js.map +1 -0
  165. package/package.json +75 -4
  166. package/scripts/sync-providers.cjs +8 -0
  167. package/src/AgentClient.ts +897 -0
  168. package/src/AgenticID.ts +1382 -0
  169. package/src/AgenticIDClient.ts +238 -0
  170. package/src/AttestorClient.ts +1306 -0
  171. package/src/Providers.ts +176 -0
  172. package/src/ReputationClient.ts +821 -0
  173. package/src/SandboxClient.ts +227 -0
  174. package/src/ServeProof.ts +290 -0
  175. package/src/ServeSession.ts +421 -0
  176. package/src/Settings.ts +296 -0
  177. package/src/abi.ts +1282 -0
  178. package/src/cli/commands/cells.ts +61 -0
  179. package/src/cli/commands/doctor.ts +235 -0
  180. package/src/cli/commands/interactive.ts +2715 -0
  181. package/src/cli/commands/list.ts +117 -0
  182. package/src/cli/commands/providers.ts +16 -0
  183. package/src/cli/commands/settings.ts +197 -0
  184. package/src/cli/commands/status.ts +170 -0
  185. package/src/cli/commands/update.ts +86 -0
  186. package/src/cli/config.ts +225 -0
  187. package/src/cli/env.ts +90 -0
  188. package/src/cli/envelope.ts +57 -0
  189. package/src/cli/errors.ts +114 -0
  190. package/src/cli/inference.ts +57 -0
  191. package/src/cli/logo.ts +125 -0
  192. package/src/cli/main.ts +235 -0
  193. package/src/cli/proofs.ts +160 -0
  194. package/src/cli/ref.ts +58 -0
  195. package/src/cli/sdk.ts +65 -0
  196. package/src/cli/settings.ts +153 -0
  197. package/src/cli/tokenize.ts +131 -0
  198. package/src/cli/types.ts +27 -0
  199. package/src/constants.ts +106 -0
  200. package/src/context.ts +161 -0
  201. package/src/index.ts +129 -0
  202. package/src/provider-catalog.json +23 -0
  203. package/src/seal.ts +163 -0
  204. package/src/secretEnv.ts +250 -0
  205. package/src/taskHash.ts +100 -0
  206. package/src/types.ts +357 -0
@@ -0,0 +1,821 @@
1
+ /**
2
+ * @file ReputationClient.ts
3
+ * @description Client for the split reputation architecture: feedback is
4
+ * STORED in the official canonical ERC-8004 ReputationRegistry (native
5
+ * per-client attribution, visible to every 8004 reader), and the local
6
+ * VerifiedFeedbackRegistry records which canonical entries were backed by a
7
+ * TEE-signed ServeProof.
8
+ *
9
+ * `giveFeedback` bundles the two client calls (canonical write → read the
10
+ * assigned index → attest); reads go to whichever contract owns the data
11
+ * (feedback values: canonical; verification marks + serve data: local).
12
+ * The canonical registry's address is discovered from the local contract
13
+ * (`getCanonicalReputation`), so configuration needs only `verifiedFeedback`.
14
+ */
15
+
16
+ import {
17
+ type WalletClient,
18
+ type PublicClient,
19
+ type Address,
20
+ type Hash,
21
+ type Chain,
22
+ type Account,
23
+ type WriteContractReturnType,
24
+ type TransactionReceipt,
25
+ encodeAbiParameters,
26
+ encodeFunctionData,
27
+ keccak256,
28
+ parseEventLogs,
29
+ toBytes,
30
+ } from 'viem';
31
+ import { agenticIDAbi, canonicalReputationAbi, verifiedFeedbackAbi, feedbackBatcherAbi } from './abi';
32
+ import { RECEIPT_WAIT } from './constants';
33
+ import { type Ctx } from './context';
34
+ import { verifyServeProofSignature } from './ServeProof';
35
+ import type {
36
+ ServeProof,
37
+ GiveFeedbackParams,
38
+ GiveFeedbackResult,
39
+ AppendResponseParams,
40
+ ReadAllFeedbackParams,
41
+ GetSummaryParams,
42
+ Feedback,
43
+ FeedbackSummary,
44
+ ServeData,
45
+ TaskReveal,
46
+ } from './types';
47
+
48
+ const ZERO32 = ('0x' + '0'.repeat(64)) as `0x${string}`;
49
+ const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
50
+
51
+ /**
52
+ * Seconds of headroom the sequential preflight demands before a proof's
53
+ * deadline: the attest lands only after the canonical write has mined, so a
54
+ * proof that is valid right now but lapses within this window would still
55
+ * orphan the canonical entry.
56
+ */
57
+ const ATTEST_DEADLINE_MARGIN_S = 60n;
58
+
59
+ /** keccak256("SERVEPROOF") — the registry's nonce-key domain tag. */
60
+ const SERVEPROOF_NONCE_TAG = keccak256(toBytes('SERVEPROOF'));
61
+
62
+ /**
63
+ * The VerifiedFeedbackRegistry nonce key a ServeProof consumes when it
64
+ * attests: keccak256(abi.encode(keccak256("SERVEPROOF"), agentId, signature)).
65
+ * A proof whose key `isNonceConsumed` reports has already been redeemed.
66
+ */
67
+ export function serveProofNonceKey(agentId: bigint, signature: `0x${string}`): `0x${string}` {
68
+ return keccak256(encodeAbiParameters(
69
+ [{ type: 'bytes32' }, { type: 'uint256' }, { type: 'bytes' }],
70
+ [SERVEPROOF_NONCE_TAG, agentId, signature],
71
+ ));
72
+ }
73
+
74
+ /**
75
+ * FIND-02: the registry recomputes taskHash with the status code as decimal
76
+ * text, so it accepts only the fixed 3-digit width (100..999) and reverts
77
+ * anything else with VerifiedFeedbackInvalidTaskReveal. Refuse such a reveal
78
+ * before anything is broadcast — on the sequential path a late revert would
79
+ * leave an orphaned canonical entry behind.
80
+ */
81
+ function assertTaskStatusCode(task: TaskReveal): void {
82
+ const s = task.statusCode;
83
+ if (!Number.isInteger(s) || s < 100 || s > 999) {
84
+ throw new Error(
85
+ `reputation: task.statusCode must be an integer HTTP status in 100..999 (got ${String(s)}) — ` +
86
+ 'the VerifiedFeedbackRegistry rejects any other value (VerifiedFeedbackInvalidTaskReveal)',
87
+ );
88
+ }
89
+ }
90
+
91
+ /**
92
+ * FIND-04: the registry only marks entries with |value| ≤ 1e9 and at most 18
93
+ * decimals (VerifiedFeedbackValueOutOfRange) — summaries skip anything else.
94
+ * Refuse such a value before anything is broadcast: on the sequential path the
95
+ * canonical entry would land and then never verify.
96
+ */
97
+ export const MAX_ABS_FEEDBACK_VALUE = 1_000_000_000n;
98
+
99
+ function assertFeedbackValueInRange(value: bigint, valueDecimals: number): void {
100
+ if (!Number.isInteger(valueDecimals) || valueDecimals < 0 || valueDecimals > 18) {
101
+ throw new Error(
102
+ `reputation: valueDecimals must be an integer in 0..18 (got ${String(valueDecimals)}) — ` +
103
+ 'the VerifiedFeedbackRegistry rejects any other value (VerifiedFeedbackValueOutOfRange)',
104
+ );
105
+ }
106
+ if (value > MAX_ABS_FEEDBACK_VALUE || value < -MAX_ABS_FEEDBACK_VALUE) {
107
+ throw new Error(
108
+ `reputation: |value| must be at most ${MAX_ABS_FEEDBACK_VALUE} (got ${value}) — ` +
109
+ 'the VerifiedFeedbackRegistry rejects larger values (VerifiedFeedbackValueOutOfRange)',
110
+ );
111
+ }
112
+ }
113
+
114
+ /**
115
+ * Internal client for the reputation pair (canonical ERC-8004 registry +
116
+ * VerifiedFeedbackRegistry). Consumers use the `AgenticID` facade's
117
+ * `reputation` namespace, not this directly.
118
+ */
119
+ export class ReputationClient {
120
+ /** Cached canonical registry address, discovered from the local contract. */
121
+ private canonicalAddr?: Address;
122
+
123
+ constructor(private readonly ctx: Ctx) {}
124
+
125
+ private get publicClient(): PublicClient { return this.ctx.publicClient; }
126
+ private get walletClient(): WalletClient | undefined { return this.ctx.walletClient; }
127
+ private get account(): Account | undefined { return this.ctx.account; }
128
+ private get chain(): Chain { return this.ctx.chain; }
129
+
130
+ private get verifiedFeedbackAddr(): Address {
131
+ const a = this.ctx.addresses.verifiedFeedback;
132
+ // Zero = "not deployed in this environment" (fromAttestor maps an absent
133
+ // /config address to zero). Fail fast with the real reason instead of
134
+ // letting the contract call die on an undecodable empty response.
135
+ if (a === '0x0000000000000000000000000000000000000000') {
136
+ throw new Error(
137
+ 'reputation: this environment has no VerifiedFeedbackRegistry deployed ' +
138
+ '(the attestor /config reports no verified_feedback_addr) — ' +
139
+ 'the ag.reputation.* methods are unavailable here',
140
+ );
141
+ }
142
+ return a;
143
+ }
144
+
145
+ /** Canonical ERC-8004 ReputationRegistry address — read once from the local contract, then cached. */
146
+ private async canonical(): Promise<Address> {
147
+ if (!this.canonicalAddr) {
148
+ this.canonicalAddr = (await this.publicClient.readContract({
149
+ address: this.verifiedFeedbackAddr,
150
+ abi: verifiedFeedbackAbi,
151
+ functionName: 'getCanonicalReputation',
152
+ })) as Address;
153
+ }
154
+ return this.canonicalAddr;
155
+ }
156
+
157
+ // ── Give Feedback (canonical write + verification mark, bundled) ──
158
+
159
+ /**
160
+ * Give feedback for an agent — canonical ERC-8004 write (attribution = the
161
+ * connected wallet) + ServeProof mark on the VerifiedFeedbackRegistry.
162
+ *
163
+ * Two execution paths:
164
+ * - **Atomic (EIP-7702)** — when the environment advertises a
165
+ * `feedbackBatcher` (only done on 7702-enabled chains): ONE type-4
166
+ * transaction executes both calls in the EOA's own context; either
167
+ * everything lands or nothing does. `feedbackTx === attestTx`, already
168
+ * mined on return.
169
+ * - **Sequential (fallback)** — canonical write (mined in-call so the
170
+ * assigned index can be read), then attest. `attestTx` is returned
171
+ * unmined — wait for it before reading `isVerified`. Because the
172
+ * canonical entry lands first, the proof is checked gas-free beforehand
173
+ * and the known permanent attest failures are refused with nothing
174
+ * broadcast: agent / submitter mismatch, another registry, a deadline
175
+ * past or within 60s, a zero or after-deadline timestamp, a signature not
176
+ * recovering to the on-chain agentSeal, self-feedback (agentSeal / owner
177
+ * / approved / operator / payment wallet) and an already-redeemed proof.
178
+ * On both paths a value outside |value| ≤ 1e9 / 0..18 decimals is
179
+ * refused up front ({@link MAX_ABS_FEEDBACK_VALUE}). Not covered: a paused registry, a deadline
180
+ * beyond the nonce retention, state changing before the attest, non-proof
181
+ * tx failures. If the attest leg still fails, retry it later with
182
+ * `attestFeedback` (the proof is not consumed by a reverted attempt).
183
+ */
184
+ async giveFeedback(params: GiveFeedbackParams): Promise<GiveFeedbackResult> {
185
+ this.requireWallet();
186
+ // Before EITHER path broadcasts: covers the atomic batch and the
187
+ // sequential canonical write that precedes attestFeedbackWithTask.
188
+ if (params.task) assertTaskStatusCode(params.task);
189
+ assertFeedbackValueInRange(params.value, params.valueDecimals ?? 0);
190
+
191
+ const batcher = this.ctx.addresses.feedbackBatcher;
192
+ if (batcher && batcher !== '0x0000000000000000000000000000000000000000') {
193
+ const atomic = await this.giveFeedbackAtomic(batcher, params);
194
+ if (atomic) return atomic;
195
+ // fall through: the wallet couldn't sign a 7702 authorization — nothing
196
+ // was broadcast, so the sequential path is safe to take.
197
+ }
198
+
199
+ await this.preflightServeProof(params.agentId, params.serveProof);
200
+ const canonical = await this.canonical();
201
+ const feedbackTx = await this.walletClient!.writeContract({
202
+ address: canonical,
203
+ abi: canonicalReputationAbi,
204
+ functionName: 'giveFeedback',
205
+ args: [
206
+ params.agentId,
207
+ params.value,
208
+ params.valueDecimals ?? 0,
209
+ params.tag1 ?? '',
210
+ params.tag2 ?? '',
211
+ params.endpoint ?? '',
212
+ params.feedbackURI ?? '',
213
+ params.feedbackHash ?? ('0x' + '0'.repeat(64) as `0x${string}`),
214
+ ],
215
+ account: this.account!,
216
+ chain: this.chain,
217
+ });
218
+ // The attest step needs the entry's canonical index, which only exists
219
+ // once the write mines — this wait is inherent to the flow, not politeness.
220
+ await this.waitForTransaction(feedbackTx);
221
+ const feedbackIndex = await this.getLastIndex(params.agentId, this.account!.address);
222
+ const attestTx = params.task
223
+ ? await this.attestFeedbackWithTask(params.agentId, feedbackIndex, params.serveProof, params.task)
224
+ : await this.attestFeedback(params.agentId, feedbackIndex, params.serveProof);
225
+ return { feedbackTx, attestTx, feedbackIndex };
226
+ }
227
+
228
+ /**
229
+ * Sequential-path preflight. There the canonical entry is written (and
230
+ * mined) BEFORE the registry sees the proof, so a proof that can never
231
+ * attest would leave an orphaned, unverified canonical entry that no
232
+ * `attestFeedback` retry can rescue. Refused here, gas-free (views only)
233
+ * and before anything is broadcast:
234
+ * - agent mismatch (`proof.agentId` ≠ `agentId`) and submitter mismatch
235
+ * (the proof is bound to another wallet) — local checks;
236
+ * - a proof whose envelope names another VerifiedFeedbackRegistry;
237
+ * - a deadline already past, or within {@link ATTEST_DEADLINE_MARGIN_S}
238
+ * of the latest block's timestamp; a zero timestamp or one after the
239
+ * deadline (VerifiedFeedbackInvalidProofTimestamp);
240
+ * - a signature that does not recover to the on-chain agentSeal under
241
+ * this registry's domain (signed for another registry, a pre-upgrade
242
+ * image's legacy personal_sign wrap, an agent with no seal), or an
243
+ * encoding the registry's OZ ECDSA rejects (not 65 bytes, v ∉ {27,28},
244
+ * high s);
245
+ * - self-feedback: the connected wallet is the agentSeal, the agent's
246
+ * owner, its `getApproved` address, an `isApprovedForAll` operator, or
247
+ * the agent's payment wallet (`getAgentWallet`);
248
+ * - a proof already redeemed here (`isNonceConsumed`).
249
+ * NOT prevented — these can still leave the canonical entry unverified: a
250
+ * paused registry, a deadline beyond the registry's nonce retention
251
+ * (NonceDeadlineTooFar), state that changes between this check and the
252
+ * attest (an approval granted, the proof redeemed by a concurrent attest),
253
+ * and the attest transaction failing for non-proof reasons (gas, RPC).
254
+ * Those leave the proof unconsumed; retry with `attestFeedback` where that
255
+ * can help.
256
+ * The atomic path needs none of this: a bad proof reverts the whole batch.
257
+ */
258
+ private async preflightServeProof(agentId: bigint, proof: ServeProof): Promise<void> {
259
+ const registry = this.verifiedFeedbackAddr;
260
+ const agenticID = this.ctx.addresses.agenticID;
261
+ const me = this.account!.address;
262
+ const refuse = (why: string): never => {
263
+ throw new Error(
264
+ `reputation: serve-proof cannot attest (${why}) — refused before the canonical write, nothing was broadcast`,
265
+ );
266
+ };
267
+ if (proof.agentId !== agentId) refuse(`proof is for agent ${proof.agentId}, not ${agentId}`);
268
+ if (proof.submitter.toLowerCase() !== me.toLowerCase()) {
269
+ refuse(`proof is bound to submitter ${proof.submitter}, not the connected wallet ${me}`);
270
+ }
271
+ if (proof.validator && proof.validator.toLowerCase() !== registry.toLowerCase()) {
272
+ refuse(`proof signed for a different VerifiedFeedbackRegistry (proof: ${proof.validator}, configured: ${registry})`);
273
+ }
274
+ if (proof.timestamp === 0n || proof.timestamp > proof.deadline) {
275
+ refuse(`proof timestamp ${proof.timestamp} is zero or after its deadline ${proof.deadline} (VerifiedFeedbackInvalidProofTimestamp)`);
276
+ }
277
+ // NonceExpired is checked against the attest block's timestamp, which is
278
+ // later than the latest one by at least the canonical write's mining.
279
+ const now = (await this.publicClient.getBlock({ blockTag: 'latest' })).timestamp;
280
+ if (proof.deadline <= now + ATTEST_DEADLINE_MARGIN_S) {
281
+ refuse(
282
+ proof.deadline < now
283
+ ? `proof deadline ${proof.deadline} has passed (latest block ${now})`
284
+ : `proof deadline ${proof.deadline} is within ${ATTEST_DEADLINE_MARGIN_S}s of the latest block (${now}) — too close to land the attest`,
285
+ );
286
+ }
287
+ const agentSeal = (await this.publicClient.readContract({
288
+ address: agenticID,
289
+ abi: agenticIDAbi,
290
+ functionName: 'getAgentSeal',
291
+ args: [agentId],
292
+ })) as Address;
293
+ if (agentSeal.toLowerCase() === me.toLowerCase()) {
294
+ refuse("the connected wallet is this agent's own agentSeal (VerifiedFeedbackSelfFeedback)");
295
+ }
296
+ const signerMatches =
297
+ agentSeal !== ZERO_ADDRESS &&
298
+ (await verifyServeProofSignature(proof, agentSeal, {
299
+ chainId: BigInt(this.chain.id),
300
+ verifyingContract: agenticID,
301
+ validator: registry,
302
+ }));
303
+ if (!signerMatches) {
304
+ refuse(
305
+ proof.validator
306
+ ? 'signature does not match the on-chain agentSeal'
307
+ : 'signature does not match the on-chain agentSeal; the proof names no validator — likely a pre-upgrade sealed image, which only an owner reset fixes',
308
+ );
309
+ }
310
+ // Owner / operator self-feedback — the registry's ERC-721 checks against
311
+ // the local AgenticID owner (the agent exists: its seal is non-zero).
312
+ const owner = (await this.publicClient.readContract({
313
+ address: agenticID, abi: agenticIDAbi, functionName: 'ownerOf', args: [agentId],
314
+ })) as Address;
315
+ if (owner.toLowerCase() === me.toLowerCase()) {
316
+ refuse("the connected wallet owns this agent (VerifiedFeedbackSelfFeedback)");
317
+ }
318
+ const [approved, operator, paymentWallet] = await Promise.all([
319
+ this.publicClient.readContract({
320
+ address: agenticID, abi: agenticIDAbi, functionName: 'getApproved', args: [agentId],
321
+ }) as Promise<Address>,
322
+ this.publicClient.readContract({
323
+ address: agenticID, abi: agenticIDAbi, functionName: 'isApprovedForAll', args: [owner, me],
324
+ }) as Promise<boolean>,
325
+ this.publicClient.readContract({
326
+ address: agenticID, abi: agenticIDAbi, functionName: 'getAgentWallet', args: [agentId],
327
+ }) as Promise<Address>,
328
+ ]);
329
+ if (approved.toLowerCase() === me.toLowerCase()) {
330
+ refuse("the connected wallet is this agent's approved address (VerifiedFeedbackSelfFeedback)");
331
+ }
332
+ if (operator) {
333
+ refuse("the connected wallet is an approved operator of this agent's owner (VerifiedFeedbackSelfFeedback)");
334
+ }
335
+ if (paymentWallet.toLowerCase() === me.toLowerCase()) {
336
+ refuse("the connected wallet is this agent's payment wallet (VerifiedFeedbackSelfFeedback)");
337
+ }
338
+ const consumed = (await this.publicClient.readContract({
339
+ address: registry,
340
+ abi: verifiedFeedbackAbi,
341
+ functionName: 'isNonceConsumed',
342
+ args: [serveProofNonceKey(proof.agentId, proof.signature)],
343
+ })) as boolean;
344
+ if (consumed) refuse('this proof was already redeemed at this registry (NonceAlreadyUsed)');
345
+ }
346
+
347
+ /**
348
+ * Atomic (EIP-7702) leg of giveFeedback. Returns null ONLY when no
349
+ * transaction was broadcast (the wallet can't sign a 7702 authorization) —
350
+ * the caller then safely falls back to the sequential flow. Failures after
351
+ * broadcast propagate: the batch reverts as a whole, nothing is written,
352
+ * and silently retrying sequentially could orphan a canonical entry the
353
+ * user didn't ask for twice.
354
+ */
355
+ private async giveFeedbackAtomic(
356
+ batcher: Address,
357
+ params: GiveFeedbackParams,
358
+ ): Promise<GiveFeedbackResult | null> {
359
+ const me = this.account!.address;
360
+
361
+ // Delegation designator this EOA needs: 0xef0100 ‖ batcher.
362
+ const designator = ('0xef0100' + batcher.slice(2)).toLowerCase();
363
+ const code = (await this.publicClient.getCode({ address: me })) ?? '0x';
364
+ let authorizationList;
365
+ if (code.toLowerCase() !== designator) {
366
+ try {
367
+ authorizationList = [
368
+ await this.walletClient!.signAuthorization({
369
+ account: this.account!,
370
+ contractAddress: batcher,
371
+ // The EOA itself sends the type-4 tx (auth nonce = account nonce + 1).
372
+ executor: 'self',
373
+ }),
374
+ ];
375
+ } catch {
376
+ return null; // wallet can't do 7702 (e.g. JSON-RPC account) — no side effects yet
377
+ }
378
+ }
379
+
380
+ const sp = params.serveProof;
381
+ const txHash = await this.walletClient!.sendTransaction({
382
+ account: this.account!,
383
+ chain: this.chain,
384
+ to: me, // self-call executes the delegated batcher code as the EOA
385
+ data: encodeFunctionData({
386
+ abi: feedbackBatcherAbi,
387
+ functionName: 'giveFeedbackAndAttest',
388
+ args: [
389
+ params.agentId,
390
+ params.value,
391
+ params.valueDecimals ?? 0,
392
+ params.tag1 ?? '',
393
+ params.tag2 ?? '',
394
+ params.endpoint ?? '',
395
+ params.feedbackURI ?? '',
396
+ params.feedbackHash ?? ('0x' + '0'.repeat(64) as `0x${string}`),
397
+ // Field by field — the eight on-chain ServeProof fields. The proof's
398
+ // informational `validator` is not one of them (ABI encoding would
399
+ // drop an undeclared key anyway; this keeps the intent explicit).
400
+ {
401
+ agentId: sp.agentId,
402
+ submitter: sp.submitter,
403
+ timestamp: sp.timestamp,
404
+ deadline: sp.deadline,
405
+ taskHash: sp.taskHash,
406
+ dataHashes: sp.dataHashes,
407
+ frameworkHash: sp.frameworkHash,
408
+ signature: sp.signature,
409
+ },
410
+ // No task: placeholder with an EMPTY method — FeedbackBatcher routes
411
+ // that to plain attestFeedback, so statusCode 0 is never checked.
412
+ params.task ?? { method: '', uri: '', reqBodyHash: ZERO32, respBodyHash: ZERO32, statusCode: 0 },
413
+ ],
414
+ }),
415
+ authorizationList,
416
+ });
417
+
418
+ const receipt = await this.waitForTransaction(txHash);
419
+ if (receipt.status !== 'success') {
420
+ throw new Error(
421
+ `atomic feedback batch reverted (tx ${txHash}) — nothing was written; ` +
422
+ 'check the proof (expired deadline / timestamp after deadline / wrong submitter / ' +
423
+ 'self-feedback by the owner, an approved operator, the payment wallet or the agentSeal / ' +
424
+ 'proof signed for a different registry or by a pre-upgrade sealed image)',
425
+ );
426
+ }
427
+ const events = parseEventLogs({
428
+ abi: verifiedFeedbackAbi,
429
+ logs: receipt.logs,
430
+ eventName: 'FeedbackVerified',
431
+ });
432
+ if (events.length === 0) {
433
+ throw new Error(`atomic feedback batch mined without a FeedbackVerified event (tx ${txHash})`);
434
+ }
435
+ const feedbackIndex = BigInt((events[0].args as { feedbackIndex: bigint }).feedbackIndex);
436
+ return { feedbackTx: txHash, attestTx: txHash, feedbackIndex };
437
+ }
438
+
439
+ /**
440
+ * Attest an EXISTING canonical feedback entry of the connected wallet with
441
+ * a ServeProof (the second half of `giveFeedback`, exposed for callers that
442
+ * submitted the canonical entry separately).
443
+ */
444
+ async attestFeedback(
445
+ agentId: bigint,
446
+ feedbackIndex: bigint,
447
+ proof: ServeProof,
448
+ ): Promise<WriteContractReturnType> {
449
+ this.requireWallet();
450
+ return this.walletClient!.writeContract({
451
+ address: this.verifiedFeedbackAddr,
452
+ abi: verifiedFeedbackAbi,
453
+ functionName: 'attestFeedback',
454
+ args: [
455
+ agentId,
456
+ feedbackIndex,
457
+ {
458
+ agentId: proof.agentId,
459
+ submitter: proof.submitter,
460
+ timestamp: proof.timestamp,
461
+ deadline: proof.deadline,
462
+ taskHash: proof.taskHash,
463
+ dataHashes: proof.dataHashes,
464
+ frameworkHash: proof.frameworkHash,
465
+ signature: proof.signature,
466
+ },
467
+ ],
468
+ account: this.account!,
469
+ chain: this.chain,
470
+ });
471
+ }
472
+
473
+ /**
474
+ * Like {@link attestFeedback}, additionally opening the proof's taskHash
475
+ * commitment: the contract recomputes the hash from the revealed receipt
476
+ * materials and records `task.uri` as the entry's TEE-verified endpoint.
477
+ */
478
+ async attestFeedbackWithTask(
479
+ agentId: bigint,
480
+ feedbackIndex: bigint,
481
+ proof: ServeProof,
482
+ task: TaskReveal,
483
+ ): Promise<WriteContractReturnType> {
484
+ this.requireWallet();
485
+ assertTaskStatusCode(task);
486
+ return this.walletClient!.writeContract({
487
+ address: this.verifiedFeedbackAddr,
488
+ abi: verifiedFeedbackAbi,
489
+ functionName: 'attestFeedbackWithTask',
490
+ args: [
491
+ agentId,
492
+ feedbackIndex,
493
+ {
494
+ agentId: proof.agentId,
495
+ submitter: proof.submitter,
496
+ timestamp: proof.timestamp,
497
+ deadline: proof.deadline,
498
+ taskHash: proof.taskHash,
499
+ dataHashes: proof.dataHashes,
500
+ frameworkHash: proof.frameworkHash,
501
+ signature: proof.signature,
502
+ },
503
+ task,
504
+ ],
505
+ account: this.account!,
506
+ chain: this.chain,
507
+ });
508
+ }
509
+
510
+ // ── Canonical writes ──
511
+
512
+ /**
513
+ * Revoke previously given feedback (on the canonical registry; the
514
+ * verification mark stays, but verified summaries skip revoked entries).
515
+ */
516
+ async revokeFeedback(agentId: bigint, feedbackIndex: bigint): Promise<WriteContractReturnType> {
517
+ this.requireWallet();
518
+ return this.walletClient!.writeContract({
519
+ address: await this.canonical(),
520
+ abi: canonicalReputationAbi,
521
+ functionName: 'revokeFeedback',
522
+ args: [agentId, feedbackIndex],
523
+ account: this.account!,
524
+ chain: this.chain,
525
+ });
526
+ }
527
+
528
+ /**
529
+ * Append a response to a feedback entry (on the canonical registry).
530
+ */
531
+ async appendResponse(params: AppendResponseParams): Promise<WriteContractReturnType> {
532
+ this.requireWallet();
533
+ return this.walletClient!.writeContract({
534
+ address: await this.canonical(),
535
+ abi: canonicalReputationAbi,
536
+ functionName: 'appendResponse',
537
+ args: [
538
+ params.agentId,
539
+ params.clientAddress,
540
+ params.feedbackIndex,
541
+ params.responseURI,
542
+ params.responseHash,
543
+ ],
544
+ account: this.account!,
545
+ chain: this.chain,
546
+ });
547
+ }
548
+
549
+ // ── Canonical reads (feedback values) ──
550
+
551
+ /**
552
+ * Read a single canonical feedback entry (1-based index).
553
+ */
554
+ async readFeedback(
555
+ agentId: bigint,
556
+ clientAddress: Address,
557
+ feedbackIndex: bigint,
558
+ ): Promise<Feedback> {
559
+ const result = await this.publicClient.readContract({
560
+ address: await this.canonical(),
561
+ abi: canonicalReputationAbi,
562
+ functionName: 'readFeedback',
563
+ args: [agentId, clientAddress, feedbackIndex],
564
+ });
565
+ const [value, valueDecimals, tag1, tag2, isRevoked] = result as [bigint, number, string, string, boolean];
566
+ return { value, valueDecimals, tag1, tag2, isRevoked };
567
+ }
568
+
569
+ /**
570
+ * Read all canonical feedback for an agent, optionally filtered by clients
571
+ * and tags. Includes UNVERIFIED entries — the canonical registry is
572
+ * permissionless; intersect with `isVerified`/`getVerifiedIndexes` when
573
+ * authenticity matters.
574
+ */
575
+ async readAllFeedback(params: ReadAllFeedbackParams): Promise<Feedback[]> {
576
+ const result = await this.publicClient.readContract({
577
+ address: await this.canonical(),
578
+ abi: canonicalReputationAbi,
579
+ functionName: 'readAllFeedback',
580
+ args: [
581
+ params.agentId,
582
+ (params.clientAddresses ?? []),
583
+ (params.tag1 ?? ''),
584
+ (params.tag2 ?? ''),
585
+ (params.includeRevoked ?? false),
586
+ ],
587
+ });
588
+ const [, , values, valueDecimals, tag1s, tag2s, revokedStatuses] = result as [
589
+ `0x${string}`[], bigint[], bigint[], number[], string[], string[], boolean[],
590
+ ];
591
+ return values.map((value, i) => ({
592
+ value,
593
+ valueDecimals: valueDecimals[i],
594
+ tag1: tag1s[i],
595
+ tag2: tag2s[i],
596
+ isRevoked: revokedStatuses[i],
597
+ }));
598
+ }
599
+
600
+ /**
601
+ * Summary over RAW canonical feedback (verified or not). For the
602
+ * TEE-verified aggregate use `getVerifiedSummary`.
603
+ */
604
+ async getSummary(params: GetSummaryParams): Promise<FeedbackSummary> {
605
+ // getSummary reverts on an empty clientAddresses list — when the caller
606
+ // doesn't scope to specific clients, default to "all clients that have
607
+ // left feedback" (getClients), matching the intuitive "summary of
608
+ // everything". No clients yet → empty summary rather than a revert.
609
+ let clients = params.clientAddresses ?? [];
610
+ if (clients.length === 0) {
611
+ clients = await this.getClients(params.agentId);
612
+ if (clients.length === 0) return { count: 0n, summaryValue: 0n, summaryValueDecimals: 0 };
613
+ }
614
+ const result = await this.publicClient.readContract({
615
+ address: await this.canonical(),
616
+ abi: canonicalReputationAbi,
617
+ functionName: 'getSummary',
618
+ args: [params.agentId, clients, (params.tag1 ?? ''), (params.tag2 ?? '')],
619
+ });
620
+ const [count, summaryValue, summaryValueDecimals] = result as [bigint, bigint, number];
621
+ return { count, summaryValue, summaryValueDecimals };
622
+ }
623
+
624
+ /**
625
+ * Get the response count for a feedback entry from specified responders.
626
+ */
627
+ async getResponseCount(
628
+ agentId: bigint,
629
+ clientAddress: Address,
630
+ feedbackIndex: bigint,
631
+ responders: Address[],
632
+ ): Promise<bigint> {
633
+ return this.publicClient.readContract({
634
+ address: await this.canonical(),
635
+ abi: canonicalReputationAbi,
636
+ functionName: 'getResponseCount',
637
+ args: [agentId, clientAddress, feedbackIndex, responders],
638
+ }) as Promise<bigint>;
639
+ }
640
+
641
+ /**
642
+ * All clients who have given canonical feedback for an agent (verified or
643
+ * not — see `getVerifiedClients` for the proof-backed subset).
644
+ */
645
+ async getClients(agentId: bigint): Promise<Address[]> {
646
+ return this.publicClient.readContract({
647
+ address: await this.canonical(),
648
+ abi: canonicalReputationAbi,
649
+ functionName: 'getClients',
650
+ args: [agentId],
651
+ }) as Promise<Address[]>;
652
+ }
653
+
654
+ /**
655
+ * The last (1-based) canonical feedback index for a client on an agent;
656
+ * 0 when there is none.
657
+ */
658
+ async getLastIndex(agentId: bigint, clientAddress: Address): Promise<bigint> {
659
+ return this.publicClient.readContract({
660
+ address: await this.canonical(),
661
+ abi: canonicalReputationAbi,
662
+ functionName: 'getLastIndex',
663
+ args: [agentId, clientAddress],
664
+ }) as Promise<bigint>;
665
+ }
666
+
667
+ // ── Verified reads (TEE marks) ──
668
+
669
+ /**
670
+ * Whether the canonical entry (agentId, clientAddress, feedbackIndex) was
671
+ * attested with a valid ServeProof.
672
+ */
673
+ async isVerified(agentId: bigint, clientAddress: Address, feedbackIndex: bigint): Promise<boolean> {
674
+ return this.publicClient.readContract({
675
+ address: this.verifiedFeedbackAddr,
676
+ abi: verifiedFeedbackAbi,
677
+ functionName: 'isVerified',
678
+ args: [agentId, clientAddress, feedbackIndex],
679
+ }) as Promise<boolean>;
680
+ }
681
+
682
+ /**
683
+ * All verified canonical feedback indexes of a client for an agent.
684
+ */
685
+ async getVerifiedIndexes(agentId: bigint, clientAddress: Address): Promise<bigint[]> {
686
+ const r = await this.publicClient.readContract({
687
+ address: this.verifiedFeedbackAddr,
688
+ abi: verifiedFeedbackAbi,
689
+ functionName: 'getVerifiedIndexes',
690
+ args: [agentId, clientAddress],
691
+ });
692
+ return r as bigint[];
693
+ }
694
+
695
+ /**
696
+ * All clients with at least one verified entry for an agent.
697
+ */
698
+ async getVerifiedClients(agentId: bigint): Promise<Address[]> {
699
+ return this.publicClient.readContract({
700
+ address: this.verifiedFeedbackAddr,
701
+ abi: verifiedFeedbackAbi,
702
+ functionName: 'getVerifiedClients',
703
+ args: [agentId],
704
+ }) as Promise<Address[]>;
705
+ }
706
+
707
+ /**
708
+ * Summary over VERIFIED canonical feedback only (values read live from the
709
+ * canonical registry; revoked entries and pre-1.2.0 marks outside
710
+ * |value| ≤ 1e9 / 18 decimals skipped). Empty `clientAddresses`
711
+ * defaults to all verified clients (the contract itself requires a
712
+ * non-empty set); no verified clients yet → empty summary.
713
+ */
714
+ async getVerifiedSummary(params: GetSummaryParams): Promise<FeedbackSummary> {
715
+ let clients = params.clientAddresses ?? [];
716
+ if (clients.length === 0) {
717
+ clients = await this.getVerifiedClients(params.agentId);
718
+ if (clients.length === 0) return { count: 0n, summaryValue: 0n, summaryValueDecimals: 0 };
719
+ }
720
+ const result = await this.publicClient.readContract({
721
+ address: this.verifiedFeedbackAddr,
722
+ abi: verifiedFeedbackAbi,
723
+ functionName: 'getVerifiedSummary',
724
+ args: [params.agentId, clients, (params.tag1 ?? ''), (params.tag2 ?? '')],
725
+ });
726
+ const [count, summaryValue, summaryValueDecimals] = result as [bigint, bigint, number];
727
+ return { count, summaryValue, summaryValueDecimals };
728
+ }
729
+
730
+ /**
731
+ * The TEE-verified endpoint of a verified entry — empty string when it was
732
+ * attested without opening its task receipt.
733
+ */
734
+ async getVerifiedEndpoint(agentId: bigint, clientAddress: Address, feedbackIndex: bigint): Promise<string> {
735
+ return this.publicClient.readContract({
736
+ address: this.verifiedFeedbackAddr,
737
+ abi: verifiedFeedbackAbi,
738
+ functionName: 'getVerifiedEndpoint',
739
+ args: [agentId, clientAddress, feedbackIndex],
740
+ }) as Promise<string>;
741
+ }
742
+
743
+ /**
744
+ * Summary over verified entries whose TEE-verified endpoint equals `uri`
745
+ * (non-empty). Empty `clientAddresses` defaults to all verified clients;
746
+ * none yet → empty summary.
747
+ */
748
+ async getVerifiedSummaryForEndpoint(
749
+ agentId: bigint,
750
+ uri: string,
751
+ clientAddresses?: Address[],
752
+ ): Promise<FeedbackSummary> {
753
+ // The registry reverts on "" (VerifiedFeedbackEndpointRequired): entries
754
+ // attested without a task reveal store "", so it would match exactly the
755
+ // unproven ones.
756
+ if (uri === '') throw new Error('reputation: getVerifiedSummaryForEndpoint needs a non-empty uri');
757
+ let clients = clientAddresses ?? [];
758
+ if (clients.length === 0) {
759
+ clients = await this.getVerifiedClients(agentId);
760
+ if (clients.length === 0) return { count: 0n, summaryValue: 0n, summaryValueDecimals: 0 };
761
+ }
762
+ const result = await this.publicClient.readContract({
763
+ address: this.verifiedFeedbackAddr,
764
+ abi: verifiedFeedbackAbi,
765
+ functionName: 'getVerifiedSummaryForEndpoint',
766
+ args: [agentId, clients, uri],
767
+ });
768
+ const [count, summaryValue, summaryValueDecimals] = result as [bigint, bigint, number];
769
+ return { count, summaryValue, summaryValueDecimals };
770
+ }
771
+
772
+ /**
773
+ * Serve-proof audit data stored for a VERIFIED entry: the dataHashes and
774
+ * frameworkHash in effect when that feedback's service call happened.
775
+ * Buyer due-diligence entrypoint — compare against intelligentDatasOf().
776
+ */
777
+ async getServeData(
778
+ agentId: bigint,
779
+ clientAddress: Address,
780
+ feedbackIndex: bigint,
781
+ ): Promise<ServeData> {
782
+ const result = await this.publicClient.readContract({
783
+ address: this.verifiedFeedbackAddr,
784
+ abi: verifiedFeedbackAbi,
785
+ functionName: 'getServeData',
786
+ args: [agentId, clientAddress, feedbackIndex],
787
+ });
788
+ const [dataHashes, frameworkHash] = result as [Hash[], Hash];
789
+ return { dataHashes, frameworkHash };
790
+ }
791
+
792
+ // ── Transaction Helpers ──
793
+
794
+ /**
795
+ * Wait for a transaction to be mined and return the receipt.
796
+ */
797
+ async waitForTransaction(txHash: Hash): Promise<TransactionReceipt> {
798
+ return this.publicClient.waitForTransactionReceipt({ hash: txHash, ...RECEIPT_WAIT });
799
+ }
800
+
801
+ // ── Private helpers ──
802
+
803
+ /**
804
+ * Ensure a wallet client and account are available for write operations.
805
+ * @throws if no wallet client or account is set
806
+ */
807
+ private requireWallet(): void {
808
+ if (!this.walletClient) {
809
+ throw new Error(
810
+ 'ReputationClient: walletClient is required for write operations. ' +
811
+ 'Provide it in the constructor options.'
812
+ );
813
+ }
814
+ if (!this.account) {
815
+ throw new Error(
816
+ 'ReputationClient: account is required for write operations. ' +
817
+ 'Provide it in the constructor options.'
818
+ );
819
+ }
820
+ }
821
+ }