Defining Contract Error using Soroban Assembly Script SDK

Hi! in my previous post, i already illustrates how to use the Soroban AssemblyScript SDK to store and retrieve data in a simple smart contract, and now we will add error handler in that contract using Soroban Assembly Script SDK.

We will explore how to define and generate error for Soroban smart contract using AssemblyScript SDK, that allows contract caller to understand and handle the error. This example will showcase failWithErrorCode() function from context module provided by the as-soroban-sdk library.

The Contract Code

The contract code will be similar to my previous post with additional code to do error handling. Let's dive into the code:

import { RawVal, toU32, fromU32 } from "as-soroban-sdk/lib/value";
import * as ledger from "as-soroban-sdk/lib/ledger";
import * as context from "as-soroban-sdk/lib/context";

In this section, an additional modules added context module. These modules will give us functionality to define and handle error.

enum ERR_CODES {
  MAX_REACHED = 1
};

export function increment(): RawVal {

  let data = "COUNTER";
  var counter = 0;
  var max = 5;

  if (ledger.hasDataFor(data)) {
    let dataObj = ledger.getDataFor(data);
    counter = toU32(dataObj);
  }

  counter ++;

  if(counter > max) {
    context.failWithErrorCode(ERR_CODES.MAX_REACHED);
  }
  ledger.putDataFor(data, fromU32(counter));
  return ledger.getDataFor(data);
}

The code defines an ERR_CODES enum to represent possible error codes. It has a single error code: MAX_REACHED, indicating the counter has reached its maximum allowed value, and max variable is the maximum allowed value. increment function work similarly like the previous contract, check counter data in storage, increment it, and it checks if the new count is greater than the maximum allowed (set to 5). If so, it fails the transaction and returns an error code using the context.failWithErrorCode function. Otherwise, it updates the COUNTER data in the ledger with the new count value converted back to a RawVal with fromU32. It returns the final count value from the ledger.

Next, create contract.json file in your project directory, this file contains metadata for the contract.

{
    "name": "Store and Retrieve Data Contract (Error Handling)",
    "version": "0.1.0",
    "description": "example",
    "host_functions_version": 29,
    "functions": [
        {
            "name" : "increment",
            "arguments": [],
            "returns" : "u32"
        }
    ]
}

Before compiling the contract, we need to edit the asconfig.json file of your project. Replace its content with the following:

{
  "extends": "as-soroban-sdk/sdkasconfig",
  "targets": {
    "release": {
      "outFile": "build/release.wasm",
      "textFile": "build/release.wat"
    },
    "debug": {
      "outFile": "build/debug.wasm",
      "textFile": "build/debug.wat"
    }
  }
}

The asconfig.json file is used by the AssemblyScript compiler (asc) to define the configuration for your project.

Compiling the Contract

You need to compile it into WebAssembly first. To do this, you'll use the following command :

npx asc assembly/index.ts --target release

Now you should see two new files in the build/ directory: release.wasm and release.wat.

Running The Contract on Sandbox

Let's run the contract to see if it's works, we're gonna run the contract using soroban-cli on sandbox using the following command :

soroban contract invoke --wasm build/release.wasm --id 1 --fn increment

You should get the output:

1

Run it a couple of times, and in 6th run you will get this output:

error: HostError
Value: Status(ContractError(1))

Closing

This example demonstrates how to define and handle error on soroban smart contract using the Soroban AssemblyScript SDK. By knowing the exact error code, contract caller will know what's wrong with the contract or the invocation. With this foundation, you can move on to build more advanced and feature-rich smart contracts on the Soroban platform. Happy Sorobaning!