Build Your Own SDK
This is for building an SDK for writing smart contracts.
Soroban currently has one SDF-maintained SDK for writing contracts in Rust, which can be found here. A community-maintained SDK is available for writing contracts in AssemblyScript, 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.
Functionality
Value Conversions
Host Functions
The host functions defined in env.json 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, unions, or enums, 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 Val.
Structs
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>.
Structs with unnamed fields should be translated into a Vec with the values as the elements. i.e. Vec<V>.
Unions
Unions (or enums in some languages) with named variants and unit or tuple values should be translated into a Vec with the first element as a Symbol of the name of the variant, and zero or more additional elements representing a value stored with the variant.
Enums
Enums with integer values should be translated into a u32.
User Defined Errors
Errors are u32 values that are translated into a Error.
Environment 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.
Contract Meta Generation
Contracts may optionally contain a Wasm custom section with name contractmetav0 and containing a serialized SCMetaEntry. Contracts may store any metadata in the entries that can be used by applications and tooling off-network.
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.