Transactions

Note

All build_* methods return unsigned transaction bytes (bytes). To execute, sign with Keypair.sign() and submit via execute_transaction(). For common workflows, use the convenience methods instead.

Executing Transactions

execute_transaction

Submit a signed transaction for execution.

async def execute_transaction(tx_bytes: bytes) -> TransactionEffects

Parameter	Type	Required	Default	Description
tx_bytes	bytes	Yes	—	Signed transaction bytes

Returns: TransactionEffects

simulate_transaction

Dry-run a transaction without committing it.

async def simulate_transaction(tx_data_bytes: bytes) -> TransactionEffects

Parameter	Type	Required	Default	Description
tx_data_bytes	bytes	Yes	—	Unsigned transaction data bytes

Returns: TransactionEffects

get_transaction

Fetch the effects of a previously executed transaction.

async def get_transaction(digest: str) -> TransactionEffects

Parameter	Type	Required	Default	Description
digest	str	Yes	—	Transaction digest

Returns: TransactionEffects

Coin & Transfer Builders

build_transfer_coin

Build a transaction to transfer a coin (or a portion of it) to a recipient.

async def build_transfer_coin(
    sender: str, recipient: str, coin: ObjectRef,
    amount: Optional[int] = None, gas: Optional[ObjectRef] = None,
) -> bytes

Parameter	Type	Required	Default	Description
sender	str	Yes	—	Sender address
recipient	str	Yes	—	Recipient address
coin	ObjectRef	Yes	—	Coin to transfer
amount	int	No	None	Amount in shannons (entire coin if omitted)
gas	ObjectRef	No	None	Gas coin (auto-selected if omitted)

build_transfer_objects

Build a transaction to transfer one or more objects.

async def build_transfer_objects(
    sender: str, recipient: str, objects: list[ObjectRef],
    gas: Optional[ObjectRef] = None,
) -> bytes

Parameter	Type	Required	Default	Description
sender	str	Yes	—	Sender address
recipient	str	Yes	—	Recipient address
objects	list[ObjectRef]	Yes	—	Objects to transfer
gas	ObjectRef	No	None	Gas coin

build_pay_coins

Build a transaction to pay multiple recipients from multiple coins.

async def build_pay_coins(
    sender: str, recipients: list[str], amounts: list[int],
    coins: list[ObjectRef], gas: Optional[ObjectRef] = None,
) -> bytes

Parameter	Type	Required	Default	Description
sender	str	Yes	—	Sender address
recipients	list[str]	Yes	—	Recipient addresses
amounts	list[int]	Yes	—	Amounts in shannons (must match recipients length)
coins	list[ObjectRef]	Yes	—	Input coins
gas	ObjectRef	No	None	Gas coin

Staking Builders

build_add_stake

Stake SOMA with a validator.

async def build_add_stake(
    sender: str, validator: str, coin: ObjectRef,
    amount: Optional[int] = None, gas: Optional[ObjectRef] = None,
) -> bytes

Parameter	Type	Required	Default	Description
sender	str	Yes	—	Sender address
validator	str	Yes	—	Validator address
coin	ObjectRef	Yes	—	Coin to stake
amount	int	No	None	Amount in shannons (entire coin if omitted)
gas	ObjectRef	No	None	Gas coin

build_withdraw_stake

Withdraw staked SOMA.

async def build_withdraw_stake(
    sender: str, staked_soma: ObjectRef,
    gas: Optional[ObjectRef] = None,
) -> bytes

Parameter	Type	Required	Default	Description
sender	str	Yes	—	Sender address
staked_soma	ObjectRef	Yes	—	StakedSoma object
gas	ObjectRef	No	None	Gas coin

build_add_stake_to_model

Stake SOMA with a model.

async def build_add_stake_to_model(
    sender: str, model_id: str, coin: ObjectRef,
    amount: Optional[int] = None, gas: Optional[ObjectRef] = None,
) -> bytes

Parameter	Type	Required	Default	Description
sender	str	Yes	—	Sender address
model_id	str	Yes	—	Model object ID
coin	ObjectRef	Yes	—	Coin to stake
amount	int	No	None	Amount in shannons
gas	ObjectRef	No	None	Gas coin

Model Builders

build_commit_model

Build a commit-model transaction (phase 1 of commit-reveal).

async def build_commit_model(
    sender: str, model_id: str, weights_url_commitment: str,
    weights_commitment: str, stake_amount: int, commission_rate: int,
    staking_pool_id: str, gas: Optional[ObjectRef] = None,
) -> bytes

Parameter	Type	Required	Default	Description
sender	str	Yes	—	Sender address
model_id	str	Yes	—	Pre-assigned model ID
weights_url_commitment	str	Yes	—	Hash of the encrypted weights URL
weights_commitment	str	Yes	—	Hash of the decrypted weights
stake_amount	int	Yes	—	Stake in shannons
commission_rate	int	Yes	—	Basis points (100 = 1%)
staking_pool_id	str	Yes	—	Staking pool object ID
gas	ObjectRef	No	None	Gas coin

build_reveal_model

Build a reveal-model transaction (phase 2 of commit-reveal).

async def build_reveal_model(
    sender: str, model_id: str, weights_url: str, weights_checksum: str,
    weights_size: int, decryption_key: str, embedding: list[float],
    gas: Optional[ObjectRef] = None,
) -> bytes

Parameter	Type	Required	Default	Description
sender	str	Yes	—	Sender address
model_id	str	Yes	—	Model ID from commit phase
weights_url	str	Yes	—	URL of encrypted weights
weights_checksum	str	Yes	—	Hex checksum of weights file
weights_size	int	Yes	—	File size in bytes
decryption_key	str	Yes	—	Hex AES-256 decryption key
embedding	list[float]	Yes	—	Model embedding vector
gas	ObjectRef	No	None	Gas coin

build_commit_model_update

Commit updated weights for an active model.

async def build_commit_model_update(
    sender: str, model_id: str, weights_url_commitment: str,
    weights_commitment: str, gas: Optional[ObjectRef] = None,
) -> bytes

build_reveal_model_update

Reveal updated weights for an active model. Same parameters as build_reveal_model.

async def build_reveal_model_update(
    sender: str, model_id: str, weights_url: str, weights_checksum: str,
    weights_size: int, decryption_key: str, embedding: list[float],
    gas: Optional[ObjectRef] = None,
) -> bytes

build_deactivate_model

Voluntarily deactivate a model. No slash is applied.

async def build_deactivate_model(
    sender: str, model_id: str, gas: Optional[ObjectRef] = None,
) -> bytes

build_set_model_commission_rate

Set a model’s commission rate for the next epoch.

async def build_set_model_commission_rate(
    sender: str, model_id: str, new_rate: int,
    gas: Optional[ObjectRef] = None,
) -> bytes

Parameter	Type	Required	Default	Description
sender	str	Yes	—	Model owner address
model_id	str	Yes	—	Model ID
new_rate	int	Yes	—	New rate in basis points
gas	ObjectRef	No	None	Gas coin

build_report_model

Report a misbehaving model (validators only).

async def build_report_model(
    sender: str, model_id: str, gas: Optional[ObjectRef] = None,
) -> bytes

build_undo_report_model

Undo a previous model report.

async def build_undo_report_model(
    sender: str, model_id: str, gas: Optional[ObjectRef] = None,
) -> bytes

Data Submission Builders

build_submit_data

Build a data submission transaction for a target.

async def build_submit_data(
    sender: str, target_id: str, data_commitment: str, data_url: str,
    data_checksum: str, data_size: int, model_id: str,
    embedding: list[float], distance_score: float, bond_coin: ObjectRef,
    gas: Optional[ObjectRef] = None,
) -> bytes

Parameter	Type	Required	Default	Description
sender	str	Yes	—	Sender address
target_id	str	Yes	—	Target to submit to
data_commitment	str	Yes	—	Hash of raw data
data_url	str	Yes	—	URL where data is hosted
data_checksum	str	Yes	—	Checksum of data file
data_size	int	Yes	—	Data size in bytes
model_id	str	Yes	—	Model used for scoring
embedding	list[float]	Yes	—	Data embedding vector
distance_score	float	Yes	—	Distance to target (must be ≤ threshold)
bond_coin	ObjectRef	Yes	—	Coin for bond payment
gas	ObjectRef	No	None	Gas coin

build_claim_rewards

Claim rewards from a filled target after the challenge window closes.

async def build_claim_rewards(
    sender: str, target_id: str, gas: Optional[ObjectRef] = None,
) -> bytes

build_report_submission

Report a fraudulent submission.

async def build_report_submission(
    sender: str, target_id: str, challenger: Optional[str] = None,
    gas: Optional[ObjectRef] = None,
) -> bytes

build_undo_report_submission

Undo a previous submission report.

async def build_undo_report_submission(
    sender: str, target_id: str, gas: Optional[ObjectRef] = None,
) -> bytes

Challenge Builders

build_initiate_challenge

Initiate a fraud challenge against a filled target’s submission. Requires a bond.

async def build_initiate_challenge(
    sender: str, target_id: str, bond_coin: ObjectRef,
    gas: Optional[ObjectRef] = None,
) -> bytes

Parameter	Type	Required	Default	Description
sender	str	Yes	—	Challenger address
target_id	str	Yes	—	Target ID to challenge
bond_coin	ObjectRef	Yes	—	Coin for challenger bond
gas	ObjectRef	No	None	Gas coin

build_report_challenge

Report a challenge (validators only).

async def build_report_challenge(
    sender: str, challenge_id: str, gas: Optional[ObjectRef] = None,
) -> bytes

build_undo_report_challenge

Undo a challenge report.

async def build_undo_report_challenge(
    sender: str, challenge_id: str, gas: Optional[ObjectRef] = None,
) -> bytes

build_claim_challenge_bond

Claim the bond from a resolved challenge.

async def build_claim_challenge_bond(
    sender: str, challenge_id: str, gas: Optional[ObjectRef] = None,
) -> bytes

Validator Builders

build_add_validator

Register a new validator.

async def build_add_validator(
    sender: str, pubkey_bytes: bytes, network_pubkey_bytes: bytes,
    worker_pubkey_bytes: bytes, proof_of_possession: bytes,
    net_address: bytes, p2p_address: bytes, primary_address: bytes,
    proxy_address: bytes, gas: Optional[ObjectRef] = None,
) -> bytes

Parameter	Type	Required	Default	Description
sender	str	Yes	—	Validator account address
pubkey_bytes	bytes	Yes	—	Protocol public key
network_pubkey_bytes	bytes	Yes	—	Network public key
worker_pubkey_bytes	bytes	Yes	—	Worker public key
proof_of_possession	bytes	Yes	—	Proof of possession
net_address	bytes	Yes	—	BCS-encoded network address
p2p_address	bytes	Yes	—	BCS-encoded P2P address
primary_address	bytes	Yes	—	BCS-encoded primary address
proxy_address	bytes	Yes	—	BCS-encoded proxy address
gas	ObjectRef	No	None	Gas coin

build_remove_validator

Remove a validator from the committee.

async def build_remove_validator(
    sender: str, pubkey_bytes: bytes, gas: Optional[ObjectRef] = None,
) -> bytes

build_update_validator_metadata

Update validator metadata (takes effect next epoch).

async def build_update_validator_metadata(
    sender: str, gas: Optional[ObjectRef] = None,
    next_epoch_network_address: Optional[bytes] = None,
    next_epoch_p2p_address: Optional[bytes] = None,
    next_epoch_primary_address: Optional[bytes] = None,
    next_epoch_proxy_address: Optional[bytes] = None,
    next_epoch_protocol_pubkey: Optional[bytes] = None,
    next_epoch_worker_pubkey: Optional[bytes] = None,
    next_epoch_network_pubkey: Optional[bytes] = None,
    next_epoch_proof_of_possession: Optional[bytes] = None,
) -> bytes

build_set_commission_rate

Set the validator commission rate for the next epoch.

async def build_set_commission_rate(
    sender: str, new_rate: int, gas: Optional[ObjectRef] = None,
) -> bytes

build_report_validator

Report a misbehaving validator.

async def build_report_validator(
    sender: str, reportee: str, gas: Optional[ObjectRef] = None,
) -> bytes

build_undo_report_validator

Undo a previous validator report.

async def build_undo_report_validator(
    sender: str, reportee: str, gas: Optional[ObjectRef] = None,
) -> bytes