@0gfoundation/0g-agentdna 0.2.3 → 0.5.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 (255) hide show
  1. package/GUIDE.md +190 -40
  2. package/OPERATORS.md +164 -0
  3. package/OPERATORS.zh.md +141 -0
  4. package/PROVIDERS.md +6 -0
  5. package/PROVIDERS.zh.md +3 -1
  6. package/README.md +84 -11
  7. package/dist/AgentClient.d.ts +374 -26
  8. package/dist/AgentClient.d.ts.map +1 -1
  9. package/dist/AgentClient.js +323 -40
  10. package/dist/AgentClient.js.map +1 -1
  11. package/dist/AgenticID.d.ts +170 -80
  12. package/dist/AgenticID.d.ts.map +1 -1
  13. package/dist/AgenticID.js +300 -42
  14. package/dist/AgenticID.js.map +1 -1
  15. package/dist/AttestorClient.d.ts +115 -31
  16. package/dist/AttestorClient.d.ts.map +1 -1
  17. package/dist/AttestorClient.js +276 -56
  18. package/dist/AttestorClient.js.map +1 -1
  19. package/dist/Credentials.d.ts +574 -0
  20. package/dist/Credentials.d.ts.map +1 -0
  21. package/dist/Credentials.js +838 -0
  22. package/dist/Credentials.js.map +1 -0
  23. package/dist/Operators.d.ts +60 -0
  24. package/dist/Operators.d.ts.map +1 -0
  25. package/dist/Operators.js +38 -0
  26. package/dist/Operators.js.map +1 -0
  27. package/dist/Providers.d.ts +13 -0
  28. package/dist/Providers.d.ts.map +1 -1
  29. package/dist/Providers.js +20 -1
  30. package/dist/Providers.js.map +1 -1
  31. package/dist/Releases.d.ts +51 -0
  32. package/dist/Releases.d.ts.map +1 -0
  33. package/dist/Releases.js +72 -0
  34. package/dist/Releases.js.map +1 -0
  35. package/dist/ReputationClient.d.ts +47 -3
  36. package/dist/ReputationClient.d.ts.map +1 -1
  37. package/dist/ReputationClient.js +204 -78
  38. package/dist/ReputationClient.js.map +1 -1
  39. package/dist/ServeProof.d.ts +70 -23
  40. package/dist/ServeProof.d.ts.map +1 -1
  41. package/dist/ServeProof.js +94 -35
  42. package/dist/ServeProof.js.map +1 -1
  43. package/dist/ServeSession.d.ts +17 -2
  44. package/dist/ServeSession.d.ts.map +1 -1
  45. package/dist/ServeSession.js +77 -9
  46. package/dist/ServeSession.js.map +1 -1
  47. package/dist/Settings.d.ts +25 -1
  48. package/dist/Settings.d.ts.map +1 -1
  49. package/dist/Settings.js +53 -1
  50. package/dist/Settings.js.map +1 -1
  51. package/dist/TrustRegistry.d.ts +28 -0
  52. package/dist/TrustRegistry.d.ts.map +1 -0
  53. package/dist/TrustRegistry.js +67 -0
  54. package/dist/TrustRegistry.js.map +1 -0
  55. package/dist/abi.d.ts +346 -34
  56. package/dist/abi.d.ts.map +1 -1
  57. package/dist/abi.js +150 -30
  58. package/dist/abi.js.map +1 -1
  59. package/dist/cli/attach.d.ts +79 -0
  60. package/dist/cli/attach.d.ts.map +1 -0
  61. package/dist/cli/attach.js +253 -0
  62. package/dist/cli/attach.js.map +1 -0
  63. package/dist/cli/commands/cells.d.ts +45 -0
  64. package/dist/cli/commands/cells.d.ts.map +1 -1
  65. package/dist/cli/commands/cells.js +77 -0
  66. package/dist/cli/commands/cells.js.map +1 -1
  67. package/dist/cli/commands/cred.d.ts +12 -0
  68. package/dist/cli/commands/cred.d.ts.map +1 -0
  69. package/dist/cli/commands/cred.js +43 -0
  70. package/dist/cli/commands/cred.js.map +1 -0
  71. package/dist/cli/commands/doctor.d.ts.map +1 -1
  72. package/dist/cli/commands/doctor.js +44 -35
  73. package/dist/cli/commands/doctor.js.map +1 -1
  74. package/dist/cli/commands/interactive.d.ts +597 -21
  75. package/dist/cli/commands/interactive.d.ts.map +1 -1
  76. package/dist/cli/commands/interactive.js +5082 -1323
  77. package/dist/cli/commands/interactive.js.map +1 -1
  78. package/dist/cli/commands/list.d.ts +5 -5
  79. package/dist/cli/commands/list.d.ts.map +1 -1
  80. package/dist/cli/commands/list.js +21 -26
  81. package/dist/cli/commands/list.js.map +1 -1
  82. package/dist/cli/commands/providers.d.ts +4 -0
  83. package/dist/cli/commands/providers.d.ts.map +1 -1
  84. package/dist/cli/commands/providers.js +19 -5
  85. package/dist/cli/commands/providers.js.map +1 -1
  86. package/dist/cli/commands/releases.d.ts +13 -0
  87. package/dist/cli/commands/releases.d.ts.map +1 -0
  88. package/dist/cli/commands/releases.js +65 -0
  89. package/dist/cli/commands/releases.js.map +1 -0
  90. package/dist/cli/commands/settings.d.ts +5 -0
  91. package/dist/cli/commands/settings.d.ts.map +1 -1
  92. package/dist/cli/commands/settings.js +70 -24
  93. package/dist/cli/commands/settings.js.map +1 -1
  94. package/dist/cli/commands/status.d.ts +2 -1
  95. package/dist/cli/commands/status.d.ts.map +1 -1
  96. package/dist/cli/commands/status.js +22 -19
  97. package/dist/cli/commands/status.js.map +1 -1
  98. package/dist/cli/config.d.ts +48 -1
  99. package/dist/cli/config.d.ts.map +1 -1
  100. package/dist/cli/config.js +114 -5
  101. package/dist/cli/config.js.map +1 -1
  102. package/dist/cli/credentials.d.ts +179 -0
  103. package/dist/cli/credentials.d.ts.map +1 -0
  104. package/dist/cli/credentials.js +1443 -0
  105. package/dist/cli/credentials.js.map +1 -0
  106. package/dist/cli/download.d.ts +21 -0
  107. package/dist/cli/download.d.ts.map +1 -0
  108. package/dist/cli/download.js +89 -0
  109. package/dist/cli/download.js.map +1 -0
  110. package/dist/cli/env.d.ts +6 -0
  111. package/dist/cli/env.d.ts.map +1 -1
  112. package/dist/cli/env.js +18 -6
  113. package/dist/cli/env.js.map +1 -1
  114. package/dist/cli/envelope.d.ts +4 -2
  115. package/dist/cli/envelope.d.ts.map +1 -1
  116. package/dist/cli/envelope.js +10 -6
  117. package/dist/cli/envelope.js.map +1 -1
  118. package/dist/cli/errors.d.ts +45 -1
  119. package/dist/cli/errors.d.ts.map +1 -1
  120. package/dist/cli/errors.js +77 -0
  121. package/dist/cli/errors.js.map +1 -1
  122. package/dist/cli/inference.d.ts.map +1 -1
  123. package/dist/cli/inference.js +7 -0
  124. package/dist/cli/inference.js.map +1 -1
  125. package/dist/cli/inkView.d.ts +341 -0
  126. package/dist/cli/inkView.d.ts.map +1 -0
  127. package/dist/cli/inkView.js +1019 -0
  128. package/dist/cli/inkView.js.map +1 -0
  129. package/dist/cli/legacy/modelKey.d.ts +24 -0
  130. package/dist/cli/legacy/modelKey.d.ts.map +1 -0
  131. package/dist/cli/legacy/modelKey.js +32 -0
  132. package/dist/cli/legacy/modelKey.js.map +1 -0
  133. package/dist/cli/livePrompt.d.ts +212 -0
  134. package/dist/cli/livePrompt.d.ts.map +1 -0
  135. package/dist/cli/livePrompt.js +576 -0
  136. package/dist/cli/livePrompt.js.map +1 -0
  137. package/dist/cli/main.js +206 -72
  138. package/dist/cli/main.js.map +1 -1
  139. package/dist/cli/modelkey.d.ts +64 -0
  140. package/dist/cli/modelkey.d.ts.map +1 -0
  141. package/dist/cli/modelkey.js +113 -0
  142. package/dist/cli/modelkey.js.map +1 -0
  143. package/dist/cli/outboxSync.d.ts +51 -0
  144. package/dist/cli/outboxSync.d.ts.map +1 -0
  145. package/dist/cli/outboxSync.js +210 -0
  146. package/dist/cli/outboxSync.js.map +1 -0
  147. package/dist/cli/plain.d.ts +46 -0
  148. package/dist/cli/plain.d.ts.map +1 -0
  149. package/dist/cli/plain.js +260 -0
  150. package/dist/cli/plain.js.map +1 -0
  151. package/dist/cli/proofs.d.ts +5 -0
  152. package/dist/cli/proofs.d.ts.map +1 -1
  153. package/dist/cli/proofs.js +20 -0
  154. package/dist/cli/proofs.js.map +1 -1
  155. package/dist/cli/ref.d.ts.map +1 -1
  156. package/dist/cli/ref.js +3 -2
  157. package/dist/cli/ref.js.map +1 -1
  158. package/dist/cli/releaseNotice.d.ts +64 -0
  159. package/dist/cli/releaseNotice.d.ts.map +1 -0
  160. package/dist/cli/releaseNotice.js +194 -0
  161. package/dist/cli/releaseNotice.js.map +1 -0
  162. package/dist/cli/sdk.d.ts +18 -0
  163. package/dist/cli/sdk.d.ts.map +1 -1
  164. package/dist/cli/sdk.js +99 -1
  165. package/dist/cli/sdk.js.map +1 -1
  166. package/dist/cli/settings.d.ts +90 -9
  167. package/dist/cli/settings.d.ts.map +1 -1
  168. package/dist/cli/settings.js +273 -21
  169. package/dist/cli/settings.js.map +1 -1
  170. package/dist/cli/textfit.d.ts +28 -0
  171. package/dist/cli/textfit.d.ts.map +1 -0
  172. package/dist/cli/textfit.js +111 -0
  173. package/dist/cli/textfit.js.map +1 -0
  174. package/dist/constants.d.ts +1 -1
  175. package/dist/constants.js +1 -1
  176. package/dist/context.d.ts +26 -0
  177. package/dist/context.d.ts.map +1 -1
  178. package/dist/context.js +1 -0
  179. package/dist/context.js.map +1 -1
  180. package/dist/index.d.ts +19 -11
  181. package/dist/index.d.ts.map +1 -1
  182. package/dist/index.js +35 -2
  183. package/dist/index.js.map +1 -1
  184. package/dist/legacy/modelKey.d.ts +67 -0
  185. package/dist/legacy/modelKey.d.ts.map +1 -0
  186. package/dist/legacy/modelKey.js +80 -0
  187. package/dist/legacy/modelKey.js.map +1 -0
  188. package/dist/legacy/serveProofV1.d.ts +56 -0
  189. package/dist/legacy/serveProofV1.d.ts.map +1 -0
  190. package/dist/legacy/serveProofV1.js +91 -0
  191. package/dist/legacy/serveProofV1.js.map +1 -0
  192. package/dist/provider-catalog.json +3 -2
  193. package/dist/secretEnv.d.ts +18 -3
  194. package/dist/secretEnv.d.ts.map +1 -1
  195. package/dist/secretEnv.js +16 -2
  196. package/dist/secretEnv.js.map +1 -1
  197. package/dist/types.d.ts +63 -1
  198. package/dist/types.d.ts.map +1 -1
  199. package/dist/viemErrors.d.ts +30 -0
  200. package/dist/viemErrors.d.ts.map +1 -0
  201. package/dist/viemErrors.js +36 -0
  202. package/dist/viemErrors.js.map +1 -0
  203. package/package.json +5 -1
  204. package/src/AgentClient.ts +622 -68
  205. package/src/AgenticID.ts +345 -56
  206. package/src/AttestorClient.ts +330 -83
  207. package/src/Credentials.ts +1027 -0
  208. package/src/Operators.ts +71 -0
  209. package/src/Providers.ts +20 -0
  210. package/src/Releases.ts +95 -0
  211. package/src/ReputationClient.ts +231 -79
  212. package/src/ServeProof.ts +123 -39
  213. package/src/ServeSession.ts +91 -9
  214. package/src/Settings.ts +61 -1
  215. package/src/TrustRegistry.ts +75 -0
  216. package/src/abi.ts +153 -30
  217. package/src/cli/attach.ts +257 -0
  218. package/src/cli/commands/cells.ts +104 -0
  219. package/src/cli/commands/cred.ts +44 -0
  220. package/src/cli/commands/doctor.ts +45 -37
  221. package/src/cli/commands/interactive.ts +4120 -664
  222. package/src/cli/commands/list.ts +21 -30
  223. package/src/cli/commands/providers.ts +17 -4
  224. package/src/cli/commands/releases.ts +60 -0
  225. package/src/cli/commands/settings.ts +75 -28
  226. package/src/cli/commands/status.ts +24 -21
  227. package/src/cli/config.ts +119 -4
  228. package/src/cli/credentials.ts +1379 -0
  229. package/src/cli/download.ts +80 -0
  230. package/src/cli/env.ts +22 -7
  231. package/src/cli/envelope.ts +10 -6
  232. package/src/cli/errors.ts +92 -0
  233. package/src/cli/inference.ts +8 -1
  234. package/src/cli/inkView.ts +969 -0
  235. package/src/cli/legacy/modelKey.ts +35 -0
  236. package/src/cli/livePrompt.ts +615 -0
  237. package/src/cli/main.ts +206 -76
  238. package/src/cli/modelkey.ts +124 -0
  239. package/src/cli/outboxSync.ts +231 -0
  240. package/src/cli/plain.ts +260 -0
  241. package/src/cli/proofs.ts +27 -0
  242. package/src/cli/ref.ts +5 -4
  243. package/src/cli/releaseNotice.ts +200 -0
  244. package/src/cli/sdk.ts +87 -7
  245. package/src/cli/settings.ts +275 -25
  246. package/src/cli/textfit.ts +95 -0
  247. package/src/constants.ts +1 -1
  248. package/src/context.ts +28 -0
  249. package/src/index.ts +50 -7
  250. package/src/legacy/modelKey.ts +80 -0
  251. package/src/legacy/serveProofV1.ts +124 -0
  252. package/src/provider-catalog.json +3 -2
  253. package/src/secretEnv.ts +18 -3
  254. package/src/types.ts +60 -1
  255. package/src/viemErrors.ts +39 -0
@@ -0,0 +1,71 @@
1
+ import type { Address, Hash } from 'viem';
2
+
3
+ /** Owner-signed, agent-scoped runtime delegation (not an NFT approval). */
4
+ export const OPERATOR_DOMAIN = 'AgenticID.Operator.v1';
5
+
6
+ /** End-of-block ownership checkpoint covered by the owner's grant signature. */
7
+ export interface OperatorCheckpoint {
8
+ number: number;
9
+ hash: Hash;
10
+ }
11
+
12
+ /** Public operator routing metadata; the attestor authorizes runtime requests independently. */
13
+ export interface OperatorState {
14
+ sealId: Hash;
15
+ owner: Address;
16
+ operator: Address | null;
17
+ version: number;
18
+ allowRecreate: boolean;
19
+ /** Unix seconds; 0 means until replaced or revoked. */
20
+ expiresAt: number;
21
+ /** Normally null. Appointing an operator separately requests a fresh checkpoint; revocation signs null. */
22
+ checkpoint: OperatorCheckpoint | null;
23
+ }
24
+
25
+ export interface OperatorOptions {
26
+ /** Unix seconds; omitted/0 means until replaced or revoked. */
27
+ expiresAt?: number;
28
+ /** Permit replacing an existing runtime, in addition to first provision and start/stop. Default false. */
29
+ allowRecreate?: boolean;
30
+ /** Optional compare-and-swap version. Omitted: read the current version before signing. */
31
+ baseVersion?: number;
32
+ }
33
+
34
+ /** Binding on an operator-signed sandbox envelope; not forwarded in the create payload. */
35
+ export interface RuntimeBinding {
36
+ chain_id: number;
37
+ contract: Address;
38
+ seal_id: Hash;
39
+ operator_version: number;
40
+ }
41
+
42
+ /** Runtime delegation does not authorize owner settings or credential writes. */
43
+ export function assertOperatorComputeOptions(options: {
44
+ apiKey?: unknown; sealedModelKey?: unknown; sealedSecretEnv?: unknown;
45
+ provider?: unknown; beforeWrite?: unknown; keepStoredModelKey?: unknown;
46
+ }): void {
47
+ if (options.apiKey !== undefined || options.sealedModelKey !== undefined ||
48
+ options.sealedSecretEnv !== undefined || options.provider !== undefined ||
49
+ options.beforeWrite !== undefined || options.keepStoredModelKey !== undefined) {
50
+ throw new Error('operator manages compute only; the NFT owner must configure model settings and credentials before starting the agent');
51
+ }
52
+ }
53
+
54
+ /** A grant write raced another owner write; never automatically retried. */
55
+ export class OperatorConflictError extends Error {
56
+ constructor(readonly sealId: Hash, readonly baseVersion: number, detail: string) {
57
+ super(`operator authorization changed for ${sealId}; re-read getOperator() before retrying (base version ${baseVersion}). ${detail}`);
58
+ this.name = 'OperatorConflictError';
59
+ }
60
+ }
61
+
62
+ /** The ownership checkpoint must be refreshed and explicitly signed again; never automatically retried. */
63
+ export class OperatorCheckpointSupersededError extends Error {
64
+ readonly code = 'operator_checkpoint_superseded';
65
+ readonly status = 409;
66
+
67
+ constructor(readonly sealId: Hash, readonly baseVersion: number, detail: string, readonly minimumBlock?: number) {
68
+ super(`operator checkpoint for ${sealId} is no longer usable; explicitly refresh the checkpoint and sign a new setOperator() request${minimumBlock === undefined ? '' : ` at or after block ${minimumBlock}`}. ${detail}`);
69
+ this.name = 'OperatorCheckpointSupersededError';
70
+ }
71
+ }
package/src/Providers.ts CHANGED
@@ -23,6 +23,25 @@ export interface InferenceProvider {
23
23
  modelCatalog?: string;
24
24
  models?: InferenceModel[];
25
25
  compatibility?: Record<string, boolean | string>;
26
+ /** The web search service this provider's key pays for (sealed `inference.SearchServices`); not routing, outside {@link routeHash}. */
27
+ webSearch?: WebSearchService;
28
+ }
29
+
30
+ /** Web search services sealed's inference route can call. */
31
+ export const WEB_SEARCH_SERVICES = ['0g-router', 'openai', 'anthropic'] as const;
32
+ export type WebSearchService = (typeof WEB_SEARCH_SERVICES)[number];
33
+
34
+ /**
35
+ * The web search service provider's key pays for, as sealed decides it
36
+ * (`inference.webSearchOf`, `nativeEndpoints`): the registry's `webSearch`
37
+ * field, else the 0G router for `0g-compute` (a registry published before the
38
+ * field existed), and the provider's own service for native `openai` and
39
+ * `anthropic`; undefined for none.
40
+ */
41
+ export function providerWebSearch(provider: InferenceProvider): WebSearchService | undefined {
42
+ if (provider.native && (provider.id === 'openai' || provider.id === 'anthropic')) return provider.id;
43
+ if (provider.webSearch) return provider.webSearch;
44
+ return provider.id === '0g-compute' ? '0g-router' : undefined;
26
45
  }
27
46
 
28
47
  /** Offline/built-in seed. Instance registries discover operator-published definitions. */
@@ -98,6 +117,7 @@ export function validateProvider(provider: InferenceProvider): void {
98
117
  Object.keys(provider.endpoints ?? {}).length !== provider.formats.length ||
99
118
  provider.formats.some((format) => !validURL(provider.endpoints?.[format] ?? ''))) throw new Error('invalid managed provider endpoints');
100
119
  if (provider.modelCatalog && !validURL(provider.modelCatalog)) throw new Error('invalid provider model catalog');
120
+ if (provider.webSearch !== undefined && !(WEB_SEARCH_SERVICES as readonly string[]).includes(provider.webSearch)) throw new Error('invalid provider web search service');
101
121
  }
102
122
 
103
123
  export interface ProviderRegistrySnapshot {
@@ -0,0 +1,95 @@
1
+ /**
2
+ * @file Releases.ts
3
+ * @description Release notices: what each release changes, and which of an
4
+ * owner's agents it asks to move to a newer image, by when.
5
+ *
6
+ * The attestor serves the deployer's release file on `GET /releases`
7
+ * (public) and, on the owner tier of `GET /deployments`, a `migrate` entry on
8
+ * each agent whose image a published release replaces. Until `until` the old
9
+ * image stays allowed; after it the image may be retired, and an agent still
10
+ * on it is then refused at its container's next boot until it is reset.
11
+ * `urgent` marks an image that may be retired sooner (a security fix).
12
+ */
13
+
14
+ export type MigrationState = 'recommended' | 'soon' | 'overdue';
15
+
16
+ /** One image a release replaces, and the end of its transition period. */
17
+ export interface ReleaseMigration {
18
+ framework: string;
19
+ imageHash: `0x${string}`;
20
+ /** ISO time: the old image is retired no earlier than this, unless `urgent`. */
21
+ until: string;
22
+ urgent: boolean;
23
+ }
24
+
25
+ export interface ReleaseNotice {
26
+ version: string;
27
+ /** ISO time. */
28
+ publishedAt: string;
29
+ notes: string;
30
+ notesZh: string | null;
31
+ migrate: ReleaseMigration[];
32
+ }
33
+
34
+ /** On an owner's agent: the release that replaces its image, and by when to move. */
35
+ export interface AgentMigration {
36
+ version: string;
37
+ framework: string;
38
+ /** ISO time. */
39
+ until: string;
40
+ urgent: boolean;
41
+ /** `soon`: 7 days or less left; `overdue`: the transition period is over. */
42
+ state: MigrationState;
43
+ }
44
+
45
+ const STATES: readonly string[] = ['recommended', 'soon', 'overdue'];
46
+
47
+ function str(v: unknown): string | null {
48
+ return typeof v === 'string' && v.length > 0 ? v : null;
49
+ }
50
+
51
+ /** A release as `GET /releases` serves it, or null when malformed. */
52
+ export function releaseNoticeOf(raw: unknown): ReleaseNotice | null {
53
+ if (!raw || typeof raw !== 'object') return null;
54
+ const r = raw as Record<string, unknown>;
55
+ const version = str(r.version);
56
+ const publishedAt = str(r.published_at);
57
+ const notes = typeof r.notes === 'string' ? r.notes : null;
58
+ if (!version || !publishedAt || notes === null) return null;
59
+ const migrate: ReleaseMigration[] = [];
60
+ for (const m of Array.isArray(r.migrate) ? r.migrate : []) {
61
+ const e = (m ?? {}) as Record<string, unknown>;
62
+ const framework = str(e.framework);
63
+ const imageHash = str(e.image_hash);
64
+ const until = str(e.until);
65
+ if (!framework || !imageHash || !/^0x[0-9a-fA-F]{64}$/.test(imageHash) || !until) continue;
66
+ migrate.push({ framework, imageHash: imageHash as `0x${string}`, until, urgent: e.urgent === true });
67
+ }
68
+ return { version, publishedAt, notes, notesZh: str(r.notes_zh), migrate };
69
+ }
70
+
71
+ /** A deployment row's `migrate` entry, or null when absent or malformed. */
72
+ export function agentMigrationOf(raw: unknown): AgentMigration | null {
73
+ if (!raw || typeof raw !== 'object') return null;
74
+ const r = raw as Record<string, unknown>;
75
+ const version = str(r.version);
76
+ const framework = str(r.framework);
77
+ const until = str(r.until);
78
+ const state = str(r.state);
79
+ if (!version || !framework || !until || !state || !STATES.includes(state)) return null;
80
+ return { version, framework, until, urgent: r.urgent === true, state: state as MigrationState };
81
+ }
82
+
83
+ /**
84
+ * The attestor's published releases, newest first. An attestor without
85
+ * release notices (404) has none.
86
+ */
87
+ export async function fetchReleases(attestorUrl: string, opts: { signal?: AbortSignal } = {}): Promise<ReleaseNotice[]> {
88
+ const res = await fetch(`${attestorUrl.replace(/\/+$/, '')}/releases`, { signal: opts.signal ?? AbortSignal.timeout(10_000) });
89
+ if (res.status === 404) return [];
90
+ if (!res.ok) throw new Error(`GET /releases: HTTP ${res.status}`);
91
+ const body = (await res.json()) as { releases?: unknown };
92
+ return (Array.isArray(body.releases) ? body.releases : [])
93
+ .map(releaseNoticeOf)
94
+ .filter((r): r is ReleaseNotice => r !== null);
95
+ }
@@ -11,6 +11,11 @@
11
11
  * (feedback values: canonical; verification marks + serve data: local).
12
12
  * The canonical registry's address is discovered from the local contract
13
13
  * (`getCanonicalReputation`), so configuration needs only `verifiedFeedback`.
14
+ *
15
+ * The proof's own `version` picks the registry entry point: a v2 proof goes
16
+ * to `attestVersionedFeedback` (registry 1.3.0+, batcher
17
+ * `giveFeedbackAndAttestVersioned`), a proof without one to the v1 entry
18
+ * points (LEGACY(v1): legacy/serveProofV1.ts).
14
19
  */
15
20
 
16
21
  import {
@@ -18,6 +23,7 @@ import {
18
23
  type PublicClient,
19
24
  type Address,
20
25
  type Hash,
26
+ type Hex,
21
27
  type Chain,
22
28
  type Account,
23
29
  type WriteContractReturnType,
@@ -31,7 +37,9 @@ import {
31
37
  import { agenticIDAbi, canonicalReputationAbi, verifiedFeedbackAbi, feedbackBatcherAbi } from './abi';
32
38
  import { RECEIPT_WAIT } from './constants';
33
39
  import { type Ctx } from './context';
34
- import { verifyServeProofSignature } from './ServeProof';
40
+ import { SERVE_PROOF_VERSION, serveProofLayers, verifyServeProofSignature } from './ServeProof';
41
+ import { attestV1, batchCallV1 } from './legacy/serveProofV1';
42
+ import { findViemError, isContractRevert } from './viemErrors';
35
43
  import type {
36
44
  ServeProof,
37
45
  GiveFeedbackParams,
@@ -42,12 +50,58 @@ import type {
42
50
  Feedback,
43
51
  FeedbackSummary,
44
52
  ServeData,
53
+ ServeLayers,
45
54
  TaskReveal,
46
55
  } from './types';
47
56
 
48
57
  const ZERO32 = ('0x' + '0'.repeat(64)) as `0x${string}`;
49
58
  const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
50
59
 
60
+ /** The canonical giveFeedback arguments, in the batcher's order. */
61
+ export type FeedbackArgs = readonly [bigint, bigint, number, string, string, string, string, Hex];
62
+
63
+ /** The task argument when there is no receipt to open: an EMPTY method makes
64
+ * the batcher (and attestVersionedFeedback) skip the opening, so statusCode
65
+ * 0 is never checked. */
66
+ const NO_TASK: TaskReveal = { method: '', uri: '', reqBodyHash: ZERO32, respBodyHash: ZERO32, statusCode: 0 };
67
+
68
+ /** The first VerifiedFeedbackRegistry version with attestVersionedFeedback
69
+ * and getServeLayers. LEGACY(pre-1.4.0): checked only because a registry
70
+ * before it may still be configured. */
71
+ const VERSIONED_REGISTRY = [1, 3, 0] as const;
72
+
73
+ /** Whether a "major.minor.patch" version string is at least `min`. */
74
+ function versionAtLeast(version: string, min: readonly [number, number, number]): boolean {
75
+ const m = /^(\d+)\.(\d+)\.(\d+)/.exec(version);
76
+ if (!m) return false;
77
+ for (let i = 0; i < 3; i++) {
78
+ const part = Number(m[i + 1]);
79
+ if (part !== min[i]) return part > min[i];
80
+ }
81
+ return true;
82
+ }
83
+
84
+ /** The thirteen on-chain fields of a v2 proof, for attestVersionedFeedback
85
+ * and the batcher. The caller has checked the layer fields. */
86
+ function versionedTuple(proof: ServeProof) {
87
+ const layers = serveProofLayers(proof)!;
88
+ return {
89
+ version: proof.version!,
90
+ agentId: proof.agentId,
91
+ submitter: proof.submitter,
92
+ timestamp: proof.timestamp,
93
+ deadline: proof.deadline,
94
+ taskHash: proof.taskHash,
95
+ dataHashes: proof.dataHashes,
96
+ frameworkHash: proof.frameworkHash,
97
+ sealedHash: layers.sealedHash,
98
+ harnessHash: layers.harnessHash,
99
+ inferenceURL: layers.inferenceURL,
100
+ model: layers.model,
101
+ signature: proof.signature,
102
+ };
103
+ }
104
+
51
105
  /**
52
106
  * Seconds of headroom the sequential preflight demands before a proof's
53
107
  * deadline: the attest lands only after the canonical write has mined, so a
@@ -119,6 +173,10 @@ function assertFeedbackValueInRange(value: bigint, valueDecimals: number): void
119
173
  export class ReputationClient {
120
174
  /** Cached canonical registry address, discovered from the local contract. */
121
175
  private canonicalAddr?: Address;
176
+ /** Cached VerifiedFeedbackRegistry VERSION, once it takes versioned proofs. */
177
+ private registryVersionValue?: string;
178
+ /** Per batcher address: whether it has giveFeedbackAndAttestVersioned. */
179
+ private readonly batcherVersioned = new Map<string, boolean>();
122
180
 
123
181
  constructor(private readonly ctx: Ctx) {}
124
182
 
@@ -142,6 +200,49 @@ export class ReputationClient {
142
200
  return a;
143
201
  }
144
202
 
203
+ /** The VerifiedFeedbackRegistry's VERSION. Kept once it is 1.3.0 or later;
204
+ * LEGACY(pre-1.4.0): an older one is read again each time, as its upgrade
205
+ * can land while this client lives. */
206
+ private async registryVersion(): Promise<string> {
207
+ if (this.registryVersionValue !== undefined) return this.registryVersionValue;
208
+ const version = (await this.publicClient.readContract({
209
+ address: this.verifiedFeedbackAddr,
210
+ abi: verifiedFeedbackAbi,
211
+ functionName: 'VERSION',
212
+ })) as string;
213
+ if (versionAtLeast(version, VERSIONED_REGISTRY)) this.registryVersionValue = version;
214
+ return version;
215
+ }
216
+
217
+ /**
218
+ * Refuse, before anything is broadcast, a versioned proof this SDK or the
219
+ * configured registry cannot take: a version other than 2, malformed layer
220
+ * fields, or a registry before 1.3.0 (no attestVersionedFeedback). Without
221
+ * this the sequential path would land the canonical entry and then fail
222
+ * its attest.
223
+ */
224
+ private async assertVersionedAccepted(proof: ServeProof): Promise<void> {
225
+ if (proof.version !== SERVE_PROOF_VERSION) {
226
+ throw new Error(
227
+ `reputation: unsupported serve-proof version ${String(proof.version)} — this SDK submits v2, and v1 without a version; nothing was broadcast`,
228
+ );
229
+ }
230
+ if (!serveProofLayers(proof)) {
231
+ throw new Error(
232
+ 'reputation: v2 serve-proof with missing or malformed layer fields (sealedHash and harnessHash are 32-byte hex; ' +
233
+ 'inferenceURL and model strings) — nothing was broadcast',
234
+ );
235
+ }
236
+ // LEGACY(pre-1.4.0): a registry before 1.3.0 has no attestVersionedFeedback.
237
+ const version = await this.registryVersion();
238
+ if (!versionAtLeast(version, VERSIONED_REGISTRY)) {
239
+ throw new Error(
240
+ `reputation: the VerifiedFeedbackRegistry at ${this.verifiedFeedbackAddr} is ${version}; a v2 serve-proof needs ` +
241
+ `${VERSIONED_REGISTRY.join('.')} or later (attestVersionedFeedback) — nothing was broadcast`,
242
+ );
243
+ }
244
+ }
245
+
145
246
  /** Canonical ERC-8004 ReputationRegistry address — read once from the local contract, then cached. */
146
247
  private async canonical(): Promise<Address> {
147
248
  if (!this.canonicalAddr) {
@@ -187,6 +288,8 @@ export class ReputationClient {
187
288
  // sequential canonical write that precedes attestFeedbackWithTask.
188
289
  if (params.task) assertTaskStatusCode(params.task);
189
290
  assertFeedbackValueInRange(params.value, params.valueDecimals ?? 0);
291
+ // LEGACY(v1): a proof without a version takes the v1 entry points.
292
+ if (params.serveProof.version !== undefined) await this.assertVersionedAccepted(params.serveProof);
190
293
 
191
294
  const batcher = this.ctx.addresses.feedbackBatcher;
192
295
  if (batcher && batcher !== '0x0000000000000000000000000000000000000000') {
@@ -219,9 +322,7 @@ export class ReputationClient {
219
322
  // once the write mines — this wait is inherent to the flow, not politeness.
220
323
  await this.waitForTransaction(feedbackTx);
221
324
  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);
325
+ const attestTx = await this.attest(params.agentId, feedbackIndex, params.serveProof, params.task);
225
326
  return { feedbackTx, attestTx, feedbackIndex };
226
327
  }
227
328
 
@@ -304,7 +405,8 @@ export class ReputationClient {
304
405
  refuse(
305
406
  proof.validator
306
407
  ? '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',
408
+ : // LEGACY(v1): the hint for an image from before the validator.
409
+ '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
410
  );
309
411
  }
310
412
  // Owner / operator self-feedback — the registry's ERC-721 checks against
@@ -357,6 +459,13 @@ export class ReputationClient {
357
459
  params: GiveFeedbackParams,
358
460
  ): Promise<GiveFeedbackResult | null> {
359
461
  const me = this.account!.address;
462
+ const sp = params.serveProof;
463
+ // LEGACY(v1): a proof without a version takes the v1 batch.
464
+ const versioned = sp.version !== undefined;
465
+ // LEGACY(pre-1.4.0): a batcher deployed before versioned proofs has no
466
+ // entry for them: take the sequential path, before anything is signed or
467
+ // sent.
468
+ if (versioned && !(await this.batcherTakesVersioned(batcher))) return null;
360
469
 
361
470
  // Delegation designator this EOA needs: 0xef0100 ‖ batcher.
362
471
  const designator = ('0xef0100' + batcher.slice(2)).toLowerCase();
@@ -377,41 +486,28 @@ export class ReputationClient {
377
486
  }
378
487
  }
379
488
 
380
- const sp = params.serveProof;
489
+ const feedback: FeedbackArgs = [
490
+ params.agentId,
491
+ params.value,
492
+ params.valueDecimals ?? 0,
493
+ params.tag1 ?? '',
494
+ params.tag2 ?? '',
495
+ params.endpoint ?? '',
496
+ params.feedbackURI ?? '',
497
+ params.feedbackHash ?? ZERO32,
498
+ ];
499
+ const data: Hex = versioned
500
+ ? encodeFunctionData({
501
+ abi: feedbackBatcherAbi,
502
+ functionName: 'giveFeedbackAndAttestVersioned',
503
+ args: [...feedback, versionedTuple(sp), params.task ?? NO_TASK],
504
+ })
505
+ : batchCallV1(feedback, sp, params.task ?? NO_TASK);
381
506
  const txHash = await this.walletClient!.sendTransaction({
382
507
  account: this.account!,
383
508
  chain: this.chain,
384
509
  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
- }),
510
+ data,
415
511
  authorizationList,
416
512
  });
417
513
 
@@ -437,39 +533,90 @@ export class ReputationClient {
437
533
  }
438
534
 
439
535
  /**
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).
536
+ * Whether `batcher` has giveFeedbackAndAttestVersioned, asked gas-free: a
537
+ * call from anyone but the delegated EOA itself reverts BatcherNotSelf
538
+ * when the entry exists, and with no data when it does not (the batcher
539
+ * has no fallback). Only those answers are kept. Anything else — an
540
+ * unreachable RPC, an error the node answered that is no revert — counts
541
+ * as no this time and is asked again next time; it only costs the
542
+ * atomicity: the sequential path checks the proof first.
543
+ * LEGACY(pre-1.4.0): needed while a batcher before v5 may be configured.
443
544
  */
444
- async attestFeedback(
545
+ private async batcherTakesVersioned(batcher: Address): Promise<boolean> {
546
+ const known = this.batcherVersioned.get(batcher.toLowerCase());
547
+ if (known !== undefined) return known;
548
+ let takes = false;
549
+ try {
550
+ await this.publicClient.simulateContract({
551
+ address: batcher,
552
+ abi: feedbackBatcherAbi,
553
+ functionName: 'giveFeedbackAndAttestVersioned',
554
+ args: [
555
+ 0n, 0n, 0, '', '', '', '', ZERO32,
556
+ {
557
+ version: SERVE_PROOF_VERSION, agentId: 0n, submitter: ZERO_ADDRESS, timestamp: 0n, deadline: 0n,
558
+ taskHash: ZERO32, dataHashes: [], frameworkHash: ZERO32, sealedHash: ZERO32, harnessHash: ZERO32,
559
+ inferenceURL: '', model: '', signature: '0x',
560
+ },
561
+ NO_TASK,
562
+ ],
563
+ });
564
+ takes = true;
565
+ } catch (e) {
566
+ // The batcher's own error, decoded, is its answer; a revert without one
567
+ // is the missing entry. viem wraps a node's internal error in a
568
+ // ContractFunctionRevertedError too, so that alone is no answer.
569
+ const reverted = findViemError(e, ['ContractFunctionRevertedError']);
570
+ if (reverted?.data?.errorName === 'BatcherNotSelf') takes = true;
571
+ else if (!isContractRevert(e)) return false; // not an answer from the batcher: ask again next time
572
+ }
573
+ this.batcherVersioned.set(batcher.toLowerCase(), takes);
574
+ return takes;
575
+ }
576
+
577
+ /** The attest call for `proof`'s version, with or without a task. */
578
+ private async attest(
445
579
  agentId: bigint,
446
580
  feedbackIndex: bigint,
447
581
  proof: ServeProof,
582
+ task?: TaskReveal,
448
583
  ): Promise<WriteContractReturnType> {
449
- this.requireWallet();
584
+ if (task) assertTaskStatusCode(task);
585
+ // LEGACY(v1): a proof without a version takes the v1 entry points.
586
+ if (proof.version === undefined) {
587
+ return attestV1(
588
+ this.walletClient!,
589
+ { address: this.verifiedFeedbackAddr, account: this.account!, chain: this.chain },
590
+ agentId, feedbackIndex, proof, task,
591
+ );
592
+ }
593
+ await this.assertVersionedAccepted(proof);
450
594
  return this.walletClient!.writeContract({
451
595
  address: this.verifiedFeedbackAddr,
452
596
  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
- ],
597
+ functionName: 'attestVersionedFeedback',
598
+ args: [agentId, feedbackIndex, versionedTuple(proof), task ?? NO_TASK],
468
599
  account: this.account!,
469
600
  chain: this.chain,
470
601
  });
471
602
  }
472
603
 
604
+ /**
605
+ * Attest an EXISTING canonical feedback entry of the connected wallet with
606
+ * a ServeProof (the second half of `giveFeedback`, exposed for callers that
607
+ * submitted the canonical entry separately). A v2 proof goes to
608
+ * attestVersionedFeedback (registry 1.3.0+), a v1 proof (LEGACY(v1)) to
609
+ * attestFeedback.
610
+ */
611
+ async attestFeedback(
612
+ agentId: bigint,
613
+ feedbackIndex: bigint,
614
+ proof: ServeProof,
615
+ ): Promise<WriteContractReturnType> {
616
+ this.requireWallet();
617
+ return this.attest(agentId, feedbackIndex, proof);
618
+ }
619
+
473
620
  /**
474
621
  * Like {@link attestFeedback}, additionally opening the proof's taskHash
475
622
  * commitment: the contract recomputes the hash from the revealed receipt
@@ -482,29 +629,7 @@ export class ReputationClient {
482
629
  task: TaskReveal,
483
630
  ): Promise<WriteContractReturnType> {
484
631
  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
- });
632
+ return this.attest(agentId, feedbackIndex, proof, task);
508
633
  }
509
634
 
510
635
  // ── Canonical writes ──
@@ -789,6 +914,33 @@ export class ReputationClient {
789
914
  return { dataHashes, frameworkHash };
790
915
  }
791
916
 
917
+ /**
918
+ * The layers a VERIFIED entry's ServeProof named (v2): the sealed program
919
+ * and the official harness version that served the call. Zero hashes for an
920
+ * entry attested with a v1 proof. Needs a registry of 1.3.0 or later.
921
+ */
922
+ async getServeLayers(
923
+ agentId: bigint,
924
+ clientAddress: Address,
925
+ feedbackIndex: bigint,
926
+ ): Promise<ServeLayers> {
927
+ // LEGACY(pre-1.4.0): a registry before 1.3.0 has no getServeLayers.
928
+ const version = await this.registryVersion();
929
+ if (!versionAtLeast(version, VERSIONED_REGISTRY)) {
930
+ throw new Error(
931
+ `reputation: the VerifiedFeedbackRegistry at ${this.verifiedFeedbackAddr} is ${version}; ` +
932
+ `it records serve layers from ${VERSIONED_REGISTRY.join('.')} on`,
933
+ );
934
+ }
935
+ const [sealedHash, harnessHash] = (await this.publicClient.readContract({
936
+ address: this.verifiedFeedbackAddr,
937
+ abi: verifiedFeedbackAbi,
938
+ functionName: 'getServeLayers',
939
+ args: [agentId, clientAddress, feedbackIndex],
940
+ })) as [Hash, Hash];
941
+ return { sealedHash, harnessHash };
942
+ }
943
+
792
944
  // ── Transaction Helpers ──
793
945
 
794
946
  /**