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