Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'
This commit is contained in:
ruv
303
vendor/ruvector/crates/ruvector-economy-wasm/pkg/README.md
vendored
Normal file
303
vendor/ruvector/crates/ruvector-economy-wasm/pkg/README.md
vendored
Normal file
@@ -0,0 +1,303 @@
|
||||
# @ruvector/economy-wasm - CRDT Credit Economy for Distributed Compute
|
||||
|
||||
[](https://www.npmjs.com/package/ruvector-economy-wasm)
|
||||
[](https://github.com/ruvnet/ruvector)
|
||||
[](https://www.npmjs.com/package/ruvector-economy-wasm)
|
||||
[](https://webassembly.org/)
|
||||
|
||||
A **CRDT-based autonomous credit economy** for distributed compute networks. Provides conflict-free P2P credit tracking, stake/slash mechanics, and reputation scoring - a blockchain alternative for edge computing and AI agent coordination.
|
||||
|
||||
## Key Features
|
||||
|
||||
- **CRDT Ledger**: G-Counter and PN-Counter for P2P-safe credit tracking with guaranteed eventual consistency
|
||||
- **10x Early Adopter Curve**: Contribution multiplier decaying from 10x to 1x baseline as network grows
|
||||
- **Stake/Slash Mechanics**: Participation requirements with slashing for sybil attacks, double-spending, and bad behavior
|
||||
- **Reputation Scoring**: Multi-factor composite score based on accuracy, uptime, and stake weight
|
||||
- **Merkle State Root**: Fast ledger verification with cryptographic proofs
|
||||
- **WASM-Optimized**: Runs in browsers, Node.js, and edge runtimes
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install ruvector-economy-wasm
|
||||
# or
|
||||
yarn add ruvector-economy-wasm
|
||||
# or
|
||||
pnpm add ruvector-economy-wasm
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### TypeScript/JavaScript
|
||||
|
||||
```typescript
|
||||
import init, {
|
||||
CreditLedger,
|
||||
ReputationScore,
|
||||
StakeManager,
|
||||
contribution_multiplier,
|
||||
SlashReason
|
||||
} from 'ruvector-economy-wasm';
|
||||
|
||||
// Initialize WASM module
|
||||
await init();
|
||||
|
||||
// Create a credit ledger for a node
|
||||
const ledger = new CreditLedger("node-123");
|
||||
|
||||
// Earn credits for completed tasks
|
||||
ledger.credit(100n, "task:compute-job-456");
|
||||
console.log(`Balance: ${ledger.balance()}`);
|
||||
|
||||
// Check early adopter multiplier
|
||||
const mult = contribution_multiplier(50000.0); // 50K network compute hours
|
||||
console.log(`Multiplier: ${mult.toFixed(2)}x`); // ~8.5x for early adopters
|
||||
|
||||
// Credit with multiplier applied
|
||||
ledger.creditWithMultiplier(50n, "task:bonus-789");
|
||||
|
||||
// Track reputation
|
||||
const rep = new ReputationScore(0.95, 0.98, 1000n);
|
||||
console.log(`Composite score: ${rep.compositeScore()}`);
|
||||
console.log(`Tier: ${rep.tierName()}`);
|
||||
```
|
||||
|
||||
## Understanding CRDTs
|
||||
|
||||
**Conflict-free Replicated Data Types (CRDTs)** enable distributed systems to:
|
||||
- Merge updates in any order with identical results
|
||||
- Operate offline and sync later without conflicts
|
||||
- Scale horizontally without coordination bottlenecks
|
||||
|
||||
This package uses:
|
||||
- **G-Counter**: Grow-only counter for earned credits (monotonically increasing)
|
||||
- **PN-Counter**: Positive-negative counter for spending (allows refunds/disputes)
|
||||
|
||||
```typescript
|
||||
// P2P merge example - works regardless of message order
|
||||
const nodeA = new CreditLedger("node-A");
|
||||
const nodeB = new CreditLedger("node-B");
|
||||
|
||||
// Both nodes earn credits independently
|
||||
nodeA.credit(100n, "job-1");
|
||||
nodeB.credit(50n, "job-2");
|
||||
|
||||
// Export for P2P sync
|
||||
const earnedA = nodeA.exportEarned();
|
||||
const spentA = nodeA.exportSpent();
|
||||
|
||||
// Merge on node B - associative, commutative, idempotent
|
||||
const merged = nodeB.merge(earnedA, spentA);
|
||||
console.log(`Merged ${merged} updates`);
|
||||
```
|
||||
|
||||
## Contribution Curve
|
||||
|
||||
Early network contributors receive higher rewards that decay as the network matures:
|
||||
|
||||
```
|
||||
Multiplier = 1 + 9 * exp(-compute_hours / 100,000)
|
||||
|
||||
Network Hours | Multiplier
|
||||
---------------|------------
|
||||
0 | 10.0x (Genesis)
|
||||
10,000 | ~9.0x
|
||||
50,000 | ~6.0x
|
||||
100,000 | ~4.3x
|
||||
200,000 | ~2.2x
|
||||
500,000 | ~1.0x (Baseline)
|
||||
```
|
||||
|
||||
```typescript
|
||||
import { contribution_multiplier, get_tier_name, get_tiers_json } from 'ruvector-economy-wasm';
|
||||
|
||||
// Check current multiplier
|
||||
const hours = 25000;
|
||||
const mult = contribution_multiplier(hours);
|
||||
console.log(`At ${hours} hours: ${mult.toFixed(2)}x multiplier`);
|
||||
|
||||
// Get tier name
|
||||
const tier = get_tier_name(hours); // "Pioneer"
|
||||
|
||||
// Get all tier definitions
|
||||
const tiers = JSON.parse(get_tiers_json());
|
||||
```
|
||||
|
||||
## Stake/Slash Mechanics
|
||||
|
||||
```typescript
|
||||
import { StakeManager, SlashReason } from 'ruvector-economy-wasm';
|
||||
|
||||
const stakeManager = new StakeManager();
|
||||
|
||||
// Stake credits for network participation
|
||||
stakeManager.stake("node-123", 1000n);
|
||||
console.log(`Staked: ${stakeManager.getStake("node-123")}`);
|
||||
|
||||
// Check if node meets minimum stake
|
||||
if (stakeManager.meetsMinimum("node-123")) {
|
||||
console.log("Node can participate");
|
||||
}
|
||||
|
||||
// Delegate stake to another node
|
||||
stakeManager.delegate("node-123", "validator-1", 500n);
|
||||
console.log(`Effective stake: ${stakeManager.getEffectiveStake("validator-1")}`);
|
||||
|
||||
// Slash for bad behavior
|
||||
const slashedAmount = stakeManager.slash(
|
||||
"bad-actor",
|
||||
SlashReason.DoubleSpend,
|
||||
"Evidence: duplicate transaction IDs"
|
||||
);
|
||||
console.log(`Slashed ${slashedAmount} credits`);
|
||||
```
|
||||
|
||||
### Slash Reasons
|
||||
|
||||
| Reason | Severity | Description |
|
||||
|--------|----------|-------------|
|
||||
| `InvalidResult` | Medium | Submitted incorrect computation results |
|
||||
| `DoubleSpend` | High | Attempted to spend same credits twice |
|
||||
| `SybilAttack` | Critical | Multiple fake identities detected |
|
||||
| `Downtime` | Low | Excessive offline periods |
|
||||
| `Spam` | Medium | Flooding the network |
|
||||
| `Malicious` | Critical | Intentional harmful behavior |
|
||||
|
||||
## Reputation System
|
||||
|
||||
```typescript
|
||||
import { ReputationScore, composite_reputation } from 'ruvector-economy-wasm';
|
||||
|
||||
// Create reputation with tracking
|
||||
const rep = ReputationScore.newWithTracking(
|
||||
950n, // tasks completed
|
||||
50n, // tasks failed
|
||||
BigInt(30 * 24 * 3600), // uptime seconds
|
||||
BigInt(31 * 24 * 3600), // total seconds
|
||||
5000n // stake amount
|
||||
);
|
||||
|
||||
// Record task outcomes
|
||||
rep.recordSuccess();
|
||||
rep.recordFailure();
|
||||
|
||||
// Calculate composite score
|
||||
// Formula: accuracy^2 * uptime * stake_weight
|
||||
const score = rep.compositeScore();
|
||||
console.log(`Composite: ${(score * 100).toFixed(1)}%`);
|
||||
|
||||
// Get tier
|
||||
console.log(`Tier: ${rep.tierName()}`); // "Elite", "Trusted", "Standard", etc.
|
||||
|
||||
// Check participation eligibility
|
||||
if (rep.meetsMinimum(0.9, 0.95, 100n)) {
|
||||
console.log("Eligible for premium tasks");
|
||||
}
|
||||
|
||||
// Compare reputations
|
||||
const rep2 = new ReputationScore(0.92, 0.96, 3000n);
|
||||
console.log(`Better reputation: ${rep.isBetterThan(rep2) ? 'rep1' : 'rep2'}`);
|
||||
```
|
||||
|
||||
### Reputation Tiers
|
||||
|
||||
| Tier | Score Range | Benefits |
|
||||
|------|-------------|----------|
|
||||
| Elite | >= 0.95 | Priority task assignment, lowest fees |
|
||||
| Trusted | >= 0.85 | High-value tasks, reduced collateral |
|
||||
| Standard | >= 0.70 | Normal participation |
|
||||
| Probation | >= 0.50 | Limited task types |
|
||||
| Restricted | < 0.50 | Basic tasks only, increased monitoring |
|
||||
|
||||
## Merkle State Verification
|
||||
|
||||
```typescript
|
||||
const ledger = new CreditLedger("node-123");
|
||||
ledger.credit(100n, "job-1");
|
||||
ledger.credit(200n, "job-2");
|
||||
|
||||
// Get state root for verification
|
||||
const stateRoot = ledger.stateRoot();
|
||||
const stateRootHex = ledger.stateRootHex();
|
||||
console.log(`State root: ${stateRootHex}`);
|
||||
|
||||
// Verify state integrity
|
||||
const isValid = ledger.verifyStateRoot(expectedRoot);
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### CreditLedger
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `new(node_id)` | Create ledger for node |
|
||||
| `credit(amount, reason)` | Earn credits |
|
||||
| `creditWithMultiplier(base_amount, reason)` | Earn with network multiplier |
|
||||
| `deduct(amount)` | Spend credits |
|
||||
| `refund(event_id, amount)` | Refund a deduction |
|
||||
| `balance()` | Get available balance |
|
||||
| `stake(amount)` | Lock credits for participation |
|
||||
| `slash(amount)` | Penalty for bad behavior |
|
||||
| `merge(other_earned, other_spent)` | CRDT merge operation |
|
||||
| `exportEarned()` / `exportSpent()` | Export for P2P sync |
|
||||
| `stateRoot()` / `stateRootHex()` | Merkle verification |
|
||||
|
||||
### ReputationScore
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `new(accuracy, uptime, stake)` | Create with scores |
|
||||
| `newWithTracking(...)` | Create with detailed tracking |
|
||||
| `compositeScore()` | Calculate composite (0.0-1.0) |
|
||||
| `tierName()` | Get reputation tier |
|
||||
| `recordSuccess()` / `recordFailure()` | Track task outcomes |
|
||||
| `stakeWeight()` | Logarithmic stake weight |
|
||||
| `meetsMinimum(accuracy, uptime, stake)` | Check eligibility |
|
||||
|
||||
### StakeManager
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `new()` | Create manager |
|
||||
| `stake(node_id, amount)` | Stake credits |
|
||||
| `unstake(node_id, amount)` | Unstake (if unlocked) |
|
||||
| `delegate(from, to, amount)` | Delegate to another node |
|
||||
| `slash(node_id, reason, evidence)` | Slash for violation |
|
||||
| `getEffectiveStake(node_id)` | Own + delegated stake |
|
||||
| `meetsMinimum(node_id)` | Check stake requirement |
|
||||
|
||||
## Use Cases
|
||||
|
||||
- **Distributed AI Training**: Reward compute contributors fairly
|
||||
- **Edge Computing Networks**: Track and reward edge node participation
|
||||
- **Federated Learning**: Incentivize model training contributions
|
||||
- **P2P Storage**: Credit-based storage allocation
|
||||
- **Agent Coordination**: Economic layer for multi-agent systems
|
||||
- **Decentralized Inference**: Pay-per-inference without blockchain overhead
|
||||
|
||||
## Bundle Size
|
||||
|
||||
- **WASM binary**: ~177KB (uncompressed)
|
||||
- **Gzip compressed**: ~65KB
|
||||
- **JavaScript glue**: ~8KB
|
||||
|
||||
## Related Packages
|
||||
|
||||
- [ruvector-learning-wasm](https://www.npmjs.com/package/ruvector-learning-wasm) - MicroLoRA adaptation
|
||||
- [ruvector-exotic-wasm](https://www.npmjs.com/package/ruvector-exotic-wasm) - NAO governance, morphogenetic networks
|
||||
- [ruvector-nervous-system-wasm](https://www.npmjs.com/package/ruvector-nervous-system-wasm) - Bio-inspired neural components
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
||||
## Links
|
||||
|
||||
- [GitHub Repository](https://github.com/ruvnet/ruvector)
|
||||
- [Full Documentation](https://ruv.io)
|
||||
- [Bug Reports](https://github.com/ruvnet/ruvector/issues)
|
||||
|
||||
---
|
||||
|
||||
**Keywords**: CRDT, distributed systems, credits, P2P, peer-to-peer, blockchain alternative, reputation, stake, slash, economy, WebAssembly, WASM, edge computing, decentralized, conflict-free, eventual consistency, G-Counter, PN-Counter
|
||||
Reference in New Issue
Block a user