KNIRVGRAPH - Decentralized Knowledge Graph with Economics

A comprehensive graph-based blockchain application featuring Network Resolution Vectors (NRV), Proof-of-Solution consensus, NRN token economics, and seamless integration with the KNIRV ecosystem.

Architecture

` ┌─────────────────────────────────────────────────────────────┐ │ KNIRVGRAPH Layer │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │ │ NRV System │ │ ErrorNodes │ │ SkillNodes │ │ │ └─────────────┘ └─────────────┘ └─────────────────────┘ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │ │ Economics │ │ Proof-of- │ │ Graph Explorer │ │ │ │ Integration │ │ Solution │ │ (React) │ │ │ └─────────────┘ └─────────────┘ └─────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ │ HTTP/REST API + Economics │ ┌─────────────────────────────────────────────────────────────┐ │ Backend (Go) │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │ │ RPC Server │ │ GraphChain │ │ NRV System │ │ │ │ +Economics │ │ Core │ │ (Vectors) │ │ │ └─────────────┘ └─────────────┘ └─────────────────────┘ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │ │ Storage │ │ NRN Token │ │ KNIRVORACLE │ │ │ │ (BluntDB) │ │ Integration │ │ Integration │ │ │ └─────────────┘ └─────────────┘ └─────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ `

Features

🧠 Network Resolution Vector (NRV) System

- Vector Management: Create, resolve, and maintain NetworkResolutionVectors - ErrorNodes: Specialized nodes for tracking and resolving network errors - SkillNodes: Capability-based nodes for AI agent skills and solutions - Confidence Scoring: Cryptographic confidence verification for resolutions - Signature Verification: Secure validation of vector authenticity

💰 Economics Integration

- NRN Token Integration: Seamless integration with KNIRVORACLE for NRN operations - Skill Confirmation: Skill validation for KNIRVCHAIN commitment - Proof-of-Solution: Reward distribution based on solution quality and efficiency - Economic Metrics: Real-time tracking of network economic activity - Reward Distribution: Automated NRN rewards for network participation

🧪 Phase 7 Testing Infrastructure

Testing Architecture

KNIRVGRAPH implements comprehensive testing for both backend (Go) and frontend (React) components:

Frontend Testing (React + TypeScript)

`bash

Run frontend tests

npm test

Run tests with coverage

npm run test:coverage

Run tests in watch mode

npm run test:watch

Lint code

npm run lint `

Backend Testing (Go)

`bash

Run Go backend tests

go test -v ./...

Run specific test packages

go test -v ./internal/... go test -v ./pkg/... go test -v ./cmd/... `

Integration with Network Tests

`bash

From project root - run KNIRVGRAPH network integration tests

cd integration-tests && go test -v -run TestKNIRVGRAPH

Run comprehensive KNIRVGRAPH test suite

make test-graph

Run KNIRVGRAPH comprehensive tests

cd KNIRVGRAPH && ./scripts/run-comprehensive-tests.sh `

Test Structure

` src/ ├── __tests__/ # Frontend unit tests │ └── App.test.tsx ├── test/ # Test utilities and setup │ └── setup.ts └── components/ # Component tests alongside source

backend/ ├── internal/ # Go backend tests ├── pkg/ # Package tests └── cmd/ # Command tests `

🔗 KNIRV Ecosystem Integration

- KNIRVORACLE Connectivity: Direct integration with KNIRV blockchain - Cross-Component Communication: Seamless interaction with other KNIRV services - Unified Authentication: Shared authentication across KNIRV ecosystem - Real-time Synchronization: Live updates and state synchronization

🏗️ Backend (Go)

- Graph Consensus: Byzantine fault-tolerant consensus adapted for graph structures - BluntDB Storage: High-performance graph data persistence with NRV support - REST API: Complete graph data access with economics endpoints - P2P Networking: Distributed node communication - CLI Tools: Command-line interface for graph and NRV interaction - Graph Operations: Node creation, edge management, path finding - Multi-dimensional Relationships: Complex node interconnections with NRV vectors

🎨 Frontend (React)

- Real-time Dashboard: Live graph and economics statistics - NRV Explorer: Browse and manage Network Resolution Vectors - ErrorNode Management: Track and resolve network errors - SkillNode Registry: Manage AI capabilities and skills - Economics Dashboard: Monitor NRN token flows and rewards - Graph Visualization: Interactive graph structure display with NRV overlays - Dark Theme: Modern UI inspired by ai.google.dev - Responsive Design: Mobile-friendly interface

Quick Start

Prerequisites

- Go 1.21+ - Node.js 18+ - npm or yarn - KNIRVORACLE running (for economics integration)

Development Setup

1. Clone and setup backend `bash # Install Go dependencies cd KNIRVGRAPH go mod tidy

# Build KNIRVGRAPH node go build -o bin/knirvgraph ./cmd/node/main.go `

2. Setup frontend `bash # Install frontend dependencies npm install `

3. Start KNIRVGRAPH with Economics Integration `bash # From project root - starts KNIRVGRAPH with full economics integration ./scripts/start-knirvgraph-with-economics.sh `

4. Alternative: Manual startup `bash # Terminal 1: Start KNIRVGRAPH node cd KNIRVGRAPH ./bin/knirvgraph --home ~/.knirvgraph --port 8081

# Terminal 2: Start frontend dev server npm run dev `

5. Access the application - Frontend: http://localhost:5173 - Backend API: http://localhost:8081 - Economics Endpoints: http://localhost:8081/economics/ - NRV System: http://localhost:8081/nrv/

Using the CLI

`bash

Build CLI tool

make build

Get GraphChain height

./build/graphchain-cli height

Get node information

./build/graphchain-cli node genesis

Get edge information

./build/graphchain-cli edge edge123

Get graph heads

./build/graphchain-cli heads

Get node neighbors

./build/graphchain-cli neighbors node1

Find path between nodes

./build/graphchain-cli path node1 node2

Create a new node

./build/graphchain-cli create-node --id node1 --parents genesis --weight 0.8

Create a new edge

./build/graphchain-cli create-edge --from node1 --to node2 --weight 0.5

Get account balance

./build/graphchain-cli account 0x1234567890123456789012345678901234567890

Send graph transaction

./build/graphchain-cli send-tx \ --from 0x1234567890123456789012345678901234567890 \ --to 0x0987654321098765432109876543210987654321 \ --amount 100 \ --fee 1 \ --type 5 `

API Endpoints

Graph REST API

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /height | Get current GraphChain height | | GET | /node/{nodeID} | Get node by ID | | GET | /edge/{edgeID} | Get edge by ID | | GET | /graph/heads | Get current graph heads | | GET | /graph/neighbors/{nodeID} | Get node neighbors | | GET | /graph/path/{from}/{to} | Find path between nodes | | POST | /graph/traverse | Execute graph traversal query | | GET | /account/{address} | Get account information | | POST | /transaction | Submit new graph transaction | | POST | /node | Create new graph node | | POST | /edge | Create new graph edge |

NRV System API

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /nrv/vectors | Get all NRV vectors | | POST | /nrv/vectors | Create new NRV vector | | GET | /nrv/vectors/resolve/{targetHash} | Resolve target hash to vectors | | GET | /nrv/errors | Get all error nodes | | POST | /nrv/errors | Create new error node | | GET | /nrv/skills | Get all skill nodes | | POST | /nrv/skills | Create new skill node | | GET | /nrv/skills/for-error/{errorType} | Get skills for specific error type |

Economics API

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /economics/metrics | Get economic metrics and statistics | | POST | /economics/skill/confirm | Confirm skill for KNIRVCHAIN commitment | | POST | /economics/rewards/distribute | Distribute NRN rewards | | POST | /economics/proof/solution | Submit proof of solution for rewards |

System API

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /health | System health check with service status |

Example API Usage

Graph Operations

`bash

Get current height

curl http://localhost:8081/height

Get node

curl http://localhost:8081/node/genesis

Get graph heads

curl http://localhost:8081/graph/heads

Find path between nodes

curl http://localhost:8081/graph/path/node1/node2

Create node

curl -X POST http://localhost:8081/node \ -H "Content-Type: application/json" \ -d '{ "id": "node1", "parents": ["genesis"], "weight": 0.8, "data": { "transactions": [], "state_changes": [], "edges": [] } }' `

NRV System Operations

`bash

Create an error node

curl -X POST http://localhost:8081/nrv/errors \ -H "Content-Type: application/json" \ -d '{ "error_type": "network_timeout", "description": "Connection timeout to external service", "context": { "service": "api.example.com", "timeout": 30000, "retry_count": 3 }, "severity": 2 }'

Create a skill node

curl -X POST http://localhost:8081/nrv/skills \ -H "Content-Type: application/json" \ -d '{ "skill_type": "network_diagnostics", "capabilities": ["ping_test", "traceroute", "dns_lookup"], "requirements": { "min_confidence": 0.8, "network_access": true } }'

Create NRV vector

curl -X POST http://localhost:8081/nrv/vectors \ -H "Content-Type: application/json" \ -d '{ "target_hash": "abc123def456", "coordinates": [0.1, 0.2, 0.3, 0.4, 0.5], "metadata": { "error_type": "network_timeout", "skill_type": "network_diagnostics" } }'

Get all error nodes

curl http://localhost:8081/nrv/errors

Get skills for specific error type

curl http://localhost:8081/nrv/skills/for-error/network_timeout `

Economics Operations

`bash

Get economic metrics

curl http://localhost:8081/economics/metrics

Confirm a skill for KNIRVCHAIN commitment

curl -X POST http://localhost:8081/economics/skill/confirm \ -H "Content-Type: application/json" \ -d '{ "skill_id": "skill456", "nrv_id": "nrv789", "creator_id": "creator123" }'

Distribute rewards

curl -X POST http://localhost:8081/economics/rewards/distribute \ -H "Content-Type: application/json" \ -d '{ "recipient_id": "solver123", "amount": "500000", "reason": "successful_error_resolution" }'

Submit solution proof

curl -X POST http://localhost:8081/economics/proof/solution \ -H "Content-Type: application/json" \ -d '{ "error_node_id": "error123", "skill_node_id": "skill456", "solver_id": "solver789", "efficiency_score": 0.95, "quality_score": 0.88 }' `

System Health

`bash

Check system health

curl http://localhost:8081/health `

Testing Economics Integration

Automated Testing

`bash

Run comprehensive economics integration tests

./scripts/test-knirvgraph-economics.sh

This will test:

- KNIRVGRAPH connectivity

- KNIRVORACLE integration

- NRV system operations

- Economics endpoints

- Skill confirmation for KNIRVCHAIN commitment

- Reward distribution

- Proof-of-Solution mechanism

Manual Testing Workflow

`bash

1. Start KNIRVGRAPH with economics

./scripts/start-knirvgraph-with-economics.sh

2. In another terminal, test the integration

./scripts/test-knirvgraph-economics.sh

3. Monitor logs

tail -f KNIRVGRAPH/logs/knirvgraph.log `

Environment Configuration

`bash

Set KNIRVORACLE URL (default: http://localhost:1317)

export KNIRVORACLE_URL=http://localhost:1317

Set KNIRVGRAPH port (default: 8081)

export KNIRVGRAPH_PORT=8081

Enable/disable economics (default: true)

export ECONOMICS_ENABLED=true `

Project Structure

` KNIRVGRAPH/ ├── cmd/ # Command-line applications │ ├── node/ # KNIRVGRAPH node with NRV and economics │ └── cli/ # CLI tool for graph operations ├── internal/ # Private application code │ ├── app/ # Application logic with economics integration │ ├── graphchain/ # GraphChain core │ ├── nrv/ # Network Resolution Vector system │ ├── economics/ # NRN token integration and Proof-of-Solution │ │ ├── nrn_integration.go # KNIRVORACLE integration │ │ └── proof_of_solution.go # Proof-of-Solution consensus │ ├── network/ # Networking and RPC with economics endpoints │ ├── storage/ # Data persistence with NRV support │ └── types/ # Data structures for graph and NRV ├── pkg/ # Public libraries │ ├── crypto/ # Cryptographic functions │ └── utils/ # Utility functions ├── config/ # Configuration files ├── docs/ # Documentation │ └── NRV_SYSTEM.md # NRV system documentation ├── src/ # React frontend │ ├── components/ # React components with NRV and economics │ ├── pages/ # Page components │ ├── services/ # API services for graph, NRV, and economics │ └── context/ # React context ├── public/ # Static assets ├── bin/ # Built binaries ├── logs/ # Application logs ├── go.mod # Go module definition ├── package.json # Node.js dependencies ├── Makefile # Build automation └── README.md # This file `

Development

Backend Development

`bash

Run tests

make test

Format code

make fmt

Lint code

make lint

Build binaries

make build

Clean build artifacts

make clean `

Frontend Development

`bash

Start development server

npm run dev

Build for production

npm run build

Run linting

npm run lint `

Full Stack Development

`bash

Start both backend and frontend

make dev `

Graph Testing

`bash

Create genesis graph

make create-genesis-graph

Test graph operations

make test-graph `

Configuration

Backend Configuration

Edit config/default.toml:

`toml [network] listen_address = "tcp://0.0.0.0:26656" seeds = [] max_peers = 50

[consensus] timeout_propose = 3000 timeout_propose_delta = 500 timeout_prevote = 1000 timeout_precommit = 1000

[storage] db_path = "./data/graphchain.db"

[rpc] listen_address = "tcp://0.0.0.0:26657" port = 8080

[graph] max_nodes_per_level = 1000 max_edges_per_node = 100 allow_cycles = false consensus_threshold = 0.67 traversal_depth_limit = 50 max_heads = 10 weight_decay_factor = 0.95

[bluntdb] db_path = "./data/graphchain.db" sync_writes = true value_log_max_entries = 1000000 gc_interval = 300 backup_interval = 3600 `

Frontend Configuration

The frontend automatically connects to the backend API at http://localhost:8080. To change this, update src/services/api.ts.

Testing

Backend Tests

`bash make test `

Frontend Tests

`bash npm test `

Graph Operations Tests

`bash

Test node creation

./build/graphchain-cli create-node --id test1 --weight 1.0

Test edge creation

./build/graphchain-cli create-edge --from test1 --to genesis --weight 0.5

Test path finding

./build/graphchain-cli path test1 genesis `

Production Deployment

1. Build production assets `bash make prod `

2. Deploy backend `bash # Copy binary to server scp build/graphchain-node user@server:/usr/local/bin/ # Start service graphchain-node -home /var/lib/graphchain -rpc-port 8080 `

3. Deploy frontend `bash # Build and deploy static files npm run build # Deploy dist/ folder to web server `

Graph Features

Node Operations

- Create Nodes: Add new nodes with parent relationships - Update Nodes: Modify node properties and relationships - Delete Nodes: Remove nodes and update graph structure - Query Nodes: Retrieve node information and metadata

Edge Operations

- Create Edges: Establish weighted connections between nodes - Update Edges: Modify edge weights and properties - Delete Edges: Remove connections while maintaining graph integrity - Query Edges: Retrieve edge information and traversal data

Graph Traversal

- Path Finding: Discover routes between any two nodes - Neighbor Discovery: Find all connected nodes - Subgraph Extraction: Extract portions of the graph - Cycle Detection: Identify and prevent circular dependencies

Consensus Features

- Graph Validation: Ensure graph structure integrity - Multi-dimensional Consensus: Consensus across graph topology - Weight-based Validation: Consensus based on node and edge weights - Byzantine Fault Tolerance: Maintain consistency despite failures

Contributing

1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests 5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

- Open issues on GitHub - Check the documentation - Contact the development team

Roadmap

✅ Completed (August 2025)

- [x] NRV System Implementation - Complete Network Resolution Vector system - [x] Economics Integration - Full NRN token integration with KNIRVORACLE - [x] Proof-of-Solution - Reward mechanism for error resolution - [x] ErrorNodes & SkillNodes - Specialized node types for AI capabilities - [x] KNIRV Ecosystem Integration - Seamless integration with other KNIRV components - [x] Economic Metrics Tracking - Real-time economics monitoring - [x] Automated Testing - Comprehensive test suite for economics integration

🔄 In Progress

- [ ] Enhanced Graph Visualization - NRV-aware graph visualization tools - [ ] Advanced NRV Algorithms - Improved vector resolution and confidence scoring - [ ] Cross-Component DHT - Enhanced DHT integration with other KNIRV services

📋 Planned

- [ ] Graph Smart Contracts - Smart contract layer for graph operations - [ ] Enhanced Graph Consensus - Multi-dimensional consensus mechanisms - [ ] Cross-Graph Bridges - Inter-graph communication protocols - [ ] Advanced Graph Algorithms - Machine learning-enhanced graph operations - [ ] Mobile Applications - Mobile interface for KNIRVGRAPH - [ ] Graph Analytics Dashboard - Advanced analytics and insights - [ ] Multi-Language Support - SDK support for multiple programming languages - [ ] Real-time Collaboration - Multi-user graph editing and collaboration - [ ] Graph Machine Learning - AI-powered graph analysis and prediction