npm package: @genobank/biofs-node
Description: Sequentia Network node for decentralized genomic processing with x402 payments for Genomics Agentic Services and blockchain synchronization
Author: GenoBank.io
Latest version: 1.2.0

# 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

```bash
npm install -g @genobank/biofs-node
```

## 🚀 Quick Start

### Initialize Configuration

```bash
# 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:

```yaml
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

```bash
biofs-node register \
  --name "AUGenomics" \
  --wallet 0xYourLabWallet \
  --bucket s3://augenomics-genomics \
  --master https://biofs-master.genobank.io \
  --email admin@augenomics.org
```

Save the registration token and add it to your config file.

### Start Node

```bash
biofs-node start --config biofs-node.yaml
```

### Check Status

```bash
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

```yaml
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

```yaml
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

```bash
# 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

```bash
git clone https://github.com/Genobank/biofs-node.git
cd biofs-node
npm install
npm run build
```

### Run in Development Mode

```bash
npm run dev -- start --config dev-config.yaml
```

### Run Tests

```bash
npm test
```

## 🐳 Docker Deployment

```bash
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**
   ```bash
   # Create .env file (already in .gitignore)
   cp .env.example .env

   # Edit .env with your actual values
   nano .env
   ```

2. **Environment Variables**
   ```bash
   # .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

   ```yaml
   # 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:**
   ```typescript
   // 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](BIOFS_NODE_IMPLEMENTATION_PLAN.md)
- [Federated Network Architecture](BIOFS_FEDERATED_NETWORK_ARCHITECTURE.md)
- [Node/Client Architecture](BIOFS_NODE_CLIENT_ARCHITECTURE.md)

## 🤝 Contributing

Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.

## 📄 License

MIT License - see [LICENSE](LICENSE) file.

## 🆘 Support

- **Issues**: https://github.com/Genobank/biofs-node/issues
- **Email**: support@genobank.io
- **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**