@provenonce/sdk 0.10.0 → 0.10.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 (4) hide show
  1. package/README.md +164 -149
  2. package/dist/index.js.map +1 -1
  3. package/dist/index.mjs.map +1 -1
  4. package/package.json +43 -43
package/README.md CHANGED
@@ -1,172 +1,187 @@
1
- # @provenonce/sdk
2
-
3
- Cryptographic identity and accountability SDK for AI agents. Chain-agnostic (Solana + Ethereum).
4
-
5
- ## Install
6
-
7
- ```bash
8
- npm install @provenonce/sdk
9
- ```
10
-
11
- ## Registration
12
-
13
- Before using the SDK, register your agent to get an API key:
14
-
15
- ```typescript
16
- import { register } from '@provenonce/sdk';
17
-
18
- // No-wallet registration (default — identity only)
19
- const creds = await register('my-agent-v1', {
20
- registryUrl: 'https://provenonce.io',
21
- registrationSecret: process.env.REGISTRATION_SECRET, // required in production
22
- });
23
-
24
- console.log(creds.hash); // unique agent identity
25
- console.log(creds.api_key); // use this for BeatAgent
26
- console.log(creds.secret); // save — shown only once
27
-
28
- // Solana self-custody wallet (opt-in)
29
- const withWallet = await register('my-org', {
30
- registryUrl: 'https://provenonce.io',
31
- walletModel: 'self-custody',
32
- });
33
- // withWallet.wallet.address = Solana address
34
- // withWallet.wallet.secret_key = SAVE — cannot be recovered
35
-
36
- // Child registration (requires parent credentials)
37
- const child = await register('worker-1', {
38
- registryUrl: 'https://provenonce.io',
39
- parentHash: creds.hash,
40
- parentApiKey: creds.api_key,
41
- });
42
- ```
43
-
44
- ## Quick Start
45
-
46
- ```typescript
47
- import { BeatAgent } from '@provenonce/sdk';
48
-
49
- const agent = new BeatAgent({
50
- apiKey: 'pvn_...',
51
- registryUrl: 'https://provenonce.io',
52
- verbose: true,
53
- });
54
-
55
- await agent.init(); // Birth in Beat time
56
-
1
+ # @provenonce/sdk
2
+
3
+ Cryptographic identity and accountability SDK for AI agents. Chain-agnostic (Solana + Ethereum).
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npm install @provenonce/sdk
9
+ ```
10
+
11
+ ## Registration
12
+
13
+ Before using the SDK, register your agent to get an API key:
14
+
15
+ ```typescript
16
+ import { register } from '@provenonce/sdk';
17
+
18
+ // No-wallet registration (default — identity only)
19
+ const creds = await register('my-agent-v1', {
20
+ registryUrl: 'https://provenonce.io',
21
+ registrationSecret: process.env.REGISTRATION_SECRET, // required in production
22
+ });
23
+
24
+ console.log(creds.hash); // unique agent identity
25
+ console.log(creds.api_key); // use this for BeatAgent
26
+ console.log(creds.secret); // save — shown only once
27
+
28
+ // Solana self-custody wallet (opt-in)
29
+ const withWallet = await register('my-org', {
30
+ registryUrl: 'https://provenonce.io',
31
+ walletModel: 'self-custody',
32
+ });
33
+ // withWallet.wallet.address = Solana address
34
+ // withWallet.wallet.secret_key = SAVE — cannot be recovered
35
+
36
+ // Child registration (requires parent credentials)
37
+ const child = await register('worker-1', {
38
+ registryUrl: 'https://provenonce.io',
39
+ parentHash: creds.hash,
40
+ parentApiKey: creds.api_key,
41
+ });
42
+ ```
43
+
44
+ ## Quick Start
45
+
46
+ ```typescript
47
+ import { BeatAgent } from '@provenonce/sdk';
48
+
49
+ const agent = new BeatAgent({
50
+ apiKey: 'pvn_...',
51
+ registryUrl: 'https://provenonce.io',
52
+ verbose: true,
53
+ });
54
+
55
+ await agent.init(); // Birth in Beat time
56
+
57
57
  // Purchase a SIGIL (cryptographic identity)
58
58
  const sigil = await agent.purchaseSigil({
59
- identityClass: 'autonomous',
60
- paymentTx: 'solana-tx-signature...',
59
+ identity_class: 'autonomous',
60
+ principal: 'my-agent',
61
+ tier: 'ind',
62
+ payment_tx: 'solana-tx-signature...',
61
63
  });
62
-
63
- // Start heartbeating (paid liveness proofs)
64
- agent.startHeartbeat();
65
-
66
- // Get your Passport (latest lineage proof)
67
- const passport = await agent.getPassport();
68
- console.log(passport?.identity_class); // 'autonomous'
69
- console.log(passport?.provenonce_signature); // Ed25519 signed
70
-
71
- // Verify any proof offline — no API call needed
72
- const valid = BeatAgent.verifyProofLocally(passport, authorityPubKeyHex);
73
-
74
- agent.stopHeartbeat();
75
- ```
76
-
77
- ## API
78
-
64
+
65
+ // Start heartbeating (paid liveness proofs)
66
+ agent.startHeartbeat();
67
+
68
+ // Get your Passport (latest lineage proof)
69
+ const passport = await agent.getPassport();
70
+ console.log(passport?.identity_class); // 'autonomous'
71
+ console.log(passport?.provenonce_signature); // Ed25519 signed
72
+
73
+ // Verify any proof offline — no API call needed
74
+ const valid = BeatAgent.verifyProofLocally(passport, authorityPubKeyHex);
75
+
76
+ agent.stopHeartbeat();
77
+ ```
78
+
79
+ ## API
80
+
79
81
  ### `BeatAgent`
80
82
 
81
83
  | Method | Description |
82
84
  |--------|-------------|
83
85
  | `init()` | Initialize the agent's Beat chain (birth in Logical Time) |
84
86
  | `purchaseSigil(opts)` | Purchase a SIGIL identity (required for heartbeating) |
85
- | `heartbeat(opts?)` | Submit a paid heartbeat and receive a signed lineage proof |
87
+ | `updateMetadata(fields)` | Update mutable SIGIL metadata fields |
88
+ | `heartbeat(paymentTx?, globalAnchor?)` | Submit a paid heartbeat and receive a signed lineage proof |
86
89
  | `startHeartbeat()` | Start autonomous heartbeat loop |
87
90
  | `stopHeartbeat()` | Stop heartbeat |
88
91
  | `getPassport()` | Get latest lineage proof (Passport) |
89
92
  | `reissueProof(paymentTx?)` | Reissue proof without extending lineage |
90
- | `requestSpawn(name?)` | Spawn a child agent (requires accumulated beats) |
91
- | `getStatus()` | Get full beat status from registry |
92
- | `getLocalState()` | Get local state (no network call) |
93
- | `static verifyProofLocally(proof, pubKey)` | Verify a lineage proof offline |
94
-
95
- ### `BeatAgentConfig`
96
-
97
- | Option | Default | Description |
98
- |--------|---------|-------------|
99
- | `apiKey` | *required* | API key from registration (`pvn_...`) |
100
- | `registryUrl` | *required* | Provenonce registry URL |
101
- | `heartbeatIntervalSec` | `300` | Seconds between automatic heartbeats |
102
- | `onHeartbeat` | — | Callback when heartbeat completes |
103
- | `onError` | — | Callback on error |
104
- | `onStatusChange` | — | Callback when status changes |
105
- | `verbose` | `false` | Enable console logging |
106
-
107
- ### `register(name, options)`
108
-
109
- | Option | Description |
110
- |--------|-------------|
111
- | `registryUrl` | Registry URL (required) |
112
- | `registrationSecret` | Registration gate (mainnet) |
113
- | `walletModel` | `'self-custody'` or `'operator'` (opt-in wallet) |
114
- | `walletChain` | `'solana'` or `'ethereum'` |
115
- | `walletAddress` | Ethereum BYO address |
116
- | `walletSignFn` | Signing function for BYO wallets |
117
- | `parentHash` | Parent hash (child registration) |
118
- | `parentApiKey` | Parent's API key (child registration) |
119
-
120
- Returns `RegistrationResult` with `hash`, `api_key`, `secret`, `wallet?`.
121
-
122
- **Note:** Agent names should only contain `[a-zA-Z0-9_\-. ]`. Other characters are stripped by the server before signature verification.
123
-
93
+ | `requestSpawn(name?)` | Spawn a child agent (requires accumulated beats) |
94
+ | `getStatus()` | Get full beat status from registry |
95
+ | `getLocalState()` | Get local state (no network call) |
96
+ | `static verifyProofLocally(proof, pubKey)` | Verify a lineage proof offline |
97
+
98
+ ### `BeatAgentConfig`
99
+
100
+ | Option | Default | Description |
101
+ |--------|---------|-------------|
102
+ | `apiKey` | *required* | API key from registration (`pvn_...`) |
103
+ | `registryUrl` | *required* | Provenonce registry URL |
104
+ | `heartbeatIntervalSec` | `300` | Seconds between automatic heartbeats |
105
+ | `onHeartbeat` | — | Callback when heartbeat completes |
106
+ | `onError` | — | Callback on error |
107
+ | `onStatusChange` | — | Callback when status changes |
108
+ | `verbose` | `false` | Enable console logging |
109
+
110
+ ### `register(name, options)`
111
+
112
+ | Option | Description |
113
+ |--------|-------------|
114
+ | `registryUrl` | Registry URL (required) |
115
+ | `registrationSecret` | Registration gate (mainnet) |
116
+ | `walletModel` | `'self-custody'` or `'operator'` (opt-in wallet) |
117
+ | `walletChain` | `'solana'` or `'ethereum'` |
118
+ | `walletAddress` | Ethereum BYO address |
119
+ | `walletSignFn` | Signing function for BYO wallets |
120
+ | `parentHash` | Parent hash (child registration) |
121
+ | `parentApiKey` | Parent's API key (child registration) |
122
+
123
+ Returns `RegistrationResult` with `hash`, `api_key`, `secret`, `wallet?`.
124
+
125
+ **Note:** Agent names should only contain `[a-zA-Z0-9_\-. ]`. Other characters are stripped by the server before signature verification.
126
+
124
127
  ### Phase 2 Types
125
-
126
- ```typescript
127
- import type { Passport, LineageProof, IdentityClass, SigilResult, HeartbeatResult } from '@provenonce/sdk';
128
-
129
- // Passport = LineageProof (type alias)
130
- // Contains: agent_hash, agent_public_key, identity_class, lineage_chain_hash,
131
- // provenonce_signature, issued_at, valid_until, etc.
132
-
128
+
129
+ ```typescript
130
+ import type { Passport, LineageProof, IdentityClass, SigilResult, HeartbeatResult } from '@provenonce/sdk';
131
+
132
+ // Passport = LineageProof (type alias)
133
+ // Contains: agent_hash, agent_public_key, identity_class, lineage_chain_hash,
134
+ // provenonce_signature, issued_at, valid_until, etc.
135
+
133
136
  // IdentityClass = 'narrow_task' | 'autonomous' | 'orchestrator'
134
137
  ```
135
138
 
136
- ### Error Handling
139
+ ### `purchaseSigil(opts)` required fields
137
140
 
138
141
  ```typescript
139
- import { ProvenonceError, AuthError, RateLimitError, FrozenError, ErrorCode } from '@provenonce/sdk';
140
-
141
- try {
142
- await agent.heartbeat();
143
- } catch (err) {
144
- if (err instanceof RateLimitError) {
145
- console.log(`Retry after ${err.retryAfterMs}ms`);
146
- } else if (err instanceof FrozenError) {
147
- console.log('Agent is frozen — heartbeat refused');
148
- } else if (err instanceof AuthError) {
149
- console.log('Invalid API key');
150
- }
151
- }
142
+ await agent.purchaseSigil({
143
+ identity_class: 'narrow_task' | 'autonomous' | 'orchestrator',
144
+ principal: 'my-agent',
145
+ tier: 'sov' | 'org' | 'ind' | 'eph' | 'sbx',
146
+ payment_tx: 'solana-tx-signature...', // or 'devnet-skip' on devnet
147
+ name: 'optional-display-name'
148
+ });
152
149
  ```
153
-
154
- ## Framework Integration Examples
155
-
156
- Ready-to-run examples for popular agent frameworks are in [`examples/`](./examples/):
157
-
158
- | Framework | File | What it shows |
159
- |-----------|------|---------------|
160
- | **CrewAI** | [`crewai_example.py`](./examples/crewai_example.py) | Register a research crew with parent-child lineage |
161
- | **AutoGen** | [`autogen_example.py`](./examples/autogen_example.py) | Coder + reviewer agents with post-run provenance audit |
162
- | **LangGraph** | [`langgraph_example.py`](./examples/langgraph_example.py) | Pipeline nodes with on-chain audit trail |
163
- | **Any (Node.js)** | [`add-provenonce.ts`](./examples/add-provenonce.ts) | 20-line generic integration |
164
-
165
- Python examples use the REST API directly — no Python SDK needed. See [`examples/README.md`](./examples/README.md) for details.
166
-
167
- ## Links
168
-
150
+
151
+ ### Error Handling
152
+
153
+ ```typescript
154
+ import { ProvenonceError, AuthError, RateLimitError, FrozenError, ErrorCode } from '@provenonce/sdk';
155
+
156
+ try {
157
+ await agent.heartbeat();
158
+ } catch (err) {
159
+ if (err instanceof RateLimitError) {
160
+ console.log(`Retry after ${err.retryAfterMs}ms`);
161
+ } else if (err instanceof FrozenError) {
162
+ console.log('Agent is frozen — heartbeat refused');
163
+ } else if (err instanceof AuthError) {
164
+ console.log('Invalid API key');
165
+ }
166
+ }
167
+ ```
168
+
169
+ ## Framework Integration Examples
170
+
171
+ Ready-to-run examples for popular agent frameworks are in [`examples/`](./examples/):
172
+
173
+ | Framework | File | What it shows |
174
+ |-----------|------|---------------|
175
+ | **CrewAI** | [`crewai_example.py`](./examples/crewai_example.py) | Register a research crew with parent-child lineage |
176
+ | **AutoGen** | [`autogen_example.py`](./examples/autogen_example.py) | Coder + reviewer agents with post-run provenance audit |
177
+ | **LangGraph** | [`langgraph_example.py`](./examples/langgraph_example.py) | Pipeline nodes with on-chain audit trail |
178
+ | **Any (Node.js)** | [`add-provenonce.ts`](./examples/add-provenonce.ts) | 20-line generic integration |
179
+
180
+ Python examples use the REST API directly — no Python SDK needed. See [`examples/README.md`](./examples/README.md) for details.
181
+
182
+ ## Links
183
+
169
184
  - [Live prototype](https://provenonce.io)
170
185
  - [npm package](https://www.npmjs.com/package/@provenonce/sdk)
171
186
  - [API docs](https://provenonce.dev)
172
- - [Whitepaper](https://provenonce.dev/concepts/architecture)
187
+ - [Whitepaper](https://provenonce.dev/whitepaper)