Register a Model

Model registration uses a two-phase commit-reveal protocol. You first post a cryptographic commitment of your weights, then reveal the actual data in the next epoch. This prevents front-running — no one can see your weights before they’re locked in.

Register Your Model

Prepare your weights for upload:

Encrypt your weights using AES-256-CTR. This ensures validators can’t access your weights before the reveal.
```
from soma import SomaClient

weights = open("weights.safetensors", "rb").read()

encrypted_weights, decryption_key = SomaClient.encrypt_weights(weights)
```
Upload the encrypted weights and any test data to storage (S3 or compatible). You need a URL that validators can access.

Then compute the commitments — Blake2b-256 hex digests of the URL and the encrypted weights:
```
weights_url = "https://storage.example.com/my-model/weights.enc"

url_commitment = SomaClient.commitment(weights_url.encode())
weights_commitment = SomaClient.commitment(encrypted_weights)
```
Commit your model on-chain:
- CLI
- Python SDK
Terminal window
soma model commit <model_id> \ --weights-url-commitment <url_commitment_hex> \ --weights-commitment <weights_commitment_hex> \ --stake-amount <amount> \ --commission-rate <basis_points> \ --staking-pool-id <pool_id>
model_id = await client.commit_model( signer, weights_url, encrypted_weights, commission_rate, stake_amount=amount, )
commission_rate is in basis points: 100 = 1%, maximum 10000.
Verify the commit:
Terminal window
```
soma model info <model_id>
```
The model should show a committed status.

Reveal your model in the next epoch:

CLI
Python SDK

soma model reveal <model_id> \
    --weights-url <url> \
    --weights-checksum <hex> \
    --weights-size <bytes> \
    --decryption-key <key_hex> \
    --embedding <comma_separated_floats>

await client.reveal_model(
    signer,
    model_id,
    weights_url,
    encrypted_weights,
    decryption_key,
    embedding,
)

The embedding is the list[float] returned by compute_loss during training.

Verify the reveal:

soma model info <model_id>

The model should now show an active status. It will begin competing in subsequent epochs.

Update Weights

Updating weights follows the same two-phase commit-reveal pattern.

CLI
Python SDK

# Phase 1: commit the update
soma model update-commit <model_id> \
    --weights-url-commitment <url_commitment_hex> \
    --weights-commitment <weights_commitment_hex>

# Phase 2: reveal in the next epoch
soma model update-reveal <model_id> \
    --weights-url <url> \
    --weights-checksum <hex> \
    --weights-size <bytes> \
    --decryption-key <key_hex> \
    --embedding <comma_separated_floats>

# Phase 1: commit the update
tx = build_commit_model_update(model_id, url_commitment, weights_commitment)
await client.submit(signer, tx)

# Phase 2: reveal in the next epoch
tx = build_reveal_model_update(
    model_id, weights_url, weights_checksum,
    weights_size, decryption_key, embedding,
)
await client.submit(signer, tx)

Other Operations

Set commission rate — takes effect next epoch:

soma model set-commission-rate <model_id> --commission-rate <basis_points>

Deactivate your model — stops competing:

soma model deactivate <model_id>

Stake on your own model:

soma stake --model <model_id> --amount <amount>

List all models:

soma model list