Subnet Distribution Script

This repository contains a lightweight miner/validator template plus a production-ready alpha distribution script used to pay subnet contributors. The focus is on fault‑tolerant payouts with verifiable accounting, minimal gas waste, and straightforward operator workflows.

Quick Start

Step	Description	Command
1	Install deps	pip install -r requirements.txt
2	Top up wallets & stake TAO under your subnet hotkey	btcli stake add --wallet-name sn-creator --wallet-hotkey sn-hotkey --netuid 2 --amount <TAO>
3	Prepare pledger CSV (address, pledged_tao)	see data/bitstart_addresses.csv
4	Dry run distributor	python alpha_distributor.py ... --dry-run
5	Execute live transfers	remove --dry-run; inspect reports/*.json

Repository Layout

alpha_distributor.py   # Automation engine
miner.py / validator.py # Minimal subnet actors (optional reference)
data/bitstart_addresses.csv  # Sample pledger list with pledged_tao
reports/               # JSON outputs (dry run & live)

Alpha Distribution Highlights

• Fee-aware payouts: Each recipient’s share is computed from the full pool, then the configured --transfer-fee-tao is deducted on their side to avoid running the hotkey dry.
• Sequential verification: After every transfer_stake, the script queries get_stake_for_coldkey_and_hotkey to verify the increase. A single automatic retry is issued if verification fails.
• Final audit: A post-run pass double-checks all recipients. Reports include expected, fee, payout, and verification status for transparent auditing.
• Subnet safety checks: The script fetches btcli subnet show/hyperparameters data to confirm transfers are enabled and logs the snapshot in the report.
• Input flexibility: Provide either (a) a CSV with address,pledged_tao or (b) an addresses-only file + funding coldkey + SubQuery endpoint (disabled by default in local env).

Running the Distributor

python alpha_distributor.py \
  --recipients-file data/bitstart_addresses.csv \
  --wallet-name sn-creator \
  --wallet-hotkey sn-hotkey \
  --network ws://127.0.0.1:9945 \
  --netuid 2 \
  --total-raised 1000 \
  --alpha-pool 100000 \
  --transfer-fee-tao 0.002 \
  --reserve-alpha 5 \
  --min-payout 0.05 \
  --report-path reports/bitstart-netuid2-dryrun.json