Making cross-contract calls - Stellar Developer Docs

As with developing software in any language, developing a Stellar smart contract with a rich feature set can be a challenging and time-consuming task. Thankfully, someone else might already have solved part of your issues or built components which can be reused. The open source community is vibrant and Stellar’s community does not disappoint. There are two kinds of dependencies that can be introduced in a Stellar smart contract:

Other Rust crates can be used (provided that they are compatible with Soroban’s Rust dialect);
Other smart contract can be used. This is referred to as a cross-contract call.

In the following, we will see how contracts can be leveraged from within another contract.

Contract as a dependency

While finding a contract is out of scope for this guide, there are a few places to be on the lookout. Most projects and dApps publicly disclose the address of their Stellar smart contract on their website. With this information, a block explorer is a powerful tool to understand how a contract is being used. Some explorers also allow you to download the compiled contract as a Wasm file. There are also projects that provide a link to access the code itself.

Contract addressTo depend on a project, we need to know the contract address of the contract to depend on.

Public API

All public functions of a contract can be called. Using a network explorer can be helpful as some allow you to see the Rust interface of a contract. Bindings can also be generated using the CLI:

stellar contract bindings rust --network testnet --contract-id ... --output-dir ...

Making a cross-contract call

Once we know which function to call and which arguments to use, there are two main ways to make a cross-contract call: we can either manually invoke the contract or use a contract client. Let’s start by manually invoking the contract using only a contract’s address. In this example, we have an external contract with a public function named add_with which takes two u32 as input values to sum them.

#[contract]
pub struct ContractB;

#[contractimpl]
impl ContractB {
    pub fn add_with(env: Env, contract: Address, x: u32, y: u32) -> u32 {
        env.invoke_contract(&contract, symbol_short!("add"), vec![&env, x.to_val(), y.to_val()])
    }
}

Only using the contract address comes with its own challenges. We don’t have a contract client so we don’t have any typing inference, and have to manually convert function inputs to Val. If we want more tools to help us, we need to get access to a contract client. A common way to do this is to load the Wasm of a contract using contractimport!. This allows us to pass normal types without needing manual conversions from our side. Behind the scenes, this way of doing it is simply a convenient wrapper around env.invoke_contract.

mod contract_a {
    soroban_sdk::contractimport!(
        file = "soroban_contract_a.wasm"
    );
}

#[contract]
pub struct ContractB;

#[contractimpl]
impl ContractB {
    pub fn add_with(env: Env, contract: Address, x: u32, y: u32) -> u32 {
        let client = contract_a::Client::new(&env, &contract);
        client.add(&x, &y)
    }
}

Although we have access to the Wasm, we still need a contract address because there could be multiple contracts deployed on-chain that use the same underlying code. This can be of importance if, for instance, the function that you need requires access to stored values from other users.

Address and WasmThanks to the Rust bindings of the external contract, we can also use any public enum of the contract as if we would have defined them within our own contract.

client::ContractAEnum::SomeField

Handling responses

In the examples above, we have used env.invoke_contract and client.some_function. In both cases, if there is an issue with the underlying contract call, the contract will panic. This might be a valid approach, but in some cases we want to catch errors and handle them depending on the outcome. This allows you to forward a custom error message, or even trigger an alternative code path. Enter try_. By using env.try_invoke_contract or client.try_some_function, most underlying errors won’t make the contract panic. Instead, errors will be wrapped and can be handled. For example if we wanted to default to 0 in case of an error:

client.try_add(&x, &y).unwrap_or(Ok(0)).unwrap()

Of course, we could have far more complex error handling by leveraging the match statement:

match client.try_add(&x, &y) {
    // the contract returned a value
    Ok(Ok(number)) => todo!("do something with the number returned"),
    Ok(Err(ConversionError)) => todo!("got a value back, but it wasn't a number like we expected"),

    // the contract errored
    Err(Ok(Error::AnError)) => todo!("do something when an error occurs that the contract included in its contract spec"),
    Err(Err(status)) => todo!("do something when an unrecognized error, or system error, occurs"),
}

Some errors cannot be caughttry_ does not catch every error. A resource limit error, a footprint violation, or an internal host error still traps the contract, and the transaction fails. See Recoverable and Non-Recoverable Errors.

Depending on another contract

Congratulations, now you can effectively leverage the whole Soroban ecosystem and its myriad of smart contracts. There is one last point to discuss before closing up: dependability. As with calling any smart contract, depending on an external smart contract should be done with care. It is advisable to do your own research and analysis on the contract you want to use. As contracts can be updated without their address changing, it is important to pay close attention to any changes in the underlying code.

Contract WasmThe Wasm can be fetched by using the Stellar CLI. This can serve as a quick way to (for example) automate a hash check in a continuous integration system. However, such a check would not provide strong on-chain guarantees, but one could build a contract for that!

stellar contract fetch --id C... --network ... > contract.wasm

Besides this security consideration, upgrading a contract is an integral part of a contract’s lifecycle. New features are added, bugs are fixed, and public API changes are made. Here as well, it is important to observe any development on these contracts to ensure the continuous operation of your own contract.

Examples

See the following full example with tests:

Cross-contract calls shows how to create two contracts, deploy them, and then how to call one from the other.

​Contract as a dependency

​Public API

​Making a cross-contract call

​Handling responses

​Depending on another contract

​Examples

Contract as a dependency

Public API

Making a cross-contract call

Handling responses

Depending on another contract

Examples