Development Setup

Relevant Source Files

.dockerignore .gitignore Dockerfile

This document provides comprehensive guidance for developers contributing to the SN106 Bittensor subnet project. It covers development environment configuration, build system setup, containerization workflow, and project structure understanding.

For information about configuring the validator for production deployment, see Configuration. For Docker deployment in production environments, see Docker Deployment.

Development Environment Requirements

The SN106 project is built on Node.js with TypeScript and requires specific development tools and environment setup for effective contribution.

Core Requirements

Component	Version	Purpose
Node.js	20+	Runtime environment (Alpine-based in containers)
npm	Latest	Package management and build scripts
TypeScript	Latest	Type-safe development
Docker	Latest	Containerized development and deployment

The project follows a standard Node.js TypeScript structure with modular organization separating validator logic, utilities, and configuration management.

Development Environment Setup

graph TB
    subgraph "Local Development"
        NODE["Node.js 20+<br/>Runtime Environment"]
        NPM["npm<br/>Package Manager"]
        TS["TypeScript<br/>Type System"]
    end
    
    subgraph "Project Structure"
        VALIDATOR["validator/<br/>Core validation logic"]
        UTILS["utils/<br/>Shared utilities"]
        CONFIG["config/<br/>Environment configuration"]
        PACKAGE["package.json<br/>Dependencies & scripts"]
        TSCONFIG["tsconfig.json<br/>TypeScript configuration"]
    end
    
    subgraph "Build Artifacts"
        DIST["dist/<br/>Compiled output"]
        LOGS["logs/<br/>Runtime logs"]
        DATA["data/<br/>Persistent storage"]
        NODEMODULES["node_modules/<br/>Dependencies"]
    end
    
    NODE --> PACKAGE
    NPM --> NODEMODULES
    TS --> TSCONFIG
    
    PACKAGE --> VALIDATOR
    PACKAGE --> UTILS
    PACKAGE --> CONFIG
    
    TSCONFIG --> DIST
    VALIDATOR --> LOGS
    VALIDATOR --> DATA
    
    style NODE fill:#e3f2fd
    style VALIDATOR fill:#fff3e0
    style DIST fill:#ffebee

Sources: Dockerfile:1-25 , package.json (referenced) , tsconfig.json (referenced)

Project Structure and Build System

The SN106 codebase follows a modular architecture with clear separation of concerns between validation logic, utilities, and configuration management.

Directory Organization

Core Module Structure

graph LR
    subgraph "Source Code Modules"
        VALIDATOR_DIR["validator/<br/>index.ts + modules"]
        UTILS_DIR["utils/<br/>Shared functionality"]
        CONFIG_DIR["config/<br/>environment.ts"]
    end
    
    subgraph "Build Configuration"
        TSCONFIG_FILE["tsconfig.json<br/>TypeScript compiler config"]
        PACKAGE_FILE["package.json<br/>Scripts & dependencies"]
    end
    
    subgraph "Runtime Directories"
        LOGS_DIR["logs/<br/>Application logs"]
        DATA_DIR["data/<br/>Persistent state"]
        WEIGHTS_DIR["weights/<br/>Weight calculations"]
    end
    
    subgraph "Development Artifacts"
        DIST_DIR["dist/<br/>Compiled JavaScript"]
        NODE_MODULES["node_modules/<br/>Installed packages"]
        CACHE_DIR["cache/<br/>Build cache"]
    end
    
    TSCONFIG_FILE --> DIST_DIR
    PACKAGE_FILE --> NODE_MODULES
    VALIDATOR_DIR --> LOGS_DIR
    VALIDATOR_DIR --> DATA_DIR
    VALIDATOR_DIR --> WEIGHTS_DIR
    
    style VALIDATOR_DIR fill:#e3f2fd
    style CONFIG_DIR fill:#fff3e0
    style DIST_DIR fill:#ffebee
    style LOGS_DIR fill:#f3e5f5

Sources: Dockerfile:14-16 , Dockerfile:19 , .gitignore:2-4 , .gitignore:22-25

Ignored Files and Build Artifacts

The project maintains clean development and deployment environments through comprehensive ignore patterns for build artifacts, logs, and sensitive configuration.

Category	Files/Patterns	Purpose
Node.js	node_modules/, dist/, build/	Build artifacts and dependencies
Logs	*.log, npm-debug.log*, yarn-*.log*	Runtime and debug logs
TypeScript	*.tsbuildinfo	Incremental compilation cache
Environment	.env	Sensitive configuration
Development	*.swp, *.swo, .DS_Store	Editor and OS artifacts
Project-specific	artifacts/, cache/, weights/	Build cache and runtime data

The .gitignore:1-26 file ensures that development artifacts, logs, and sensitive configuration remain local to the development environment and are not committed to version control.

Sources: .gitignore:1-26

Docker Development Workflow

The SN106 project provides a comprehensive Docker-based development workflow that mirrors the production environment while optimizing for development iteration speed.

Container Build Process

Docker Build Pipeline

graph TD
    subgraph "Base Image Setup"
        BASEIMAGE["node:20-alpine<br/>Lightweight Node.js runtime"]
        WORKDIR["WORKDIR /app<br/>Application directory"]
    end
    
    subgraph "Dependency Installation"
        PACKAGECOPY["COPY package.json<br/>COPY tsconfig.json"]
        NPMINSTALL["RUN npm install<br/>Install dependencies"]
    end
    
    subgraph "Source Code Integration"
        SOURCECOPY["COPY validator/<br/>COPY utils/<br/>COPY config/"]
        DIRCREATE["RUN mkdir -p logs data<br/>Runtime directories"]
    end
    
    subgraph "Container Configuration"
        EXPOSE["EXPOSE 3000<br/>Port exposure"]
        CMD["CMD npm run validator<br/>Start command"]
    end
    
    BASEIMAGE --> WORKDIR
    WORKDIR --> PACKAGECOPY
    PACKAGECOPY --> NPMINSTALL
    NPMINSTALL --> SOURCECOPY
    SOURCECOPY --> DIRCREATE
    DIRCREATE --> EXPOSE
    EXPOSE --> CMD
    
    style BASEIMAGE fill:#e3f2fd
    style NPMINSTALL fill:#fff3e0
    style CMD fill:#c8e6c9

Sources: Dockerfile:1-25

Docker Ignore Strategy

The .dockerignore:1-19 file optimizes container build performance by excluding development artifacts, test files, and documentation from the Docker build context:

• Development artifacts: node_modules, debug logs, coverage reports
• Source control: .git, .gitignore, repository metadata
• Documentation: README.md, Docker configuration files
• Test infrastructure: test/, tests/, *.test.*, *.spec.*
• Runtime data: logs/, data/ directories

This approach ensures minimal container size and faster build times by including only essential application code and configuration.

Sources: .dockerignore:1-19

Development Best Practices

Environment Management

The development environment relies on proper configuration management through environment variables and TypeScript configuration. The .env file contains sensitive configuration and should never be committed to version control as specified in .gitignore:5 .

Build System Integration

The TypeScript compilation system generates output to the dist/ directory as specified in .gitignore:3 . The build system maintains incremental compilation metadata in *.tsbuildinfo files as noted in .gitignore:12 .

Container Development

For development with Docker:

1. Use the provided Dockerfile:1-25 for consistent environment setup
2. Ensure proper volume mounting for logs and data persistence
3. Leverage the .dockerignore patterns for optimized builds
4. Use the exposed port 3000 as defined in Dockerfile:22

The container startup command npm run validator as specified in Dockerfile:25 provides the entry point for both development and production environments.

Sources: Dockerfile:1-25, .gitignore:1-26 , .dockerignore:1-19