@0gfoundation/0g-agentdna 0.4.0 → 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 +87 -6
  167. package/dist/cli/settings.d.ts.map +1 -1
  168. package/dist/cli/settings.js +270 -18
  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 +272 -22
  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
package/src/ServeProof.ts CHANGED
@@ -8,6 +8,22 @@
8
8
  * proofHash = keccak256(abi.encode(<proof fields>)) (buildServeProofMessageHash)
9
9
  * digest = keccak256(0x19 ‖ 0x00 ‖ validator ‖ proofHash) (buildServeProofSigningHash)
10
10
  *
11
+ * The proof's own `version` picks the preimage (sealed/LAYERS.md §7):
12
+ *
13
+ * - v2 (`version: 2`, 0g-harness on the layered runtime) opens with
14
+ * keccak256("AgentDNA.ServeProof.v2"), then v1's nine words, then what
15
+ * each layer ran:
16
+ * keccak256(abi.encode(tag, chainId, identityRegistry, submitter,
17
+ * agentId, timestamp, deadline, taskHash,
18
+ * keccak256(abi.encodePacked(dataHashes)), frameworkHash,
19
+ * sealedHash, harnessHash,
20
+ * keccak256(bytes(inferenceURL)), keccak256(bytes(model))))
21
+ * - LEGACY(v1): v1 (no `version`, every image before it) is the nine words
22
+ * alone — legacy/serveProofV1.ts.
23
+ *
24
+ * v1's preimage opens with the chain id and is 9 words long, v2's with the
25
+ * tag and 14, so a signature over either never verifies as the other.
26
+ *
11
27
  * The signed digest is EIP-191 version 0x00 ("data with intended validator",
12
28
  * OZ `MessageHashUtils.toDataWithIntendedValidatorHash`), where `validator` is
13
29
  * the VerifiedFeedbackRegistry proxy that redeems the proof. It is NOT
@@ -28,14 +44,23 @@ import {
28
44
  concat,
29
45
  isAddress,
30
46
  recoverAddress,
47
+ stringToBytes,
31
48
  type Address,
32
49
  type Hex,
33
50
  type Hash,
34
51
  } from 'viem';
35
52
  import type { ServeProof as ServeProofType } from './types';
53
+ import { serveProofHashV1 } from './legacy/serveProofV1';
36
54
 
37
55
  const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
38
56
 
57
+ /** The ServeProof version this SDK signs and verifies; LEGACY(v1): a proof
58
+ * without a version is v1 (legacy/serveProofV1.ts). */
59
+ export const SERVE_PROOF_VERSION = 2;
60
+
61
+ /** keccak256("AgentDNA.ServeProof.v2") — the first word of the v2 preimage. */
62
+ export const SERVE_PROOF_V2_TAG: Hash = keccak256(stringToBytes('AgentDNA.ServeProof.v2'));
63
+
39
64
  /**
40
65
  * Parameters for building a ServeProof message hash (the inner `proofHash`).
41
66
  */
@@ -57,8 +82,54 @@ export interface BuildServeProofHashParams {
57
82
  taskHash: Hash;
58
83
  /** Hashes of the data involved in the service */
59
84
  dataHashes: Hash[];
60
- /** Hash of the agent framework version */
85
+ /** Hash of the agent framework version: the image hash (base) */
61
86
  frameworkHash: Hash;
87
+ /** 2 for a versioned proof, which then also needs the four fields below;
88
+ * LEGACY(v1): absent for v1, the format of images before the layered
89
+ * runtime. */
90
+ version?: number;
91
+ /** v2: sha256 of the sealed program the loader verified and ran */
92
+ sealedHash?: Hash;
93
+ /** v2: sha256 of the official harness version running */
94
+ harnessHash?: Hash;
95
+ /** v2: where sealed's inference proxy forwards model calls; '' when the
96
+ * framework dials its provider itself */
97
+ inferenceURL?: string;
98
+ /** v2: the model name the inference proxy sends, the owner's setting */
99
+ model?: string;
100
+ }
101
+
102
+ /** What a v2 proof signs beyond v1: what each layer ran. */
103
+ export interface ServeProofLayers {
104
+ sealedHash: Hash;
105
+ harnessHash: Hash;
106
+ inferenceURL: string;
107
+ model: string;
108
+ }
109
+
110
+ const BYTES32 = /^0x[0-9a-fA-F]{64}$/;
111
+
112
+ /**
113
+ * A v2 proof's layer fields when they are well-formed (two 32-byte hashes,
114
+ * two strings), else null. The fields come from an untrusted header, and
115
+ * viem's `concat` checks no lengths, so a short hash would otherwise hash
116
+ * into a digest that matches nothing.
117
+ */
118
+ export function serveProofLayers(p: {
119
+ sealedHash?: unknown;
120
+ harnessHash?: unknown;
121
+ inferenceURL?: unknown;
122
+ model?: unknown;
123
+ }): ServeProofLayers | null {
124
+ if (typeof p.sealedHash !== 'string' || !BYTES32.test(p.sealedHash)) return null;
125
+ if (typeof p.harnessHash !== 'string' || !BYTES32.test(p.harnessHash)) return null;
126
+ if (typeof p.inferenceURL !== 'string' || typeof p.model !== 'string') return null;
127
+ return {
128
+ sealedHash: p.sealedHash as Hash,
129
+ harnessHash: p.harnessHash as Hash,
130
+ inferenceURL: p.inferenceURL,
131
+ model: p.model,
132
+ };
62
133
  }
63
134
 
64
135
  /**
@@ -72,44 +143,39 @@ export interface BuildServeProofSigningHashParams extends BuildServeProofHashPar
72
143
  }
73
144
 
74
145
  /**
75
- * Compute the ServeProof message hash exactly as the Solidity contract does.
146
+ * Compute the ServeProof message hash exactly as the registry does, picking
147
+ * the preimage by `params.version`: 2 → the v2 hash (the registry's
148
+ * `_serveProofHashV2`); absent → the v1 hash (`_serveProofHash`).
76
149
  *
77
- * Solidity:
78
- * ```solidity
79
- * bytes32 messageHash = keccak256(abi.encode(
80
- * block.chainid,
81
- * identityRegistry, // verifyingContract
82
- * submitter,
83
- * agentId,
84
- * timestamp,
85
- * deadline,
86
- * taskHash,
87
- * keccak256(abi.encodePacked(dataHashes)),
88
- * frameworkHash
89
- * ));
90
- * ```
91
- *
92
- * chainId + verifyingContract give cross-chain / cross-deployment separation;
93
- * submitter binds the proof to the single address allowed to redeem it.
94
- * This is the inner hash only — what gets signed is
95
- * {@link buildServeProofSigningHash}.
150
+ * chainId + verifyingContract (the identity registry the reputation contract
151
+ * is anchored to) give cross-chain / cross-deployment separation; submitter
152
+ * binds the proof to the single address allowed to redeem it. This is the
153
+ * inner hash only — what gets signed is {@link buildServeProofSigningHash}.
96
154
  *
97
155
  * @param params - The ServeProof hash parameters
98
156
  * @returns The keccak256 hash of the abi.encode payload
157
+ * @throws for a version other than 2, or a v2 proof whose layer fields are
158
+ * missing or malformed
99
159
  */
100
160
  export function buildServeProofMessageHash(params: BuildServeProofHashParams): Hash {
161
+ // LEGACY(v1): a proof without a version.
162
+ if (params.version === undefined) return serveProofHashV1(params);
163
+ if (params.version !== SERVE_PROOF_VERSION) {
164
+ throw new Error(
165
+ `buildServeProofMessageHash: unsupported serve-proof version ${String(params.version)} (v2, or v1 without a version)`,
166
+ );
167
+ }
168
+ const layers = serveProofLayers(params);
169
+ if (!layers) {
170
+ throw new Error(
171
+ 'buildServeProofMessageHash: a v2 proof needs sealedHash and harnessHash (32-byte hex) and inferenceURL and model (strings)',
172
+ );
173
+ }
101
174
  const { chainId, verifyingContract, submitter, agentId, timestamp, deadline, taskHash, dataHashes, frameworkHash } = params;
102
-
103
- // Step 1: keccak256(abi.encodePacked(dataHashes)) — concatenate bytes32 values
104
- const packedDataHashes: Hex = dataHashes.length > 0
105
- ? concat(dataHashes as readonly Hex[])
106
- : '0x';
107
- const dataHashesHash = keccak256(packedDataHashes);
108
-
109
- // Step 2: abi.encode(chainId, verifyingContract, submitter, agentId, timestamp,
110
- // deadline, taskHash, dataHashesHash, frameworkHash). Each field is a static
111
- // 32-byte word: uint256 = 32, address = 32 (left-padded), bytes32 = 32.
112
- const encoded = concat([
175
+ const packedDataHashes: Hex = dataHashes.length > 0 ? concat(dataHashes as readonly Hex[]) : '0x';
176
+ // Every field is a static 32-byte word, so abi.encode is a concatenation.
177
+ return keccak256(concat([
178
+ SERVE_PROOF_V2_TAG,
113
179
  pad(toHex(chainId), { size: 32 }),
114
180
  pad(verifyingContract as Hex, { size: 32 }),
115
181
  pad(submitter as Hex, { size: 32 }),
@@ -117,12 +183,13 @@ export function buildServeProofMessageHash(params: BuildServeProofHashParams): H
117
183
  pad(toHex(timestamp), { size: 32 }),
118
184
  pad(toHex(deadline), { size: 32 }),
119
185
  pad(taskHash as Hex, { size: 32 }),
120
- pad(dataHashesHash as Hex, { size: 32 }),
186
+ keccak256(packedDataHashes),
121
187
  pad(frameworkHash as Hex, { size: 32 }),
122
- ]);
123
-
124
- // Step 3: keccak256(encoded)
125
- return keccak256(encoded);
188
+ layers.sealedHash,
189
+ layers.harnessHash,
190
+ keccak256(stringToBytes(layers.inferenceURL)),
191
+ keccak256(stringToBytes(layers.model)),
192
+ ]));
126
193
  }
127
194
 
128
195
  /** True for a well-formed (any case), non-zero 20-byte address. viem's
@@ -185,6 +252,9 @@ export function buildServeProof(
185
252
  * that produces the personal_sign (0x19 0x45) form, which the registry
186
253
  * rejects on purpose, and the proof fails `verifyServeProofSignature`.
187
254
  *
255
+ * Pass `version: 2` and the four layer fields for a v2 proof; without a
256
+ * version the proof is v1 (LEGACY(v1)).
257
+ *
188
258
  * @param params - The ServeProof parameters plus the validator (VerifiedFeedbackRegistry)
189
259
  * @param sign - A function that raw-signs the final digest (e.g. `account.sign`)
190
260
  * @returns The complete ServeProof with signature (and `validator`, informational)
@@ -218,11 +288,17 @@ export async function signServeProof(
218
288
  frameworkHash: params.frameworkHash,
219
289
  signature,
220
290
  validator: params.validator,
291
+ // buildServeProofSigningHash has checked these for a v2 proof.
292
+ // LEGACY(v1): a proof without a version carries no layers.
293
+ ...(params.version === undefined
294
+ ? {}
295
+ : { version: params.version, ...serveProofLayers(params)! }),
221
296
  };
222
297
  }
223
298
 
224
299
  /**
225
- * Verify that a ServeProof signature matches the expected agentSeal address.
300
+ * Verify that a ServeProof signature matches the expected agentSeal address,
301
+ * over the digest the proof's own `version` picks (2, or v1 without one).
226
302
  *
227
303
  * The digest is domain-bound, so the caller supplies the chain id, the
228
304
  * identity-registry (verifyingContract) the proof was issued against, and the
@@ -240,7 +316,8 @@ export async function signServeProof(
240
316
  * @param expectedSigner - The agentSeal address that should have signed
241
317
  * @param domain - The chainId + verifyingContract + validator the proof is bound to
242
318
  * @returns True if the signature is valid for the expected signer; false for a
243
- * missing / malformed / zero validator or a non-canonical signature encoding
319
+ * missing / malformed / zero validator, a non-canonical signature encoding,
320
+ * an unsupported version, or a v2 proof with missing or malformed layer fields
244
321
  */
245
322
  export async function verifyServeProofSignature(
246
323
  proof: ServeProofType,
@@ -251,6 +328,12 @@ export async function verifyServeProofSignature(
251
328
  // legacy personal_sign digest.
252
329
  if (!isUsableValidator(domain?.validator)) return false;
253
330
  if (!isRegistryCanonicalSignature(proof.signature)) return false;
331
+ let layers: ServeProofLayers | null = null;
332
+ // LEGACY(v1): without a version the proof is checked as v1.
333
+ if (proof.version !== undefined) {
334
+ layers = proof.version === SERVE_PROOF_VERSION ? serveProofLayers(proof) : null;
335
+ if (!layers) return false;
336
+ }
254
337
  const signingHash = buildServeProofSigningHash({
255
338
  chainId: domain.chainId,
256
339
  verifyingContract: domain.verifyingContract,
@@ -262,6 +345,7 @@ export async function verifyServeProofSignature(
262
345
  taskHash: proof.taskHash,
263
346
  dataHashes: proof.dataHashes,
264
347
  frameworkHash: proof.frameworkHash,
348
+ ...(layers ? { version: proof.version, ...layers } : {}),
265
349
  });
266
350
  // A malformed signature (bad length / invalid v) is just a failed verification,
267
351
  // not an exception — a buyer verifying a hostile proof should get `false`.
@@ -16,9 +16,12 @@
16
16
  * X-Agent-Proof: 0x<65-byte sig hex>.<base64url(envelope JSON)>
17
17
  * envelope JSON = { agent_id, submitter, timestamp, deadline, task_hash,
18
18
  * data_hashes[], framework_hash, validator }
19
+ * v2 adds { version: 2, sealed_hash, harness_hash, inference_url, model }
19
20
  * `validator` (the VerifiedFeedbackRegistry the signature is bound to) is
20
21
  * diagnostics only — not part of the on-chain ServeProof tuple — and absent on
21
- * images that predate it.
22
+ * images that predate it. LEGACY(v1): a v1 envelope has no `version`.
23
+ * The envelope is UTF-8 JSON: a v2 `model` and `inference_url` are the
24
+ * owner's text and may be non-ASCII.
22
25
  */
23
26
 
24
27
  import {
@@ -30,7 +33,8 @@ import {
30
33
  type PublicClient,
31
34
  } from 'viem';
32
35
  import { agenticIDAbi } from './abi';
33
- import { verifyServeProofSignature } from './ServeProof';
36
+ import { SERVE_PROOF_VERSION, serveProofLayers, verifyServeProofSignature } from './ServeProof';
37
+ import { isListed, trustRegistryOf } from './TrustRegistry';
34
38
  import { taskHashOf, requestUriCandidates } from './taskHash';
35
39
  import { type Ctx } from './context';
36
40
  import type { ServeProof, TaskReveal } from './types';
@@ -46,27 +50,44 @@ interface RawEnvelope {
46
50
  data_hashes: `0x${string}`[];
47
51
  framework_hash: `0x${string}`;
48
52
  validator?: `0x${string}`;
53
+ // v2 (sealed/LAYERS.md §7)
54
+ version?: unknown;
55
+ sealed_hash?: unknown;
56
+ harness_hash?: unknown;
57
+ inference_url?: unknown;
58
+ model?: unknown;
49
59
  }
50
60
 
51
61
  const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000' as const;
52
62
 
63
+ /** The envelope's JSON text: base64url → bytes → UTF-8. atob (and Buffer's
64
+ * 'binary') give one character per byte, which garbles any non-ASCII
65
+ * character and so the digest of the string that carries it. */
53
66
  function b64urlDecode(s: string): string {
54
67
  const b64 = s.replace(/-/g, '+').replace(/_/g, '/');
55
68
  const g = globalThis as { atob?: (d: string) => string };
56
- if (typeof g.atob === 'function') return g.atob(b64);
57
- // Node fallback (envelope is ASCII, so binary === utf8 here).
58
- return Buffer.from(b64, 'base64').toString('binary');
69
+ const bytes =
70
+ typeof g.atob === 'function'
71
+ ? Uint8Array.from(g.atob(b64), (c) => c.charCodeAt(0))
72
+ : Buffer.from(b64, 'base64');
73
+ return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
59
74
  }
60
75
 
61
76
  /**
62
77
  * Parse an `X-Agent-Proof` header value into a ServeProof ready for
63
- * ReputationClient.giveFeedback.
78
+ * ReputationClient.giveFeedback. A v2 envelope keeps its version and layer
79
+ * fields as sent (strings only); whether they are well-formed and signed is
80
+ * for verification to say, so a version this SDK does not know still parses.
64
81
  */
65
82
  export function parseServeProofHeader(value: string): ServeProof {
66
83
  const dot = value.indexOf('.');
67
84
  if (dot < 0) throw new Error('malformed X-Agent-Proof header (missing ".")');
68
85
  const signature = value.slice(0, dot) as `0x${string}`;
69
86
  const env = JSON.parse(b64urlDecode(value.slice(dot + 1))) as RawEnvelope;
87
+ if (env.version !== undefined && typeof env.version !== 'number') {
88
+ throw new Error('malformed X-Agent-Proof header (version is not a number)');
89
+ }
90
+ const text = (v: unknown) => (typeof v === 'string' ? v : undefined);
70
91
  return {
71
92
  agentId: BigInt(env.agent_id),
72
93
  submitter: env.submitter ?? ZERO_ADDRESS,
@@ -78,6 +99,16 @@ export function parseServeProofHeader(value: string): ServeProof {
78
99
  signature,
79
100
  // Unsigned diagnostics from an untrusted header: keep only a string.
80
101
  ...(typeof env.validator === 'string' && env.validator ? { validator: env.validator } : {}),
102
+ // LEGACY(v1): an envelope without a version is a v1 proof.
103
+ ...(env.version === undefined
104
+ ? {}
105
+ : {
106
+ version: env.version,
107
+ sealedHash: text(env.sealed_hash) as `0x${string}` | undefined,
108
+ harnessHash: text(env.harness_hash) as `0x${string}` | undefined,
109
+ inferenceURL: text(env.inference_url),
110
+ model: text(env.model),
111
+ }),
81
112
  };
82
113
  }
83
114
 
@@ -247,6 +278,12 @@ export interface ProofVerification {
247
278
  * (`signerMatches` is false too) — a configuration mismatch, not
248
279
  * necessarily a bad proof. */
249
280
  registryMatches: boolean;
281
+ /** v2 proofs: whether the image (frameworkHash), the sealed program and the
282
+ * official harness version the proof names are all on the trust
283
+ * registry's lists now (sealed/LAYERS.md §7) — a version delisted since
284
+ * the proof was signed fails. LEGACY(v1): null for a v1 proof, which names
285
+ * no layers. Required for `ok` when not null. */
286
+ layersListed: boolean | null;
250
287
  /** null when no task was passed to verifyProof (the call means signer
251
288
  * attribution only). With a task: whether the proof's taskHash equals
252
289
  * the hash recomputed from that task — binding the proof to THIS
@@ -331,6 +368,17 @@ export class ServeSession {
331
368
  const notExpired = proof.deadline > BigInt(this.now() - this.clockSkew);
332
369
  if (!notExpired) reasons.push('proof deadline has passed');
333
370
 
371
+ // The proof's own version picks the digest: 2, or v1 without one
372
+ // (LEGACY(v1)). Anything else, or a v2 proof with missing or malformed
373
+ // layer fields, cannot be checked at all.
374
+ const versioned = proof.version !== undefined;
375
+ let unverifiable: string | null = null;
376
+ if (versioned && proof.version !== SERVE_PROOF_VERSION) {
377
+ unverifiable = `unsupported serve-proof version ${String(proof.version)} (this SDK verifies v2, and v1 without a version)`;
378
+ } else if (versioned && !serveProofLayers(proof)) {
379
+ unverifiable = 'v2 proof with missing or malformed layer fields (sealedHash and harnessHash are 32-byte hex; inferenceURL and model strings)';
380
+ }
381
+
334
382
  // The signature is bound to the registry that redeems it (EIP-191 v0x00
335
383
  // intended validator). Without one there is nothing to verify against;
336
384
  // when the envelope names another one, the signature cannot match ours.
@@ -339,7 +387,9 @@ export class ServeSession {
339
387
  isAddress(registry, { strict: false }) && registry.toLowerCase() !== ZERO_ADDRESS;
340
388
  let registryMatches = registryConfigured;
341
389
  let signerMatches = false;
342
- if (!registryConfigured) {
390
+ if (unverifiable) {
391
+ reasons.push(unverifiable);
392
+ } else if (!registryConfigured) {
343
393
  reasons.push('no VerifiedFeedbackRegistry configured — cannot verify serve-proof');
344
394
  } else if (proof.validator && proof.validator.toLowerCase() !== registry.toLowerCase()) {
345
395
  registryMatches = false;
@@ -368,11 +418,20 @@ export class ServeSession {
368
418
  reasons.push(
369
419
  proof.validator
370
420
  ? 'signature does not match the on-chain agentSeal'
371
- : 'signature does not match the on-chain agentSeal (the proof names no validator — likely a pre-upgrade sealed image)',
421
+ : // LEGACY(v1): the hint for an image from before the validator.
422
+ 'signature does not match the on-chain agentSeal (the proof names no validator — likely a pre-upgrade sealed image)',
372
423
  );
373
424
  }
374
425
  }
375
426
 
427
+ // v2: the base image, the sealed program and the official harness the
428
+ // proof names, against the trust registry's lists. LEGACY(v1): null for
429
+ // a proof without a version.
430
+ let layersListed: boolean | null = null;
431
+ if (versioned) {
432
+ layersListed = unverifiable ? false : await this.layersListed(proof, reasons);
433
+ }
434
+
376
435
  // dataHashes ⊆ intelligentDatasOf(agentId)
377
436
  let dataOnChain = true;
378
437
  if (proof.dataHashes.length > 0) {
@@ -409,13 +468,36 @@ export class ServeSession {
409
468
  }
410
469
 
411
470
  return {
412
- ok: signerMatches && notExpired && dataOnChain && taskMatches !== false,
471
+ ok: signerMatches && notExpired && dataOnChain && layersListed !== false && taskMatches !== false,
413
472
  signerMatches,
414
473
  notExpired,
415
474
  dataOnChain,
416
475
  registryMatches,
476
+ layersListed,
417
477
  taskMatches,
418
478
  reasons,
419
479
  };
420
480
  }
481
+
482
+ /** A v2 proof's image, sealed and harness hashes against the trust
483
+ * registry's IMAGE, SEALED and HARNESS lists; each one missing is a
484
+ * reason. */
485
+ private async layersListed(proof: ServeProof, reasons: string[]): Promise<boolean> {
486
+ const trust = await trustRegistryOf(this.publicClient, this.agenticID);
487
+ // LEGACY(pre-1.4.0): a chain whose AgenticID names no trust registry.
488
+ if (!trust) {
489
+ reasons.push('the chain has no trust registry (AgenticID before 1.4.0) — the layers a v2 proof names cannot be checked');
490
+ return false;
491
+ }
492
+ const layers = [
493
+ ['image', proof.frameworkHash],
494
+ ['sealed', proof.sealedHash!],
495
+ ['harness', proof.harnessHash!],
496
+ ] as const;
497
+ const listed = await Promise.all(layers.map(([kind, hash]) => isListed(this.publicClient, trust, kind, hash)));
498
+ layers.forEach(([kind, hash], i) => {
499
+ if (!listed[i]) reasons.push(`the ${kind} ${hash} is not on the trust registry's ${kind} list`);
500
+ });
501
+ return listed.every(Boolean);
502
+ }
421
503
  }
package/src/Settings.ts CHANGED
@@ -85,6 +85,15 @@ export interface SettingsDoc {
85
85
  * JSON value. `undefined`/`null` omits the section entirely.
86
86
  */
87
87
  others?: unknown;
88
+ /**
89
+ * The owner's pick of the layered runtime's versions (0g-harness): the
90
+ * sealed program and the official harness package, each by its sha256
91
+ * ("0x" + 64 hex) from the trust registry's lists. A pick runs while the
92
+ * registry lists it; a layer with no pick keeps its running version while
93
+ * that stays listed, and otherwise moves to the newest listed one
94
+ * (sealed/LAYERS.md §10). The other frameworks ignore it.
95
+ */
96
+ versions?: VersionPicks;
88
97
  /**
89
98
  * The document is EXTENSIBLE by design: the container defines the
90
99
  * vocabulary, so a field newer than this SDK is legitimate. It is carried
@@ -94,12 +103,40 @@ export interface SettingsDoc {
94
103
  [key: string]: unknown;
95
104
  }
96
105
 
106
+ /** The layered runtime's version picks — Go's `settings.Versions`. */
107
+ export interface VersionPicks {
108
+ sealed?: string;
109
+ harness?: string;
110
+ /** A pick for a layer this SDK does not know yet: carried through
111
+ * {@link canonicalSettings} untouched, like an unknown top-level field. */
112
+ [layer: string]: unknown;
113
+ }
114
+
97
115
  /** `'0g-compute'` — the provider for which the platform routes the model. */
98
116
  export const ZG_COMPUTE_PROVIDER = '0g-compute';
99
117
 
100
118
  /** The fields the PLATFORM names and guarantees, in Go declaration order.
101
119
  * Everything else in a document belongs to the container. */
102
- export const SETTINGS_FIELDS = ['provider', 'model', 'thinking', 'others'] as const;
120
+ export const SETTINGS_FIELDS = ['provider', 'model', 'thinking', 'others', 'versions'] as const;
121
+
122
+ /**
123
+ * What is wrong with a document's version picks, or null: each pick, when
124
+ * set, must be "0x" + 64 hex (the container's `settings.Validate` refuses
125
+ * anything else, and storing it would only fail the live push and then the
126
+ * next boot).
127
+ */
128
+ export function versionPicksProblem(versions: unknown): string | null {
129
+ if (versions === undefined || versions === null) return null;
130
+ if (typeof versions !== 'object' || Array.isArray(versions)) return 'versions must be an object {sealed?, harness?}';
131
+ for (const layer of ['sealed', 'harness'] as const) {
132
+ const pick = (versions as Record<string, unknown>)[layer];
133
+ if (pick === undefined || pick === '') continue;
134
+ if (typeof pick !== 'string' || !/^0x[0-9a-fA-F]{64}$/.test(pick)) {
135
+ return `versions.${layer} must be a sha256 hash, "0x" + 64 hex (got ${JSON.stringify(pick)})`;
136
+ }
137
+ }
138
+ return null;
139
+ }
103
140
 
104
141
  /**
105
142
  * THE serialization. Its output is what gets hashed into the signed header
@@ -134,6 +171,29 @@ export function canonicalSettings(doc: SettingsDoc): string {
134
171
  const raw = JSON.stringify(doc.others);
135
172
  if (raw !== undefined) parts.push(`"others":${raw}`);
136
173
  }
174
+ // A pointer in Go: dropped when nil. Here an object with no pick is
175
+ // dropped too — it picks nothing either way.
176
+ const v = doc.versions as unknown;
177
+ if (v !== undefined && v !== null) {
178
+ if (typeof v === 'object' && !Array.isArray(v)) {
179
+ const picks = v as VersionPicks;
180
+ const inner: string[] = [];
181
+ if (picks.sealed) inner.push(`"sealed":${JSON.stringify(picks.sealed)}`);
182
+ if (picks.harness) inner.push(`"harness":${JSON.stringify(picks.harness)}`);
183
+ // A pick for a layer this SDK has never heard of goes through untouched,
184
+ // in its own order, for the reason unknown top-level fields do (below).
185
+ for (const [layer, pick] of Object.entries(picks)) {
186
+ if (layer === 'sealed' || layer === 'harness' || pick === undefined) continue;
187
+ const raw = JSON.stringify(pick);
188
+ if (raw !== undefined) inner.push(`${JSON.stringify(layer)}:${raw}`);
189
+ }
190
+ if (inner.length) parts.push(`"versions":{${inner.join(',')}}`);
191
+ } else {
192
+ // Not the shape the container takes: passed through for it to refuse.
193
+ const raw = JSON.stringify(v);
194
+ if (raw !== undefined) parts.push(`"versions":${raw}`);
195
+ }
196
+ }
137
197
  // Anything this SDK version has never heard of goes through untouched, in
138
198
  // its own order. The container owns the vocabulary, so a field newer than
139
199
  // this build is legitimate — and a read-modify-write that dropped it would
@@ -0,0 +1,75 @@
1
+ /**
2
+ * @file TrustRegistry.ts
3
+ * @description Reads of the trust registry (AgenticID 1.4.0+): the images,
4
+ * sealed programs and official harness versions the deployer trusts. A v2
5
+ * serve-proof's layers are checked against these lists, and an owner picks
6
+ * the layered runtime's versions from them (sealed/LAYERS.md §7, §10).
7
+ */
8
+
9
+ import { keccak256, stringToBytes, type Address, type Hash, type PublicClient } from 'viem';
10
+ import { agenticIDAbi, trustRegistryAbi } from './abi';
11
+ import { isContractRevert } from './viemErrors';
12
+
13
+ /** The registry's list kinds, each keccak256 of its name (TrustRegistry.sol). */
14
+ export const TRUST_KINDS = {
15
+ image: keccak256(stringToBytes('image')),
16
+ sealed: keccak256(stringToBytes('sealed')),
17
+ harness: keccak256(stringToBytes('harness')),
18
+ } as const;
19
+
20
+ export type TrustKind = keyof typeof TRUST_KINDS;
21
+
22
+ const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
23
+
24
+ /**
25
+ * The trust registry AgenticID names, or null when the chain has none: an
26
+ * AgenticID before 1.4.0 has no `trustRegistry()` and reverts. Any other
27
+ * failure throws — an unreachable RPC, or an error the node answered that is
28
+ * no revert (an internal error, a missing header): "no registry" is a fact
29
+ * about the chain, never a guess from a failed read.
30
+ */
31
+ export async function trustRegistryOf(publicClient: PublicClient, agenticID: Address): Promise<Address | null> {
32
+ try {
33
+ const registry = (await publicClient.readContract({
34
+ address: agenticID,
35
+ abi: agenticIDAbi,
36
+ functionName: 'trustRegistry',
37
+ })) as Address;
38
+ return registry.toLowerCase() === ZERO_ADDRESS ? null : registry;
39
+ } catch (e) {
40
+ // LEGACY(pre-1.4.0): the null a chain before AgenticID 1.4.0 answers.
41
+ if (isContractRevert(e)) return null;
42
+ throw e;
43
+ }
44
+ }
45
+
46
+ /** Whether `registry` lists `hash` under `kind`. */
47
+ export async function isListed(
48
+ publicClient: PublicClient,
49
+ registry: Address,
50
+ kind: TrustKind,
51
+ hash: Hash,
52
+ ): Promise<boolean> {
53
+ return (await publicClient.readContract({
54
+ address: registry,
55
+ abi: trustRegistryAbi,
56
+ functionName: 'isListed',
57
+ args: [TRUST_KINDS[kind], hash],
58
+ })) as boolean;
59
+ }
60
+
61
+ /** A kind's list in listing order; the last entry is the registry's `latest`. */
62
+ export async function listedHashes(
63
+ publicClient: PublicClient,
64
+ registry: Address,
65
+ kind: TrustKind,
66
+ ): Promise<Hash[]> {
67
+ return [
68
+ ...((await publicClient.readContract({
69
+ address: registry,
70
+ abi: trustRegistryAbi,
71
+ functionName: 'listed',
72
+ args: [TRUST_KINDS[kind]],
73
+ })) as readonly Hash[]),
74
+ ];
75
+ }