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

$3

`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
`

$3

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_..."
`

$3

`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.

$3

`bash
biofs-node start --config biofs-node.yaml
`

$3

`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

$3

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

$3

- 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

$3

- 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

$3

`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
`

$3

`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

$3

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

$3

`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

$3

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

$3

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

$3

`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

$3

⚠️ 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)
``

$3

- 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: support@genobank.io
- Discord: https://discord.gg/genobank

🎯 Roadmap

$3

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

$3

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

$3

- S3 replication
- Automatic failover
- Traffic shifting

---

Built with ❤️ by GenoBank.io