DSRCH Node Documentation

Complete technical reference for running, configuring, and operating a DSRCH decentralized search node.

Overview

DSRCH (Decentralized Search Ranking Consensus Hypernetwork) is a purpose-built Layer 1 blockchain for decentralized web search. Each node crawls the web, builds a local search index, serves queries, and earns DSRCH tokens through Proof-of-Index consensus.

Architecture

Quick Start

Option 1: From Binary

# Build from source
cd dsrch && go build -o dsrchd ./cmd/dsrchd

# Initialize node
./dsrchd init --mode full --port 9090

# Start node
./dsrchd start --api-port 8080 --epoch-duration 30s

Option 2: Docker

# Build and run
docker build -t dsrch-node .
docker run -d --name dsrch \
  -p 8080:8080 -p 9090:9090 \
  -v dsrch-data:/home/dsrch/.dsrch \
  --restart unless-stopped \
  dsrch-node start --api-port 8080 --epoch-duration 30s

Option 3: Docker Compose (3-node testnet)

docker compose up -d

CLI Reference

dsrch init

Initialize a new DSRCH node. Generates Ed25519 keypair and default configuration.

Generated files:

~/.dsrch/
├── config.yaml    # Node configuration
└── node.key       # Ed25519 private key (keep secure!)

dsrch start

Start the full DSRCH node with all subsystems.

dsrch status

Display current node status and document count.

Configuration

Configuration is stored in ~/.dsrch/config.yaml:

node:
  mode: "full"           # light | full | validator
  dataDir: "/home/user/.dsrch"
  apiPort: 8080

p2p:
  listenPort: 9090
  bootstrapPeers: []
  enableMDNS: true
  enableDHT: true
  externalIP: ""         # Public IP for NAT/Docker

Node Modes

Data Directory

~/.dsrch/
├── config.yaml      # Configuration
├── node.key         # Ed25519 private key
├── index/           # Bluge full-text index
├── state.json       # Blockchain state
└── query.log        # Search query log

API Reference

Base URL: https://api.dsrch.net · Full interactive docs: api.dsrch.net

Search

curl "https://api.dsrch.net/api/search?q=ukraine&limit=5"

Node Status

{
  "nodeId": "12D3KooW...",
  "status": "running",
  "documents": 2921,
  "version": "329.11.81",
  "chainId": "dsrch-mainnet-1"
}

Network

Epoch & Consensus

Staking

Governance

Crawler

curl -X POST "https://api.dsrch.net/api/crawl/add?url=https://example.com&depth=3&maxPages=200"

Webmaster Tools

Other Endpoints

P2P Networking

DSRCH uses libp2p for all peer-to-peer communication.

Protocols

Discovery

• DHT — Kademlia distributed hash table for global discovery
• mDNS — Local network discovery (development/LAN)
• Bootstrap peers — Hardcoded seed nodes for initial connectivity
• Periodic discovery — Runs every 30 seconds

Crawler Engine

Components

Auto-Seeder

Ensures continuous indexing by providing new seed URLs when the queue is empty:

• 56+ curated seeds: Wikipedia (UK, EN, DE, FR, ES, PL, JA), BBC, DW, Reuters, Ukrainian media, tech sites, science journals, blockchain resources
• Link discovery: External links from crawled pages become new seeds automatically
• Domain deduplication: Each domain crawled once to prevent re-crawling
• Blocklist integration: Russian, Chinese, NK, Iranian, Belarus state media blocked

Crawl Parameters

Search & Indexing

• Bluge — High-performance Go full-text search engine
• Scatter-Gather — Distributed search across shard nodes with consistent hash routing
• Index Replication — Manifest-based sync every 2 minutes + event-triggered sync
• Autocomplete — Seeded from indexed page titles

Consensus: Proof-of-Index

DSRCH uses a custom Proof-of-Index consensus mechanism.

Epochs

Default duration: 1 hour (configurable, 30s for testnet). At epoch end, each node generates a Work Report:

{
  "nodeId": "12D3KooW...",
  "epoch": 42,
  "pageCount": 150,
  "queriesServed": 89,
  "avgLatency": "15ms",
  "shardsStored": 3,
  "crawlMerkle": "a1b2c3d4..."
}

Validation Flow

1. Node crawls pages and serves queries throughout the epoch
2. Activity tracked by ActivityTracker
3. At epoch end, work report generated and broadcast via GossipSub
4. DSRCHApp.ProcessEpochWithValidation validates all reports
5. Valid nodes receive DSRCH token rewards
6. State persisted to disk

Blockchain Modules

Governance

DSRCH has on-chain governance for protocol upgrades and parameter changes.

• Only staked nodes can vote
• Voting options: yes, no, abstain, veto
• Voting power proportional to stake
• Lifecycle: submitted → quorum → voting → tally → executed

Staking & Rewards

Rewards are distributed based on:

• Pages indexed — crawl work
• Queries served — utility
• Uptime — reliability
• Shard storage — data availability

Docker Deployment

# Single node
docker build -t dsrch-node .
docker run -d --name dsrch \
  -p 8080:8080 -p 9090:9090 \
  -v dsrch-data:/home/dsrch/.dsrch \
  --restart unless-stopped \
  dsrch-node start --api-port 8080 --external-ip YOUR_PUBLIC_IP

# 3-node testnet
docker compose up -d

Production Setup

Recommended

• Reverse proxy: Caddy or Nginx for TLS termination
• Firewall: Open ports 8080 (HTTP) and 9090 (P2P, TCP+UDP)
• Resources: 2+ vCPU, 4+ GB RAM, 50+ GB SSD

Caddy Config

explorer.dsrch.net {
    reverse_proxy localhost:8080
}
api.dsrch.net {
    reverse_proxy localhost:8080
}
docs.dsrch.net {
    reverse_proxy localhost:8080
}

Monitoring

• Prometheus metrics at /metrics: request counts, latency histograms, index size
• Dashboard at /dashboard: node status, peers, epochs, rewards
• Explorer at /explorer: network overview, all nodes, search

Security

• Private key: ~/.dsrch/node.key (permissions: 0600) — never share
• Rate limiting: Built-in per-IP rate limiter on all endpoints
• CORS: Configurable origin whitelist
• CSP headers: Content Security Policy on all pages
• TLS: --tls-cert and --tls-key flags
• robots.txt: Crawler respects Robots Exclusion Protocol

Troubleshooting

Node won't start

Run dsrch init first to generate config and keypair.

No peers connecting

• Check firewall: port 9090 must be open (TCP + UDP)
• If behind NAT/Docker: use --external-ip YOUR_PUBLIC_IP
• Verify bootstrap peers are reachable

Crawl queue empty

The auto-seeder provides URLs automatically. If still stopped, manually seed:

curl -X POST "https://api.dsrch.net/api/crawl/add?url=https://example.com"

Search returns no results

Check document count with curl https://api.dsrch.net/api/status. If 0, wait for crawler to index pages.