Contract Lifecycle

Development

Contract development can be done on a local computer with as little as 3 necessary components: an IDE, a copy of the Rust toolchain, and a copy of the Soroban SDK.

The SDK contains a full working copy of the host environment, as well as a "mock" version of the ledger for persistent storage of contract data. It is therefore possible (and encouraged) to edit, compile, test and debug contracts directly against this "local" copy of the host, entirely offline and without even accessing a test network.

To make the local development process even more convenient and fast, the contract being developed can (and should) be compiled as native code and linked directly to the local host, rather than compiled to Wasm and run in a local VM sandbox. Both configurations are possible, but the native configuration is fastest and provides the richest testing and debugging experience.

The SDK-provided local contract host also contains a local web server that serves the necessary HTTP API endpoint used for client applications to interact with a contract. This can be used for local development of applications, again without needing to deploy contracts to any test or live network.

Deployment

Once a contract has been tested and debugged locally, it can be deployed. To do this it must be compiled to Wasm code, and then included by value in a transaction sent to the intended deployment network.

The SDK provides a command-line utility that invokes the Rust compiler with the correct settings for producing a Wasm bundle for deployment, but developers can also build this themselves.

Before submitting to the network, developers should inspect the resulting Wasm binary emitted by the Rust compiler to ensure that it contains only the intended code and data, and is as small as possible. The SDK command-line utility contains diagnostic commands to assist with this process.

The SDK command-line utility can also build and submit the transaction deploying a Wasm contract to the network. Deployment requires sufficient network credentials to sign a transaction performing the deployment and pay its fees. Contracts should be deployed to test networks and thoroughly tested there before being deployed to the live network.

Execution

Deployed contracts live on chain in a CONTRACT_DATA ledger entry. They are executed within a VM sandbox managed by a host environment inside stellar-core. Each transaction that leads to a contract execution is run in a separate host environment, and each contract called by such a transaction (either directly or indirectly from another contract) is executed in a separate guest Wasm VM contained within the transaction’s host environment.

Execution is initiated by a host function called "call". The "call" host function can itself be invoked two different ways: either by someone submitting a transaction to the network that invokes "call" directly, or indirectly by some other contract invoking "call".

In either case, the "call" host function is provided with the ID of a contract to invoke, the name of a function in the contract, and a vector of argument values to pass. The "call" host function then sets up a VM sandbox for the called contract, loads and instantiates its Wasm bytecode, and invokes the named function, passing the provided arguments.

Each contract execution continues until the contract either completes successfully or traps with an error condition. If execution completes successfully, all ledger entries modified during execution will be written back to the ledger atomically. If execution traps, all modified ledger entries will be discarded and the contract will have no effect on the ledger.

A variety of conditions in either the guest or host environments can cause a contract to trap. If a host function is called with invalid arguments, for example, the host will trap. Similarly if the contract performs an erroneous Wasm bytecode such as a division by zero or access to memory out of bounds, the Wasm VM will trap. Also if the contract uses more resources than its enclosing transaction has paid for, the contract will trap.

Monitoring

Contracts can be monitored in two main ways: by observing events emitted during their execution, and by examining the ledger entries written by them.

TBD: expand this section.

Upgrading contracts

See the Upgrading Contracts page for details on this.