SDK Updates: Deploying Stateful Smart Contracts

Arguably the most anticipated feature of the recent Algorand v2.1.3 release is stateful smart contracts. Much has been written about how they will enable software developers to author applications. This article is a developer’s treasure map providing links to guide readers from understanding the basics to using the SDK Documentation for advanced smart contract application deployments.

Basics: Stateless vs. Stateful Smart Contracts

All Algorand Smart Contracts (ASC1) are compiled programs executed by validation nodes during consensus evaluation. Program execution must complete with a single non-zero unit64 value remaining on the stack to be valid, thus appending the ledger with the resulting state transitions. The Transaction Execution Approval Language (TEAL) is used to author programs based on the available OpCodes and their defined mode of use.

Stateless smart contracts are able to approve transactions, either as a Contract Account or a Delegated Account.

Stateful smart contracts are able to store data or “maintain state” of bytes and ints within the ledger. Two programs (approval and clear) define a stateful smart contract, referred to as an application. Application Call Transactions are broadcast by a user to interact with these programs. Calls may include user-defined arguments (additional data) which are evaluated by the program logic at run-time. State changes (value updates) take effect only after successful program execution.

Basics: Stateful Storage

Each stateful smart contract has access to three storage locations where key/value pairs are defined: global, local and foreign.

Global storage, provisioned within the application creator’s account, represents application-specific data. The application’s global storage reflects current state to each call transaction. The application may read from or write to its own global storage.

Local storage is provisioned within a user account for the specific application only after the user issues an Opt-In call transaction. Local values reflect current state of the application, unique to each account. Read access is granted to anyone, but write access is limited to the application’s program logic.

Foreign storage is the global or local storage location of a referenced application or account respectively. The program logic may read from these storage locations but may only write if the foreign entity has successfully confirmed an Opt-In call transaction for this application.

Prerequisite: Developer API

An important prerequisite for your smart contract development environment is enabling the Developer API on the algod node software. It’s just a quick config file tweak and restart of the node software.

Building Stateful Smart Contracts: SDK Walkthrough

With the basics covered and your development environment configured, ensure your SDK is updated (Python, JavaScript, Java and Go) and familiarize yourself with PyTeal. It’s time to design, develop, deploy and interact with your application. The SDK Walkthrough iterates on the Hello World counter application by adding global storage and a timestamp.

Design

Start by reviewing this boilerplate stateful application TEAL approval program. It lays out a series of handlers for each of the call transactions, then branch accordingly based on type. It’s imperative to add custom logic within the handle_updateapp and handle_delete sections to protect your application against unauthorized access. Initial designs will likely define a check for the creator’s address within these sections. Fully tested and decentralized designs may define the zero address in these sections, thus preventing future updates or deletion. The result of the design phase will be program logic for the handle_noop, handle_optin and handle_closeout sections.

The SDK Walkthrough annotates both the approval and clear example programs.

Develop

Your SDK project will follow the logic defined within the stateful smart contract program source code. At minimum you will define methods which compile, create and call the deployed application. The bulk of your time will likely be spent within makeApplicationNoOpTxn call methods. This is where you will formulate the application logic and likely calculate arguments to be included with these call transactions. Debugging is an important tool to become familiar with during the design and development phases (look for a future article with a detailed walkthrough).

Deploy

Use the compile endpoint of the Developer API to convert your TEAL source code into the byte string required by the SDKs. Next, use the makeApplicationCreate method types to deploy the initial application.

Interact

The user will first interact with the application using the makeApplicationOptIn method. Now calls using the makeApplicationNoOpTxn method will execute logic within the handle_noop section of the approval program. Calls to other makeApplication type call methods are similarly demonstrated for Update, Clear and CloseOut and execute the TEAL code for their respective handler. Any of these calls may modify global, local and/or foreign state as defined in program logic and enforced by consensus evaluation.

Reading data from storage within the SDK is a simple API call to any user’s account for a specific app-id. Displaying the state data is just parsing the JSON response into its key/value pairs.

Wrapping Up

This guide is designed to accelerate your learning about Algorand stateful smart contracts and then apply that knowledge to build your own applications using the SDK. The Developer Portal provides many resources for building applications on Algorand. A series of stateful smart contract solutions detail building a crowdfunding app, a permissioned voting app and a permissionless voting app. The Developer Forums remain the goto for Q&A on all dev topics. Start building your application today; we’re here to help guide you and get you to done.

Signup for the Developer Newsletter to keep connected with our latest updates.