Submit Stellar smart contract transactions

12 min

Introduction

The Custody Infrastructure system provides a secure way to submit Stellar smart contracts transactions through the API client.

This is an API process. Be sure you are comfortable making API calls and interpreting the responses. See Getting Started with the API for details.

Summary

The Custody Infrastructure API can be used to send a Stellar smart contract transaction to the Stellar network. The process requires creating a Soroban Authorization entry, checking the suggested gas limit for the transaction, then simulating the transaction and finally submitting the transaction to the Steller network.

All of these stages are available directly from the Custody Infrastructure API.

The Stellar smart contract submittion procedure

Build the Soroban Authorization Entry for a contract call

Check the suggested gas limit

Simulate the transaction

Submit the smart contract transaction

Endpoint deep dive *

*Endpoint deep dive - Expanded

getSorobanAuthorizationEntrySignedByMpc

getGasLimitSuggestedForTransactionToStellarContractWithContractInfo

callReadFunctionForStellarSmartContract

sendTransactionToStellarContractWithContractInfo

The Stellar smart contract submittion procedure

Build the Soroban Authorization Entry for a contract call

Call the getSorobanAuthorizationEntrySignedByMpcgetSorobanAuthorizationEntrySignedByMpc function to initialize the smart contract call.

Add the parameters for the call including the specific function name and its parameters. The authorization entry is returned.

            getSorobanAuthorizationEntrySignedByMpc(
                account_id=42,
                contract_address="CCOZ5XDWPXVYLIUCLK2YKW5RXPOWINDB2FIQBM5JUXAWLMQW5RRMELNF",
                max_fee=4000000,
                function_name="execute",
                parameters_fields_types_and_values=[
                    ["address", "GBCT2KLG4F4Y7A53KITD4WAM4QW5P5BPBQAFPTUEQWXIROVQU3TNEICW"]
                ],
                structs=None,
                specificFromAddress="GBCT2KLG4F4Y7A53KITD4WAM4QW5P5BPBQAFPTUEQWXIROVQU3TNEICW"
            )

Check the suggested gas limit

Use the getGasLimitSuggestedForTransactionToStellarContractWithContractInfo function to get the suggested 'compute limit' (the Soroban equivalent to gas limit) which is based on a simulation of the function call.

 getGasLimitSuggestedForTransactionToStellarContractWithContractInfo(
                account_id=42,
                contract_address="CCOZ5XDWPXVYLIUCLK2YKW5RXPOWINDB2FIQBM5JUXAWLMQW5RRMELNF",
                function_name="execute",
                parameters_fields_types_and_values=[
                    ["address","GBCT2KLG4F4Y7A53KITD4WAM4QW5P5BPBQAFPTUEQWXIROVQU3TNEICW"]
                ],
                specificFromAddress="GBCT2KLG4F4Y7A53KITD4WAM4QW5P5BPBQAFPTUEQWXIROVQU3TNEICW",
                multiplier=2
            )

This function does not submit the transaction, but rather simulates the transaction to estimate the compute value. Use the returned value as the compute limit when building your final transaction. The estimate reflects the function body and any sub-invocations it triggers.

If your call requires require_auth, pair this with an authorization entry obtained from getSorobanAuthorizationEntrySignedByMpc when you later build or submit the transaction.

Simulate the transaction

Before submitting the transaction to the blockchain, use callReadFunctionForStellarSmartContract to simulate the smart contract function call that performs a dry run. This allows you to test the contract interactions and retrieve return values without executing an actual transaction or spending gas.

This is useful for testing contract state changes and validating parameters before sending actual transactions.

            callReadFunctionForStellarSmartContract(
                contract_address="CCOZ5XDWPXVYLIUCLK2YKW5RXPOWINDB2FIQBM5JUXAWLMQW5RRMELNF",
                function_name="decimals",
                parameters_fields_types_and_values=[["address", "GBCT2KLG4F4Y7A53KITD4WAM4QW5P5BPBQAFPTUEQWXIROVQU3TNEICW"]],
                structs=None
            )

Submit the smart contract transaction

Finally, once the transaction has been checked, use sendTransactionToStellarContractWithContractInfo to fully build, sign and submit the transaction to the Stellar network. This includes the MPC signing the transaction as part of the Custody Infrastructure transaction process.

 sendTransactionToStellarContractWithContractInfo(
                account_id=42,
                contract_address="CCOZ5XDWPXVYLIUCLK2YKW5RXPOWINDB2FIQBM5JUXAWLMQW5RRMELNF",
                max_fee=4000000,
                function_name="execute",
                parameters_fields_types_and_values=[
                    ["address","GBCT2KLG4F4Y7A53KITD4WAM4QW5P5BPBQAFPTUEQWXIROVQU3TNEICW"],
                    ["u32","3"]
                ],
                authorization_entry_xdrs=[
                    "AAAAAAAAAAAAAAABtEB4spfq7O6TROKjVeMq3czkdXbv2bS+ofmsxduN3CQAAAAHZXhl..."
                ],
                validate_transaction=True,
                description="MPC wallet delegated execute call",
                specificFromAddress="GBCT2KLG4F4Y7A53KITD4WAM4QW5P5BPBQAFPTUEQWXIROVQU3TNEICW"
            )

The deployment will be submitted as a transaction for approval according to your configured policies.

Endpoint Deep Dive

getSorobanAuthorizationEntrySignedByMpc

Build and MPC-sign the Soroban Authorization Entry for a contract call. This endpoint prepares the Soroban authorization for `require_auth` paths, including any nested sub-invocations discovered during simulation. It returns both the a base64 XDR blob(s) and a human-readable JSON rendering of the authorization tree.

GET

getSorobanAuthorizationEntrySignedByMpc( account_id: int, contract_address: str, max_fee: int, function_name: str, parameters_fields_types_and_values: list, structs: Optional[dict] = None, specificFromAddress: Optional[str] = None):

For more information about this endpoint, see getSorobanAuthorizationEntrySignedByMpc.

getGasLimitSuggestedForTransactionToStellarContractWithContractInfo

Returns a suggested **compute limit** (“gas” analogue for Soroban) for invoking a Soroban contract function, based on simulation of the provided call.

GET

getGasLimitSuggestedForTransactionToStellarContractWithContractInfo (account_id: int, contract_address: str, function_name: str, parameters_fields_types_and_values: list, specificFromAddress: Optional[str] = None, multiplier: Optional[int] = None):

For more information about this endpoint, see getGasLimitSuggestedForTransactionToStellarContractWithContractInfo.

callReadFunctionForStellarSmartContract

Evaluates a smart contract function call by performing a dry run using eth_call. This allows you to test contract interactions and retrieve return values without executing an actual transaction or spending gas. Useful for testing contract state changes and validating parameters before sending actual transactions.

GET

callReadFunctionForStellarSmartContract( contract_address: str, function_name: str, parameters_fields_types_and_values: list, structs: Optional[dict] = None):

For more information about this endpoint, see callReadFunctionForStellarSmartContract.

sendTransactionToStellarContractWithContractInfo

Build, sign, and send a Soroban smart-contract invocation through the MPC system. This endpoint creates a full `InvokeHostFunction` transaction targeting the given Soroban contract (C-address) and submits it to the Stellar network.

GET

sendTransactionToStellarContractWithContractInfo( account_id: int, contract_address: str, max_fee: int, function_name: str, parameters_fields_types_and_values: list, authorization_entry_xdr: Optional[str], structs: Optional[dict[str, str]] = None, validate_transaction: bool = True, description: str = "", specificFromAddress: Optional[str] = None):

For more information about this endpoint, see sendTransactionToStellarContractWithContractInfo