1. Workspace Setup
This section is a getting started guide for developers looking to build applications on the Algorand blockchain. Start here to learn what it means to build an application on Algorand and how to get started quickly.
What does it mean to build on Algorand?¶
Building an application on Algorand means that your application, directly or indirectly, reads from or writes to the Algorand blockchain. Writing to the Algorand blockchain is synonymous with issuing a transaction that will later be confirmed within a block. Reading from the blockchain means reading back transactions that have been confirmed within prior blocks.
The following is a brief primer on some terms and relationships of the components that comprise the Algorand development environment. Figure 1. below illustrates these components and how they fit together.
The Algorand blockchain is a distributed system of nodes each maintaining their local state based on validating the history of blocks and the transactions therein. State data is maintained by the consensus protocol which is implemented within the algod daemon, often referred to as the node software. As a developer, this is most likely the base layer for your applications.
An application connects to the Algorand blockchain through an algod client. The algod client requires a valid algod REST endpoint IP address and algod token from an Algorand node that is connected to the network you plan to interact with.
Available tools¶
Software Development Kits (SDK)¶
Algorand officially supports four SDKs for developing applications: Javascript, Java, Python, and Go. Additionally, Community Provided SDKs expand the development reach.
Command Line Interface (CLI) Tools¶
Algorand provides three command-line utilities packaged with Algorand node software: goal, kmd, and algokey.
goal is the primary tool for operating a node and it also contains functionality to manage keys, sign and send transactions, create assets, and perform many of the same or similar functions that are available in the SDKs. Although not required to build an application, developers who run nodes may find it useful to achieve some level of fluency in goal as a complementary tool during testing and validation. goal is required to setup more advanced testing environments using private networks.
kmd is the CLI for the Algorand Key Management daemon and algokey is a standalone utility for generating Algorand accounts and for signing transactions. It is often used as a lightweight offline client for secure key signing. These two tools are not essential for getting started, so details of their use are described elsewhere.
There are also REST APIs available for both algod and kmd processes.
Indexer¶
Algorand provides a standalone daemon algorand-indexer that reads committed blocks from the Algorand blockchain and maintains a local database of transactions and accounts that are searchable and indexed. A REST API is available which enables application developers to perform rich and efficient queries on accounts, transactions, assets, and so forth.
Choosing a network¶
There are three public Algorand Networks paired with the functionality to create private networks using any protocol version.
MainNet is the primary Algorand Network with real-value assets, including Algorand's native currency - the Algo. TestNet mirrors MainNet in terms of its protocol (i.e. software) version, but it has test Algos, available via a faucet, and a different genesis block, which means that the state of accounts and distribution of funds is different. BetaNet is where new protocol-level features will be released for initial testing. Therefore, quality and features may not be final, and protocol upgrades and network restarts are common.
Recommended Use¶
If your application depends on features currently available on MainNet, use TestNet as your public testing network. If your application depends on features only available on BetaNet, use BetaNet as your public testing network. In all cases, use private networks, as needed, for greater control and isolation of your development environment. Learn more about feature availability on each of the networks in the Network Reference section. Sections in these docs marked with 🔷 indicate a feature available on BetaNet only.
If you are not sure which network to start with, TestNet is usually a good option as it allows you to develop against live features without risking real assets. Switching networks later will be trivial.
| MainNet | TestNet | BetaNet | |
|---|---|---|---|
| Protocol Version | Current | Current | Future |
| Genesis Distribution | Unique | Unique | Unique |
| Algo Accessibility | For sale | Free from faucet | Free from faucet |
| Network Reliability | Most Stable | Very Stable, but restarts are possible | Experimental; frequent restarts |
How do I obtain an algod address and token?¶
There are three recommended ways to obtain an algod REST endpoint IP address and access token that each have their respective pros and cons depending on what your goals are. Below is an explanation of each followed by a side-by-side comparison.
1. Use a third-party service¶
This method is recommended if you plan to use only the SDKs or the algod RESTful interface, and want to get connected as fast as possible.
A third-party service runs a node and provides access to that node through its own API keys. On signup, the service provides you with an algod address and an API key which will replace your algod token.
See the list of known API services on the Community Projects page.
2. Use Docker Sandbox¶
This method is recommended if you need access to all developer tools including goal, kmd, and algokey, but can't wait days for your node to catchup.
Visit this Github link for Sandbox setup instructions.
Warning
Bootstrapping from a snapshot bypasses the normal node catchup procedure that cryptographically verifies the whole history of the blockchain - a procedure that is imperative to maintaining a healthy network. Therefore, this method is only recommended in the context of early-stage application development to avoid catchup wait times and get started quickly. It should never be used to run a node in production or participate in consensus. Make sure that you migrate your application to a node that has undergone full catchup prior to launching your application in production.
Info
When using sandbox, goal should be replaced by ./sandbox goal. Furthermore, ./sandbox goal runs in its own Docker container and cannot directly access files in the current folder. To run any goal command that uses files in the current folder, you need to first copy the files. For example, to send the transactions in the file mytransaction.sig, you need to run:
./sandbox copyTo mytransaction.sig
./sandbox goal clerk rawsend -f mytransaction.sig
goal clerk rawsend -f mytransaction.sig
3. Run your own node¶
This method is recommended if you need access to all developer tools including goal, kmd, and algokey, and want to setup a production-ready environment. This is the recommended follow-on to option 2 before launching an application on MainNet. This method gives you full control of your node and its configuration.
Read the docs to setup and run a node.
After setup, find your REST endpoint's IP address here:
$ cat $ALGORAND_DATA/algod.net
and your algod token (required by your application to authenticate against algod) here:
$ cat $ALGORAND_DATA/algod.token
| Use a third-party service | Use Docker Sandbox | Run your own node | |
|---|---|---|---|
| Time | Seconds - Just signup | Minutes - Same as running a node with no catchup | Days - need to wait for node to catchup |
| Trust | 1 party | 1 party | Yourself |
| Cost | Usually free for development; pay based on rate limits in production | Variable (with free option) - see node types | Variable (with free option) - see node types |
| Private Networks | ❌ | ✅ | ✅ |
goal, algokey, kmd |
❌ | ✅ | ✅ |
| Platform | Varies | MacOS; Linux | MacOS; Linux |
| Production Ready | ✅ | ❌ | ✅ |
Install your preferred SDK¶
Install your preferred SDK by following the setup instructions in the SDK reference docs.
Other Setup Tips¶
If you use goal, it is recommended that you set the ALGORAND_DATA environment variable to avoid the need to specify it for each goal command. It is also recommended that you place goal, kmd, and algokey within your executable path. The examples in these docs will assume you have done both of these.
So you will use:
$ goal node status
instead of:
$ goal node status -d <your-node-directory>