@provenonce/sdk 0.9.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.
- package/README.md +163 -148
- package/dist/index.d.mts +92 -5
- package/dist/index.d.ts +92 -5
- package/dist/index.js +88 -25
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +88 -25
- package/dist/index.mjs.map +1 -1
- package/package.json +43 -43
package/README.md
CHANGED
|
@@ -1,171 +1,186 @@
|
|
|
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
|
-
|
|
60
|
-
|
|
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
|
-
| `
|
|
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
|
-
###
|
|
139
|
+
### `purchaseSigil(opts)` required fields
|
|
137
140
|
|
|
138
141
|
```typescript
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
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
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
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)
|
package/dist/index.d.mts
CHANGED
|
@@ -28,6 +28,18 @@
|
|
|
28
28
|
*/
|
|
29
29
|
/** SIGIL identity class — determines tier pricing and heartbeat volume caps */
|
|
30
30
|
type IdentityClass = 'narrow_task' | 'autonomous' | 'orchestrator';
|
|
31
|
+
/** SIGIL trust governance tier — orthogonal to identity_class (fee axis) */
|
|
32
|
+
type SigilTier = 'sov' | 'org' | 'ind' | 'eph' | 'sbx';
|
|
33
|
+
/** Substrate — what the agent runs on */
|
|
34
|
+
type Substrate = 'frontier' | 'open' | 'local' | 'symbolic' | 'hybrid' | 'human';
|
|
35
|
+
/** Substrate provider */
|
|
36
|
+
type SubstrateProvider = 'anthropic' | 'openai' | 'google' | 'meta' | 'mistral' | 'xai' | 'cohere' | 'deepseek' | 'custom';
|
|
37
|
+
/** Capability — what the agent primarily does */
|
|
38
|
+
type Capability = 'analyst' | 'executor' | 'orchestrator' | 'guardian' | 'retriever' | 'renderer' | 'witness';
|
|
39
|
+
/** Protocol — how to reach the agent */
|
|
40
|
+
type SigilProtocol = 'http' | 'grpc' | 'websocket' | 'mcp' | 'a2a' | 'custom';
|
|
41
|
+
/** Compliance regime */
|
|
42
|
+
type ComplianceRegime = 'gdpr' | 'pdpa' | 'hipaa' | 'sox' | 'aisi' | 'none' | 'custom';
|
|
31
43
|
/**
|
|
32
44
|
* Ed25519-signed lineage proof — portable, offline-verifiable credential.
|
|
33
45
|
* Also known as the agent's "passport" — a cryptographic proof of identity
|
|
@@ -47,10 +59,48 @@ interface LineageProof {
|
|
|
47
59
|
}
|
|
48
60
|
/** Passport = LineageProof. The agent's portable, offline-verifiable credential. */
|
|
49
61
|
type Passport = LineageProof;
|
|
62
|
+
/** Options for purchasing a SIGIL with full namespace */
|
|
63
|
+
interface SigilPurchaseOptions {
|
|
64
|
+
identity_class: IdentityClass;
|
|
65
|
+
principal: string;
|
|
66
|
+
tier: SigilTier;
|
|
67
|
+
name?: string;
|
|
68
|
+
payment_tx: string;
|
|
69
|
+
substrate?: Substrate;
|
|
70
|
+
substrate_provider?: SubstrateProvider;
|
|
71
|
+
substrate_model?: string;
|
|
72
|
+
capability?: Capability;
|
|
73
|
+
capability_scope?: string;
|
|
74
|
+
tools?: string[];
|
|
75
|
+
modality_input?: string[];
|
|
76
|
+
modality_output?: string[];
|
|
77
|
+
protocol?: SigilProtocol;
|
|
78
|
+
endpoint?: string;
|
|
79
|
+
compliance_regime?: ComplianceRegime;
|
|
80
|
+
}
|
|
81
|
+
/** Mutable SIGIL metadata fields for PATCH updates */
|
|
82
|
+
interface SigilMutableFields {
|
|
83
|
+
substrate?: Substrate;
|
|
84
|
+
substrate_provider?: SubstrateProvider;
|
|
85
|
+
substrate_model?: string;
|
|
86
|
+
capability?: Capability;
|
|
87
|
+
capability_scope?: string;
|
|
88
|
+
generation_trigger?: string;
|
|
89
|
+
tools?: string[];
|
|
90
|
+
modality_input?: string[];
|
|
91
|
+
modality_output?: string[];
|
|
92
|
+
protocol?: SigilProtocol;
|
|
93
|
+
endpoint?: string;
|
|
94
|
+
compliance_regime?: ComplianceRegime;
|
|
95
|
+
}
|
|
50
96
|
/** Result from purchasing a SIGIL (Structured Identity Governance and Intelligent Lookup) */
|
|
51
97
|
interface SigilResult {
|
|
52
98
|
ok: boolean;
|
|
53
99
|
sigil?: {
|
|
100
|
+
sigil: string;
|
|
101
|
+
sigil_name: string;
|
|
102
|
+
principal: string;
|
|
103
|
+
tier: SigilTier;
|
|
54
104
|
identity_class: IdentityClass;
|
|
55
105
|
issued_at_beat: number;
|
|
56
106
|
birth_tx: string | null;
|
|
@@ -64,6 +114,29 @@ interface SigilResult {
|
|
|
64
114
|
};
|
|
65
115
|
error?: string;
|
|
66
116
|
}
|
|
117
|
+
/** Result from updating mutable SIGIL metadata */
|
|
118
|
+
interface MetadataUpdateResult {
|
|
119
|
+
ok: boolean;
|
|
120
|
+
sigil?: string;
|
|
121
|
+
generation?: number;
|
|
122
|
+
updated_fields?: string[];
|
|
123
|
+
error?: string;
|
|
124
|
+
}
|
|
125
|
+
/** Result from offline lineage proof verification */
|
|
126
|
+
interface VerificationResult {
|
|
127
|
+
/** Overall validity: signature is valid AND not expired */
|
|
128
|
+
valid: boolean;
|
|
129
|
+
/** Ed25519 signature verification passed */
|
|
130
|
+
signatureValid: boolean;
|
|
131
|
+
/** Proof has passed its valid_until timestamp */
|
|
132
|
+
expired: boolean;
|
|
133
|
+
/** The beat index of the agent's last heartbeat */
|
|
134
|
+
lastHeartbeatBeat: number;
|
|
135
|
+
/** Beats elapsed since last heartbeat (null if currentBeat not provided) */
|
|
136
|
+
beatsSinceHeartbeat: number | null;
|
|
137
|
+
/** Human-readable warning if proof is expired or stale */
|
|
138
|
+
warning?: string;
|
|
139
|
+
}
|
|
67
140
|
/** Result from a paid heartbeat */
|
|
68
141
|
interface HeartbeatResult {
|
|
69
142
|
ok: boolean;
|
|
@@ -332,10 +405,20 @@ declare class BeatAgent {
|
|
|
332
405
|
* SIGILs gate heartbeating, lineage proofs, and offline verification.
|
|
333
406
|
* One-time purchase — cannot be re-purchased.
|
|
334
407
|
*
|
|
335
|
-
* @param
|
|
336
|
-
*
|
|
408
|
+
* @param options - SIGIL purchase options (identity_class, principal, tier, name, payment_tx, + optional metadata)
|
|
409
|
+
*
|
|
410
|
+
* Legacy signature (deprecated):
|
|
411
|
+
* @param identityClass - 'narrow_task' | 'autonomous' | 'orchestrator'
|
|
412
|
+
* @param paymentTx - Solana transaction signature or 'devnet-skip'
|
|
413
|
+
*/
|
|
414
|
+
purchaseSigil(optionsOrClass: SigilPurchaseOptions | IdentityClass, paymentTx?: string): Promise<SigilResult>;
|
|
415
|
+
/**
|
|
416
|
+
* Update mutable SIGIL metadata fields.
|
|
417
|
+
* Requires a SIGIL. Cannot modify immutable fields.
|
|
418
|
+
*
|
|
419
|
+
* @param fields - Subset of mutable SIGIL fields to update
|
|
337
420
|
*/
|
|
338
|
-
|
|
421
|
+
updateMetadata(fields: Partial<SigilMutableFields>): Promise<MetadataUpdateResult>;
|
|
339
422
|
/**
|
|
340
423
|
* Send a paid heartbeat to the registry.
|
|
341
424
|
* Requires a SIGIL. Returns a signed lineage proof.
|
|
@@ -371,10 +454,14 @@ declare class BeatAgent {
|
|
|
371
454
|
* Verify a lineage proof locally using the authority public key.
|
|
372
455
|
* Offline verification — no API call, no SOL cost.
|
|
373
456
|
*
|
|
457
|
+
* Returns a VerificationResult object. The object is truthy when valid,
|
|
458
|
+
* so `if (BeatAgent.verifyProofLocally(proof, key))` still works.
|
|
459
|
+
*
|
|
374
460
|
* @param proof - The LineageProof to verify
|
|
375
461
|
* @param authorityPubKeyHex - 32-byte hex-encoded Ed25519 public key from /.well-known/provenonce-authority.json
|
|
462
|
+
* @param currentBeat - Optional current global beat index (for beatsSinceHeartbeat calculation)
|
|
376
463
|
*/
|
|
377
|
-
static verifyProofLocally(proof: LineageProof, authorityPubKeyHex: string):
|
|
464
|
+
static verifyProofLocally(proof: LineageProof, authorityPubKeyHex: string, currentBeat?: number): VerificationResult;
|
|
378
465
|
/**
|
|
379
466
|
* Get this agent's full beat status from the registry.
|
|
380
467
|
*/
|
|
@@ -486,4 +573,4 @@ declare class ServerError extends ProvenonceError {
|
|
|
486
573
|
constructor(message: string, statusCode?: number);
|
|
487
574
|
}
|
|
488
575
|
|
|
489
|
-
export { type AgentStatus, AuthError, type Beat, BeatAgent, type BeatAgentConfig, type CheckinResult, ErrorCode, FrozenError, type HeartbeatResult, type IdentityClass, type LineageProof, NetworkError, NotFoundError, type Passport, ProvenonceError, RateLimitError, type RegistrationResult, ServerError, type SigilResult, type SpawnResult, StateError, ValidationError, type WalletInfo, computeBeat, computeBeatsLite, generateWalletKeypair, register };
|
|
576
|
+
export { type AgentStatus, AuthError, type Beat, BeatAgent, type BeatAgentConfig, type Capability, type CheckinResult, type ComplianceRegime, ErrorCode, FrozenError, type HeartbeatResult, type IdentityClass, type LineageProof, type MetadataUpdateResult, NetworkError, NotFoundError, type Passport, ProvenonceError, RateLimitError, type RegistrationResult, ServerError, type SigilMutableFields, type SigilProtocol, type SigilPurchaseOptions, type SigilResult, type SigilTier, type SpawnResult, StateError, type Substrate, type SubstrateProvider, ValidationError, type VerificationResult, type WalletInfo, computeBeat, computeBeatsLite, generateWalletKeypair, register };
|
package/dist/index.d.ts
CHANGED
|
@@ -28,6 +28,18 @@
|
|
|
28
28
|
*/
|
|
29
29
|
/** SIGIL identity class — determines tier pricing and heartbeat volume caps */
|
|
30
30
|
type IdentityClass = 'narrow_task' | 'autonomous' | 'orchestrator';
|
|
31
|
+
/** SIGIL trust governance tier — orthogonal to identity_class (fee axis) */
|
|
32
|
+
type SigilTier = 'sov' | 'org' | 'ind' | 'eph' | 'sbx';
|
|
33
|
+
/** Substrate — what the agent runs on */
|
|
34
|
+
type Substrate = 'frontier' | 'open' | 'local' | 'symbolic' | 'hybrid' | 'human';
|
|
35
|
+
/** Substrate provider */
|
|
36
|
+
type SubstrateProvider = 'anthropic' | 'openai' | 'google' | 'meta' | 'mistral' | 'xai' | 'cohere' | 'deepseek' | 'custom';
|
|
37
|
+
/** Capability — what the agent primarily does */
|
|
38
|
+
type Capability = 'analyst' | 'executor' | 'orchestrator' | 'guardian' | 'retriever' | 'renderer' | 'witness';
|
|
39
|
+
/** Protocol — how to reach the agent */
|
|
40
|
+
type SigilProtocol = 'http' | 'grpc' | 'websocket' | 'mcp' | 'a2a' | 'custom';
|
|
41
|
+
/** Compliance regime */
|
|
42
|
+
type ComplianceRegime = 'gdpr' | 'pdpa' | 'hipaa' | 'sox' | 'aisi' | 'none' | 'custom';
|
|
31
43
|
/**
|
|
32
44
|
* Ed25519-signed lineage proof — portable, offline-verifiable credential.
|
|
33
45
|
* Also known as the agent's "passport" — a cryptographic proof of identity
|
|
@@ -47,10 +59,48 @@ interface LineageProof {
|
|
|
47
59
|
}
|
|
48
60
|
/** Passport = LineageProof. The agent's portable, offline-verifiable credential. */
|
|
49
61
|
type Passport = LineageProof;
|
|
62
|
+
/** Options for purchasing a SIGIL with full namespace */
|
|
63
|
+
interface SigilPurchaseOptions {
|
|
64
|
+
identity_class: IdentityClass;
|
|
65
|
+
principal: string;
|
|
66
|
+
tier: SigilTier;
|
|
67
|
+
name?: string;
|
|
68
|
+
payment_tx: string;
|
|
69
|
+
substrate?: Substrate;
|
|
70
|
+
substrate_provider?: SubstrateProvider;
|
|
71
|
+
substrate_model?: string;
|
|
72
|
+
capability?: Capability;
|
|
73
|
+
capability_scope?: string;
|
|
74
|
+
tools?: string[];
|
|
75
|
+
modality_input?: string[];
|
|
76
|
+
modality_output?: string[];
|
|
77
|
+
protocol?: SigilProtocol;
|
|
78
|
+
endpoint?: string;
|
|
79
|
+
compliance_regime?: ComplianceRegime;
|
|
80
|
+
}
|
|
81
|
+
/** Mutable SIGIL metadata fields for PATCH updates */
|
|
82
|
+
interface SigilMutableFields {
|
|
83
|
+
substrate?: Substrate;
|
|
84
|
+
substrate_provider?: SubstrateProvider;
|
|
85
|
+
substrate_model?: string;
|
|
86
|
+
capability?: Capability;
|
|
87
|
+
capability_scope?: string;
|
|
88
|
+
generation_trigger?: string;
|
|
89
|
+
tools?: string[];
|
|
90
|
+
modality_input?: string[];
|
|
91
|
+
modality_output?: string[];
|
|
92
|
+
protocol?: SigilProtocol;
|
|
93
|
+
endpoint?: string;
|
|
94
|
+
compliance_regime?: ComplianceRegime;
|
|
95
|
+
}
|
|
50
96
|
/** Result from purchasing a SIGIL (Structured Identity Governance and Intelligent Lookup) */
|
|
51
97
|
interface SigilResult {
|
|
52
98
|
ok: boolean;
|
|
53
99
|
sigil?: {
|
|
100
|
+
sigil: string;
|
|
101
|
+
sigil_name: string;
|
|
102
|
+
principal: string;
|
|
103
|
+
tier: SigilTier;
|
|
54
104
|
identity_class: IdentityClass;
|
|
55
105
|
issued_at_beat: number;
|
|
56
106
|
birth_tx: string | null;
|
|
@@ -64,6 +114,29 @@ interface SigilResult {
|
|
|
64
114
|
};
|
|
65
115
|
error?: string;
|
|
66
116
|
}
|
|
117
|
+
/** Result from updating mutable SIGIL metadata */
|
|
118
|
+
interface MetadataUpdateResult {
|
|
119
|
+
ok: boolean;
|
|
120
|
+
sigil?: string;
|
|
121
|
+
generation?: number;
|
|
122
|
+
updated_fields?: string[];
|
|
123
|
+
error?: string;
|
|
124
|
+
}
|
|
125
|
+
/** Result from offline lineage proof verification */
|
|
126
|
+
interface VerificationResult {
|
|
127
|
+
/** Overall validity: signature is valid AND not expired */
|
|
128
|
+
valid: boolean;
|
|
129
|
+
/** Ed25519 signature verification passed */
|
|
130
|
+
signatureValid: boolean;
|
|
131
|
+
/** Proof has passed its valid_until timestamp */
|
|
132
|
+
expired: boolean;
|
|
133
|
+
/** The beat index of the agent's last heartbeat */
|
|
134
|
+
lastHeartbeatBeat: number;
|
|
135
|
+
/** Beats elapsed since last heartbeat (null if currentBeat not provided) */
|
|
136
|
+
beatsSinceHeartbeat: number | null;
|
|
137
|
+
/** Human-readable warning if proof is expired or stale */
|
|
138
|
+
warning?: string;
|
|
139
|
+
}
|
|
67
140
|
/** Result from a paid heartbeat */
|
|
68
141
|
interface HeartbeatResult {
|
|
69
142
|
ok: boolean;
|
|
@@ -332,10 +405,20 @@ declare class BeatAgent {
|
|
|
332
405
|
* SIGILs gate heartbeating, lineage proofs, and offline verification.
|
|
333
406
|
* One-time purchase — cannot be re-purchased.
|
|
334
407
|
*
|
|
335
|
-
* @param
|
|
336
|
-
*
|
|
408
|
+
* @param options - SIGIL purchase options (identity_class, principal, tier, name, payment_tx, + optional metadata)
|
|
409
|
+
*
|
|
410
|
+
* Legacy signature (deprecated):
|
|
411
|
+
* @param identityClass - 'narrow_task' | 'autonomous' | 'orchestrator'
|
|
412
|
+
* @param paymentTx - Solana transaction signature or 'devnet-skip'
|
|
413
|
+
*/
|
|
414
|
+
purchaseSigil(optionsOrClass: SigilPurchaseOptions | IdentityClass, paymentTx?: string): Promise<SigilResult>;
|
|
415
|
+
/**
|
|
416
|
+
* Update mutable SIGIL metadata fields.
|
|
417
|
+
* Requires a SIGIL. Cannot modify immutable fields.
|
|
418
|
+
*
|
|
419
|
+
* @param fields - Subset of mutable SIGIL fields to update
|
|
337
420
|
*/
|
|
338
|
-
|
|
421
|
+
updateMetadata(fields: Partial<SigilMutableFields>): Promise<MetadataUpdateResult>;
|
|
339
422
|
/**
|
|
340
423
|
* Send a paid heartbeat to the registry.
|
|
341
424
|
* Requires a SIGIL. Returns a signed lineage proof.
|
|
@@ -371,10 +454,14 @@ declare class BeatAgent {
|
|
|
371
454
|
* Verify a lineage proof locally using the authority public key.
|
|
372
455
|
* Offline verification — no API call, no SOL cost.
|
|
373
456
|
*
|
|
457
|
+
* Returns a VerificationResult object. The object is truthy when valid,
|
|
458
|
+
* so `if (BeatAgent.verifyProofLocally(proof, key))` still works.
|
|
459
|
+
*
|
|
374
460
|
* @param proof - The LineageProof to verify
|
|
375
461
|
* @param authorityPubKeyHex - 32-byte hex-encoded Ed25519 public key from /.well-known/provenonce-authority.json
|
|
462
|
+
* @param currentBeat - Optional current global beat index (for beatsSinceHeartbeat calculation)
|
|
376
463
|
*/
|
|
377
|
-
static verifyProofLocally(proof: LineageProof, authorityPubKeyHex: string):
|
|
464
|
+
static verifyProofLocally(proof: LineageProof, authorityPubKeyHex: string, currentBeat?: number): VerificationResult;
|
|
378
465
|
/**
|
|
379
466
|
* Get this agent's full beat status from the registry.
|
|
380
467
|
*/
|
|
@@ -486,4 +573,4 @@ declare class ServerError extends ProvenonceError {
|
|
|
486
573
|
constructor(message: string, statusCode?: number);
|
|
487
574
|
}
|
|
488
575
|
|
|
489
|
-
export { type AgentStatus, AuthError, type Beat, BeatAgent, type BeatAgentConfig, type CheckinResult, ErrorCode, FrozenError, type HeartbeatResult, type IdentityClass, type LineageProof, NetworkError, NotFoundError, type Passport, ProvenonceError, RateLimitError, type RegistrationResult, ServerError, type SigilResult, type SpawnResult, StateError, ValidationError, type WalletInfo, computeBeat, computeBeatsLite, generateWalletKeypair, register };
|
|
576
|
+
export { type AgentStatus, AuthError, type Beat, BeatAgent, type BeatAgentConfig, type Capability, type CheckinResult, type ComplianceRegime, ErrorCode, FrozenError, type HeartbeatResult, type IdentityClass, type LineageProof, type MetadataUpdateResult, NetworkError, NotFoundError, type Passport, ProvenonceError, RateLimitError, type RegistrationResult, ServerError, type SigilMutableFields, type SigilProtocol, type SigilPurchaseOptions, type SigilResult, type SigilTier, type SpawnResult, StateError, type Substrate, type SubstrateProvider, ValidationError, type VerificationResult, type WalletInfo, computeBeat, computeBeatsLite, generateWalletKeypair, register };
|