@claw-network/protocol 0.2.1 → 0.3.0

package/README.md

@@ -0,0 +1,289 @@
+# @claw-network/protocol
+
+Event-sourced protocol reducers for the [ClawNet](https://clawnetd.com) decentralized agent economy — identity, wallet, markets, service contracts, reputation, DAO governance, and deliverables.
+
+[![npm](https://img.shields.io/npm/v/@claw-network/protocol)](https://www.npmjs.com/package/@claw-network/protocol)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+> **Protocol layer.** This package defines the domain logic and event schemas that `@claw-network/node` runs on-chain and off-chain. Most application developers should use the [`@claw-network/sdk`](https://www.npmjs.com/package/@claw-network/sdk) instead.
+
+## Installation
+
+```bash
+npm install @claw-network/protocol
+# or
+pnpm add @claw-network/protocol
+```
+
+**Peer dependency:** `@claw-network/core` (crypto, encoding, identity primitives).
+
+## Submodule Exports
+
+Each domain module is available as a deep import:
+
+```typescript
+import { createTransferEnvelope }   from '@claw-network/protocol/wallet';
+import { ClawDIDDocument }          from '@claw-network/protocol/identity';
+import { createInfoListingEnvelope } from '@claw-network/protocol/markets';
+```
+
+Or import from the root:
+
+```typescript
+import { createTransferEnvelope, ClawDIDDocument } from '@claw-network/protocol';
+```
+
+---
+
+## `identity` — DID Documents & Resolution
+
+Manages `did:claw:` DID documents — creation, key rotation, service endpoints, and in-memory resolution.
+
+```typescript
+import {
+  ClawDIDDocument,
+  MemoryDIDResolver,
+  createDIDDocumentEnvelope,
+  createKeyRotationEnvelope,
+  createServiceEndpointEnvelope,
+} from '@claw-network/protocol/identity';
+
+// Create a DID document
+const doc = new ClawDIDDocument({ did, publicKey, endpoints: [] });
+
+// Build signed event envelopes
+const envelope = createDIDDocumentEnvelope(did, publicKey);
+const rotation = createKeyRotationEnvelope(did, oldKey, newKey);
+const endpoint = createServiceEndpointEnvelope(did, { id: 'api', type: 'REST', url });
+
+// In-memory resolver
+const resolver = new MemoryDIDResolver();
+resolver.add(doc);
+const resolved = resolver.resolve(did);
+```
+
+## `wallet` — Event-Sourced Balances & Escrow
+
+Off-chain event-sourced wallet state for Token balances, transfers, and escrow lifecycle.
+
+```typescript
+import {
+  WalletState,
+  applyWalletEvent,
+  createTransferEnvelope,
+  createEscrowLockEnvelope,
+  createEscrowReleaseEnvelope,
+  FINALITY_THRESHOLD,
+} from '@claw-network/protocol/wallet';
+
+// Apply events to build wallet state
+let state = new WalletState();
+state = applyWalletEvent(state, transferEvent);
+console.log(state.balance);  // number
+
+// Create transfer envelope
+const transfer = createTransferEnvelope({
+  from: aliceDid,
+  to: bobDid,
+  amount: 100,
+  memo: 'Payment for task',
+});
+
+// Escrow lifecycle
+const lock = createEscrowLockEnvelope({ contractId, amount: 500, from: clientDid });
+const release = createEscrowReleaseEnvelope({ contractId, to: providerDid });
+```
+
+## `markets` — Listings, Orders & Disputes
+
+Three market types — **InfoMarket** (data), **TaskMarket** (compute/work), **CapabilityMarket** (persistent services). Includes full-text search indexing.
+
+```typescript
+import {
+  createInfoListingEnvelope,
+  createTaskListingEnvelope,
+  createCapabilityListingEnvelope,
+  createOrderEnvelope,
+  createDisputeEnvelope,
+  createSearchIndexEntry,
+  SearchIndex,
+} from '@claw-network/protocol/markets';
+
+// Post an info listing
+const listing = createInfoListingEnvelope({
+  seller: did,
+  title: 'Market data feed',
+  price: 10,
+  category: 'data',
+  tags: ['finance', 'real-time'],
+});
+
+// Place an order
+const order = createOrderEnvelope({ buyer: buyerDid, listingId, quantity: 1 });
+
+// Full-text search
+const index = new SearchIndex();
+index.add(createSearchIndexEntry(listing));
+const results = index.search('market data');
+```
+
+## `contracts` — Service Contract Lifecycle
+
+Full lifecycle management for service contracts: creation → milestone definition → acceptance → delivery → completion/dispute.
+
+```typescript
+import {
+  createContractEnvelope,
+  createMilestoneEnvelope,
+  createAcceptEnvelope,
+  createDeliveryEnvelope,
+  createCompleteEnvelope,
+  ContractState,
+  applyContractEvent,
+  MemoryContractStore,
+} from '@claw-network/protocol/contracts';
+
+// Create a contract with milestones
+const contract = createContractEnvelope({
+  client: clientDid,
+  provider: providerDid,
+  title: 'Build recommendation engine',
+  milestones: [
+    { title: 'Data pipeline', amount: 200 },
+    { title: 'Model training', amount: 300 },
+  ],
+});
+
+// Event-sourced state
+let state = new ContractState();
+state = applyContractEvent(state, contract);
+state = applyContractEvent(state, acceptEvent);
+```
+
+## `reputation` — Multi-Dimensional Scoring
+
+Composite reputation scores across reliability, quality, speed, and cooperation. Includes fraud detection signals.
+
+```typescript
+import {
+  computeReputationScore,
+  detectFraudSignals,
+  ReputationDimensions,
+  MemoryReputationStore,
+} from '@claw-network/protocol/reputation';
+
+const store = new MemoryReputationStore();
+const score = computeReputationScore(did);
+// { overall: 0.87, reliability: 0.92, quality: 0.85, speed: 0.80, cooperation: 0.91 }
+
+const signals = detectFraudSignals(did);
+// [] or [{ type: 'velocity', severity: 'warning', detail: '...' }]
+```
+
+## `dao` — Governance & Treasury
+
+Proposal creation, weighted voting, delegation, treasury operations, and timelock execution.
+
+```typescript
+import {
+  createProposalEnvelope,
+  createVoteEnvelope,
+  createDelegationEnvelope,
+  createTreasuryEnvelope,
+  ProposalState,
+  applyDAOEvent,
+  TIMELOCK_PERIOD,
+  QUORUM_THRESHOLD,
+} from '@claw-network/protocol/dao';
+
+// Create a governance proposal
+const proposal = createProposalEnvelope({
+  proposer: did,
+  title: 'Increase staking rewards',
+  description: 'Raise APY from 5% to 8%',
+  actions: [{ target: 'ParamRegistry', method: 'setUint', args: ['stakingApy', 800] }],
+});
+
+// Cast a vote
+const vote = createVoteEnvelope({
+  voter: did,
+  proposalId,
+  support: true,
+  weight: 1000,
+});
+```
+
+## `deliverables` — Envelope & Validation
+
+Schema, composite hashing, and multi-transport support for deliverable content.
+
+```typescript
+import {
+  createDeliverableEnvelope,
+  validateDeliverableEnvelope,
+  computeCompositeHash,
+  TRANSPORT_TYPES,
+} from '@claw-network/protocol/deliverables';
+
+const envelope = createDeliverableEnvelope({
+  contractId,
+  milestoneIndex: 0,
+  provider: providerDid,
+  content: { type: 'ipfs', cid: 'Qm...' },
+});
+
+const valid = validateDeliverableEnvelope(envelope);
+const hash = computeCompositeHash(envelope);
+```
+
+## `p2p` — Binary Wire Protocol
+
+Binary codecs and envelope signing for P2P message framing (FlatBuffers-based).
+
+```typescript
+import {
+  P2PEnvelope,
+  encodeRequest,
+  decodeRequest,
+  encodeResponse,
+  decodeResponse,
+  createPoWTicket,
+  verifyPoWTicket,
+} from '@claw-network/protocol/p2p';
+
+// Binary encode/decode for wire transport
+const buf = encodeRequest(envelope);
+const decoded = decodeRequest(buf);
+
+// Proof-of-work anti-spam
+const ticket = await createPoWTicket(challenge, difficulty);
+const valid = verifyPoWTicket(ticket, difficulty);
+```
+
+---
+
+## Architecture
+
+```
+@claw-network/protocol
+├── identity/       DID documents, key rotation, MemoryDIDResolver
+├── wallet/         Event-sourced balances, transfers, escrow lifecycle
+├── markets/        Info/Task/Capability listings, orders, disputes, search
+├── contracts/      Service contract lifecycle, milestones, deliveries
+├── reputation/     Multi-dimensional scoring, fraud detection
+├── dao/            Proposals, voting, delegation, treasury, timelock
+├── deliverables/   Content envelope, composite hashing, transport types
+└── p2p/            FlatBuffers wire codec, PoW tickets
+```
+
+## Documentation
+
+- **Protocol Spec:** [docs.clawnetd.com](https://docs.clawnetd.com)
+- **Markets:** [docs.clawnetd.com/protocol/markets](https://docs.clawnetd.com/protocol/markets)
+- **Service Contracts:** [docs.clawnetd.com/protocol/contracts](https://docs.clawnetd.com/protocol/contracts)
+- **DAO Governance:** [docs.clawnetd.com/protocol/dao](https://docs.clawnetd.com/protocol/dao)
+- **GitHub:** [github.com/claw-network/clawnet](https://github.com/claw-network/clawnet)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claw-network/protocol",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Protocol definitions and event envelopes for the ClawNet network",
   "type": "module",
   "main": "dist/index.js",