@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.
- package/GUIDE.md +975 -0
- package/LICENSE +21 -0
- package/MIGRATION.md +84 -0
- package/MIGRATION.zh.md +70 -0
- package/PROVIDERS.md +273 -0
- package/PROVIDERS.zh.md +234 -0
- package/README.md +334 -2
- package/dist/AgentClient.d.ts +312 -0
- package/dist/AgentClient.d.ts.map +1 -0
- package/dist/AgentClient.js +715 -0
- package/dist/AgentClient.js.map +1 -0
- package/dist/AgenticID.d.ts +823 -0
- package/dist/AgenticID.d.ts.map +1 -0
- package/dist/AgenticID.js +1188 -0
- package/dist/AgenticID.js.map +1 -0
- package/dist/AgenticIDClient.d.ts +68 -0
- package/dist/AgenticIDClient.d.ts.map +1 -0
- package/dist/AgenticIDClient.js +198 -0
- package/dist/AgenticIDClient.js.map +1 -0
- package/dist/AttestorClient.d.ts +465 -0
- package/dist/AttestorClient.d.ts.map +1 -0
- package/dist/AttestorClient.js +1030 -0
- package/dist/AttestorClient.js.map +1 -0
- package/dist/Providers.d.ts +72 -0
- package/dist/Providers.d.ts.map +1 -0
- package/dist/Providers.js +182 -0
- package/dist/Providers.js.map +1 -0
- package/dist/ReputationClient.d.ts +213 -0
- package/dist/ReputationClient.d.ts.map +1 -0
- package/dist/ReputationClient.js +708 -0
- package/dist/ReputationClient.js.map +1 -0
- package/dist/SandboxClient.d.ts +107 -0
- package/dist/SandboxClient.d.ts.map +1 -0
- package/dist/SandboxClient.js +200 -0
- package/dist/SandboxClient.js.map +1 -0
- package/dist/ServeProof.d.ts +161 -0
- package/dist/ServeProof.d.ts.map +1 -0
- package/dist/ServeProof.js +230 -0
- package/dist/ServeProof.js.map +1 -0
- package/dist/ServeSession.d.ts +180 -0
- package/dist/ServeSession.d.ts.map +1 -0
- package/dist/ServeSession.js +336 -0
- package/dist/ServeSession.js.map +1 -0
- package/dist/Settings.d.ts +179 -0
- package/dist/Settings.d.ts.map +1 -0
- package/dist/Settings.js +247 -0
- package/dist/Settings.js.map +1 -0
- package/dist/abi.d.ts +2216 -0
- package/dist/abi.d.ts.map +1 -0
- package/dist/abi.js +1248 -0
- package/dist/abi.js.map +1 -0
- package/dist/cli/commands/cells.d.ts +62 -0
- package/dist/cli/commands/cells.d.ts.map +1 -0
- package/dist/cli/commands/cells.js +113 -0
- package/dist/cli/commands/cells.js.map +1 -0
- package/dist/cli/commands/doctor.d.ts +15 -0
- package/dist/cli/commands/doctor.d.ts.map +1 -0
- package/dist/cli/commands/doctor.js +236 -0
- package/dist/cli/commands/doctor.js.map +1 -0
- package/dist/cli/commands/interactive.d.ts +115 -0
- package/dist/cli/commands/interactive.d.ts.map +1 -0
- package/dist/cli/commands/interactive.js +3052 -0
- package/dist/cli/commands/interactive.js.map +1 -0
- package/dist/cli/commands/list.d.ts +31 -0
- package/dist/cli/commands/list.d.ts.map +1 -0
- package/dist/cli/commands/list.js +91 -0
- package/dist/cli/commands/list.js.map +1 -0
- package/dist/cli/commands/providers.d.ts +3 -0
- package/dist/cli/commands/providers.d.ts.map +1 -0
- package/dist/cli/commands/providers.js +21 -0
- package/dist/cli/commands/providers.js.map +1 -0
- package/dist/cli/commands/settings.d.ts +22 -0
- package/dist/cli/commands/settings.d.ts.map +1 -0
- package/dist/cli/commands/settings.js +188 -0
- package/dist/cli/commands/settings.js.map +1 -0
- package/dist/cli/commands/status.d.ts +16 -0
- package/dist/cli/commands/status.d.ts.map +1 -0
- package/dist/cli/commands/status.js +148 -0
- package/dist/cli/commands/status.js.map +1 -0
- package/dist/cli/commands/update.d.ts +21 -0
- package/dist/cli/commands/update.d.ts.map +1 -0
- package/dist/cli/commands/update.js +95 -0
- package/dist/cli/commands/update.js.map +1 -0
- package/dist/cli/config.d.ts +73 -0
- package/dist/cli/config.d.ts.map +1 -0
- package/dist/cli/config.js +239 -0
- package/dist/cli/config.js.map +1 -0
- package/dist/cli/env.d.ts +36 -0
- package/dist/cli/env.d.ts.map +1 -0
- package/dist/cli/env.js +74 -0
- package/dist/cli/env.js.map +1 -0
- package/dist/cli/envelope.d.ts +33 -0
- package/dist/cli/envelope.d.ts.map +1 -0
- package/dist/cli/envelope.js +62 -0
- package/dist/cli/envelope.js.map +1 -0
- package/dist/cli/errors.d.ts +48 -0
- package/dist/cli/errors.d.ts.map +1 -0
- package/dist/cli/errors.js +81 -0
- package/dist/cli/errors.js.map +1 -0
- package/dist/cli/inference.d.ts +21 -0
- package/dist/cli/inference.d.ts.map +1 -0
- package/dist/cli/inference.js +60 -0
- package/dist/cli/inference.js.map +1 -0
- package/dist/cli/logo.d.ts +21 -0
- package/dist/cli/logo.d.ts.map +1 -0
- package/dist/cli/logo.js +131 -0
- package/dist/cli/logo.js.map +1 -0
- package/dist/cli/main.d.ts +14 -0
- package/dist/cli/main.d.ts.map +1 -0
- package/dist/cli/main.js +223 -0
- package/dist/cli/main.js.map +1 -0
- package/dist/cli/proofs.d.ts +67 -0
- package/dist/cli/proofs.d.ts.map +1 -0
- package/dist/cli/proofs.js +133 -0
- package/dist/cli/proofs.js.map +1 -0
- package/dist/cli/ref.d.ts +39 -0
- package/dist/cli/ref.d.ts.map +1 -0
- package/dist/cli/ref.js +48 -0
- package/dist/cli/ref.js.map +1 -0
- package/dist/cli/sdk.d.ts +24 -0
- package/dist/cli/sdk.d.ts.map +1 -0
- package/dist/cli/sdk.js +65 -0
- package/dist/cli/sdk.js.map +1 -0
- package/dist/cli/settings.d.ts +66 -0
- package/dist/cli/settings.d.ts.map +1 -0
- package/dist/cli/settings.js +137 -0
- package/dist/cli/settings.js.map +1 -0
- package/dist/cli/tokenize.d.ts +61 -0
- package/dist/cli/tokenize.d.ts.map +1 -0
- package/dist/cli/tokenize.js +157 -0
- package/dist/cli/tokenize.js.map +1 -0
- package/dist/cli/types.d.ts +25 -0
- package/dist/cli/types.d.ts.map +1 -0
- package/dist/cli/types.js +8 -0
- package/dist/cli/types.js.map +1 -0
- package/dist/constants.d.ts +107 -0
- package/dist/constants.d.ts.map +1 -0
- package/dist/constants.js +74 -0
- package/dist/constants.js.map +1 -0
- package/dist/context.d.ts +108 -0
- package/dist/context.d.ts.map +1 -0
- package/dist/context.js +64 -0
- package/dist/context.js.map +1 -0
- package/dist/index.d.ts +45 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +118 -0
- package/dist/index.js.map +1 -0
- package/dist/provider-catalog.json +23 -0
- package/dist/seal.d.ts +47 -0
- package/dist/seal.d.ts.map +1 -0
- package/dist/seal.js +145 -0
- package/dist/seal.js.map +1 -0
- package/dist/secretEnv.d.ts +119 -0
- package/dist/secretEnv.d.ts.map +1 -0
- package/dist/secretEnv.js +199 -0
- package/dist/secretEnv.js.map +1 -0
- package/dist/taskHash.d.ts +39 -0
- package/dist/taskHash.d.ts.map +1 -0
- package/dist/taskHash.js +119 -0
- package/dist/taskHash.js.map +1 -0
- package/dist/types.d.ts +336 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +19 -0
- package/dist/types.js.map +1 -0
- package/package.json +75 -4
- package/scripts/sync-providers.cjs +8 -0
- package/src/AgentClient.ts +897 -0
- package/src/AgenticID.ts +1382 -0
- package/src/AgenticIDClient.ts +238 -0
- package/src/AttestorClient.ts +1306 -0
- package/src/Providers.ts +176 -0
- package/src/ReputationClient.ts +821 -0
- package/src/SandboxClient.ts +227 -0
- package/src/ServeProof.ts +290 -0
- package/src/ServeSession.ts +421 -0
- package/src/Settings.ts +296 -0
- package/src/abi.ts +1282 -0
- package/src/cli/commands/cells.ts +107 -0
- package/src/cli/commands/doctor.ts +235 -0
- package/src/cli/commands/interactive.ts +2738 -0
- package/src/cli/commands/list.ts +95 -0
- package/src/cli/commands/providers.ts +16 -0
- package/src/cli/commands/settings.ts +197 -0
- package/src/cli/commands/status.ts +170 -0
- package/src/cli/commands/update.ts +86 -0
- package/src/cli/config.ts +225 -0
- package/src/cli/env.ts +90 -0
- package/src/cli/envelope.ts +57 -0
- package/src/cli/errors.ts +114 -0
- package/src/cli/inference.ts +57 -0
- package/src/cli/logo.ts +125 -0
- package/src/cli/main.ts +235 -0
- package/src/cli/proofs.ts +160 -0
- package/src/cli/ref.ts +58 -0
- package/src/cli/sdk.ts +65 -0
- package/src/cli/settings.ts +153 -0
- package/src/cli/tokenize.ts +131 -0
- package/src/cli/types.ts +27 -0
- package/src/constants.ts +106 -0
- package/src/context.ts +161 -0
- package/src/index.ts +129 -0
- package/src/provider-catalog.json +23 -0
- package/src/seal.ts +163 -0
- package/src/secretEnv.ts +250 -0
- package/src/taskHash.ts +100 -0
- 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.
|