Skip to main content

High level overview

Rust language

Contracts are small programs written in the Rust programming language. In order to write contracts, install a Rust toolchain, configure your editor to support Rust programs, and learn at least some basic Rust concepts.

Contracts can be compiled to native code for local (off-chain) testing, but must be compiled as WebAssembly ("WASM") for deployment. The on-chain host environment only allows uploading WASM contracts, and runs them within a WASM "sandbox" virtual machine ("VM").

In practice several special characteristics of the contract execution environment -- resource constraints, security considerations, nonstandard IO and invocation primitives, the requirement for strict determinism -- will mean that contracts can only use a very narrow subset of the full Rust language, and must use specialized libraries for most tasks. See the rust dialect section for details.

In particular both the Rust standard library and most 3rd party libraries ("crates" in Rust parlance) will not be available for direct off-the-shelf use in contracts, due to the constraints listed above. Some crates will be possible to adapt to use in contracts, others may be incorporated into the host environment as host objects or functions.

In the future it is possible that other source languages may be supported. The execution environment is somewhat language-agnostic, and some very early experiments suggest that other languages may be possible. However, at this time only Rust is supported.

SDK

Contracts are developed with the help of a Software Development Kit or SDK. The SDK consists of both a Rust crate and a command-line tool.

The SDK crate acts as a substitute for the Rust standard library -- providing data structures and utility functions for contracts -- as well as providing access to smart-contract-specific functionality from the contract environment, like cryptographic hashing and signature verification, access to on-chain persistent storage, and location and invocation of secondary contracts via stable identifiers.

Local testing mode

The SDK command-line tool provides a developer-focused front-end for compiling, testing, inspecting, versioning and deploying contracts.

The SDK also includes a complete implementation of the contract host environment -- identical to the one that runs on-chain -- such that contracts can be run locally on a developer's workstation, and can be tested and debugged directly with a local debugger within a standard IDE, as well as a native test harness for fast-feedback unit testing and high-speed fuzzing or property testing.

Host Environment

The host environment is a set of Rust crates that are compiled into both the SDK command-line tool and stellar-core, the transaction processor at the heart of the stellar network. It comprises a set of host objects and functions, an interface to on-chain storage and contract invocation, a resource-accounting and fee-charging system, and a WASM interpreter.

Most contract developers will not frequently need to interact with the host environment directly -- SDK functions wrap most of its facilities and provide richer and more ergonomic types and functions -- but it is helpful to understand its structure in order to understand the conceptual model the SDK is presenting. It is also likely that some parts of the host environment will be visible when testing or debugging contracts compiled natively on a local workstation.