@provenonce/sdk 0.4.0 → 0.4.2
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 +90 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# @provenonce/sdk
|
|
2
|
+
|
|
3
|
+
Agent heartbeat client for sovereign time authentication on Solana.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @provenonce/sdk
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Quick Start
|
|
12
|
+
|
|
13
|
+
```typescript
|
|
14
|
+
import { BeatAgent } from '@provenonce/sdk';
|
|
15
|
+
|
|
16
|
+
const agent = new BeatAgent({
|
|
17
|
+
apiKey: 'pvn_...',
|
|
18
|
+
registryUrl: 'https://provenonce.vercel.app',
|
|
19
|
+
verbose: true,
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
await agent.init(); // Birth in Beat time
|
|
23
|
+
agent.startHeartbeat(); // Compute + check in continuously
|
|
24
|
+
|
|
25
|
+
// ... your agent does work ...
|
|
26
|
+
|
|
27
|
+
agent.stopHeartbeat();
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## API
|
|
31
|
+
|
|
32
|
+
### `BeatAgent`
|
|
33
|
+
|
|
34
|
+
| Method | Description |
|
|
35
|
+
|--------|-------------|
|
|
36
|
+
| `init()` | Initialize the agent's Beat chain (birth in Logical Time) |
|
|
37
|
+
| `pulse(count?)` | Compute N beats locally (VDF hash chain) |
|
|
38
|
+
| `checkin()` | Submit beat proof to the registry |
|
|
39
|
+
| `startHeartbeat()` | Start autonomous pulse + check-in loop |
|
|
40
|
+
| `stopHeartbeat()` | Stop heartbeat (time freezes) |
|
|
41
|
+
| `resync()` | Re-sync after being offline/frozen |
|
|
42
|
+
| `requestSpawn(name?)` | Spawn a child agent (requires accumulated beats) |
|
|
43
|
+
| `getStatus()` | Get full beat status from registry |
|
|
44
|
+
| `getLocalState()` | Get local state (no network call) |
|
|
45
|
+
|
|
46
|
+
### `BeatAgentConfig`
|
|
47
|
+
|
|
48
|
+
| Option | Default | Description |
|
|
49
|
+
|--------|---------|-------------|
|
|
50
|
+
| `apiKey` | *required* | API key from registration (`pvn_...`) |
|
|
51
|
+
| `registryUrl` | *required* | Provenonce registry URL |
|
|
52
|
+
| `beatsPerPulse` | `10` | Beats to compute per pulse |
|
|
53
|
+
| `checkinIntervalSec` | `300` | Seconds between automatic check-ins |
|
|
54
|
+
| `onPulse` | — | Callback when heartbeat ticks |
|
|
55
|
+
| `onCheckin` | — | Callback when check-in completes |
|
|
56
|
+
| `onError` | — | Callback on error |
|
|
57
|
+
| `onStatusChange` | — | Callback when status changes |
|
|
58
|
+
| `verbose` | `false` | Enable console logging |
|
|
59
|
+
|
|
60
|
+
### Standalone helpers
|
|
61
|
+
|
|
62
|
+
```typescript
|
|
63
|
+
import { computeBeat, computeBeatsLite } from '@provenonce/sdk';
|
|
64
|
+
|
|
65
|
+
// Single beat
|
|
66
|
+
const beat = computeBeat(prevHash, beatIndex, difficulty);
|
|
67
|
+
|
|
68
|
+
// N sequential beats (returns only the last)
|
|
69
|
+
const { lastBeat, elapsed } = computeBeatsLite(startHash, startIndex, count, difficulty);
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## Framework Integration Examples
|
|
73
|
+
|
|
74
|
+
Ready-to-run examples for popular agent frameworks are in [`examples/`](./examples/):
|
|
75
|
+
|
|
76
|
+
| Framework | File | What it shows |
|
|
77
|
+
|-----------|------|---------------|
|
|
78
|
+
| **CrewAI** | [`crewai_example.py`](./examples/crewai_example.py) | Register a research crew with parent-child lineage |
|
|
79
|
+
| **AutoGen** | [`autogen_example.py`](./examples/autogen_example.py) | Coder + reviewer agents with post-run provenance audit |
|
|
80
|
+
| **LangGraph** | [`langgraph_example.py`](./examples/langgraph_example.py) | Pipeline nodes with on-chain audit trail |
|
|
81
|
+
| **Any (Node.js)** | [`add-provenonce.ts`](./examples/add-provenonce.ts) | 20-line generic integration |
|
|
82
|
+
|
|
83
|
+
Python examples use the REST API directly — no Python SDK needed. See [`examples/README.md`](./examples/README.md) for details.
|
|
84
|
+
|
|
85
|
+
## Links
|
|
86
|
+
|
|
87
|
+
- [Live prototype](https://provenonce.vercel.app)
|
|
88
|
+
- [npm package](https://www.npmjs.com/package/@provenonce/sdk)
|
|
89
|
+
- [API docs](https://provenonce.vercel.app/docs)
|
|
90
|
+
- [GitHub](https://github.com/jarekpiot/provenonce)
|