Skip to main content

Invoking Contracts with Stellar Transactions

Stellar supports invoking and deploying contracts with a new Operation named InvokeHostFunctionOp. The soroban-cli abstracts these details away from the user, but SDKs do not yet and if you're building a dapp you'll probably find yourself building the XDR transaction to submit to the network.

The InvokeHostFunctionOp can be used to invoke host functions. Host functions are built-in to Soroban and give the invoker access to:

  • Invoking contract functions.
  • Deploying new contracts.
  • Deploying token contracts for Stellar Assets.

InvokeHostFunctionOp

The XDR of HostFunction and InvokeHostFunctionOp below can be found here

enum HostFunction
{
HOST_FN_INVOKE_CONTRACT = 0,
HOST_FN_CREATE_CONTRACT_WITH_ED25519 = 1,
HOST_FN_CREATE_CONTRACT_WITH_SOURCE_ACCOUNT = 2,
HOST_FN_CREATE_TOKEN_CONTRACT_WITH_SOURCE_ACCOUNT = 3,
HOST_FN_CREATE_TOKEN_CONTRACT_WITH_ASSET = 4
};

struct InvokeHostFunctionOp
{
// The host function to invoke
HostFunction function;

// Parameters to the host function
SCVec parameters;

// The footprint for this invocation
LedgerFootprint footprint;
};

Function

The parameters in InvokeHostFunctionOp will be forwarded to the HostFunction specifed in function. The options are -

  1. HOST_FN_INVOKE_CONTRACT
    • This will call the call_n host function, invoking a contract function.
    • parameters is expected to contain the contract id, contract function name, and the parameters to the contract function being invoked.
  2. HOST_FN_CREATE_CONTRACT_WITH_ED25519
    • This is disabled for now. Calling it will result in an error.
  3. HOST_FN_CREATE_CONTRACT_WITH_SOURCE_ACCOUNT
    • This will call the create_contract_from_source_account host function, creating a contract using the stellar source account that submitted the transaction. The contract id will be the SHA256 hash of this HashIDPreimage.
    • parameters is expected to contain two elements: the WASM contract code and a salt.
  4. HOST_FN_CREATE_TOKEN_CONTRACT_WITH_SOURCE_ACCOUNT
    • This will call the create_token_from_source_account host function, creating a built-in token contract using the stellar source account that submitted the transaction. The contract id will be the SHA256 hash of this HashIDPreimage.
    • parameters is expected to contain a salt.
  5. HOST_FN_CREATE_TOKEN_CONTRACT_WITH_ASSET
    • This will call the create_token_from_asset host function, creating a built-in token contract that wraps a classic Stellar asset. The contract id will be the SHA256 hash of this HashIDPreimage. create_token_from_asset will also initialize the token contract, so the user is not expected to call any intialize functions.
    • parameters is expected to contain a xdr Asset.

Parameters

This SCVec contains the parameters that will be passed to the host function that is being invoked.

Footprint

The footprint must contain the LedgerKeys that will be read and/or written. More information about the footprint can be found in the advanced section of interacting with contracts.