Types

All types are returned as SimpleNamespace objects with attribute access. They are not importable classes at runtime — they exist only for documentation and IDE type checking.

Core Types

ObjectRef

Reference to an on-chain object.

Field	Type	Description
id	str	Object ID
version	int	Object version
digest	str	Object digest

OwnedObjectRef

Object reference with owner information.

Field	Type	Description
id	str	Object ID
version	int	Object version
digest	str	Object digest
owner	str	Owner address

TransactionEffects

Result of transaction execution.

Field	Type	Description
status	str	Execution status ("success" or error)
gas_used	GasUsed	Gas usage breakdown
transaction_digest	str	Transaction digest
created	list[OwnedObjectRef]	Objects created
mutated	list[OwnedObjectRef]	Objects mutated
deleted	list[str]	Object IDs deleted

GasUsed

Gas usage breakdown.

Field	Type	Description
computation_cost	int	Computation gas cost
storage_cost	int	Storage gas cost
storage_rebate	int	Storage rebate
non_refundable_storage_fee	int	Non-refundable portion

Epoch & System

EpochInfo

Information about an epoch.

Field	Type	Description
epoch	int	Epoch number
first_checkpoint_id	int	First checkpoint in this epoch
epoch_total_transactions	int	Total transactions in epoch
reference_gas_price	int	Reference gas price
epoch_start_timestamp_ms	int	Epoch start time (ms since Unix epoch)
end_of_epoch_info	EndOfEpochInfo?	Present only for completed epochs

EndOfEpochInfo

Field	Type	Description
last_checkpoint_id	int	Last checkpoint in the epoch
epoch_end_timestamp_ms	int	Epoch end time
reference_gas_price	int	Final gas price

SystemState

Full system state for the current epoch.

Field	Type	Description
epoch	int	Current epoch
protocol_version	int	Protocol version
validators	ValidatorSet	Active and pending validators
parameters	SystemParameters	On-chain protocol parameters
epoch_start_timestamp_ms	int	Epoch start time
validator_report_records	dict[str, list[str]]	Validator report records
model_registry	object	Model registry state
emission_pool	EmissionPool	Emission pool state
target_state	TargetState	Target generation state
safe_mode	bool	Whether safe mode is active
safe_mode_accumulated_fees	int	Fees accumulated during safe mode
safe_mode_accumulated_emissions	int	Emissions accumulated during safe mode

SystemParameters

On-chain protocol configuration.

Field	Type	Description
epoch_duration_ms	int	Epoch duration in milliseconds
validator_reward_allocation_bps	int	Validator reward share (basis points)
model_min_stake	int	Minimum model stake (shannons)
model_architecture_version	int	Required model architecture version
model_reveal_slash_rate_bps	int	Slash rate for missed reveals
model_tally_slash_rate_bps	int	Slash rate for tally failures
target_models_per_target	int	Models assigned per target
target_embedding_dim	int	Required embedding dimension
target_reward_allocation_bps	int	Target reward share
target_hits_per_epoch	int	Target hits per epoch
target_submitter_reward_share_bps	int	Submitter’s reward share
target_model_reward_share_bps	int	Model owner’s reward share
target_claimer_incentive_bps	int	Claimer incentive
submission_bond_per_byte	int	Submission bond per byte
challenger_bond_per_byte	int	Challenger bond per byte
max_submission_data_size	int	Maximum data size
base_fee	int	Base transaction fee
write_object_fee	int	Fee per object write

EmissionPool

Field	Type	Description
balance	int	Remaining emission balance
emission_per_epoch	int	Emissions distributed per epoch

Validators

Validator

Field	Type	Description
metadata	ValidatorMetadata	Validator addresses and keys
voting_power	int	Voting power
staking_pool	StakingPool	Staking pool state
commission_rate	int	Current commission rate (bps)
next_epoch_stake	int	Projected stake for next epoch
next_epoch_commission_rate	int	Commission rate for next epoch

ValidatorMetadata

Field	Type	Description
soma_address	str	Validator’s SOMA address
protocol_pubkey	str	Protocol public key
network_pubkey	str	Network public key
worker_pubkey	str	Worker public key
net_address	str	Network address
p2p_address	str	P2P address
primary_address	str	Primary address
proxy_address	str	Proxy address
proof_of_possession	str	Proof of possession

Pending updates are available as next_epoch_* optional fields.

ValidatorSet

Field	Type	Description
total_stake	int	Total staked across all validators
validators	list[Validator]	Active validators
pending_validators	list[Validator]	Pending validators
pending_removals	list[int]	Indices of validators pending removal
staking_pool_mappings	dict[str, str]	Pool ID → validator address
inactive_validators	dict[str, Validator]	Inactive validators
at_risk_validators	dict[str, int]	Validators at risk of removal

StakingPool

Field	Type	Description
id	str	Pool object ID
activation_epoch	int?	Epoch when pool was activated
deactivation_epoch	int?	Epoch when pool was deactivated
soma_balance	int	Total SOMA balance
rewards_pool	int	Accumulated rewards
pool_token_balance	int	Pool token supply
exchange_rates	dict[int, PoolTokenExchangeRate]	Epoch → exchange rate
pending_stake	int	Stake pending activation
pending_total_soma_withdraw	int	SOMA pending withdrawal
pending_pool_token_withdraw	int	Pool tokens pending withdrawal

PoolTokenExchangeRate

Field	Type	Description
soma_amount	int	SOMA in the rate
pool_token_amount	int	Pool tokens in the rate

Targets & Data

Target

Field	Type	Description
id	str	Target object ID
status	str	"open", "filled", or "claimed"
embedding	list[float]	Target embedding vector
model_ids	list[str]	Assigned model IDs
distance_threshold	float	Maximum distance for valid submissions
reward_pool	int	Reward in shannons
generation_epoch	int	Epoch when target was generated
bond_amount	int	Required bond amount
submitter	str?	Submitter address (if filled)
winning_model_id	str?	Winning model ID (if filled)

TargetState

Global target generation state.

Field	Type	Description
distance_threshold	object	Current distance threshold
targets_generated_this_epoch	int	Targets generated so far
hits_this_epoch	int	Successful submissions this epoch
hits_ema	int	Exponential moving average of hits
reward_per_target	int	Current reward per target

ListTargetsResponse

Field	Type	Description
targets	list[Target]	Target list
next_page_token	str?	Pagination token

ModelManifest

Model weight manifest returned by get_model_manifests().

Field	Type	Description
url	str	URL of encrypted weights
checksum	str	Weights file checksum
size	int	Weights file size in bytes
decryption_key	str?	AES decryption key (if revealed)

ByteSequenceBatch

Tokenized batch from soma_models.v1.tokenizer.tokenize().

Field	Type	Description
token_ids	list[list[int]]	[batch, seq_len] — input token IDs
targets	list[list[int]]	[batch, seq_len] — next-token targets
pos_ids	list[list[int]]	[batch, seq_len] — global byte offsets

Challenges

ChallengeInfo

Field	Type	Description
challenge	ChallengeDetail	Challenge details

ChallengeDetail

Field	Type	Description
id	str	Challenge object ID
status	str	Challenge status
challenger	str	Challenger address
target_id	str	Target being challenged
epoch	int	Challenge epoch

ListChallengesResponse

Field	Type	Description
challenges	list[ChallengeDetail]	Challenge list
next_page_token	str?	Pagination token

Scoring & Faucet

ScoreResult

Result of scoring a data submission.

Field	Type	Description
winner	int	Index of the winning model
loss_score	list[float]	Loss score per model
embedding	list[float]	Computed data embedding
distance	list[float]	Distance to target per model

FaucetResponse

Field	Type	Description
status	str	Request status
coins_sent	list[FaucetCoinInfo]	Coins sent

FaucetCoinInfo

Field	Type	Description
amount	int	Coin amount in shannons
id	str	Coin object ID
transfer_tx_digest	str	Transfer transaction digest

Checkpoints

CheckpointSummary

Field	Type	Description
data	CheckpointData	Checkpoint data

CheckpointData

Field	Type	Description
sequence_number	int	Checkpoint sequence number
epoch	int	Epoch this checkpoint belongs to
network_total_transactions	int	Cumulative transaction count
content_digest	str	Content digest
timestamp_ms	int	Checkpoint timestamp