Define and generate errors in a smart contract.

The errors example demonstrates how to define and generate errors in a contract that invokers of the contract can understand and handle. This example is an extension of the storing data example.

Run the Example

First go through the Setup process to get your development environment configured, then clone the v23.0.0 tag of soroban-examples repository:

git clone -b v23.0.0 https://github.com/stellar/soroban-examples

Or, skip the development environment setup and open this example in GitHub Codespaces or Code Anywhere. To run the tests for the example, navigate to the errors directory, and use cargo test.

cd errors
cargo test

You should see output that begins like this:

running 2 tests
test test::test ... ok
test test::test_panic - should panic ... ok

[Diagnostic Event] contract:CAAA..., topics:[log], data:["count: {}", 0]
[Diagnostic Event] contract:CAAA..., topics:[log], data:["count: {}", 1]
[Diagnostic Event] contract:CAAA..., topics:[log], data:["count: {}", 2]
[Diagnostic Event] contract:CAAA..., topics:[log], data:["count: {}", 3]
[Diagnostic Event] contract:CAAA..., topics:[log], data:["count: {}", 4]
[Diagnostic Event] contract:CAAA..., topics:[log], data:["count: {}", 5]
[Failed Diagnostic Event (not emitted)] contract:CAAA..., topics:[log], data:["count: {}", 5]

thread 'test::test_panic' panicked at .../src/host.rs: HostError: Error(Contract, #1)

Event log (newest first):
   0: [Diagnostic Event] topics:[error, Error(Contract, #1)], data:"escalating error to panic"
   1: [Diagnostic Event] topics:[error, Error(Contract, #1)], data:["contract call failed", increment, []]
   2: [Failed Diagnostic Event (not emitted)] contract:CAAA..., topics:[error, Error(Contract, #1)], data:"escalating Ok(ScErrorType::Contract) frame-exit to Err"
   3: [Failed Diagnostic Event (not emitted)] contract:CAAA..., topics:[fn_return, increment], data:Error(Contract, #1)
   4: [Failed Diagnostic Event (not emitted)] contract:CAAA..., topics:[log], data:["count: {}", 5]
   5: [Diagnostic Event] topics:[fn_call, CAAA..., increment], data:Void
...

successes:
    test::test
    test::test_panic

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.16s

Code

errors/src/lib.rs

#[contracterror]
#[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
#[repr(u32)]
pub enum Error {
    LimitReached = 1,
}

const COUNTER: Symbol = symbol_short!("COUNTER");
const MAX: u32 = 5;

#[contract]
pub struct IncrementContract;

#[contractimpl]
impl IncrementContract {
    /// Increment increments an internal counter, and returns the value. Errors
    /// if the value is attempted to be incremented past 5.
    pub fn increment(env: Env) -> Result<u32, Error> {
        // Get the current count.
        let mut count: u32 = env.storage().instance().get(&COUNTER).unwrap_or(0); // If no value set, assume 0.
        log!(&env, "count: {}", count);

        // Increment the count.
        count += 1;

        // Check if the count exceeds the max.
        if count <= MAX {
            // Save the count.
            env.storage().instance().set(&COUNTER, &count);

            // Return the count to the caller.
            Ok(count)
        } else {
            // Return an error if the max is exceeded.
            Err(Error::LimitReached)
        }
    }
}

Ref: https://github.com/stellar/soroban-examples/tree/v23.0.0/errors

How it Works

Open the errors/src/lib.rs file to follow along.

Defining an Error

Contract errors are Rust u32 enums where every variant of the enum is assigned an integer. The #[contracterror] attribute is used to set the error up so it can be used in the return value of contract functions. The enum has some constraints:

It must have the #[repr(u32)] attribute.
It must have the #[derive(Copy)] attribute.
Every variant must have an explicit integer value assigned.

#[contracterror]
#[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
#[repr(u32)]
pub enum Error {
    LimitReached = 1,
}

Contract errors cannot be stored as contract data, and therefore cannot be used as types on fields of contract types.

If an error is returned from a function anything the function has done is rolled back. If ledger entries have been altered, or contract data stored, all those changes are reverted and will not be persisted.

Returning an Error

Errors can be returned from contract functions by returning Result<_, E>. The increment function returns a Result<u32, Error>, which means it returns Ok(u32) in the successful case, and Err(Error) in the error case.

pub fn increment(env: Env) -> Result<u32, Error> {
    // ...
    if count <= MAX {
        // ...
        Ok(count)
    } else {
        // ...
        Err(Error::LimitReached)
    }
}

Panicking with an Error

Errors can also be panicked instead of being returned from the function. The increment function could also be written as follows with a u32 return value. The error can be passed to the environment using the panic_with_error! macro.

pub fn increment(env: Env) -> u32 {
    // ...
    if count <= MAX {
        // ...
        count
    } else {
        // ...
        panic_with_error!(&env, Error::LimitReached)
    }
}

Functions that do not return a Result<_, E> type do not include in their specification what the possible error values are. This makes it more difficult for other contracts and clients to integrate with the contract. However, this might be ideal if the errors are diagnostic and debugging, and not intended to be handled.

Tests

Open the errors/src/test.rs file to follow along.

errors/src/test.rs

#[test]
fn test() {
    let env = Env::default();
    let contract_id = env.register(IncrementContract, ());
    let client = IncrementContractClient::new(&env, &contract_id);

    assert_eq!(client.try_increment(), Ok(Ok(1)));
    assert_eq!(client.try_increment(), Ok(Ok(2)));
    assert_eq!(client.try_increment(), Ok(Ok(3)));
    assert_eq!(client.try_increment(), Ok(Ok(4)));
    assert_eq!(client.try_increment(), Ok(Ok(5)));
    assert_eq!(client.try_increment(), Err(Ok(Error::LimitReached)));

    std::println!("{}", env.logs().all().join("\n"));
}

#[test]
#[should_panic(expected = "HostError: Error(Contract, #1)")]
fn test_panic() {
    let env = Env::default();
    let contract_id = env.register(IncrementContract, ());
    let client = IncrementContractClient::new(&env, &contract_id);

    assert_eq!(client.increment(), 1);
    assert_eq!(client.increment(), 2);
    assert_eq!(client.increment(), 3);
    assert_eq!(client.increment(), 4);
    assert_eq!(client.increment(), 5);
    client.increment();
}

In any test the first thing that is always required is an Env, which is the Soroban environment that the contract will run in.

let env = Env::default();

The contract is registered with the environment using the contract type.

let contract_id = env.register(IncrementContract, ());

All public functions within an impl block that is annotated with the #[contractimpl] attribute have a corresponding function generated in a generated client type. The client type will be named the same as the contract type with Client appended. For example, in our contract the contract type is IncrementContract, and the client is named IncrementContractClient.

let client = IncrementContractClient::new(&env, &contract_id);

Two functions are generated for every contract function, one that returns a Result<>, and the other that does not handle errors and panics if an error occurs.

`try_increment`

In the first test the try_increment function is called and returns Result<Result<u32, _>, Result<Error, InvokeError>>.

assert_eq!(client.try_increment(), Ok(Ok(5)));
assert_eq!(client.try_increment(), Err(Ok(Error::LimitReached)));

If the function call is successful, Ok(Ok(u32)) is returned.
If the function call is successful but returns a value that is not a u32, Ok(Err(_)) is returned.
If the function call is unsuccessful and fails with an error in the Error enum, Err(Ok(Error)) is returned.
If the function call is unsuccessful but returns an error code not in the Error enum, or returns a system error code, Err(Err(InvokeError)) is returned and the InvokeError can be inspected.

`increment`

In the second test the increment function is called and returns u32. When the last call is made the function panics.

assert_eq!(client.increment(), 5);
client.increment();

If the function call is successful, u32 is returned.
If the function call is successful but returns a value that is not a u32, a panic occurs.
If the function call is unsuccessful, a panic occurs.

Build the Contract

To build the contract, use the stellar contract build command.

stellar contract build

A .wasm file should be outputted in the target directory:

target/wasm32v1-none/release/soroban_errors_contract.wasm

Run the Contract

Let’s deploy the contract to Testnet so we can run it. The value provided as --source-account was set up in our Getting Started guide; please change accordingly if you created a different identity.

macOS/Linux
Windows (PowerShell)

stellar contract deploy \
  --wasm target/wasm32v1-none/release/soroban_errors_contract.wasm \
  --source-account alice \
  --network testnet

stellar contract deploy `
  --wasm target/wasm32v1-none/release/soroban_errors_contract.wasm `
  --source-account alice `
  --network testnet

The command above will output the contract id, which in our case is CA4KWO3HL6M5F5MZ5ITVFLCQ6ZM2GDSP2NOTNXOT4GIRECQOVX3I6CXL. Now that we’ve deployed the contract, we can invoke it.

macOS/Linux
Windows (PowerShell)

stellar contract invoke \
    --id CA4KWO3HL6M5F5MZ5ITVFLCQ6ZM2GDSP2NOTNXOT4GIRECQOVX3I6CXL \
    --network testnet \
    --source-account alice \
    -- \
    increment

stellar contract invoke `
    --id CA4KWO3HL6M5F5MZ5ITVFLCQ6ZM2GDSP2NOTNXOT4GIRECQOVX3I6CXL `
    --network testnet `
    --source-account alice `
    -- `
    increment

Run the command a few times and on the 6th invocation you should see an error like this:

❌ error: transaction simulation failed: HostError: Error(Contract, #1)

Event log (newest first):
   0: [Diagnostic Event] contract:CA4KWO3HL6M5F5MZ5ITVFLCQ6ZM2GDSP2NOTNXOT4GIRECQOVX3I6CXL, topics:[error, Error(Contract, #1)], data:"escalating Ok(ScErrorType::Contract) frame-exit to Err"
   1: [Diagnostic Event] topics:[fn_call, CA4KWO3HL6M5F5MZ5ITVFLCQ6ZM2GDSP2NOTNXOT4GIRECQOVX3I6CXL, increment], data:Void

To retrieve the current counter value, use the command stellar contract read.

macOS/Linux
Windows (PowerShell)

stellar contract read \
  --id CA4KWO3HL6M5F5MZ5ITVFLCQ6ZM2GDSP2NOTNXOT4GIRECQOVX3I6CXL \
  --network testnet \
  --source-account alice \
  --durability persistent \
  --output json

stellar contract read `
  --id CA4KWO3HL6M5F5MZ5ITVFLCQ6ZM2GDSP2NOTNXOT4GIRECQOVX3I6CXL `
  --network testnet `
  --source-account alice `
  --durability persistent `
  --output json

​Run the Example

​Code

​How it Works

​Defining an Error

​Returning an Error

​Panicking with an Error

​Tests

​try_increment

​increment

​Build the Contract

​Run the Contract

Run the Example

Code

How it Works

Defining an Error

Returning an Error

Panicking with an Error

Tests

`try_increment`

`increment`

Build the Contract

Run the Contract