Skip to main content

Introduction

Soroban is the smart contracts platform on the Stellar network. Contracts are small programs written in the Rust programming language and compiled as WebAssembly (Wasm) for deployment.

To begin writing contracts, install a Rust toolchain, configure your editor to support Rust programs, and learn some basic Rust concepts.

Rust on Soroban​

Soroban has several characteristics (such as resource limits, security considerations, and more) that force contracts to use only a narrow subset of the full Rust language and must use specialized libraries for most tasks. Read more in the Contract Rust Dialect section.

In particular, the Rust standard library and most third-party libraries (called “crates”) will not be available for direct off-the-shelf use in contracts due to the abovementioned constraints. Some crates can be adapted for use in contracts, and others may be incorporated into the host environment as host objects or functions.

Support for other languages may be supported in the future, but at this time, only Rust is supported.

Soroban SDK​

Contracts are developed using a software development kit (SDK). The Soroban SDK consists of 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.

The Soroban SDK command-line tool provides a developer-focused front-end for compiling, testing, inspecting, versioning, and deploying contracts. It also includes a complete implementation of the contract host environment that is identical to the one that runs on-chain, called local testing mode. With this capability, 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 compiled into the SDK command-line tool and stellar-core. 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 to understand the conceptual model the SDK is presenting. Some parts of the host environment will likely be visible when testing or debugging contracts compiled natively on a local workstation.

Read more in the Environment Concepts section.

Soroban FAQs​

What is Soroban to Stellar? Is it a new blockchain?​

Soroban is not a new blockchain. Soroban is a smart contract platform integrated into the existing Stellar blockchain. It is an additive feature that lives alongside and doesn't replace the existing set of Stellar operations.

How do I invoke a Soroban contract on Stellar?​

Invoke a Soroban contract by submitting a transaction that contains the new operation: InvokeHostFunctionOp.

Can Soroban contracts use Stellar accounts for authentication?​

Yes. Stellar accounts are shared with Soroban. Smart contacts have access to Stellar account signer configuration and know the source account that directly invoked them in a transaction. Check out the Authorization section for more information.

Can Soroban contracts interact with Stellar assets?​

Yes. Soroban contains a built-in Stellar Asset Contract that can interact with classic trustlines.

Do issuers of Stellar assets maintain authorization over an asset sent to a non-account identifier in Soroban (AUTH_REQUIRED, AUTH_REVOCABLE, AUTH_CLAWBACK)​?

Yes. Issuers retain the same level of control on Soroban as they have regularly. This functionality is accessible through a set of admin functions (clawback, set_auth) on the built-in Stellar Asset Contract.

Can Soroban contracts interact with any other Stellar operations?​

No. Aside from the interactions with accounts and assets mentioned above. This means that Soroban contracts cannot interact with the SDEX, claimable balances, or sponsorships.

Does the Stellar base reserve apply to Soroban contracts?​

No. Soroban has a different fee structure, and ledger entries that are allocated by Soroban contracts do not add to an account's required minimal balance.

Should I issue my token as a Stellar asset or a custom Soroban token?​

To the greatest extent possible, we recommend issuing tokens as Stellar assets. These tokens will benefit from being interoperable with the existing tools available in the Stellar ecosystem and are more performant because the Stellar Asset Contract is built into the host.

Need help finding what you're looking for?​

Join #soroban on the Stellar Developer Discord.