Add support for smart contracts

Stellar recently upgraded its protocol to support smart contracts, adding a new way to interact with the network. This one-pager highlights key considerations for integrating with Stellar’s smart contracts specifically for wallets and exchanges that already support Stellar’s “classic” operations. It quickly outlines what changes to expect, provides links to detailed documentation, and is a starting point for adapting existing Stellar Classic processes to the new smart contract environment.

1. Infrastructure

Transitioning from Horizon to RPC

To properly support Stellar's smart contracts, you must use Stellar RPC. More specifically, you need RPC to simulate transactions that execute smart contracts, as described in the "Simulating Transactions" section, and it provides a convenient API for consuming contract events. Both of these features are not available in Horizon.

Running Your Own RPC vs. Leveraging Third-Party Providers

You can set up an RPC environment by hosting your own node or using a third-party provider. For guidance on hosting your own instance, including a Docker-based setup, refer to the Admin Guide. Alternatively, a list of trusted providers is available in the ecosystem RPC providers documentation.

2. Data Ingestion

Ingesting Smart Contract Events

Horizon offers an effects endpoint that describes state changes executed by classic operations. Similarly, contracts emit events that describe changes to their state, which can be fetched via RPC's API. Off-chain solutions can monitor and ingest these events (for token transfers or protocol updates) and remain in sync with on-chain data. Each event is defined by the contract and is subject to standards applied to the implementation. Depending on the requirements for retention, a solution might have to handle ingestion directly or use a third-party service for a longer-term history.

Simulating Transaction

While events should be used to monitor changes to a contract’s state, clients may also need to determine the current state of a contract. Simulation allows clients to execute contract invocations with incurring fees or finalizing changes, making it an ideal approach for fetching contracts’ current state. For example, clients can call the balance function on a SEP-0041-compliant token contract to fetch a user’s current balance.

3. Transaction Workflow Changes

Building Transactions

Transaction construction involves specifying a call to a contract function rather than any of the built-in operations Stellar offers. When building these contract calls, it is necessary to specify the relevant contract ID and function arguments according to the contract interface. See more at Documentation for Contract Interaction - Stellar Transaction.

You can still use the libraries or tools you’re already familiar with to assemble these transactions, but keep in mind the extra steps required for contract invocation.

Simulating Transaction

Transactions that execute smart contracts must be simulated before sending. That is because simulation doesn’t just provide the results of executing transactions; it also provides essential information such as the transaction’s read/write footprint and authorizations needed, and clients must add this information to the transaction before sending it to the network for execution.

Signing & Auth Entries

Smart contracts can define their own custom authorization logic, meaning you might need additional signatures for specific authorization data to prove permission for certain contract calls. Each contract can have its own requirements, so a good practice is to leverage transaction simulations to identify specific authorization requirements for a transaction.

Asynchronous Transaction Submission

Unlike Horizon, RPC only queues transactions for inclusion rather than waiting for final confirmation. Therefore, it is necessary to poll the transaction’s status to determine if a transaction eventually succeeds or fails. This asynchronous model, as well as other common challenges, can be seen at the Documentation for Dapp Development - Common Pitfalls.