Soma

Expert guide for participating in the SOMA network — a decentralized system that trains a foundation model through competition. Provides data submission workflows, model training pipelines, reward claiming, SDK code generation, CLI command guidance, and competitive strategy optimization. Use when user mentions "SOMA", "soma-sdk", "soma-models", "submit data to SOMA", "train a SOMA model", "SOMA targets", "SOMA rewards", "next-byte prediction network", "decentralized model training", or asks about earning SOMA tokens through data or model contributions. Do NOT use for general machine learning, PyTorch, or JAX questions unrelated to the SOMA network.

# SOMA Network

> **Security & credentials**: This skill requires sensitive environment variables (`SOMA_SECRET_KEY`, `HF_TOKEN`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`) for on-chain signing, dataset access, and artifact storage. Credentials are stored in a local `.env` file (gitignored) and pushed to Modal's encrypted secret store — never committed to git. Submission data and encrypted model weights are uploaded with public-read ACLs as required by the SOMA protocol for validator audits. **Always use testnet keys** for development and automated pipelines. Scope S3 API tokens to a single bucket with minimal permissions.

SOMA is an open-source network that trains a unified foundation model through decentralized competition. Models independently train on the same byte-level transformer architecture, compete on a universal objective (next-byte prediction), and integrate into one system. The best weights are rewarded with SOMA tokens.

There are three ways to earn SOMA:
1. **Submit data** — find or generate data matching network targets, score it against assigned models, submit valid results (50% of target reward)
2. **Train models** — train weights on the shared architecture, publish them on-chain via commit-reveal, earn commission when your model wins (50% of target reward)
3. **Run a validator** — operate consensus nodes, generate targets, audit submissions (20% of epoch rewards)

## The Game

You're not just submitting data or training models. You're a specialist in a collective brain.

SOMA's foundation model is the sum of all its specialists. Every model that dominates a niche — Python ML code, Rust networking, LaTeX papers, binary protocols — teaches the collective something no single centralized model could learn as deeply. Your strategic choices — what domain to master, what data to curate, how to position your model — directly determine whether this collective intelligence rivals or surpasses the largest centralized foundation models.

**The metagame**: SOMA is a game within a game. The inner game is technical execution: training, submitting, claiming. The outer game is strategic positioning: where in the 2048-dimensional embedding space to compete, what domains to specialize in, when to pivot, how to read the network. Most participants will play the inner game. Winners play the outer game.

**Why specialization beats generalism**: A model that's mediocre at everything loses to a model that's excellent at one thing. The embedding space is vast. The agent that finds an underserved niche and dominates it earns more than the agent that competes in crowded regions. The network needs breadth — be the specialist it doesn't have yet.

## Quick Decision Tree

**What do you want to do?**

- **"I'm starting from scratch"** / **"Help me start contributing"** → Follow **Getting Started** below to deploy the data submitter on testnet — the fastest path to earning. No GPU on your machine, no model training. Once you're earning, optimize your niche with `references/strategies.md` and graduate to model training.
- **"I want to submit data and earn rewards"** → See the **Data Submission Workflow** section below
- **"I want to train a model"** → See the **Model Training Workflow** section below
- **"I want to claim my rewards"** → See the **Claiming Rewards** section below
- **"I need to set up my environment"** → See **Getting Started** — it walks through setup and deploys the submitter in one flow
- **"Where should I compete?"** → See `references/strategies.md` (Part II: Choose Your Territory)
- **"What's the current state of the game?"** → See `references/strategies.md` (Part I: Read the Board) and `references/quickstart-patterns.md` (Network Analysis Pattern)
- **"How do I find the right data?"** → See `references/data-strategies.md`
- **"How do I improve my model?"** → See `references/model-strategies.md`
- **"I want competitive strategies"** → See `references/strategies.md`
- **"I want to understand how SOMA works"** → See `references/architecture.md`
- **"I need SDK API details"** → See `references/sdk-reference.md`
- **"I need CLI commands"** → See `references/cli-reference.md`
- **"I want working code examples"** → See `references/quickstart-patterns.md`
- **"I want to fork the quickstart repo"** → See **Getting Started** Step 2, then `references/quickstart-patterns.md` (Repo File Map)

## Getting Started

The fastest path to earning SOMA is **data submission**: fork the quickstart, configure credentials, deploy the submitter to Modal. No GPU needed on your machine, no model training, no localnet.

### Step 1: Install CLI and Create Wallet

```bash
curl -fsSL https://sup.soma.org | bash && sup install soma
soma wallet new
soma faucet           # fund on testnet
soma wallet export    # save the secret key — you'll need it next
```

### Step 2: Fork the Quickstart

```bash
git clone https://github.com/soma-org/quickstart
cd quickstart
cp .env.example .env
uv sync
```

Requires Python 3.13+ and [uv](https://docs.astral.sh/uv/getting-started/installation/).

### Step 3: Configure Credentials

Fill in `.env`. Each credential is required — here's what it does and where to get it:

| Credential | Why it's needed | Where to get it |
|-----------|----------------|-----------------|
| `SOMA_SECRET_KEY` | Signs your on-chain transactions (submissions, claims) | `soma wallet export` → copy the secret key |
| `HF_TOKEN` | Accesses The Stack v2 training data for submission scoring | [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) — create a read token, then accept terms on the [dataset page](https://huggingface.co/datasets/bigcode/the-stack-v2-dedup) |
| `S3_BUCKET` | Stores submission data at a public URL — validators must download your data to audit it | [Cloudflare R2](https://dash.cloudflare.com) → R2 Object Storage → create a bucket (free tier, zero egress fees) |
| `S3_ACCESS_KEY_ID` / `S3_SECRET_ACCESS_KEY` | Authenticates uploads to your bucket | R2 → Manage R2 API Tokens → create token with Object Read & Write |
| `S3_ENDPOINT_URL` | S3-compatible API endpoint for uploads | R2 → Account Details → S3 API (e.g. `https://<id>.r2.cloudflarestorage.com`) |
| `S3_PUBLIC_URL` | Public download URL for validators | R2 → your bucket → Settings → enable Public Development URL |

**Why can't I skip these?** SOMA is a decentralized network — validators independently verify every submission by downloading and re-scoring your data. This means your data must be at a public URL (→ S3/R2), and scoring runs 1.2B-parameter models on GPU (→ Modal, or a local GPU with 24GB+ VRAM). All services have generous free tiers: Modal gives $30 free credits (with credit card), R2 gives 10 GB/month free with zero egress fees, and HuggingFace is free.

### Step 4: Deploy the Submitter

```bash
# Sign up at modal.com — adding a credit card unlocks $30 extra free credits
uv run modal setup
uv run create-secrets                              # pushes .env to Modal
uv run modal run src/quickstart/submitter.py       # test run
```

**You're now scoring data against open targets and earning SOMA.** The submitter streams source code from The Stack v2, scores it using an L4 GPU on Modal, and submits valid hits on-chain.

Deploy and start immediately (also sets up a 24h cron schedule):
```bash
uv run modal deploy src/quickstart/submitter.py && uv run submit
```

### What's Next?

- **Claim rewards** — after 2 epochs, run `uv run claim` (see **Claiming Rewards** below)
- **Optimize your niche** — see `references/strategies.md` for competitive positioning and target selection
- **Train a model** — earn the other 50% of target rewards (see **Model Training Workflow** below)

### Quick Connection Test

If you want to verify your connection before deploying:

```python
import asyncio
from soma_sdk import SomaClient, Keypair

async def test():
    client = await SomaClient(chain="testnet")
    kp = Keypair.from_secret_key("YOUR_SECRET_KEY")
    balance = await client.get_bal