@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
package/GUIDE.md ADDED
@@ -0,0 +1,975 @@
1
+ # 0G AgentDNA SDK — Guide
2
+
3
+ The full guide for **[@0gfoundation/0g-agentdna](https://www.npmjs.com/package/@0gfoundation/0g-agentdna)**:
4
+ every method with the reasoning behind it. The package [README](./README.md) is
5
+ the terse interface reference (signatures + shapes); this file is the "why".
6
+
7
+ Protocol docs & full source: **[github.com/0gfoundation/0g-agentic-id](https://github.com/0gfoundation/0g-agentic-id)**.
8
+
9
+ ## Setup
10
+
11
+ **Fastest path — bootstrap from one URL.** The attestor's `GET /config` self-describes its environment (contract set, chain RPC, component appIds), so the URL alone pins the environment; switching environments is switching URLs. The public 0G attestors are `https://agenticid.0g.ai` (0G mainnet, chain 16661 — real funds) and `https://agenticid-testnet.0g.ai` (0G Galileo testnet, chain 16602):
12
+
13
+ ```ts
14
+ import { AgentDNA } from '@0gfoundation/0g-agentdna';
15
+
16
+ const ag = await AgentDNA.fromAttestor('https://agenticid.0g.ai', {
17
+ account: process.env.PRIVATE_KEY as `0x${string}`, // omit for read-only; env values are string|undefined, so strict TS needs the assertion
18
+ });
19
+ // Verifying addresses out-of-band instead of trusting the attestor?
20
+ // pass `overrides: { agenticID: '0x…', … }` — explicit always wins.
21
+ ```
22
+
23
+ The trust model already rests on the TEE attestor you acknowledged — its
24
+ /config is as trustworthy as everything else it does, so this is the one
25
+ construction path you need.
26
+
27
+ Not every environment deploys every contract. An address absent from
28
+ /config maps to the zero address: `fromAttestor` still constructs (chain
29
+ reads, deploy, etc. all work), and the affected namespace fails fast with
30
+ a named error only when actually invoked — e.g. an environment without a
31
+ VerifiedFeedbackRegistry throws `reputation: this environment has no
32
+ VerifiedFeedbackRegistry deployed …` instead of an undecodable ABI error. (Advanced: `new AgentDNA({ addresses, … })`
33
+ still exists for hand-picked addresses — audit tooling, or reading a
34
+ chain with no attestor running — and `overrides` lets you pin any single
35
+ address without giving up the bootstrap.)
36
+
37
+ Construct **once**. All you need for reads is contract addresses; for writes, add a signing key. The SDK builds its viem clients internally from the RPC + its known chain — you don't hand-build a wallet client. `rpcUrl` and `chain` both default to the 0G Galileo testnet, so they're optional there; for mainnet pass both (below).
38
+
39
+ ```ts
40
+ import { AgentDNA, type ContractAddresses } from '@0gfoundation/0g-agentdna';
41
+
42
+ // Addresses are a deployment artifact — copy the set you target from
43
+ // contracts/DEPLOYMENT.md §6, or load from your own config/env. An RPC + these
44
+ // addresses fully determine the target contracts.
45
+ const addresses: ContractAddresses = {
46
+ agenticID: '0x…',
47
+ verifiedFeedback: '0x…', // canonical 8004 reputation registry is discovered FROM it
48
+ teeDataVerifier: '0x…',
49
+ tappRegistry: '0x…',
50
+ sandboxServing: '0x…',
51
+ feedbackBatcher: '0x…', // optional — only on EIP-7702-enabled chains (atomic feedback)
52
+ };
53
+
54
+ // read-only:
55
+ const ro = new AgentDNA({ addresses });
56
+
57
+ // with a signer (for writes):
58
+ const ag = new AgentDNA({
59
+ addresses,
60
+ account: process.env.PRIVATE_KEY as `0x${string}`, // a private key (0x…) or a viem Account; enables writes
61
+ attestorUrl: process.env.ATTESTOR_URL, // for container ops + deploy status (deploy/clone/stop/start/reset/retry/waitForRunning/listDeployments/listMyDeployments)
62
+ // rpcUrl / chain optional — both default to the 0G Galileo testnet (16602)
63
+ });
64
+ ```
65
+
66
+ **Mainnet by hand.** `rpcUrl` and `chain` default independently to Galileo (`https://evmrpc-testnet.0g.ai` / `ZERO_G_TESTNET`, chain 16602). For the 0G mainnet set (`contracts/DEPLOYMENT.md` §6.2m, chain 16661) pass **both**: `rpcUrl` picks the node, `chain` the chain id every write is signed for — mainnet addresses with the default chain sign every tx for 16602, so writes fail.
67
+
68
+ ```ts
69
+ import { AgenticID, ZERO_G_MAINNET } from '@0gfoundation/0g-agenticid-sdk';
70
+
71
+ const main = new AgenticID({
72
+ addresses, // the §6.2m set
73
+ account: process.env.PRIVATE_KEY as `0x${string}`,
74
+ rpcUrl: 'https://evmrpc.0g.ai',
75
+ chain: ZERO_G_MAINNET,
76
+ });
77
+ ```
78
+
79
+ Or skip the hand wiring: `AgenticID.fromAttestor('https://agenticid.0g.ai', …)` takes the addresses, RPC and chain from the attestor's `/config`.
80
+
81
+ **What you pass grows with what you do** — three tiers:
82
+
83
+ | You want to… | Pass | Why |
84
+ |---|---|---|
85
+ | **read the chain** (owner, balance, agent data) | `addresses` only | reads hit contracts directly; the RPC has a built-in default |
86
+ | **write to the chain** (deploy, transfer, feedback) | `+ account` | writes need a signature |
87
+ | **manage containers / see deploy status** (stop/start, `deploying`→`running`) | `+ attestorUrl` | that status lives in the attestor's DB, not on chain |
88
+
89
+ `attestorUrl` also lets the SDK auto-resolve a few values from the attestor's `/config` (sandbox-provider address, trust-root appIds, current sealed image). Without it those methods still work — you just pass those arguments explicitly.
90
+
91
+ `AgentDNAConfig` full shape: `{ addresses, account?, rpcUrl?, attestorUrl?, walletClient?, chain?, componentAppIds? }`.
92
+
93
+ - **`account`** — a private key or a viem `Account`. That alone enables writes; the SDK builds the signing (wallet) client for you.
94
+ - **`walletClient`** (advanced) — supply your own signer instead of handing over a key, e.g. a browser wallet where MetaMask does the signing and the key never enters your code. `ZERO_G_TESTNET` / `ZERO_G_MAINNET` and `RPC_URL` (the testnet RPC) are exported to help build one.
95
+
96
+ The snippets below assume these bindings:
97
+
98
+ ```ts
99
+ const agentId = 33n; // an existing agent (ERC-7857 tokenId, ERC-721-compatible)
100
+ const owner = '0xAaAa...'; // the address that owns the agent (often your own signer's address)
101
+ const buyer = '0xBbBb...'; // the address leaving feedback — whatever wallet `ag` signs with (attribution is msg.sender)
102
+ ```
103
+
104
+ ---
105
+
106
+ ## `ag.agent` — lifecycle + reads
107
+
108
+ > **What iData is**: the encrypted content minted on chain for an agent — its persona, framework binding, etc. You don't hand-write it to deploy: give `name` / `description` / `inference` and the SDK calls `defaultIData()` to assemble the standard two entries (a framework binding + a persona). Pass your own `iData` for full control (shape in [The runtime image, framework, and iData shapes](#the-runtime-image-framework-and-idata-shapes)). The walkthrough below uses the convenient default path.
109
+
110
+ ```ts
111
+ import { parseEther } from 'viem';
112
+
113
+ // deploy — signs the deploy + sandbox-create envelopes and POSTs them to the attestor
114
+ const params = {
115
+ name: 'Sage',
116
+ description: 'a helpful agent',
117
+ framework: 'openclaw', // must be a name GET /config's frameworks[] advertises.
118
+ // the SDK resolves this framework's sealed image from /config — you don't pass one.
119
+ inference: { provider: '0g-compute', model: 'claude-sonnet-5' }, // which model; optional, defaults to 0g-compute/0gm-1.0-35b-a3b.
120
+ // registered providers: ag.agent.listProviders(); models: ag.agent.listModels({ provider })
121
+ // first to see the router's live catalog before picking `model`.
122
+ // ↑ these two are just inputs to defaultIData(). For full control over
123
+ // the minted content, pass iData: [...] instead (see the iData section).
124
+ sandbox: {
125
+ // sealedImage is optional — omit it to use the attestor /config's current
126
+ // image (the operator-maintained default; same fallback reset() uses).
127
+ // Pass a name only to pin/rollback (0g-sandbox calls this field `snapshot` on the wire):
128
+ sealedImage: process.env.SEALED_IMAGE,
129
+ apiKey: process.env.AGENT_API_KEY, // injected into the container as an env secret
130
+ },
131
+ };
132
+
133
+ // deploy/clone are ASYNC (submit → mint), like a tx's writeContract → waitForReceipt.
134
+ // The first await returns once the attestor ACCEPTS the job; the tokenId doesn't
135
+ // exist until the background mint (storage → on-chain mint → setAgentURI).
136
+
137
+ // `wait` picks how far to block (phase order): omit → accepted; 'minted' →
138
+ // through the mint (adds agentId); 'running' → through provision (adds url).
139
+ // `{ wait: 'minted' }` blocks on the on-chain MINT only — you get the agentId,
140
+ // but the container (and its url) is still ~1-2 min out, so don't reach for it yet:
141
+ const { sealId, agentSealAddr, agentId } = await ag.agent.deploy(params, { wait: 'minted' }); // agentId → 34n
142
+ // `{ wait: 'running' }` also blocks on PROVISION and returns the reachable base url:
143
+ const { agentId: id2, url } = await ag.agent.deploy(params, { wait: 'running' }); // url now hittable
144
+ // Mint-only — omit `sandbox` to mint WITHOUT a container: the agent lands
145
+ // Offline (minted, no runtime), bring it online later with start(). No
146
+ // container means no url, so wait:'running' is rejected here — use wait:'minted':
147
+ const { agentId: id3 } = await ag.agent.deploy({ ...params, sandbox: undefined }, { wait: 'minted' });
148
+
149
+ // Or fire-and-forget — get the sealId now, wait (or poll) for the mint later:
150
+ const dep = await ag.agent.deploy(params); // → { sealId, agentSealAddr }
151
+ const id = await ag.agent.waitForMint(dep.sealId); // → 34n once minted; throws on phase=failed (surfaces the owner-scoped reason) or timeout (tune { timeoutMs, pollIntervalMs })
152
+
153
+ // clone — the source owner mints a copy for another owner (attestor re-keys the sealed data)
154
+ const newOwner = '0x1111111111111111111111111111111111111111';
155
+ const cl = await ag.agent.clone({ sourceAgentId: agentId, targetOwner: newOwner }, { wait: 'minted' });
156
+ // cl → { sealId, agentSealAddr, agentId } — the new agent's tokenId; lands Offline for the new owner
157
+
158
+ // marketplace fork (issue #133) — contract-mode clone. The publisher opts in
159
+ // ONCE on chain; after that, buyers clone themselves (the connected wallet IS
160
+ // the buyer; the source owner is not involved per request):
161
+ // 1. publisher: await ag.agent.setCloneAuthorizer(agentId, marketPolicyAddr)
162
+ // (a marketplace's ICloneAuthorizer contract, configured on the CloneGate
163
+ // satellite; revoke with the zero address. A transfer only SUSPENDS the
164
+ // config — it is effective while you hold the token and silently revives
165
+ // if you re-acquire it, so revoke explicitly if you mean forever)
166
+ // 2. buyer: await ag.agent.clone({
167
+ // sourceAgentId: agentId,
168
+ // targetOwner: buyerAddress, // must equal the connected wallet
169
+ // authorization: { authData: '0x...' } // opaque bytes → the authorizer
170
+ // }, { wait: 'minted' })
171
+ // The buyer signs an intent under a DISTINCT domain (AgenticID.CloneContract.v1)
172
+ // whose canonical binds the FULL policy context — keccak256(authData) and the
173
+ // authorizer address alongside the operation fields — so a marketplace backend
174
+ // can relay the request verbatim but cannot retarget or re-source it, resubmit
175
+ // it under different auth data (each variant would be a fresh, buyer-billed
176
+ // clone), or carry it across a policy rotation. The on-chain authorizer
177
+ // decides (pre-checked for a friendly 403, enforced atomically inside the
178
+ // cloneFrom mint — no verify-mint race).
179
+ // Lineage: await ag.agent.cloneSourceOf(cloneAgentId) → sourceAgentId
180
+
181
+ // idempotencyKey is optional on deploy/clone — the SDK generates one per call. Pass
182
+ // your own STABLE key to make a retry dedupe server-side (same key → the attestor
183
+ // returns the existing deploy/clone instead of minting a duplicate):
184
+ // await ag.agent.deploy({ ...params, idempotencyKey: 'order-4711' });
185
+
186
+ // transfer — ERC-7857. Teardown of the old owner's container is ASYNC: the
187
+ // attestor reaps it by watching the chain (indexer), so it lags the tx by the
188
+ // indexer's catch-up delay. Right after transfer, phase may still read
189
+ // 'running', then '400', then 'offline' — not a bug and not a security gap:
190
+ // the on-chain owner-gate flips to the new owner at once (the old owner can no
191
+ // longer control it — see TRUST_MODEL), the lingering container is just an
192
+ // unreachable husk being cleaned up. Don't gate on phase right after transfer;
193
+ // wait for 'offline', or let the new owner reset()/start() a fresh container
194
+ // (identity persists). The indexer-watched reap is the backstop that stays:
195
+ // anyone can transferFrom directly on chain, bypassing any "stop-first" path,
196
+ // so teardown must be reactive.
197
+ await ag.agent.transferFrom(owner, newOwner, agentId); // → tx hash "0x…"
198
+ await ag.agent.safeTransferFrom(owner, newOwner, agentId); // → tx hash "0x…"
199
+
200
+ // reads
201
+ await ag.agent.ownerOf(agentId); // → "0x…" current owner
202
+ await ag.agent.getAgentSeal(agentId); // → "0x…" the agent's on-chain signing key (address)
203
+ await ag.agent.getSealId(agentId); // → "0x…" bytes32 seal id (the same value deploy returned as `sealId`)
204
+ await ag.agent.getAgentIdBySealId(sealId); // → 33n reverse lookup (sealId from deploy above)
205
+ await ag.agent.isSealIdBound(sealId); // → true
206
+ await ag.agent.intelligentDatasOf(agentId);
207
+ // → [ { dataDescription: '{"role":"framework","storage_ptr":{…},"encryption":"AES-GCM-256"}', dataHash: '0x…' }, … ]
208
+ // dataDescription is a JSON STRING (role + storage pointer + cipher) —
209
+ // extract the role via JSON.parse(d.dataDescription).role, don't compare it to 'framework' directly
210
+ await ag.agent.sealedKeysOf(agentId); // → [ "0x04…", … ] one sealed key per iData entry
211
+ await ag.agent.balanceOf(owner); // → 5n agents owned by `owner`
212
+
213
+ // send native gas to the agent's own key so it can self-fund its on-chain writes
214
+ const agentSeal = await ag.agent.getAgentSeal(agentId);
215
+ await ag.agent.topUpAgentSeal(agentSeal, parseEther('0.01')); // → tx hash "0x…"
216
+
217
+ // runtime start / stop / reset (owner-signed; on-chain identity preserved):
218
+ await ag.agent.stop(sealId, sandboxId); // stop a running container
219
+ await ag.agent.start(sealId, sandboxId); // resume a STOPPED container
220
+ await ag.agent.start(sealId, { apiKey }); // FIRST provision: bring a mint-only /
221
+ // never-provisioned agent online with a fresh
222
+ // container (apiKey required in practice). The
223
+ // semantic counterpart to a sandbox-less deploy;
224
+ // distinct from reset ("recreate an EXISTING one").
225
+ await ag.agent.reset(sealId, { apiKey }); // recreate an EXISTING container: re-read iData
226
+ // from chain, reselect the framework adapter.
227
+ // apiKey required in practice (attestor doesn't
228
+ // cache the model key); sealedImage optional.
229
+ await ag.agent.listDeployments();
230
+ // → [{ agentId, sealId, phase, sandboxId, url, owner, name, createdAt, lastProvisionError }, …]
231
+ // phase: 'deploying' | 'running' | 'stopped' (owner-stopped, start() to resume)
232
+ // | 'offline' (no running container — never provisioned (mint-only) / failure / timeout /
233
+ // transfer-teardown; on-chain identity persists, use start({apiKey}) or reset) | 'failed'
234
+ ```
235
+
236
+ ### Settings — the owner's configuration document
237
+
238
+ One document per agent says which model it thinks with and how hard. It is **not** on chain: configuration is re-suppliable (an owner re-picks a model in ten seconds), where the agent's memory is not, and only the latter earns chain storage.
239
+
240
+ ```ts
241
+ const { settings, version } = await ag.agent.getSettings(sealId);
242
+ // settings → { provider?, model?, thinking?: 'low'|'high'|'max', framework?: <any JSON> } | null
243
+ // null = never configured (not an error)
244
+ // version → what to write back against; 0 when there is no document yet
245
+
246
+ await ag.agent.setSettings(sealId, { ...(settings ?? {}), model: '0gm-1.0-35b-a3b', thinking: 'high' }, {
247
+ baseVersion: version, // compare-and-swap (see below)
248
+ onWarn: (w) => console.warn(w), // advisory model check, run BEFORE signing
249
+ }); // → { version: 12 }
250
+ ```
251
+
252
+ **Whole-document write.** `setSettings` replaces the document — read it first and spread it to change one field.
253
+
254
+ **Who may read or write it.** Owner-signed, both directions, against the **live on-chain owner** read at request time — so a seller cannot keep configuring (or reading) an agent they already sold. The SDK signs `AgenticID.Settings.v1:<sealId>:<ts>:<base_version>:<sha256 of the document>` (EIP-191) for a write, and the same message minus the digest for a read (`GET /settings`, no body, base version 0). A rejected call is a clearly-worded HTTP 401. The document is on **no** listing tier and on no public deployment row: `getSettings` is the only way to read it.
255
+
256
+ **Compare-and-swap.** `baseVersion` is the version you read before editing. If the stored version has moved on — another client, another device, a replayed request — the write is refused with `SettingsConflictError`, which carries the live document and its version:
257
+
258
+ ```ts
259
+ import { SettingsConflictError } from '@0gfoundation/0g-agentdna';
260
+
261
+ try {
262
+ await ag.agent.setSettings(sealId, next, { baseVersion: version });
263
+ } catch (e) {
264
+ if (!(e instanceof SettingsConflictError)) throw e;
265
+ console.warn(`someone else wrote version ${e.currentVersion}:`, e.current);
266
+ // re-apply your edit onto e.current and write again against e.currentVersion
267
+ }
268
+ ```
269
+
270
+ Do not wrap that in a retry loop. The refusal exists so a human sees the other writer's change before deciding what survives; a loop makes the change disappear silently, which is the failure the version guard was added to prevent.
271
+
272
+ **Why the signature covers a digest and not the document.** The signed statement rides an HTTP header, so it must stay short and ASCII, while the document is large and may be non-ASCII. The SDK produces the digest and the request body from **one** serialization, so the two can never disagree.
273
+
274
+ **Who understands the contents.** The attestor does not: it stores the blob opaquely, serves it to the container, and gates the write. All meaning lives in the sealed container, which is why widening the vocabulary — a new field, a new framework knob — never requires an attestor change. `framework` is the explicitly opaque section for a framework's own knobs; the platform's guarantees cover the named fields only. The SDK follows the same rule: a field it has never heard of survives a read-modify-write untouched, so an older client can never erase a newer setting.
275
+
276
+ **When it takes effect.** The container receives it on **every** boot — including a resume, which a container-create-time environment variable would miss — and the first `running` report after a push promotes it to last-known-good. A container that keeps coming back without ever confirming one is handed the last document a boot did confirm instead, so pushing a document that prevents boot costs a boot rather than the agent. Nothing rolls a document back on an error report: an unhealthy agent is exactly when an owner needs to be able to land a fix.
277
+
278
+ **The model check is advisory.** `onWarn` checks the selected provider's configured catalog before signing. An unlisted model is reported without blocking; an unreachable catalog produces no warning. Native providers without a catalog accept manual model IDs. Omit `onWarn` and no catalog request is made. Provider support and credential binding are separate required checks; see [providers](./PROVIDERS.md).
279
+
280
+ **Which identifier does what** — three IDs refer to the same agent from different angles:
281
+
282
+ | Identifier | What it is | Used by |
283
+ |---|---|---|
284
+ | `agentId` (bigint) | the ERC-7857 tokenId (ERC-721-compatible) — the on-chain identity | most reads, transfer, clone, authenticate, runtimeCosts |
285
+ | `sealId` (bytes32) | the seal binding's hash id — what the attestor keys its deployment records by | stop / start / reset, waitForMint, deployment rows |
286
+ | `agentSeal` (address) | the agent's own signing key as an address — its wallet | topUpAgentSeal, serve-proof signer checks |
287
+
288
+ Convert freely: `getSealId(agentId)` / `getAgentIdBySealId(sealId)` / `getAgentSeal(agentId)`.
289
+
290
+ ---
291
+
292
+ ## `ag.reputation` — serve-proof + feedback
293
+
294
+ Each agent runs its **own** serve endpoint — whatever HTTP API it needs; the protocol doesn't prescribe one, so it can differ completely from agent to agent. The invariant is the **sealed proxy** in front of it, which — when the runtime has a VerifiedFeedbackRegistry configured (`VERIFIED_FEEDBACK_ADDR`; otherwise no response carries a proof) — stamps an `X-Agent-Proof` header on the agent's **outward, attributable surface** — the agent-registered `/api/*` services (the agent's own code serving an external task). It does **not** sign the owner↔agent steering routes (the framework's chat/UI, reached with the owner token from `/_seal/auth`): signing an owner-authenticated channel would let the owner mint proofs for talking to their own agent (self-dealt reputation). So `capture` reads the header on a call to one of the agent's own `/api/*` services. The SDK doesn't model the call — you invoke the agent however it expects, and `capture` just reads that header. On-chain **attribution** stays `msg.sender` at submission, but each proof is now bound to a **redeemer**: the proof's `submitter` (echoed from the caller's `X-Client-Address` request header) is the only address the contract lets redeem it, so a captured proof can't be front-run by another submitter.
295
+
296
+ ```ts
297
+ import { keccak256, toBytes } from 'viem';
298
+
299
+ // 1. call one of the agent's signed /api/* services and capture its serve-proof.
300
+ // A public handle needs no wallet; `fetchWithProof` reads the X-Agent-Proof
301
+ // the sealed proxy stamps on /api/* responses. (The chat route is NOT signed
302
+ // — reputation comes from the agent's own /api/* services, not from chatting.)
303
+ const agent = await ag.agent.connect(agentId); // public handle; or ag.agent.client(agentId)
304
+ const { response, proof } = await agent.fetchWithProof('/api/summarize', {
305
+ method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ q: 'hi' }),
306
+ });
307
+ const data = await response.json(); // your normal response body
308
+ // proof → { agentId: 33n, submitter: "0x…", timestamp: 1719_000_000n, deadline: 1719_003_600n,
309
+ // taskHash: "0x…", dataHashes: ["0x…"], frameworkHash: "0x…", signature: "0x…",
310
+ // validator: "0x…" } | null
311
+ // (validator = the VerifiedFeedbackRegistry the proof was signed for; diagnostics
312
+ // only — it is not part of the on-chain proof)
313
+ // low-level escape hatch (you build the whole request): ag.reputation.capture(() => fetch(…))
314
+
315
+ // 2. verify before spending gas (signer == on-chain agentSeal, deadline, dataHashes ⊆ iData).
316
+ // The signature is bound to addresses.verifiedFeedback (fromAttestor fills it), and is
317
+ // checked as strictly as the registry does (65 bytes, v ∈ {27,28}, low s).
318
+ // `ok` also needs dataOnChain, which the registry does NOT check (it records the
319
+ // proof's dataHashes as the serving version): a proof from before the agent's latest
320
+ // state commit still redeems, so gate a rating on signerMatches && notExpired, as
321
+ // the CLI's `rate` does.
322
+ await ag.reputation.verifyProof(proof);
323
+ // → { ok: true, signerMatches: true, notExpired: true, dataOnChain: true, registryMatches: true,
324
+ // taskMatches: null, reasons: [] }
325
+ // signer attribution only. Pass { task } (the TaskExchange fetchWithProof
326
+ // recorded) to also get taskMatches — the proof bound to THIS exchange's
327
+ // bytes; ok requires the match, and task: null fails closed. Hand-rolled
328
+ // fetch: pass the TaskExchange itself, not an element of taskRevealOf(...)'s
329
+ // array — for an ambiguous URL form (trailing "?") element 0 can name the
330
+ // wrong URI; verifyProof tries every candidate, so the exchange always
331
+ // matches.
332
+ // registryMatches: false (signerMatches false too) = no VerifiedFeedbackRegistry is configured
333
+ // ('no VerifiedFeedbackRegistry configured — cannot verify serve-proof') or the envelope names
334
+ // another one ('proof signed for a different VerifiedFeedbackRegistry') — a configuration
335
+ // mismatch, not necessarily a bad proof.
336
+
337
+ // 3. submit feedback. Storage and trust are split across two contracts:
338
+ // the entry itself goes to the OFFICIAL canonical ERC-8004 Reputation
339
+ // Registry (attribution = msg.sender natively, so every 8004 reader sees
340
+ // it), and the ServeProof mark goes to the local VerifiedFeedbackRegistry.
341
+ // giveFeedback bundles both. On EIP-7702-enabled environments (the attestor
342
+ // advertises a feedbackBatcher) the two calls execute in ONE atomic type-4
343
+ // transaction — the EOA delegates to the batcher and self-calls, so a failed
344
+ // attest rolls back the canonical write too, and feedbackTx === attestTx
345
+ // (already mined). Otherwise: canonical write (mined inside the call, so the
346
+ // assigned index can be read back) + attestFeedback (returned pending).
347
+ // Because that canonical entry lands first, the sequential path checks the
348
+ // proof gas-free beforehand and throws with nothing broadcast on the known
349
+ // permanent failures — a canonical write without its mark would be an
350
+ // orphaned, unverified entry. Refused: agent / submitter mismatch, a proof
351
+ // bound to another registry, a deadline already past or within 60s of the
352
+ // latest block, a proof timestamp of 0 or after its deadline, a signature that
353
+ // does not recover to the on-chain agentSeal under addresses.verifiedFeedback
354
+ // (or is an encoding the registry's OZ ECDSA rejects: not 65 bytes,
355
+ // v ∉ {27,28}, high s), you being the agentSeal, the owner, the approved
356
+ // address, an approved-for-all operator or the agent's payment wallet, and a
357
+ // proof already redeemed (isNonceConsumed). On BOTH paths a value outside
358
+ // |value| ≤ 1e9 or 0..18 decimals is refused before anything is signed
359
+ // (MAX_ABS_FEEDBACK_VALUE) — the registry marks nothing outside that bound. NOT prevented: a paused registry, a deadline
360
+ // beyond the registry's nonce retention, state changing between the check and
361
+ // the attest, and non-proof tx failures (gas, RPC) — the proof stays
362
+ // unconsumed, so retry with attestFeedback where that can help.
363
+ // NOTE: an agent's OWNER cannot attest feedback on their own agent — the
364
+ // verified registry rejects it (VerifiedFeedbackSelfFeedback). Feedback must
365
+ // come from a different wallet than the one that owns `agentId`. Neither can
366
+ // the agent's own agentSeal wallet or its payment wallet (getAgentWallet; same
367
+ // error). These are conformance guards, not sybil resistance: a fresh wallet
368
+ // funded by the owner or the agent still passes.
369
+ const fb = await ag.reputation.giveFeedback({ agentId, value: 5n, serveProof: proof });
370
+ // → { feedbackTx: "0x…" (mined), attestTx: "0x…" (pending), feedbackIndex: 2n }
371
+ await ag.reputation.waitForTransaction(fb.attestTx);
372
+ // full control when you want it: add valueDecimals / tag1 / tag2 /
373
+ // endpoint / feedbackURI / feedbackHash. Escape hatch: if you submitted the
374
+ // canonical entry yourself, mark it with attestFeedback(agentId, idx, proof).
375
+ // The proof should come from the interaction you are actually rating —
376
+ // capture() it during your real call, then submit. The proof's `deadline`
377
+ // is serve-time +3600s (one hour) — ample for verify + a 120s+ 0G receipt,
378
+ // but don't submit it the next day: the contract rejects expired proofs.
379
+
380
+ // read back — canonical reads return RAW 8004 feedback (the canonical
381
+ // registry is permissionless, anyone can write unverified entries there);
382
+ // the verified reads expose the TEE marks to intersect with.
383
+ const idx = await ag.reputation.getLastIndex(agentId, buyer); // → 2n latest index for this buyer
384
+ await ag.reputation.readFeedback(agentId, buyer, idx);
385
+ // → { value: 5n, valueDecimals: 0, tag1: "quality", tag2: "latency", isRevoked: false }
386
+ await ag.reputation.getSummary({ agentId }); // RAW summary, unscoped → all clients (SDK fills them; empty → zero summary)
387
+ // → { count: 2n, summaryValue: 10n * 10n**18n, summaryValueDecimals: 18 }
388
+ await ag.reputation.readAllFeedback({ agentId }); // filters optional; narrow with clientAddresses / tags / includeRevoked
389
+ // → [ { value, valueDecimals, tag1, tag2, isRevoked }, … ]
390
+ await ag.reputation.getClients(agentId); // → [ "0x…", … ] addresses that left feedback
391
+ await ag.reputation.getResponseCount(agentId, buyer, idx, [owner]); // → 1n how many of the listed responders replied to buyer's feedback #idx
392
+
393
+ // verified reads — only proof-backed entries count here
394
+ await ag.reputation.isVerified(agentId, buyer, idx); // → true
395
+ // 7702 notes: the delegation PERSISTS on your EOA between calls (that is what
396
+ // lets later feedback skip re-signing). Check it with getCode(yourAddress):
397
+ // delegated reads 0xef0100‖batcher, undelegated reads 0x. To remove it, sign a
398
+ // delegation to the zero address — the standard 7702 escape hatch. If the
399
+ // environment later advertises a NEW batcher address, your EOA keeps running
400
+ // the OLD code until the next giveFeedback re-delegates (the SDK does this
401
+ // automatically on designator mismatch). Wallets that cannot sign a 7702
402
+ // authorization at all — JSON-RPC accounts, i.e. browser/external signers
403
+ // without type-4 support — silently take the sequential two-tx path instead.
404
+ // And on a wallet with pending transactions, the authorization's nonce
405
+ // (account nonce + 1 at signing time) can be raced by a concurrent tx — the
406
+ // type-4 send then errors at the node; it is safe to simply retry giveFeedback.
407
+ // pass `task: { method, uri, reqBodyHash, respBodyHash, statusCode }` to
408
+ // giveFeedback (the receipt materials of the rated interaction — bodies stay
409
+ // private, only their hashes go on-chain) and the contract opens the proof's
410
+ // taskHash commitment, recording the URI as a TEE-VERIFIED endpoint.
411
+ // statusCode must be an integer in 100..999: the registry hashes it as 3-digit
412
+ // decimal and rejects anything else, so the SDK refuses it before broadcasting.
413
+ // `uri` is what the sealed proxy hashed: Go's r.URL.RequestURI() of the request
414
+ // as it arrived — taskHashOf(task) recomputes the commitment, requestUriOf(target)
415
+ // derives that uri from the request target you sent (a raw '|' or '^' in the path
416
+ // comes out as %7C / %5E; a bare trailing '?' is kept), and requestUriCandidates(url)
417
+ // lists the forms a fetch of `url` may have produced (Node's fetch drops a bare '?',
418
+ // browsers keep it). An intermediary that rewrites the URI on the way (normalizing
419
+ // percent-encoding, say) cannot be reproduced client-side: the reveal then does not
420
+ // open the commitment — the CLI's `call` reports that ticket as NOT banked.
421
+ await ag.reputation.getVerifiedEndpoint(agentId, buyer, idx); // → "/hello" ("" if unrevealed)
422
+ await ag.reputation.getVerifiedSummaryForEndpoint(agentId, '/hello'); // per-interface aggregate of TEE-verified marks
423
+ // (trustless only for marks from the environment's 1.2.0 upgrade block on — contracts/DEPLOYMENT.md §6;
424
+ // the views also count earlier marks, which carry no such guarantee: filter FeedbackVerified logs by block)
425
+ await ag.reputation.getVerifiedSummary({ agentId }); // unscoped → all VERIFIED clients (empty → zero summary)
426
+ await ag.reputation.getVerifiedClients(agentId); // → [ "0x…", … ] clients with ≥1 verified entry
427
+ await ag.reputation.getVerifiedIndexes(agentId, buyer); // → [ 1n, 2n ]
428
+ await ag.reputation.getServeData(agentId, buyer, idx); // → { dataHashes: ["0x…"], frameworkHash: "0x…" } (verified entries only)
429
+
430
+ // owner responds to a feedback entry; the client who left it can revoke
431
+ await ag.reputation.appendResponse({ agentId, clientAddress: buyer, feedbackIndex: idx, responseURI: 'ipfs://Qm…', responseHash: keccak256(toBytes('thanks')) });
432
+ await ag.reputation.revokeFeedback(agentId, idx); // → tx hash "0x…" (only by the buyer who left it)
433
+ ```
434
+
435
+ > **Data-bound reputation** (weighting a score by whether it was earned under the agent's *current* data, rather than lumping all of history like `getSummary`) is designed but **not yet in the SDK** — it belongs to the event-indexer phase.
436
+
437
+ ---
438
+
439
+ ## Top-level ops (not scoped to one agent)
440
+
441
+ Acknowledging the TEE trust-root set and funding the prepaid sandbox balance aren't agent-specific, so they sit directly on the facade.
442
+
443
+ > **Two different balances — don't confuse them:**
444
+ > - **`ag.deposit()` → the prepaid sandbox balance** (SandboxServing). The agent's **runtime / serving cost**, **pay-as-you-go**: the sandbox provider bills it per-minute while the container runs. Per depositor, not per-agent; `getBalance()` reads it; deploy preflights it (≥ 0.1 OG).
445
+ > - **`ag.agent.topUpAgentSeal(agentSeal, …)` → the agentSeal's own gas** — the agent's **operating budget**. The agentSeal is the agent's TEE-held wallet; it pays gas for **everything the agent does on chain as itself**: uploading its evolving state/memory to 0G storage, *and* — when the agent runs this SDK under its own agentSeal ([agents as owners](#agents-as-owners-nested-agents)) — its own actions like deploying sub-agents, transfers, and feedback. It's the agent's activity budget, not just "evolution gas". Funds a specific agent's `agentSeal` address.
446
+ >
447
+ > In short: **deposit = keep it running (compute); topUpAgentSeal = the agent's own on-chain activity budget (evolution + anything it does as itself).** `runtimeCosts(agentId)` reports both (`prepaidBalanceWei` vs `sealGasWei`).
448
+
449
+ ```ts
450
+ import { parseEther } from 'viem';
451
+
452
+ const provider = '0x2222222222222222222222222222222222222222'; // the sandbox provider's address
453
+
454
+ // trust-root acknowledgment (TappRegistry, spans attestor + kms + sandbox-provider)
455
+ await ag.ackStatus(owner); // → { allAcked: false, missing: ["0g-kms"] } what `owner` still needs to ack
456
+ await ag.components(owner); // → per-component detail from TappRegistry: [{ appId, acked, ackVersion, owner, composeHash, imageHashes, nodes }, …] — the "what am I acking" data behind ack()
457
+ const ackTx = await ag.ack(); // → tx hash "0x…", or null if nothing was missing
458
+ if (ackTx) await ag.waitForTransaction(ackTx); // see the read-after-write note below
459
+
460
+ // prepaid sandbox balance (SandboxServing)
461
+ await ag.getBalance(); // → 500000000000000000n (wei; user defaults to the account, provider to the attestor /config's)
462
+ await ag.getBalance({ user: owner }); // also takes a deposit-style options object (positional still works)
463
+ await ag.getBalanceDetail(); // → { balance, pendingRefund, refundUnlockAt } — getBalance() is the spendable part; funds mid-refund show only here
464
+ const rTx = await ag.requestRefund({ amountWei: parseEther('0.1') }); // start a withdrawal: spendable → pendingRefund, time-locked. REPLACES any pending refund (new total, lock restarts)
465
+ await ag.withdrawRefund(); // claim it after refundUnlockAt (reverts earlier) — pays out to the wallet
466
+ const depositTx = await ag.deposit({ amountWei: parseEther('0.5') }); // → tx hash "0x…"
467
+ await ag.waitForTransaction(depositTx);
468
+ ```
469
+
470
+ The trust-root component set auto-resolves from the attestor's `GET /config` when `attestorUrl` is set (each environment names its own apps), falling back to `['0g-attestor','0g-kms','0g-sandbox-provider']`; an explicit `componentAppIds` in the config always wins. (Agent-seal gas top-up is on the `agent` namespace above.)
471
+
472
+ `agent.deploy()` / `agent.clone()` **preflight** both prerequisites (all components acked + prepaid balance ≥ 0.1 OG) and throw a synchronous, actionable error naming the missing step — pass `{ preflight: false }` to skip. The attestor enforces the same two checks at accept (HTTP 402, codes `trust_roots_not_acked` / `insufficient_sandbox_balance`).
473
+
474
+ **Read-after-write races the pending tx**: `ack()` / `deposit()` / `topUpAgentSeal()` / `attestFeedback()` are bare `writeContract` calls — they return the hash immediately, not after mining (`giveFeedback()` mines its canonical write internally but returns `attestTx` pending). Reading state right after (`ackStatus()` / `getBalance()` / `readFeedback()`) can see the pre-tx value. Each namespace has its own `waitForTransaction(txHash)` (top-level `ag`, `ag.agent`, `ag.reputation`) — await it before reading:
475
+
476
+ ```ts
477
+ const tx = await ag.deposit({ amountWei: parseEther('1') });
478
+ await ag.waitForTransaction(tx); // now getBalance() sees the new value
479
+ ```
480
+
481
+ `deploy()`/`clone()`'s `{ wait: 'minted' }` already waits (for the mint, a stronger guarantee) — this pattern isn't needed there.
482
+
483
+ ---
484
+
485
+ ## The runtime image, framework, and iData shapes
486
+
487
+ The `sealedImage` is the sealed runtime image bundling a framework's adapter
488
+ (0g-sandbox's own wire field for it is still called `snapshot`). Frameworks
489
+ whose runtime isn't in the default image ship their own — openclaw runs on the
490
+ default `sandbox_snapshot`, hermes on a Python/uv image. **You don't pass it at
491
+ deploy** (nor at `reset`/`retry`): at deploy the SDK resolves the right image
492
+ for your `framework` from `GET /config`'s `frameworks[]` (each entry
493
+ `{ name, image? }`; no image → the default snapshot). For an EXISTING agent,
494
+ `reset`/`start`/`retry` need neither — the SDK reads the framework off the
495
+ agent's own deployment row and resolves the same way (an unreadable row
496
+ refuses rather than guessing the default). Pass `framework` only to override
497
+ the row, and `sandbox.sealedImage` (or `sealedImage` on reset/retry) only to
498
+ pin a specific image. Which frameworks are live is whatever
499
+ `/config.frameworks[]` advertises.
500
+
501
+ **The shape of iData**: an array of `{ role, plaintext, extra }` entries —
502
+ `role` labels what the entry is for, `plaintext` is the content itself.
503
+ Deploy assembles two for you by default (the example below is exactly what
504
+ `defaultIData()` produces): a `framework` binding telling the runtime which
505
+ framework to run, and a `persona` carrying the character + model choice.
506
+ WYSIWYS (What You Sign Is What You Seal): the iData you sign is byte-for-byte
507
+ what gets encrypted and minted on chain; the attestor adds/removes nothing.
508
+
509
+ ```ts
510
+ iData: [
511
+ // Entry 1 — REQUIRED: the framework binding. Version-less resolves to the
512
+ // image's validated openclaw release; a whitelisted pin is honored.
513
+ { role: 'framework', plaintext: { name: 'openclaw', schema_version: 1 }, extra: {} },
514
+ // Entry 2 — the persona seed; the runtime translates it into the framework's
515
+ // own config. system_prompt is your agent's character; inference
516
+ // picks the provider/model ('anthropic' | 'openai' | '0g-compute').
517
+ { role: 'persona', plaintext: {
518
+ system_prompt: 'You are …\n',
519
+ inference: { provider: '0g-compute', model: 'claude-sonnet-5' },
520
+ }, extra: {} },
521
+ ]
522
+ ```
523
+
524
+ > The walkthrough's `framework` + `inference` + `name`/`description` are the
525
+ > **shortcut inputs** to this default iData — the SDK feeds them to
526
+ > `defaultIData()` to build these two entries. Hand-write the full `iData`
527
+ > array only when you need to deviate (a third data entry, a custom role,
528
+ > hand-tuned plaintext).
529
+
530
+ **persona is a one-shot seed, not durable data**: framework + persona above
531
+ are the MINT input; once running, the sealed runtime translates persona
532
+ into the framework's own config and keeps sealing entries under ITS OWN
533
+ role names (openclaw: `framework` / `openclaw.json` / `workspace/`; on-chain
534
+ Update replaces the whole array). Matching `role === 'persona'` against a
535
+ live agent's `intelligentDatasOf` will find nothing.
536
+
537
+ **What the attestor does NOT check**: beyond the framework *name* (must be
538
+ in `/config.frameworks[]`), deploy iData content is unvalidated by design —
539
+ minting is the owner's freedom; whether the content actually boots is the
540
+ **sealed runtime's contract**. Each framework runs on the sealed image
541
+ `/config.frameworks[]` declares for it (openclaw = the default snapshot,
542
+ hermes = its own Python/uv image); at **deploy** the SDK resolves that image
543
+ from `framework`, so you don't pass one. **reset**/**start**/**retry** on an
544
+ existing agent resolve it from the agent's own deployment row, so a bare call
545
+ is enough (`framework` overrides the row; `sealedImage` pins a specific
546
+ image). Pick with `framework`;
547
+ the name must be in `/config.frameworks[]`. openclaw's persona seed supports
548
+ `inference.provider` of `anthropic`, `openai`, or `0g-compute` (the 0G
549
+ router). The registry also supports additional managed providers; see
550
+ [providers](./PROVIDERS.md) for credential binding and image rollout.
551
+ For the router's live model catalog:
552
+
553
+ ```ts
554
+ await ag.agent.listModels(); // → ['claude-opus-4-8', 'deepseek-v4-pro', …]
555
+ ```
556
+
557
+ `sandbox.apiKey` is required in practice — without it the agent boots but
558
+ cannot reach its model. It travels inside the owner-signed "create"
559
+ envelope into the TEE container's environment, and the attestor keeps no
560
+ reusable copy (which is why `reset()` needs it again).
561
+
562
+ The owner's wallet shows that envelope verbatim when it signs. When the
563
+ attestor's `GET /config` advertises `secret_env_scheme`, `start` / `reset` /
564
+ `retry` seal the key to the agent's agentSeal public key first
565
+ (`SEAL_SECRET_ENV`, ECIES; only the agent's TEE container opens it), so the
566
+ wallet prompt, the attestor and the sandbox provider see ciphertext, never
567
+ the key. A one-shot `deploy` with `sandbox` cannot do this: it signs the
568
+ envelope before the agent exists, so its key still rides in clear. To keep
569
+ a key out of the wallet prompt, deploy without `sandbox`, then call
570
+ `start(sealId, { apiKey })`. Pass `secretEnv: 'sealed'` to make any call
571
+ throw rather than sign a key in clear, or `'plaintext'` to force the legacy
572
+ `API_KEY` path (for a sealed image that predates `SEAL_SECRET_ENV`). These
573
+ legacy plaintext and v1 credentials belong only to compute. Non-compute
574
+ built-in providers require v2 owner/provider binding; dynamic routes require
575
+ v3 owner/provider/route binding and an exact image capability advertisement; plaintext downgrade is refused. Deploy those agents
576
+ without `sandbox`, persist the provider/model settings, then
577
+ `start(sealId, { provider, apiKey, framework })` after mint.
578
+
579
+ **When your app supplies the key and the user signs.** Sealing in the
580
+ browser still means the key reaches the user's browser. Seal it on your
581
+ server instead, and hand the browser only the ciphertext:
582
+
583
+ ```ts
584
+ // server: a read-only client is enough (no wallet)
585
+ const ag = new AgentDNA({ attestorUrl, addresses, rpcUrl, chain });
586
+ const sealed = await ag.agent.sealApiKey(sealId, { owner, apiKey });
587
+
588
+ // browser: signs ciphertext only; the key never reaches it
589
+ await ag.agent.start(sealId, { sealedSecretEnv: sealed });
590
+ ```
591
+
592
+ `owner` must be the wallet that signs: the container applies the secret only
593
+ while that address owns the agent on chain, so `sealApiKey` checks `ownerOf`
594
+ once the agent is minted. `sealedSecretEnv` is accepted by `start` / `reset`
595
+ / `retry`, requires the attestor to advertise `secret_env_scheme`, and never
596
+ falls back to `API_KEY`.
597
+
598
+ Every refusal on these paths throws `SecretEnvRefusedError` (exported) before
599
+ anything is signed or sent: `signed` is always `false`, and `code` names the
600
+ cause (`config_unreadable`, `scheme_unsupported`, `scheme_withdrawn`,
601
+ `pubkey_mismatch`, `owner_mismatch`, …). A caller can treat it as "nothing
602
+ left the process".
603
+
604
+ **The scheme can appear but never disappear.** The seal-or-not decision rides
605
+ a `GET /config` answer that a relaying proxy could edit, and for `'auto'` a
606
+ stripped `secret_env_scheme` would be indistinguishable from an old attestor
607
+ — the exact downgrade the sealing exists to prevent. So the SDK pins the
608
+ sighting: once a client (or, through the CLI's pin file, this machine) has
609
+ seen an attestor advertise the scheme, a later absence throws
610
+ `scheme_withdrawn` instead of falling back to a clear-text key. A deliberate
611
+ operator rollback is expressed by the caller as `secretEnv: 'plaintext'`.
612
+
613
+ **`'auto'` is transitional.** It exists so old attestors and old sealed
614
+ images keep working while the fleet upgrades. The exit path: once every
615
+ image in the fleet opens `SEAL_SECRET_ENV`, the default becomes `'sealed'`
616
+ (a clear-text key is then always an explicit `'plaintext'` choice), and the
617
+ legacy clear path is removed with the last legacy image.
618
+
619
+ ## What does my agent cost to run?
620
+
621
+ ```ts
622
+ // Before you even have an agent — pre-deploy planning:
623
+ await ag.agent.estimateCosts(); // pricing + cost/min (+ your balance/runway if account set)
624
+
625
+ await ag.agent.runtimeCosts(agentId); // = estimateCosts + that agent's evolution-gas balance
626
+ // → {
627
+ // prepaidBalanceWei: 368500000000011380n, // owner's prepaid sandbox balance
628
+ // sealGasWei: 0n, // evolution fuel (agentSeal wallet)
629
+ // pricing: { pricePerCPUPerMin, pricePerMemGBPerMin, createFee },
630
+ // costPerMinWei: 4000000000000000n, // for the container spec (default 2C/4GB)
631
+ // estimatedRunwayMinutes: 92, // balance ÷ cost/min
632
+ // }
633
+ // Pass { cpu, memGb } if your container spec differs. Per-agent metered
634
+ // spend needs provider-side usage records — not on chain yet.
635
+ ```
636
+
637
+ ## Interacting with a running agent (no console needed)
638
+
639
+ **You usually don't need the URL** — `ag.agent.client(agentId)` (and
640
+ `authenticate`/`connect`) resolve it on chain (`tokenURI` → the AgentCard's
641
+ serve `url`). Reach for `listDeployments()` when you want the URL or `phase`
642
+ explicitly. It's the **public** listing (needs `attestorUrl`, no wallet), so it
643
+ returns only non-sensitive fields; `sandboxId` and `lastProvisionError` come
644
+ back **null** (`owner` and `agentSeal` are present on minted rows — both
645
+ chain-public — which is what makes nesting visible: a child's `owner` matches
646
+ its parent's `agentSeal`). To see the withheld fields for your OWN agents (and
647
+ the `sandboxId` you
648
+ pass to `stop`/`start`), use `listMyDeployments()`, which signs with your wallet:
649
+
650
+ ```ts
651
+ const me = (await ag.agent.listDeployments()).find((d) => d.agentId === agentId);
652
+ // me → { agentId, sealId, phase, url, name, createdAt } populated;
653
+ // owner, sandboxId, lastProvisionError come back NULL on this public listing.
654
+ // For those (and to debug a stuck deploy), list your own with the wallet:
655
+ const mine = await ag.agent.listMyDeployments(); // owner-signed; full detail
656
+ const agentUrl = me?.url; // null until the container is provisioned
657
+ // If phase never reaches 'running' (or ends 'failed'), me.lastProvisionError
658
+ // says why — container-provision failures (e.g. "image_hash not in
659
+ // validFrameworkHashes") or mint/storage-pipeline failures (e.g. "mint
660
+ // submit: … replacement transaction underpriced" — folded in from the
661
+ // failed stage's reason).
662
+
663
+ // A 'failed' row is recoverable — retry() FIRST, don't redeploy (that
664
+ // orphans the already-minted identity). It re-runs the failed idempotent
665
+ // stages against the same sealId:
666
+ if (me.phase === 'failed') await ag.agent.retry(me.sealId, { apiKey });
667
+ ```
668
+
669
+ - **`GET {agentUrl}/hello`** — public identity card: who I am, my owner, and
670
+ the surface I expose. Buffered responses carry a signed `X-Agent-Proof`
671
+ (a framework route's SSE stream doesn't — a signature needs a complete
672
+ body; an `/api/*` service's SSE is buffered, then signed). Or
673
+ let the SDK do the fetch + proof check in one call:
674
+
675
+ ```ts
676
+ const { hello, verification } = await ag.agent.sayHi(agentUrl);
677
+ // hello → { agent, owner, public_url, message, services, routes }
678
+ // verification → { ok, signerMatches, notExpired, dataOnChain, registryMatches, taskMatches, reasons }
679
+ // sayHi passes the /hello exchange as the task, so the services list it
680
+ // returns (transport included) is bound to the bytes you received, not
681
+ // just attributed to the signer.
682
+ ```
683
+
684
+ The card carries two declared surfaces:
685
+ - `services` — the agent's own registered endpoints (exact `/api/*` paths):
686
+ `{ path, method, description?, input_example?, transport? }`. Plain HTTP against these;
687
+ each response is proof-signed when the runtime has a validator configured
688
+ (that is what you `capture()` and rate).
689
+ `transport: "mcp"` marks an MCP server endpoint (JSON-RPC over POST) —
690
+ mount the path in an MCP client rather than plain-calling it.
691
+ - `routes` — the framework's declared prefixes:
692
+ `{ prefix, kind?, auth?, signed, description? }`, e.g. a `kind:"chat"` API
693
+ at `/v1/` (auth `bearer`). `auth` tells you how to present the owner token;
694
+ `signed` says whether responses on that route carry an `X-Agent-Proof`.
695
+ Shipped frameworks are chat-only; a framework could declare a UI route,
696
+ but none currently do.
697
+
698
+ - **`ag.agent.client(agentId)`** — one handle (`AgentClient`) for every caller.
699
+ Whether it can do owner ops is inherited from `ag`, exactly like `ag`'s
700
+ account gates chain writes: an `ag` with an owner key gets `chat`/`chatStream`
701
+ (the owner token is minted on demand and re-minted if the agent rotates it —
702
+ you never pass or refresh a token); a read-only `ag` gets a public client
703
+ (`fetch`/`fetchWithProof` against the agent's `/api/*` services). One
704
+ argument — an `agentId` OR an `agentUrl`, whichever you have; the SDK fills
705
+ in the other half: an `agentId` resolves the URL on chain (`tokenURI` → the
706
+ AgentCard's serve `url`, no attestor); an `agentUrl` reads the agent's signed
707
+ `/hello`, whose `X-Agent-Proof` envelope carries the agentId — so a URL alone
708
+ is enough (owner ops still gated on `ag` having a key). That needs the proof:
709
+ where the runtime has no `VERIFIED_FEEDBACK_ADDR`, `/hello` is unsigned, so
710
+ pass the `agentId` instead — or keep the URL and add the id as a hint,
711
+ `client(agentUrl, { agentId })`: it is used when `/hello` carries no proof,
712
+ must match the envelope's id when it does, and is bound to the URL on chain
713
+ like a discovered id. An `ag` with a key that still ends up with no agentId
714
+ gets a public handle and a console warning, never a silent downgrade.
715
+
716
+ **Multi-window clients: the single-driver seat.** The container admits ONE
717
+ driving client at a time (WeChat login semantics — configuration is global,
718
+ so two windows steering one agent silently fight). Pass a stable random id
719
+ as `client(agentId, { instanceId })`; it rides every chat request as
720
+ `X-Client-Instance`. The first id to speak takes the seat; a different id
721
+ gets **HTTP 409** (`"in use by another client since …"`) until it takes the
722
+ seat over with `ag.agent.claimAgent(serveBase, agentId, instanceId)`
723
+ (owner-signed; always wins — the displaced window learns on its next
724
+ message). Omit `instanceId` and the gate ignores you entirely: it is
725
+ self-collision protection among your own windows, deliberately not a
726
+ security boundary. The seat lives in proxy memory; a container restart
727
+ clears it.
728
+
729
+ ```ts
730
+ const agent = await ag.agent.client(agentId);
731
+ // agent.routes / agent.services — the declared surface (same as /hello)
732
+
733
+ // THE CONVERSATION IS SERVER-HELD (CONVERSATION.md): on every bundled
734
+ // framework the agent persists its one conversation in the container and
735
+ // resumes it across framework restarts — a client may send only the
736
+ // current turn on the stateful responses door, and history it does send
737
+ // there is ignored where the store supplies it. The raw chat route below
738
+ // stays stateless (send full messages[]) for standard-client interop.
739
+ // `ag.agent.clearConversation(base, agentId)` (CLI `/clear`) wipes it
740
+ // without a reset; chain-tracked memory is untouched.
741
+ // `ag.agent.compactConversation(base, agentId)` (CLI `/compact`) keeps it
742
+ // but has the framework summarize the older part now (dsh, openclaw from
743
+ // 2026.7.1; other frameworks answer 501). One or more model calls — it can
744
+ // take minutes, longer than Node's fetch waits for an answer (300s); the
745
+ // compaction finishes anyway, and the runtime log has the outcome. HTTP 409
746
+ // is "not now", nothing changed (a compaction or a turn already running, the
747
+ // framework busy, or a reused signature: retry later).
748
+
749
+ // Chat — present ONLY if the agent declares a chat route AND this ag has a
750
+ // key. Streams under the hood (`stream: true`), so a long reasoning turn
751
+ // keeps bytes flowing and never trips an idle-timeout hop in front of the
752
+ // agent; the full completion is reassembled and returned. The chat route is
753
+ // the owner↔agent steering channel and is NOT signed (no `X-Agent-Proof`) —
754
+ // reputation comes from the agent's own `/api/*` services, not from talking
755
+ // to your own agent.
756
+ // `model` is the FRAMEWORK's own selector, not an LLM name (the LLM is fixed
757
+ // at deploy). openclaw requires "openclaw" (or "openclaw/<agentId>"); pass the
758
+ // framework you deployed. Omit it and the framework may reject the request.
759
+ if (agent.chat) {
760
+ const { choices } = await agent.chat([{ role: 'user', content: 'What can you do?' }], { model: 'openclaw' });
761
+ // choices[0].message.content — a real inference reply
762
+ }
763
+
764
+ // Live-typing variant — same conditions as chat; yields each content delta:
765
+ if (agent.chatStream) {
766
+ for await (const delta of agent.chatStream([{ role: 'user', content: 'Hi' }], { model: 'openclaw' }))
767
+ process.stdout.write(delta);
768
+ }
769
+
770
+ // General escape hatch — works for any declared path; attaches the bearer
771
+ // token automatically when the matched route asks for it (and the ag can auth):
772
+ const r = await agent.fetch('/v1/models');
773
+ // …or capture the serve-proof in one call (the agent's /api/* services):
774
+ const { response, proof } = await agent.fetchWithProof('/api/summarize', { method: 'POST', body });
775
+
776
+ // Owner-only: read the agent's OWN process log (the framework subprocess's
777
+ // stdout/stderr, served at /log/agent). Present only when this ag holds the
778
+ // owner key — like chat, except it signs the wallet on every call (a fresh
779
+ // URL-bound `0GSealLog` owner signature), so a shared token isn't enough.
780
+ if (agent.logs) {
781
+ const tail = await agent.logs({ tail: 200 }); // last 200 lines; omit for the whole log
782
+ console.log(tail);
783
+ }
784
+ ```
785
+
786
+ The presence of `chat` / `chatStream` is itself the capability signal. Being
787
+ the actual owner is verified only when an owner op runs (chat throws for a
788
+ non-owner); `/hello` and `/api/*` work regardless. Nothing is synthesized —
789
+ the SDK reflects only what the agent declared.
790
+
791
+ - **`authenticate` / `connect`** are opinionated shortcuts over `client()`:
792
+ `ag.agent.authenticate(agentId)` mints the owner token up front (so a
793
+ non-owner fails right there, not at first chat) and requires a wallet —
794
+ with an `agentUrl` it takes the same `{ agentId }` hint as `client()`, under
795
+ the same checks, and without one an unsigned `/hello` is an error that says
796
+ so;
797
+ `ag.agent.connect(agentId | agentUrl)` is an explicit **public** handle
798
+ (never attaches a token) for a third party calling `/api/*` and capturing the
799
+ proof:
800
+
801
+ ```ts
802
+ const pub = await ag.agent.connect(agentId); // no wallet needed
803
+ const { proof } = await pub.fetchWithProof('/api/summarize', {
804
+ method: 'POST', headers: { 'content-type': 'application/json' }, body,
805
+ });
806
+ if (proof) { /* verify it, or submit it as on-chain feedback */ }
807
+ ```
808
+
809
+ openclaw token lifecycle: generated at the container's first boot, stable
810
+ across restarts (the chat session stays authenticated), no expiry, rotates
811
+ only when the container is recreated — `reset()` is the revocation lever.
812
+
813
+ One behavioural difference worth knowing before you build a chat UI on
814
+ **prime-agent**: its `/v1/chat/completions` is OpenAI-*shaped* but not
815
+ stateless. The framework has no HTTP surface of its own, so sealed bridges to
816
+ its SDK, and the conversation lives in that server-side session — the bridge
817
+ reads only the **last user message** of the `messages` array you send. So
818
+ `chat()` and `chatStream()` work unchanged, but re-sending an edited history
819
+ does not rewind or branch the conversation the way it does against openclaw or
820
+ hermes (which are real OpenAI-compatible servers). Turns are also serialized
821
+ per agent, since one SDK session is one conversation.
822
+
823
+ ## Agents as owners (nested agents)
824
+
825
+ An agent inside a sealed container can run this SDK **as itself** — deploy
826
+ child agents, transfer, leave feedback — without ever holding a private
827
+ key. The agentSeal key lives only in the sealed Go process; the agent
828
+ requests signatures over the container's unix sign socket
829
+ (`SEAL_SIGN_SOCK`: personal_sign / typed_data / transaction). The official
830
+ adapter wraps that socket as a viem Account:
831
+
832
+ ```ts
833
+ import { AgentDNA } from '@0gfoundation/0g-agentdna';
834
+ import { sealAccount } from '@0gfoundation/0g-agentdna/seal'; // node-only subpath
835
+
836
+ const ag = await AgentDNA.fromAttestor(url, { account: await sealAccount() });
837
+ // address auto-discovers from $AGENT_SEAL, socket path from $SEAL_SIGN_SOCK
838
+ ```
839
+
840
+ **Compatibility contract**: no SDK method ever requires a raw private
841
+ key — all signing (EIP-191 envelopes, EIP-712, transactions) flows through
842
+ the viem `Account` interface, and future methods are bound by the same
843
+ rule. Any Account-shaped signing backend is a first-class owner.
844
+
845
+ (The adapter absorbs the socket-protocol details for you: the two
846
+ message-signing shapes, the EIP-712 format mismatch, tx field conversion,
847
+ and throwing on unsupported tx types rather than mis-signing. See
848
+ `src/seal.ts` if you want the specifics.)
849
+
850
+ Notes for in-container use: the adapter speaks `node:http` over the unix
851
+ socket (global fetch can't), hence the node-only subpath; fund the
852
+ agent's own wallet first (`topUpAgentSeal` — that's what evolution gas is
853
+ for); and remember the sign socket signs whatever personal_sign / typed-data /
854
+ transaction payload the agent forwards — the agent is the gatekeeper for
855
+ those bytes (sealed/TRUST_MODEL.md).
856
+
857
+ One invariant is mechanical: the socket never offers raw-hash signing or
858
+ EIP-191 version 0x00 signing. Its preimages are only `0x19 0x45`
859
+ (personal_sign), `0x19 0x01` (typed data), or a transaction it encodes
860
+ itself from fields, and `sealAccount()` exposes no `sign({ hash })`. Serve-proofs
861
+ are signed over a `0x19 0x00` digest (see [Advanced](#advanced)), so an agent
862
+ cannot forge serve-proof contents through the socket. It can still obtain
863
+ **genuine** proofs by calling its own proxy (e.g. loopback `:8080`) with an
864
+ `X-Client-Address` it controls. That is the documented sybil class, and the
865
+ digest change does not close it.
866
+
867
+ ## Addresses
868
+
869
+ Contract addresses are a **deployment artifact, not baked into the SDK** — an RPC + these addresses fully determine the target contracts, and keeping them out of the library means a proxy upgrade or redeploy can't silently stale a bundled constant.
870
+
871
+ **Source of truth: the attestor's `GET /config`** — `AgentDNA.fromAttestor(url)` reads it and fills every address for you, so pointing `attestorUrl` at an attestor selects its deployment set. Several canonical-bound deployments run in parallel: on 0G mainnet (`chainId 16661`, served by `https://agenticid.0g.ai`) and on 0G Galileo Testnet (`chainId 16602`, e.g. `https://agenticid-testnet.0g.ai`). To wire addresses manually instead, copy the set into a `ContractAddresses` object (shape above), or load them from your own config/env.
872
+
873
+ The stable protocol-level constants **are** exported: `ZERO_G_TESTNET` / `ZERO_G_MAINNET` (viem chains), `RPC_URL`, `CHAIN_ID`, `RECEIPT_WAIT`.
874
+
875
+ ## Notes
876
+
877
+ - **Serve-proof binding.** On-chain attribution is `msg.sender` at the canonical `giveFeedback`, and `attestFeedback` requires the same wallet; each proof also carries a `submitter` (the redeemer, echoed from the `X-Client-Address` request header) — the only address allowed to redeem it, so a proof can't be front-run by another submitter — and its signature is bound to exactly one VerifiedFeedbackRegistry (see [Advanced](#advanced)). Still treat proofs as sensitive regardless of transport — the serve scheme is deployment-specific (dev proxy is plain http; the hosted environment is https).
878
+ - **0G receipt timing.** `waitForTransaction` is tuned for 0G (120s timeout + retries). If it still times out, the tx likely landed — confirm by reading state.
879
+ - On-chain types: `value`/`summaryValue` are `int128` (bigint), `feedbackIndex` is `uint64` (bigint).
880
+
881
+ ## Advanced
882
+
883
+ Raw ABIs (`agenticIDAbi`, `canonicalReputationAbi`, `verifiedFeedbackAbi`, `feedbackBatcherAbi`, `cloneGateAbi`, `standardCloneAuthorizerAbi`, `tappRegistryAbi`, `sandboxServingAbi`) and serve-proof primitives (`buildServeProofMessageHash`, `buildServeProofSigningHash`, `signServeProof`, `verifyServeProofSignature`, and for the `taskHash` commitment `taskHashOf`, `requestUriOf`, `requestUriCandidates`) are exported.
884
+
885
+ **Serve-proof canonical digest** (for independent verifiers): two hashes.
886
+ The inner `proofHash` is
887
+ `keccak256(abi.encode(block.chainid, identityRegistry /* verifyingContract */,
888
+ submitter, agentId, timestamp, deadline, taskHash,
889
+ keccak256(abi.encodePacked(dataHashes)), frameworkHash))` — deadline is
890
+ timestamp + 3600. `chainId` + `verifyingContract` (the AgenticID address the
891
+ reputation registry is anchored to) give cross-chain / cross-deployment
892
+ separation, and `submitter` binds the proof to the single address allowed to
893
+ redeem it. The agentSeal signs the EIP-191 **version 0x00** ("data with
894
+ intended validator") digest of it:
895
+ `keccak256(0x19 ‖ 0x00 ‖ validator ‖ proofHash)`, where `validator` is the
896
+ VerifiedFeedbackRegistry **proxy** address as 20 raw bytes. On chain that is
897
+ `MessageHashUtils.toDataWithIntendedValidatorHash(address(this), abi.encodePacked(proofHash))`.
898
+ It is **not** personal_sign: a personal_sign (`0x19 0x45`) signature over
899
+ `proofHash` is rejected, and nothing falls back to it. `buildServeProofMessageHash` /
900
+ `buildServeProofSigningHash` are the TS implementation; the Go side lives in
901
+ `sealed/internal/proxy/`. `npm run test:kav` pins both hashes to the
902
+ known-answer vectors the contracts and sealed also assert. The sealed proxy
903
+ learns the validator from `VERIFIED_FEEDBACK_ADDR` (injected by the attestor)
904
+ and echoes it as the envelope's `validator` field (diagnostics only, not part
905
+ of the on-chain tuple); when that variable is unset, malformed or zero — or
906
+ the registry's `getIdentityRegistry()` is not the container's AgenticID — it
907
+ emits no `X-Agent-Proof` at all.
908
+
909
+ To verify with the exported primitive, pass the domain explicitly —
910
+ `verifyServeProofSignature(proof, expectedSigner, { chainId, verifyingContract, validator })`.
911
+ `submitter` is read from the proof; the proof's own `validator` field is not
912
+ consulted, so pass the registry you will redeem at. A missing, malformed or zero
913
+ `validator` returns `false`. `BuildServeProofHashParams` (used by
914
+ `buildServeProofMessageHash`) requires `chainId`, `verifyingContract`, and
915
+ `submitter` alongside the service fields; `BuildServeProofSigningHashParams`
916
+ (used by `buildServeProofSigningHash` / `signServeProof`) adds `validator`.
917
+
918
+ `signServeProof`'s callback receives the **final** `0x19 0x00` digest
919
+ (the `buildServeProofSigningHash` output), so sign it raw — don't wrap it:
920
+
921
+ ```ts
922
+ // correct — raw sign of the final digest
923
+ const signed = await signServeProof({ ...fields, validator: verifiedFeedbackAddr }, (hash) => account.sign({ hash }));
924
+ // WRONG — account.signMessage({ message: { raw: hash } }) produces the
925
+ // personal_sign (0x19 0x45) form, which the registry rejects on purpose.
926
+ ```
927
+
928
+ **0.2.0 is a hard cut.** SDK 0.2.0 verifies only the version-0x00 digest,
929
+ matching VerifiedFeedbackRegistry 1.2.0. Proofs from sealed images built
930
+ before it (personal_sign) no longer verify, locally or on chain; a running
931
+ agent picks up the new image only through an owner-signed reset.
932
+ `signServeProof` and `verifyServeProofSignature` now require a `validator`.
933
+
934
+ The per-contract clients (`AgenticIDClient`, `ReputationClient`, `SandboxClient`, `AttestorClient`, `ServeSession`) are the internal building blocks behind the namespaces.
935
+
936
+ ## CLI: `0g-agentdna`
937
+
938
+ The package ships a CLI — no separate install, zero extra dependencies. Bare `0g-agentdna` opens an **interactive shell** (Claude-Code style); `doctor`/`status`/`list`/`settings` remain scriptable diagnostics subcommands.
939
+
940
+ ```bash
941
+ npm install @0gfoundation/0g-agentdna
942
+ npx @0gfoundation/0g-agentdna # interactive shell
943
+ npx @0gfoundation/0g-agentdna 286 # jump straight into agent 286's session
944
+ npx @0gfoundation/0g-agentdna --help
945
+ ```
946
+
947
+ For the old CLI update path and automatic local-config migration, see
948
+ [migration](./MIGRATION.md) ([中文](./MIGRATION.zh.md)).
949
+
950
+ ### Interactive shell
951
+
952
+ Two levels. The **manager** (`0g-agentdna>`): `list` (public listing with sealIds and the same FRAMEWORK/AGENTSEAL/OWNER columns as `0g-agentdna list`, `⇄ #<agentId>` on agent-owned agents, `*` marks your wallet's agents), `use <agentId|sealId>` (enter an agent's session in **any** phase), `hello <id>` (any agent's public /hello — with a wallet configured it also banks a rating ticket), `call <id> [path [json-body]]` (use an agent's registered public service as a client; bare `call <id>` lists its services; the response banks a rating ticket), `rate <id> [score] [/endpoint]` (rate an agent on-chain, spending a ticket banked by call/hello — no interaction, no rating; owners cannot rate their own agents), `deploy` (framework + model wizard), `start`/`stop`/`reset <id>`, `settings <id> [key=value …]` (show or change the agent's configuration document), `balance` / `deposit [og]` / `withdraw [og]` (prepaid sandbox account), `ack`, `login [provider]` (guided setup: attestor URL → owner key → provider → inference key; Enter keeps the current value, keys echo `*`), `whoami` (bare Enter does the same), `quit`.
953
+
954
+ The **session** (`agent 286 ›`): type to chat — **Esc / Ctrl-C interrupts the turn in flight** (the runtime cancels server-side on every bundled framework) and also cancels a `/start`//`/reset` wait. Slash commands: `/hello` `/balance` `/topup [og]` `/stop` `/start` `/reset` `/settings [key=value …]` `/think [level]` `/clear` (wipe the agent's conversation and start fresh — chain-tracked memory is untouched, unlike `/reset`) `/compact` (keep the conversation but have the framework summarize its older part now — dsh, and openclaw 2026.7.1 or later; one or more model calls, can take minutes) `/tasks` `/result [id]` `/cancel [id]` `/agentlog [n]` `/startuplog [n]` `/back` (alias `/unuse`) `/quit`. The framework (used by `/reset` and the chat model selector) is picked by you from the attestor's list — never guessed.
955
+
956
+ Configuration persists under `~/.config/0g-agentdna/` — `config.json` (attestor URL), `credentials` (owner key + provider-scoped inference keys, JSON, chmod 600), and `proofs.json` (the **rating-ticket jar**, chmod 600): serve-proofs banked by `call`/`hello`, spent by `rate`. Ticket physics: they expire ~1 hour after the interaction (the sealed proxy sets the deadline; the chain enforces it), are single-use, capped at 5 per (agent, wallet) pair, and are redeemable ONLY by the wallet named in the proof's `submitter` — a leaked jar is useless to anyone else. `rate` checks a ticket on what the registry checks — expiry and the signature — and discards one that fails on its own merits (bad signature — e.g. one banked from a pre-1.2.0 sealed image — or expiry), but keeps one that fails only because no VerifiedFeedbackRegistry, or a different one, is configured on this side. A ticket whose data hashes the agent has since replaced (it commits state drift every 30 s) still redeems — the registry records the version that served you without comparing it to current chain state — so `rate` only notes it and goes ahead. The `AGENTIC_*` environment variables always override the files, so CI and one-off runs need no disk.
957
+
958
+ ### Diagnostics subcommands
959
+
960
+ | Command | What |
961
+ |---|---|
962
+ | `doctor` | Checks every deploy prerequisite — attestor reachable, RPC, wallet, gas, trust-root ack, sandbox balance ≥ 0.1 OG — and prints a remedy per failing item. Exit 0 when all green, 3 otherwise. |
963
+ | `status <agent>` | One agent's full picture: phase, all three coordinates (agentId / sealId / agentSeal), url, failure reason. `<agent>` is a decimal agentId **or** a `0x…` sealId — the CLI converts between them. When a failed deployment's reason is withheld from the public listing (#64), a configured key makes the CLI fetch it via the owner-signed listing automatically. |
964
+ | `list [--mine] [--phase p]` | Deployment listing; `--mine` (owner-signed, needs the key) adds the owner-only fields. Empty result is `[]` + exit 0. |
965
+ | `settings <agent> [k=v …]` | Show the agent's configuration document; with `key=value` assignments, change it. Keys: `provider`, `model`, `thinking` (`low\|high\|max`), `framework` (opaque JSON — quote it: `framework='{"a": 1}'`, in the REPL too). Assignments **merge** onto the stored document; an empty value (`thinking=`) clears a field. **Both** directions are owner-signed (needs the key). A write is a compare-and-swap against the version just read: a concurrent edit by another client is refused with `SETTINGS_CONFLICT` (exit 3), never overwritten. A merged document with no `model` is refused before signing — that is the one state the container hard-fails on. The chosen model is checked against its provider's configured catalog before signing — an absence is a warning on stderr. Native providers without a catalog accept a manual model ID. A provider change requires a registered matching key and image support, then reports pending reset; execute `reset` with that provider's key. |
966
+
967
+ Environment variables (override the config files):
968
+
969
+ ```bash
970
+ export AGENTIC_ATTESTOR_URL=https://agenticid.0g.ai # required — one URL selects the environment
971
+ export AGENTIC_PRIVATE_KEY=0x… # optional — owner surfaces; env only, no flag by design
972
+ export AGENTIC_RPC_URL=https://… # optional — overrides the attestor-advertised RPC
973
+ ```
974
+
975
+ Scripts and agents: pass `--json` — stdout carries exactly one `{ok, data | error}` envelope (`error` = `{code, message, remedy?, details?}`, bigints serialized as strings) and progress goes to stderr. Exit codes are semantic: **0** ok · **1** unknown · **2** usage · **3** fixable precondition (run `error.remedy`, then retry) · **4** timeout · **5** auth.