ChipForge

ChipForge introduces the first digital design subnet for decentralized hardware innovation. This subnet enables miners to compete in designing real silicon. Processor development is organized into on-chain challenges — spanning AI accelerators, cryptographic modules, mini-GPUs, and other critical components. Participants download specifications, leverage AI tools, and submit complete Verilog/SystemVerilog implementations. The highest-quality designs earn rewards while contributing to fully manufacturable chips.

In the short term, ChipForge focuses on advancing digital hardware design, with future applications across IoT, robotics, edge devices, and post-quantum security. Our roadmap includes progressing from design to full-scale fabrication within a year. Revenue from design IPs and fabricated chips will be reinvested into the ecosystem, ensuring sustainable value creation. Backed by the Tatsu validator team and open to strategic partnerships, ChipForge marks the beginning of a new era — decentralized, collaborative, and on-chain digital design.

Overview

ChipForge operates as a competitive platform where:

• Miners submit hardware design solutions (Verilog/SystemVerilog)
• Validators evaluate submissions using industry-standard EDA tools (Verilator, Yosys, Icarus, Openlane)
• Challenges are rotated periodically with different design requirements
• Rewards go to the latest records: every submission that beats the score to beat becomes a record, waits out a probation, and is then paid for a fixed window, sharing the miner reward with the other records being paid (the record ladder)

Architecture

Core Components

1. Chipforge Challenge Server - Manages challenges, submissions, and evaluations
2. Miners - Submit optimized hardware designs for active challenges
3. Validators - Download, evaluate, and score miner submissions against provided test benches and test cases
4. Chipforge EDA Server - Performs synthesis, place & route, and timing analysis

Workflow

1. Challenge Activation → 2. Miner Submissions → 3. Batch Creation → 
4. Validator Downloads → 5. EDA Evaluation → 6. Score Submission → 
7. Weight Setting → 8. Challenge Completion

Getting Started

Prerequisites

• Docker with the compose plugin (recommended), or Python 3.12
• Bittensor wallet with registered hotkey
• Access to Chipforge Challenge Server API
• Chipforge EDA Server (for validators)

Before you start: wallet and registration

Both miners and validators need a hotkey registered on subnet 108 (btcli docs):

btcli wallet create --wallet-name mywallet --hotkey default          # coldkey + hotkey
btcli subnets register --netuid 108 --network finney --wallet-name mywallet --hotkey default

The folder name you chose (mywallet) is what goes in VALIDATOR_WALLET_NAME / MINER_WALLET_NAME.

Validators additionally need:

• hardware: minimum 16 physical cores + 32 GB RAM, recommended 24 physical cores + 48 GB RAM (physical cores, not vCPUs); see docs/validator_requirements.md;
• a validator permit, which the chain gives to the top-staked hotkeys of the subnet: stake to your hotkey with btcli stake add --netuid 108 .... Your influence on who gets paid is proportional to your stake;
• a VALIDATOR_SECRET_KEY from the ChipForge team (ask on Discord);
• the ChipForge EDA server running and reachable at EDA_SERVER_URL (default http://localhost:8080) before the validator starts.

For testnet, use --network test with your test subnet's netuid, and set NETUID / SUBTENSOR_NETWORK in .env to match.

Running with Docker (recommended)

All settings live in .env; .env.example documents every one of them.

git clone https://github.com/TatsuProject/ChipForge_SN108
cd ChipForge_SN108
cp .env.example .env        # defaults are for mainnet (netuid 108); set the VALIDATOR_/MINER_ wallet
                            # settings (+ VALIDATOR_SECRET_KEY for a validator)
make env-check              # after updating the repo: lists settings your .env is missing

make up                     # validator
make up ROLE=miner          # miner
make logs                   # follow logs        (add ROLE=miner for the miner)
make status                 # container + heartbeat
make restart / make down
make backup-state           # tar.gz of ./data into ./backups

• Wallets: the validator and the miner have separate settings (VALIDATOR_WALLET_DIR / VALIDATOR_WALLET_NAME / VALIDATOR_HOTKEY, and the same with MINER_), so both can run from one folder with different wallets. Each role's directory is mounted read-only; the wallet name is the folder name inside it, not a path. make down stops only the selected ROLE.
• State: everything that must survive restarts (validator state, emission state, bans, downloaded submissions, logs, miner challenge packages) is kept in ./data (DATA_DIR). Moving from a bare-metal validator? Run make migrate-state once: it copies (never moves) the old state files from the repo root into ./data.
• Networking: the containers use host networking (Linux). The validator reaches the EDA server at EDA_SERVER_URL (default http://localhost:8080); the miner's axon listens on AXON_PORT (default 8091), which must be reachable from the internet.
• Health: each neuron rewrites a heartbeat file every 30 s from its event loop; the container is marked unhealthy if it goes stale for 3 minutes, and restart: unless-stopped brings it back after crashes and reboots. Logs are rotated (5 × 50 MB).
• Miner CLI in Docker: make submit FILE=solution.zip, or any command with make cli ARGS="status".
• make test runs the test-suite in a throwaway container.
• Updating: git pull, then make env-check (add any new settings from .env.example), then make up (it rebuilds the image). State in ./data is kept.

For Miners

Installation

To create wallets, visit this:

https://docs.learnbittensor.org/btcli

# Clone the repository
git clone https://github.com/TatsuProject/ChipForge_SN108
cd ChipForge_SN108

# Create an isolated environment (Python 3.12 recommended)
conda create -n chipforge-subnet python=3.12
conda activate chipforge-subnet

# Install dependencies (Bittensor 10.x classic SDK)
pip install -r requirements.txt
pip install -e .

requirements.txt lists the direct dependencies and pins the Bittensor stack (bittensor==10.5.0, bittensor-wallet==4.1.0, bittensor-cli==9.23.2, async-substrate-interface==2.2.1). requirements-lock.txt is the exact resolved set the test-suite was last run against, if you need a reproducible install:

pip install -r requirements-lock.txt

Bittensor 11 removed the axon/dendrite/Synapse networking layer that the miner and validator use, so this repo intentionally stays on the 10.x line.

Running the tests

pip install -r requirements-dev.txt
pytest                                   # unit + loopback transport tests
CHIPFORGE_LIVE_TESTS=1 pytest -m live    # optional: hits testnet (netuid 440 by default)

Running a Miner

Set parameters in .env (see .env.example; the miner's wallet is MINER_WALLET_DIR, MINER_WALLET_NAME, MINER_HOTKEY) and run:

./start_miner.sh          # or, with Docker: make up ROLE=miner

The miner polls the challenge server every MINER_POLL_SECONDS (default 300 s) and immediately when a validator announces a new challenge, then downloads and extracts the challenge package to downloaded_active_challenge/<challenge_id>/. A failed download is retried on the next poll. The axon only answers hotkeys with a validator permit.

Running with nohup (background process)

To run miner/validator through nohup (no hang up, an alternative of pm2):

nohup ./start_miner.sh > miner.log 2>&1 &

To show logs in real-time:

tail -f miner.log

To terminate the process:

# Find the process ID:
ps aux | grep miner

# Kill by PID:
kill <PID>

# Or kill by process name:
pkill -f "miner.py"

# Force kill if needed:
kill -9 <PID>

Miner Responsibilities

• Download challenge (use miner_cli.py download)
• Solve it
• Submit the solution (use miner_cli.py submit)

The miner CLI tool (python_scripts/miner_cli.py) provides all the functionality needed for these tasks. See MINER_CLI_COMMANDS.md for complete documentation.

Submitting Solutions

Using the Miner CLI Tool (Recommended):

The miner_cli.py tool provides a comprehensive command-line interface for miners:

# Check current challenge status and your submissions
python3 python_scripts/miner_cli.py status

# List all your submissions
python3 python_scripts/miner_cli.py submissions

# Download and extract the challenge package (spec, testbench) + challenge info
python3 python_scripts/miner_cli.py download

# Submit a solution (with validation)
python3 python_scripts/miner_cli.py submit solution.zip --check_status

# Dry run (validate without submitting)
python3 python_scripts/miner_cli.py submit solution.zip --dry_run

Using the Shell Script:

# Set wallet and path to zip file in .env file and run this
./submit_solution.sh

Direct Python Script:

You can also use the miner CLI directly with explicit arguments:

python3 python_scripts/miner_cli.py submit solution.zip \
    --wallet.name YOUR_WALLET \
    --wallet.hotkey YOUR_HOTKEY \
    --api_url https://api.chipforge.io \
    --check_status

--wallet.name, --wallet.hotkey, --wallet.path and --api_url can be given before or after the command.

For more details, see MINER_CLI_COMMANDS.md.

Results, logs and revealed winning designs

• Leaderboard: chipforge.io/leaderboard shows the score to beat, the current winner on chain, every submission (one row each, with the validators' consensus score and gates), a page per miner and per submission with a plain explanation of the result (e.g. "functional gate failed", "passed but below the score to beat").
• Scores are published when a batch closes. While your submission is in an open batch it shows "In batch"; no validator can see another's results before submitting its own.
• Full evaluation logs are not public (the website shows a summary: gates, metrics, error code and message). The miner who made the submission gets them, once its batch has closed:

  python3 python_scripts/miner_cli.py logs <submission_id>        # saves one file per validator
  

• Winning designs can be revealed to every hotkey registered on the subnet (miners and validators), when the subnet has reveals turned on. Each winner's design is revealed a set time after it won, earlier if a newer winner overtakes it, and/or when the challenge ends; the Winners tab on the leaderboard shows the policy and when each design becomes available.

  python3 python_scripts/miner_cli.py reveals                        # policy + status of each winning design
  python3 python_scripts/miner_cli.py reveal-download <submission_id>  # saves ./revealed_designs/<id>.zip
  

  The request is signed with your hotkey (an unregistered hotkey gets 403), downloads are limited per day and logged, and the file is checked against the winner's signed hash before it is saved.
• Copies don't win: a file byte-identical to a winning design is refused at submission, and the subnet can require each winner after the first to beat the previous winner by a minimum margin (MIN_IMPROVEMENT_PERCENT).

Solution Format

Solutions must be packaged as ZIP files containing:

• Verilog/SystemVerilog source files (.v, .sv)
• Testbench files (optional)
• Constraint files (optional)
• README with design description (optional)

Important Constraints:

• Maximum file size: 50 MB
• File must be a valid ZIP archive
• The miner CLI tool automatically validates these requirements before submission

Rate Limits

• Miner endpoints of the challenge server (submit, status, history) accept 2 requests per minute and 5 per hour per IP by default.
• logs and reveal-download have their own, separate budget (10 per minute, 60 per hour per IP by default), plus a daily cap per hotkey for revealed designs.
• One hotkey is allowed to submit a maximum 5 solutions for a specific challenge (per-challenge setting).
• The public API used by the website and miner_cli.py reveals is limited separately (120 per minute per IP).

For Validators

Running a Validator

Pull and run Chipforge EDA Server:

https://github.com/TatsuProject/chipforge_eda_server

The EDA server has no API key: keep its port (8080) closed to the internet, or bind it to 127.0.0.1 on the validator machine.

Set parameters in .env (see .env.example; defaults are for mainnet): the validator's wallet is VALIDATOR_WALLET_DIR, VALIDATOR_WALLET_NAME, VALIDATOR_HOTKEY, and VALIDATOR_SECRET_KEY goes there too (never on the command line). Then run:

make up                   # Docker (recommended), or: ./start_validator.sh

A miner can run from the same folder with its own wallet (MINER_WALLET_*, make up ROLE=miner).

What the validator does each cycle:

• polls the challenge server (/validator/sync, one cached request for challenge, batch, bans and test-case version),
• downloads the exposed batch (each file's sha256 is checked against the hash the miner signed) and evaluates it on the EDA server within the batch's deadline,
• submits scores,
• pays the record ladder: puts weights on chain as soon as the places change (a probation ends, a window closes, a new record; within the chain's rate limit) and refreshes them every WEIGHTS_REFRESH_SECONDS. The places share MINER_EMISSION_PERCENTAGE percent, the rest is burned to UID 0.

How many submissions a batch holds is set by the challenge server, and the validator evaluates all of them. EDA_MAX_CONCURRENCY only limits how many it sends to its EDA server at once (the rest wait their turn within the batch's deadline), so set it to what your EDA machine can run in parallel.

How long an evaluation may run is set by the challenge server alone: every batch has an evaluation deadline. With each submission the validator sends its EDA server the time left before that deadline (time_limit_s, minus EDA_DEADLINE_BUFFER_SECONDS for submitting scores and a minute for the answer) and the time every submission of the batch is entitled to (fair_limit_s, the evaluation window minus the same margins). The EDA server stops a run at its limit and says where (EDA_TIMEOUT_BUILD, EDA_TIMEOUT_SIMULATION, ...). A run that had the full window and still timed out scores 0; one cut shorter (it waited for an earlier submission) is reported as a failed evaluation, and the challenge server evaluates it again in a later batch. Timeouts on the validator's side are named too (VALIDATOR_NO_TIME_TO_START, VALIDATOR_EDA_NO_RESPONSE, VALIDATOR_BATCH_TIMEOUT). An EDA server older than this ignores the two fields and applies its own EVAL_TIMEOUT_S.

Record ladder. The challenge server decides the records (when a batch closes, from every validator's results) and sends, in /validator/sync, the ladder rules and every record in probation or being paid, each with its window (pays_from = end of probation, pays_until). The validator computes the places itself on its own clock (neurons/validator_utils/reward_ladder.py, the same algorithm as the server), so probation ends and windows close on time even while the server is unreachable; the last schedule is kept on disk (reward_ladder.json in CHIPFORGE_DATA_DIR) and survives restarts:

• the places go to the records being paid, one per hotkey (its newest), newest first, at most the ladder size (default 3);
• place i gets ratio^(i-1) of the miners' share, normalised over the places held (ratio 0.6: 100% | 62.5/37.5% | 51.0/30.6/18.4%);
• a place whose hotkey is unregistered, is the burn UID or has a banned coldkey is skipped and its part goes to the other places; with no payable place, or while every record is in probation, everything is burned. The challenge server's ban_emissions burns everything.

Against a challenge server without the ladder (older version), the validator falls back to picking its winner from its own evaluations. The miners' share of the weight (MINER_EMISSION_PERCENTAGE) is the validator's own setting unless the challenge server sets one, in which case the server's value is used (the validator logs when it overrides the local value). The minimum improvement margin works the same way: the challenge server sends the margin in force (0 until a challenge has its first winner, then its MIN_IMPROVEMENT_PERCENT), and the validator uses it. The MIN_IMPROVEMENT_PERCENT in the validator's .env is only a fallback for servers that don't send one.

Running with nohup (background process)

To run validator through nohup (no hang up, an alternative of pm2):

nohup ./start_validator.sh > validator.log 2>&1 &

To show logs in real-time:

tail -f validator.log

To terminate the process:

# Find the process ID:
ps aux | grep validator

# Kill by PID:
kill <PID>

# Or kill by process name:
pkill -f "validator.py"

# Force kill if needed:
kill -9 <PID>

Validator Responsibilities

• Download submissions from active batches
• Evaluate designs using EDA tools
• Submit the scores the EDA server returns: functionality, area, performance (delay), power and the overall score, plus the functional and overall gates. How the metrics are weighted is set per challenge by its evaluator bundle (see below)

Evaluation Metrics

Scoring System

Each submission is evaluated across four metrics. Their weights and targets are set per challenge (in the challenge's hidden evaluator bundle), so they can differ between challenges. A submission only counts when it passes both gates: the functional gate (enough of the testbench passes) and the overall gate.

1. Functionality Score: share of the challenge's testbench that passes in simulation (Verilator)
2. Area Score: synthesized cell area in µm² from the ASIC flow (OpenLane), compared with the challenge's target
3. Delay (performance) Score: achieved speed (e.g. maximum frequency or throughput), compared with the target
4. Power Score: estimated power in mW, compared with the target

Competitive Ranking

• Submissions are ranked by overall score (the average of the validators that evaluated them)
• The challenge server decides the winner when a batch closes, from every validator's results: a submission's score is the highest gate-passing score it received, and the best one in the batch wins if it beats the score to beat (from the second winner on, plus MIN_IMPROVEMENT_PERCENT if the subnet sets one). Ties go to the earlier submission, and the score to beat then rises to the new winner's score
• Every winner is a record: it earns nothing during its probation (the subnet can review and void it), then is paid for a fixed window
• The records being paid share MINER_EMISSION_PERCENTAGE of each validator's weight on the record ladder (see "Record ladder" above); the rest is burned
• Emissions are burned while no record is being paid
• Records keep their windows after the challenge ends; the next challenge's records rank above them
• The chain decides who is actually paid (highest incentive); the leaderboard shows it and which validators agree
• Winning designs may be revealed to registered neurons after a delay (see "Results, logs and revealed winning designs")

Challenge Types

Current Challenge Categories

1. RISC-V based Processors
2. AI Accelerators

API Reference

Miner Endpoints

GET  /api/v1/challenges/active              # Get active challenge
POST /api/v1/challenges/{id}/generate-submission-id  # Generate submission ID
POST /api/v1/challenges/{id}/submit         # Submit design solution
GET  /api/v1/challenges/{id}/submissions/hotkey/{hotkey}  # Check submissions (signed)
GET  /api/v1/challenges/{id}/download       # Challenge package
GET  /api/v1/submissions/{submission_id}/evaluation_logs   # Full logs of your own submission (signed)
GET  /api/v1/reveals/{submission_id}/download              # Revealed winning design (signed, registered hotkeys)

Public Endpoints (no key; cached; rate limited per IP)

GET  /api/v1/public/snapshot                # Active challenge, score to beat, winner (server + chain), batch
GET  /api/v1/public/challenges              # Active and past challenges
GET  /api/v1/public/challenges/{id}/leaderboard  # One row per submission
GET  /api/v1/public/submissions/{id}        # One submission: batches, per-validator results and summary
GET  /api/v1/public/miners/{hotkey}         # A miner across challenges
GET  /api/v1/public/validators              # Validators, their on-chain pick, agreement with the chain
GET  /api/v1/public/reveals?challenge_id=   # Reveal policy and status of each winning design
GET  /api/v1/public/rules                   # Competition rules as data

Validator Endpoints

GET  /api/v1/validator/sync                 # Challenge, batch, bans, test-case version in one call (ETag)
GET  /api/v1/challenges/{id}/batch/current  # Get current evaluation batch
GET  /api/v1/challenges/{id}/submissions/{submission_id}/download  # Download submission
POST /api/v1/challenges/{id}/submissions/{submission_id}/submit_score  # Submit evaluation

Configuration

Batch Management

The subnet uses a dynamic batch system:

• Submissions are grouped into evaluation batches
• Each batch has a download window and an evaluation window; the lengths come from the challenge server
• Only one batch is exposed to validators at a time
• Batches transition: EXPOSED → EVALUATING → COMPLETED

Security

Authentication

• Signature-based auth: requests are signed with your Bittensor hotkey (sr25519)
• Validator secrets: Additional secret keys for validator endpoints
• Hotkey verification: Ensures submissions come from registered miners, and evaluated scores come from registered validators
• Timestamp validation: Prevents replay attacks

Data Integrity

• File hashing: All submissions are verified with SHA256 hashes
• Signature verification: Using Bittensor's native signing methods

Monitoring

Health Checks

# Challenge server
curl https://api.chipforge.io/health
# EDA server (validators)
curl http://localhost:8080/health
# Validator / miner under Docker
make status

Troubleshooting

Common Issues

1. Signature Verification Failed

   • Ensure using Bittensor's native signing methods
   • Check timestamp accuracy (must be within 10 minutes)
   • Verify hotkey registration on subnet

2. Submission Upload Failed

   • Use miner_cli.py submit solution.zip --dry_run to validate before submitting
   • Check ZIP file format and contents
   • Verify file size limits (50 MB maximum - checked by the miner CLI before uploading)
   • Ensure proper authentication headers
   • Check wallet configuration in .env file or command-line arguments

3. Validator Download Issues

   • Confirm validator secret configuration
   • Check batch timing and availability
   • Verify network connectivity to challenge server

4. EDA Tool Integration

   • curl http://localhost:8080/health on the validator machine must answer {"status": "ok"}
   • EDA_SERVER_URL in .env must point at it (with Docker host networking, localhost is the host)
   • The EDA server's own README covers its setup and logs (make logs there)

5. Settings missing after an update

   • Run make env-check: it lists keys that .env.example has and your .env lacks

Contributing

Submission Guidelines

1. Follow PEP 8 coding standards
2. Include comprehensive tests
3. Update documentation for new features
4. Ensure backward compatibility

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Discord: ChipForge

Roadmap

Upcoming Features

• Additional challenge categories
• Enhanced evaluation metrics
• Improved toolchain integration

Version History

• v1.0.0 - Initial release with challenge download, solution design, solution verification, submitting scores, and giving reward to winner.