BioFS Node Server

Federated Genomic Data Network for Web3 Era

BioFS Node is a server daemon that enables institutions to participate in a federated network for genomic data sharing, sponsored services, and automatic failover.

🌟 Features

• Master Node: Orchestrates multiple lab nodes, provides failover, and manages network
• Lab Node: Serves institutional S3 buckets with NFT-gated access
• Health Monitoring: Automatic health checks with 30-second intervals
• Failover System: Automatic failover when labs go offline (<2 min activation)
• Sponsored Services: API key and gas fee sponsorship with master fallback
• REST API: 50+ endpoints for discovery, registration, and management
• Prometheus Metrics: Built-in metrics export for monitoring
• CLI Management: Simple commands for node lifecycle

📦 Installation

npm install -g @genobank/biofs-node

🚀 Quick Start

Initialize Configuration

# For master node
biofs-node init --type master --config master-node.yaml

# For lab node
biofs-node init --type lab --config lab-node.yaml

Edit Configuration

Edit the generated YAML file with your settings:

node:
  type: lab
  id: augenomics
  name: "AUGenomics Genomics Lab"
  wallet: "0x..."
  url: "https://biofs.augenomics.org"

api:
  port: 8080
  host: 0.0.0.0

storage:
  bucket: "augenomics-genomics"
  region: "us-east-1"

master:
  url: "https://biofs-master.genobank.io"
  registration_token: "biofs_..."

Register Lab with Master

biofs-node register \
  --name "AUGenomics" \
  --wallet 0xYourLabWallet \
  --bucket s3://augenomics-genomics \
  --master https://biofs-master.genobank.io \
  --email [email protected]

Save the registration token and add it to your config file.

Start Node

biofs-node start --config biofs-node.yaml

Check Status

biofs-node status --config biofs-node.yaml

🏗️ Architecture

Master Node (GenoBank.io)
├── Orchestrates multiple lab nodes
├── Health monitoring (30s intervals)
├── Automatic failover activation
├── Data replication management
└── API key/gas sponsorship fallback

Lab Node (Institutions)
├── Serves S3 bucket via API
├── Sends heartbeat to master
├── Optional sponsored services
└── BioNFT-gated file access

📡 API Endpoints

Health Endpoints (All Nodes)

• GET /health - Basic health check
• GET /status - Detailed node status
• GET /ready - Kubernetes readiness probe
• GET /live - Kubernetes liveness probe

Discovery Endpoints (Master Only)

• GET /api/v1/nodes - List all nodes
• GET /api/v1/nodes/:node_id - Get node details
• GET /api/v1/nodes/:node_id/health - Get node health

Registration Endpoints (Master Only)

• POST /api/v1/labs/register - Register new lab
• POST /api/v1/labs/:lab_id/heartbeat - Lab heartbeat
• GET /api/v1/labs/:lab_id/status - Lab status

🔧 Configuration

Master Node Config

node:
  type: master
  id: genobank-master
  name: "GenoBank.io Master Node"
  wallet: "0x5f5a60EaEf242c0D51A21c703f520347b96Ed19a"
  url: "https://biofs-master.genobank.io"

api:
  port: 8080
  host: 0.0.0.0
  cors_origins:
    - "https://genobank.io"
  rate_limit:
    requests_per_minute: 1000

database:
  type: postgresql
  url: "postgresql://user:pass@localhost:5432/biofs"

monitoring:
  prometheus_enabled: true
  port: 9090

services:
  anthropic_key: "sk-ant-..."  # Master fallback key
  story_executor_key: "0x..."   # Master fallback executor

Lab Node Config

node:
  type: lab
  id: augenomics
  name: "AUGenomics Genomics Lab"
  wallet: "0x..."
  url: "https://biofs.augenomics.org"

storage:
  bucket: "augenomics-genomics"
  region: "us-east-1"

master:
  url: "https://biofs-master.genobank.io"
  registration_token: "biofs_abc123..."

services:
  anthropic_key: "sk-ant-..."  # Optional: Lab-sponsored
  story_executor_key: "0x..."   # Optional: Lab-sponsored

📊 Monitoring

Prometheus Metrics

Metrics are available at http://localhost:9090/metrics:

• biofs_http_requests_total - Total HTTP requests
• biofs_http_request_duration_seconds - Request latency
• biofs_lab_status - Lab online/offline status
• biofs_replication_lag_hours - Replication lag

Health Checks

# Check if node is healthy
curl http://localhost:8080/health

# Get detailed status
curl http://localhost:8080/status

# List all nodes (master only)
curl http://localhost:8080/api/v1/nodes

🛠️ Development

Build from Source

git clone https://github.com/Genobank/biofs-node.git
cd biofs-node
npm install
npm run build

Run in Development Mode

npm run dev -- start --config dev-config.yaml

Run Tests

npm test

🐳 Docker Deployment

docker build -t biofs-node .
docker run -d \
  -v /path/to/config.yaml:/etc/biofs/config.yaml \
  -p 8080:8080 \
  -p 9090:9090 \
  biofs-node start --config /etc/biofs/config.yaml

🔐 Security

Best Practices

⚠️ NEVER commit secrets to version control!

1. Use Environment Variables for Secrets

   # Create .env file (already in .gitignore)
   cp .env.example .env
   
   # Edit .env with your actual values
   nano .env

2. Environment Variables

   # .env file
   ANTHROPIC_API_KEY=sk-ant-api03-...your_key...
   AWS_ACCESS_KEY_ID=AKIAA...
   AWS_SECRET_ACCESS_KEY=...secret...
   STORY_EXECUTOR_KEY=0x...private_key...
   DATABASE_URL=postgresql://user:password@localhost/biofs

3. Configuration Files

   • ✅ DO: Use ${VARIABLE_NAME} placeholders in YAML
   • ✅ DO: Load secrets from environment variables
   • ❌ DON'T: Hardcode API keys in config files
   • ❌ DON'T: Commit production.yaml with secrets

   # Good - Reference environment variable
   services:
     anthropic_key: "${ANTHROPIC_API_KEY}"
   
   # Bad - Hardcoded secret (NEVER DO THIS!)
   services:
     anthropic_key: "sk-ant-api03-RnJYcT28..."

4. Code automatically falls back to environment variables:

   // Priority order:
   // 1. Config file value
   // 2. Environment variable (process.env.ANTHROPIC_API_KEY)
   // 3. null (service disabled)

Security Features

• Wallet-based authentication: All nodes authenticated via Web3 signatures
• NFT-gated access: File access controlled by Story Protocol licenses
• Rate limiting: Built-in rate limiting per node
• CORS protection: Configurable CORS origins
• TLS/HTTPS: Use reverse proxy (nginx) for production TLS
• Secret management: Environment variable support with automatic fallback

📚 Documentation

• Implementation Plan
• Federated Network Architecture
• Node/Client Architecture

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

📄 License

MIT License - see LICENSE file.

🆘 Support

• Issues: https://github.com/Genobank/biofs-node/issues
• Email: [email protected]
• Discord: https://discord.gg/genobank

🎯 Roadmap

Phase 1: Core Infrastructure ✅ (Current)

• Master/Lab node modes
• Health monitoring
• Node registration
• REST API

Phase 2: Sponsored Services (Week 3)

• Anthropic API proxy
• Story Protocol gas sponsorship
• Quota management

Phase 3: Data Replication (Week 4)

• S3 replication
• Automatic failover
• Traffic shifting

Built with ❤️ by GenoBank.io