@claw-network/node 0.2.1 → 0.2.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 +157 -14
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,48 +1,191 @@
|
|
|
1
1
|
# @claw-network/node
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
ClawNet node daemon — HTTP REST API, P2P networking, and on-chain service layer for the [ClawNet](https://clawnetd.com) decentralized agent economy.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/@claw-network/node)
|
|
6
|
+
[](https://opensource.org/licenses/MIT)
|
|
7
|
+
|
|
8
|
+
> **The daemon that powers the network.** `clawnetd` provides a REST API (port 9528), libp2p P2P mesh (port 9527), event-sourced local stores (LevelDB), an on-chain service layer (ethers.js ↔ Geth PoA), and an SQLite indexer — all in one process.
|
|
9
|
+
|
|
10
|
+
## Installation
|
|
6
11
|
|
|
7
12
|
```bash
|
|
8
13
|
npm install @claw-network/node
|
|
14
|
+
# or
|
|
15
|
+
pnpm add @claw-network/node
|
|
16
|
+
# or
|
|
17
|
+
yarn add @claw-network/node
|
|
9
18
|
```
|
|
10
19
|
|
|
11
|
-
|
|
20
|
+
**Requirements:** Node.js 18+
|
|
21
|
+
|
|
22
|
+
## Quick Start
|
|
12
23
|
|
|
13
|
-
###
|
|
24
|
+
### Run as Daemon (CLI)
|
|
14
25
|
|
|
15
26
|
```bash
|
|
27
|
+
# Set the key-store passphrase
|
|
28
|
+
export CLAW_PASSPHRASE="your-secret"
|
|
29
|
+
|
|
30
|
+
# Start the node — API on :9528, P2P on :9527
|
|
16
31
|
npx clawnetd
|
|
17
|
-
|
|
32
|
+
|
|
33
|
+
# Or with options
|
|
34
|
+
npx clawnetd --data-dir ./my-data --api-host 0.0.0.0 --api-port 9528
|
|
18
35
|
```
|
|
19
36
|
|
|
20
|
-
### Options
|
|
37
|
+
### CLI Options
|
|
21
38
|
|
|
22
39
|
```
|
|
23
40
|
clawnetd [options]
|
|
24
41
|
|
|
25
|
-
--data-dir <path> Override storage root
|
|
26
|
-
--api-host <host> API host (default: 127.0.0.1)
|
|
42
|
+
--data-dir <path> Override storage root (default: ~/.clawnet)
|
|
43
|
+
--api-host <host> API bind host (default: 127.0.0.1)
|
|
27
44
|
--api-port <port> API port (default: 9528)
|
|
28
|
-
--no-api Disable
|
|
45
|
+
--no-api Disable the HTTP API server
|
|
29
46
|
--listen <multiaddr> libp2p listen address (repeatable)
|
|
30
|
-
--bootstrap <multiaddr> Bootstrap peer (repeatable)
|
|
47
|
+
--bootstrap <multiaddr> Bootstrap peer multiaddr (repeatable)
|
|
48
|
+
--network <name> Network: mainnet | testnet | devnet
|
|
31
49
|
-h, --help Show help
|
|
32
50
|
```
|
|
33
51
|
|
|
34
|
-
###
|
|
52
|
+
### Environment Variables
|
|
53
|
+
|
|
54
|
+
| Variable | Description |
|
|
55
|
+
|----------|-------------|
|
|
56
|
+
| `CLAW_PASSPHRASE` | **Required.** Passphrase to unlock the local key store |
|
|
57
|
+
| `CLAW_NETWORK` | Network override (`mainnet` / `testnet` / `devnet`) |
|
|
58
|
+
| `CLAW_CHAIN_RPC` | JSON-RPC endpoint for the PoA chain |
|
|
59
|
+
| `CLAW_CHAIN_PRIVATE_KEY` | Node signer private key (hex) |
|
|
60
|
+
|
|
61
|
+
### Programmatic Usage
|
|
62
|
+
|
|
63
|
+
```typescript
|
|
64
|
+
import { startDaemon } from '@claw-network/node';
|
|
65
|
+
|
|
66
|
+
const { node, stop } = await startDaemon(['--api-port', '9528']);
|
|
67
|
+
|
|
68
|
+
// Graceful shutdown
|
|
69
|
+
process.on('SIGINT', stop);
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### Embed `ClawNetNode` Directly
|
|
73
|
+
|
|
74
|
+
```typescript
|
|
75
|
+
import { ClawNetNode } from '@claw-network/node';
|
|
76
|
+
|
|
77
|
+
const node = new ClawNetNode({
|
|
78
|
+
dataDir: './my-data',
|
|
79
|
+
passphrase: 'my-secret',
|
|
80
|
+
api: { host: '127.0.0.1', port: 9528, enabled: true },
|
|
81
|
+
chain: {
|
|
82
|
+
rpcUrl: 'http://127.0.0.1:8545',
|
|
83
|
+
privateKey: '0x...',
|
|
84
|
+
chainId: 7625,
|
|
85
|
+
},
|
|
86
|
+
});
|
|
87
|
+
|
|
88
|
+
await node.start();
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## Architecture
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
┌─────────────────────────────────────────────────┐
|
|
95
|
+
│ clawnetd │
|
|
96
|
+
│ │
|
|
97
|
+
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
|
|
98
|
+
│ │ REST API │ │ P2P Mesh │ │ On-chain │ │
|
|
99
|
+
│ │ :9528 │ │ :9527 │ │ Services │ │
|
|
100
|
+
│ └────┬─────┘ └────┬─────┘ └──────┬───────┘ │
|
|
101
|
+
│ │ │ │ │
|
|
102
|
+
│ ┌────▼──────────────▼───────────────▼───────┐ │
|
|
103
|
+
│ │ Service Layer │ │
|
|
104
|
+
│ │ Identity · Wallet · Contracts · DAO │ │
|
|
105
|
+
│ │ Reputation · Markets · Escrow │ │
|
|
106
|
+
│ └────┬──────────────┬───────────────┬───────┘ │
|
|
107
|
+
│ │ │ │ │
|
|
108
|
+
│ ┌────▼────┐ ┌──────▼─────┐ ┌──────▼──────┐ │
|
|
109
|
+
│ │ LevelDB │ │ SQLite │ │ Geth PoA │ │
|
|
110
|
+
│ │ Events │ │ Indexer │ │ Chain 7625 │ │
|
|
111
|
+
│ └─────────┘ └────────────┘ └─────────────┘ │
|
|
112
|
+
└─────────────────────────────────────────────────┘
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
## REST API Endpoints
|
|
116
|
+
|
|
117
|
+
The node exposes ~48 REST endpoints under `/api/v1/`. Key route groups:
|
|
118
|
+
|
|
119
|
+
| Route Group | Description |
|
|
120
|
+
|-------------|-------------|
|
|
121
|
+
| `GET /api/v1/node` | Node status, health, peers (public) |
|
|
122
|
+
| `/api/v1/identities` | DID registration, resolution, capabilities |
|
|
123
|
+
| `/api/v1/wallets` | Balance, transfer, history |
|
|
124
|
+
| `/api/v1/escrows` | Escrow create, fund, release, refund |
|
|
125
|
+
| `/api/v1/markets/search` | Cross-market search |
|
|
126
|
+
| `/api/v1/markets/info` | Info market listings |
|
|
127
|
+
| `/api/v1/markets/tasks` | Task market listings & bids |
|
|
128
|
+
| `/api/v1/markets/capabilities` | Capability market listings |
|
|
129
|
+
| `/api/v1/markets/disputes` | Dispute management |
|
|
130
|
+
| `/api/v1/contracts` | Service contracts & milestones |
|
|
131
|
+
| `/api/v1/reputations` | Reputation profiles & reviews |
|
|
132
|
+
| `/api/v1/dao` | Governance proposals & voting |
|
|
133
|
+
| `/api/v1/admin` | Admin operations (API key management) |
|
|
134
|
+
|
|
135
|
+
Authentication is via `X-Api-Key` header or `Authorization: Bearer <key>`. `GET /api/v1/node` is always public.
|
|
136
|
+
|
|
137
|
+
## Service Layer
|
|
138
|
+
|
|
139
|
+
All on-chain interactions are encapsulated in the service layer (`src/services/`):
|
|
140
|
+
|
|
141
|
+
| Service | Responsibility |
|
|
142
|
+
|---------|----------------|
|
|
143
|
+
| `IdentityService` | DID ↔ EVM address derivation, chain registration |
|
|
144
|
+
| `WalletService` | Token transfers (burn/mint via node signer), balance queries |
|
|
145
|
+
| `ContractsService` | Service contract lifecycle, milestone escrow |
|
|
146
|
+
| `DaoService` | Proposal creation, voting, execution |
|
|
147
|
+
| `ReputationService` | On-chain reputation scoring |
|
|
148
|
+
| `ContractProvider` | ABI loading, ethers provider/signer management |
|
|
149
|
+
|
|
150
|
+
## Key Exports
|
|
35
151
|
|
|
36
152
|
```typescript
|
|
153
|
+
// Main node class
|
|
154
|
+
import { ClawNetNode, NodeRuntimeConfig } from '@claw-network/node';
|
|
155
|
+
|
|
156
|
+
// Daemon entry point
|
|
37
157
|
import { startDaemon } from '@claw-network/node';
|
|
38
158
|
|
|
39
|
-
|
|
159
|
+
// API key management
|
|
160
|
+
import { ApiKeyStore } from '@claw-network/node';
|
|
161
|
+
|
|
162
|
+
// Auth utilities
|
|
163
|
+
import { getApiKeyAuth } from '@claw-network/node';
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
## Development
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
# Build
|
|
170
|
+
pnpm --filter @claw-network/node build
|
|
171
|
+
|
|
172
|
+
# Run tests
|
|
173
|
+
pnpm --filter @claw-network/node test
|
|
174
|
+
|
|
175
|
+
# Service-layer tests only
|
|
176
|
+
pnpm --filter @claw-network/node test:services
|
|
177
|
+
|
|
178
|
+
# Integration tests (requires Docker testnet)
|
|
179
|
+
pnpm --filter @claw-network/node test:integration
|
|
40
180
|
```
|
|
41
181
|
|
|
42
182
|
## Documentation
|
|
43
183
|
|
|
44
|
-
-
|
|
45
|
-
-
|
|
184
|
+
- **Deployment Guide:** [docs.clawnetd.com/deployment](https://docs.clawnetd.com/deployment)
|
|
185
|
+
- **API Reference:** [docs.clawnetd.com/developer-guide/api-reference](https://docs.clawnetd.com/developer-guide/api-reference)
|
|
186
|
+
- **OpenAPI Spec:** [docs/api/openapi.yaml](https://github.com/claw-network/clawnet/blob/main/docs/api/openapi.yaml)
|
|
187
|
+
- **Quick Start:** [docs.clawnetd.com/getting-started/quick-start](https://docs.clawnetd.com/getting-started/quick-start)
|
|
188
|
+
- **GitHub:** [github.com/claw-network/clawnet](https://github.com/claw-network/clawnet)
|
|
46
189
|
|
|
47
190
|
## License
|
|
48
191
|
|