Skip to main content

Build Your Own SDK

Soroban currently has one SDK for writing contracts in Rust, which can be found here.

To build SDKs for other languages a few things need to be included in the SDK to provide contracts with the foundation they need to accept inputs, decode them, store data, call other contracts, etc.

Below is a list of functionality a Soroban SDK needs to support those things, as well as some details on what an SDK can provide in regards to testing capabilities.

caution

The Soroban environment is under active development and no API compatibility guarantee exists at this time.

Functionality

Value Conversions

Host Functions

The host functions defined in env.rs are functions callable from within the WASM Guest environment. These need to be available to contracts to call, in some form, ideally wrapped so that contracts have a nicer interface.

Host functions have friendly names in the file above, such as get_ledger_version, however in the WASM they are only importable via short names, such as x.4. The letter proceeding the dot is the module, and the value after the dot is the function name. The mappins are available in env.rs.

SDK Types

All the types in soroban-sdk should be supported. Notably:

User Defined Types

Contracts should be able to create user defined types, such as structs or unions, and have them be transmitted to the host for storing and transmitted back for loading.

SDKs do this by converting objects to and from a Val. In the soroban-sdk this is referred to as a RawVal.

Structs with named fields should be translated into a Map with keys as Symbols and the values as the field value, i.e. Map<Symbol, V>.

Unions (or enums in some languages) with named variants should be translated into a Vec with the first element as a Symbol of the name of the variant, and zero or one additional elements representing a value stored with the variant.

Meta Generation

Contracts must contain a WASM custom section with name contractenvmetav0 and containing a serialized SCEnvMetaEntry. The interface version stored within should match the version of the host functions supported.

Contract Spec Generation

Contracts should contain a WASM custom section with name contractspecv0 and containing a serialized stream of SCSpecEntry. There should be a SCSpecEntry for every function, struct, and union exported by the contract.

Testing

Any Soroban SDK ideally provides a test environment for executing contract functions in the context of a Soroban runtime environment. The soroban-sdk does this by embedding the Soroban environment Rust library, soroban-env-host.

The test environment should include:

  • Invoking contract functions.
  • Integration testing across multiple contracts.