Submit Data

This guide walks through the full submission lifecycle: finding an open target, scoring your data against it, submitting on-chain, and claiming your reward.

Prerequisites

• A funded SOMA address with enough SOMA to cover the bond
• Data you want to submit
• pip install soma-sdk for Python SDK usage

1. Find an open target

   Each epoch, validators generate new targets. Query the network for targets that are still accepting submissions.

   CLI

   soma target list --status open

   Python SDK

   targets = await client.get_targets(status="open")

   Each Target object contains:

   Field	Description
   id	Unique target identifier
   status	Current state (open, closed, etc.)
   embedding	The point in embedding space the network wants data near
   model_ids	Models that will score submissions
   distance_threshold	Maximum allowed distance from the target
   reward_pool	Total reward available for this target
   generation_epoch	Epoch when the target was created
   bond_amount	Required bond in shannons

2. Get model manifests

   Before scoring, fetch the manifests for the models associated with your target. Manifests tell you where to download model weights and how to verify them.

   manifests = await client.get_model_manifests(target)

   Each ModelManifest contains:

   Field	Description
   url	Download URL for the model weights
   checksum	Hash to verify the download
   size	File size in bytes
   decryption_key	Key to decrypt the weights after download

3. Score your data

   Run the target’s models against your data to compute an embedding and distance score. Lower distance means your data is closer to what the network needs.

   CLI

   soma target score --target-id <id> --data-url <url>

   Python SDK

   result = await client.score(
       data_url,
       models=manifests,
       target_embedding=target.embedding,
       data=raw_data,
       seed=0,
   )

   The ScoreResult contains:

   Field	Description
   winner	Index into the models list indicating which model scored best
   loss_score	Per-model loss scores (list[float])
   embedding	Computed embedding for your data (list[float])
   distance	Per-model distance from target (list[float])

   The winner is the index of the model that produced the lowest distance. Use the corresponding model_id when submitting.

   Note

   Scoring requires a scoring service. Set the scoring_url parameter in your client configuration to point to a running scoring service.

4. Build and submit

   Compute a commitment hash for your data, upload it to an accessible URL, then submit on-chain.

   CLI

   soma target submit \
       --target-id <id> \
       --data-commitment <hex> \
       --data-url <url> \
       --data-checksum <hex> \
       --data-size <bytes> \
       --model-id <model_id> \
       --embedding <comma-separated-floats> \
       --distance-score <float> \
       --bond-coin <coin_id>

   Python SDK

   # Compute the commitment hash
   commitment = SomaClient.commitment(data)
   
   # Upload data to accessible storage, then submit
   await client.submit_data(
       signer,
       target_id,
       data,
       data_url,
       model_id,
       embedding,
       distance_score,
   )

   The bond amount is specified in shannons (1 SOMA = 1,000,000,000 shannons). Convert with:

   bond_in_soma = SomaClient.to_soma(target.bond_amount)

   Verify your submission was recorded:

   soma target info <target_id>

5. Claim rewards

   After the challenge window closes (2 epochs after submission), the winning submitter can claim their reward.

   CLI

   soma target claim <target_id>

   Python SDK

   await client.claim_rewards(signer, target_id)

   Verify your balance updated:

   CLI

   soma client balance

   Python SDK

   balance = await client.get_balance(address)