Terra Smart Contract Kickstart
CosmWasm is a new smart contract platform by Confio that provides a WebAssembly (WASM) runtime through a plug-and-play module that can be easily integrated into existing Cosmos SDK blockchains. CosmWasm allows users to upload their own WASM-based smart contracts which can be written in a variety of languages, enabling the use of custom logic alongside functionality provided by the blockchain’s native modules.
Terra, whose protocol enables the issuance of stablecoins pegged to various world currencies is built on the Cosmos SDK and is compatible with CosmWasm. In Terra’s next mainnet upgrade, CosmWasm will be integrated through the new WASM module, and users will be able to write their own smart contracts that leverage the Terra blockchain’s powerful primitives for building the next generation of financial dApps.
In this post, we will go over the new Contracts section in Terra Station, where users can upload, query, and interact with smart contracts. But before we jump into the new Smart Contract feature, let’s first take a look at what Terra Station is.
Terra Station is a wallet application which allows users to connect and interact with various Terra networks. Although it is primarily used for interacting with the mainnet, Columbus, it can be used to access various testnets, including a local testnet called LocalTerra (explained below). You can access Terra Station through the web, but we recommend installing it locally as a desktop application for working with smart contracts. You can install Terra Station using the links below:
Once you open up Terra Station, you’ll see that its functionality is organized into different sections which you can navigate by clicking the various menus on the left sidebar. Make sure to set the network to the latest Tequila testnet or LocalTerra (explained below) to follow along in this tutorial.
Dashboard displays general information about the current status about Luna. You can change the graph settings to view them in a cumulative or periodic data.
The Wallet page shows the user’s various token balances (Luna and Terra stablecoins), and allows the user to send funds to another account. If the page shows that you do not have any balance on your Tequila testnet, you can always go to the Terra Faucet and get more of your desired token. More details on Faucet will be described in the section below.
This is a detailed view of user’s transaction history, detailing all the transactions issued from the wallet. By default, all transactions are visible. To see only specific types of transactions such as “send” or “receive”, you can filter by selecting one of the categories (All, Send, Receive, Staking, Market, Governance) above your transaction history.
Even on Terra testnets, you can still test staking by delegating to a testnet validator. By simply clicking on a validator, you can delegate or undelegate your testnet Luna tokens, or withdraw your current rewards.
The Terra blockchain supports stablecoins in multiple denominations, as well as Luna, the native staking asset and governance token. The market page allows users to swap between various stablecoins and as well as Luna based on the current market exchange rate as reported by the oracle.
The Market page also displays more detailed information about Luna’s exchange rate history. You can adjust the time settings from 1 minute to a day to get the desired price chart view. The page also allows you to check the exchange rate of the various Terra stablecoins to Luna.
At the bottom of the page, you can select and enter the amount of tokens to swap, and the system will automatically calculate the estimated return value based on the current exchange rate.
On-chain governance is a crucial feature of Proof-of-Stake networks. It allows any stakeholder of the Terra blockchain to change blockchain parameters by creating proposals and getting the rest of the community to vote. Terra Station provides the function of making new proposals and voting on governance proposals through a simple interface.
Please note that in order to use the “Contract” feature on Terra Station, you need to be either on the Tequila testnet or LocalTerra network. You can adjust your network settings near the lower left hand corner on Terra Station.
Terra Station provides users a friendly alternative to the command line interface, allowing users to work with smart contracts through a graphical interface.
Upload / Create Contract
On Terra, there is a distinction between uploading a smart contract’s code and instantiating (creating) a contract. Unlike in Ethereum or other smart contract platforms, these two steps are considered separate. Uploading a smart contract’s code saves it onto the blockchain and returns a code ID, which can be used to create multiple smart contracts. This promotes efficient code reuse and increases confidence as only a small set of vetted and audited archetypal contracts are needed for a majority of use cases. For instance, people can easily issue their own tokens by referring to an existing code ID for a CW20 (ERC20 analog) rather than writing their own implementation.
Users can upload their own smart contract code by clicking on the [Upload] button located in the top-right corner in the “Contracts” menu of Terra Station.
In order to upload code, you will need to provide several pieces of required information. The most important is the compiled WASM bytecode that contains the smart contract logic. You can also add additional information such as the name and description, as well as a URL address linking to a public GitHub repository containing the smart contract source code. This metadata will be recorded alongside the contract code and will allow other users to know what your smart contract does and how to use it. After the Smart Contract has successfully uploaded, you will receive a code ID corresponding to the newly registered code.
Once you have the code ID, you can instantiate the contract. This will create a contract and assign a new Terra account address which will be associated with the contract, called the contract address. In the case of the image below, the provided Code ID is “61”.
Each smart contract must be initialized by passing in an InitMsg, which is encoded in JSON. The expected format of the InitMsg is known through the schema specified in the contract code. Terra Station is unaware of the smart contract’s source code, so it is unable to provide deeper schema validation. You should double-check with the contract’s source code to make sure the InitMsg is properly formatted, otherwise it may result in your contract starting with an unexpected initial state.
The “Coins” input field allows the user to provide the contract with its initial funds. This is optional, and is only necessary if the funds are required by the smart contract to power its operations. You will be able to send from your present balance any tokens desired, including Luna and all Terra stablecoins.
Upon clicking on [NEXT] button, you will be guided to the Confirm page where you can set a transaction fee for creating this contract — enter a password to finally confirm this transaction. After this transaction, you can find your created contract from the list on the “Contracts” page and start interacting with it.
Clicking on any of the contract addresses from the list will take the user to Terra Finder, Terra’s official block explorer.
Once a smart contract has been created, it is live on the blockchain and can respond to user interaction. You can invoke functions defined in the smart contract by clicking the [Interact] button next to the smart contract’s address in Terra Station. This presents a modal where you can specify a HandleMsg and, optionally, some coins, which may be required by the smart contract.
A HandleMsg is a JSON message that the smart contract parses and routes to its appropriate logic and allows the user to specify which function as well as which arguments to execute. Like the InitMsg, the HandleMsg has an expected format and schema specified by the smart contract’s code. Please refer to the specific smart contract’s relevant documentation and source code for understanding how to properly create a HandleMsg that corresponds to that smart contract’s desired operation.
Once you are done filling out the necessary inputs, Terra Station will format the interaction request into a MsgExecuteContract and generate a transaction for you to sign and broadcast.
You can query a smart contract by pressing the [Query] button, located next to the [Interact] button. Unlike interacting (executing) a smart contract, querying a smart contract does not involve changing the contract’s state and can thus be performed without broadcasting and signing a transaction. Querying a smart contract is a read-only operation and allows the user to run a smart contract function to fetch data from the contract. You will specify a QueryMsg, which is a JSON message that will be parsed and executed by the smart contract to run a query over the contract’s state. The QueryMsg has a format that is defined in the smart contract’s source, so refer to the smart contract’s documentation for further guidance.
To get a better picture about Smart Contracts on Terra, please visit the official Terra Docs, where you’ll find a more in-depth developer guide with all the necessary information on getting started writing smart contracts for Terra.
While Faucet allows users of Tequila-0004 testnet to acquire testnet tokens to play with, this method is unnecessary if they are on LocalTerra network instead. LocalTerra is a complete Terra testnet and ecosystem containerized with Docker and orchestrated with a simple
docker-compose file, designed to make it easy for smart contract developers to test out their contracts in a sandboxed environment before moving to a live testnet or mainnet.
In order to access LocalTerra from Terra Station, you must first setup LocalTerra using the guidelines in the LocalTerra Github repository.
You can configure Terra Station to use LocalTerra by clicking on the bottom-left corner of the application. LocalTerra comes with 10 pre-configured accounts with balances, which you can switch between easily via a dropdown menu that appears next to your username when LocalTerra is selected.
By default, following TCP socket ports will be bound. Please make sure that other applications are not using them, as it may interfere with the usage of LocalTerra.
Terrad RPC: 26657 (i.e. terracli <cmd> —node tcp://localhost:26657)
FCD: 3060 (http://localhost:3060/swagger/)
— Generous contributions from Joe Lim, Paul Kim, and William Chen (Terra)