In this guide, we cover some of the key concepts that make up the way individual users interact and are represented in the Algorand network. We also discuss how these mechanisms can be created and managed with the various tools and SDKs within the network. We start with basic keys that we use and work from there.
Every user in Algorand will have at least one set of private and public keys. These keys use Ed25519 high-speed, high-security elliptic-curve signatures. We refer to these as spending keys; they are used to sign and verify transactions and to change an account’s online status.
Addresses are unique identifiers for either a single public key (the common case) or a collection of public keys (like in the case of multisignature address). An address wraps an Ed25519 public key, which is a 32-byte array. The string representation is computed by appending a 4-byte checksum (computed by taking the last 4 bytes of a SHA512/256 digest of the public key) to the public key, giving us a 36-byte array. These unique identifiers are the primary way of referring to an account in the system using either the command line utilities or the SDKs. Most use cases don't require users to ever actually know or see the true public key, and Algorand addresses are often [erroneously] referred to as public keys. Keep this in mind if you are a developer that does need to be aware of this distinction.
Accounts represent an entity on the Algorand blockchain with specific onchain data associated to a specific user address. This data includes things like the balance, address, status (online/offline) and rewards earned.
Accounts currently require a minimum balance of 0.1 Algos (100000 microalgos). In the future, this minimum may increase and accounts with balances lower than the minimum may be closed automatically. If you submit a transaction that leaves your account balance below the minimum you are required to specify a close account to which to move your remaining balance. If you are using
goal clerk send, you can do this with the -c option. The network will reject transactions that put your account below the minimum balance unless a close account is specified.
An account has a 25-word mnemonic backup phrase. This phrase can be retrieved after the account is created by using one of the command line utilities (algokey or goal) or with any of the SDKs. Retrieving this phrase requires the spending key. This mnemonic can be used to recover the account at a later time.
Accounts can be generated in several ways. You can generate an account using algokey, goal, the SDKs or using one of the Algorand mobile wallet apps (available on Apple App Store or the Google Play Store). When generating with goal, you must first create a wallet that is used to generate accounts. This wallet is managed by the node’s kmd process and acts as a normal wallet. The wallet itself has a master derivation key, which provides a 25-word mnemonic backup phrase that allows the wallet to be restored at a later date. Wallet and account mnemonics are not interchangeable. All accounts created by the kmd wallet can be regenerated using the recovered wallet. This allows you to store multiple accounts in a kmd wallet and only store the one backup phrase. You can also import and export from this wallet using goal. If you import an account into a kmd wallet, you must also store that account’s mnemonic as it will not be regenerated by the wallet. When using the SDKs, you can use stand-alone functions to create accounts, or you can connect to a node’s kmd REST endpoint and create an account in a kmd-managed wallet. If you use a standalone account it is not managed by any wallet unless you are using an external to Algorand integration.
Accounts may be online or offline. Online accounts are accounts that have generated and registered a participation key(described later in this guide), the account has been taken online using the generated participation keys and is now participating in consensus on a specific node (which could be your own). Offline accounts are accounts that have not been taken online by registering participation keys (or have been taken offline by unregistering participation keys). A node is participating in consensus if it has the participation keys accessible for one or more online accounts.
Multisignature accounts are a logical representation of an ordered set of addreses with a threshold and version. Multisignature accounts can do the same operations as normal accounts, including sending transactions and participating in consensus. The address for a multisignature account is essentially a hash of the ordered list of accounts, the threshold and version values. It is important to note that multisignature accounts can not nest other multisignature address. The threshold determines how many signatures are required to process any transaction from this multisignature account. So if there are five addresses in the multisignature account and its threshold is three, then any transaction sent from this account must be signed by at least three of the five accounts in order for it to be valid. Multisignature accounts can be created by using goal or any of the SDKs. Transactions from multisignature accounts can be signed using goal, algokey or any of the SDKs. The order of the addresses listed in a multisignature account is important. So creating a multisignature account with addressA, addressB, and addressC will not produce the same address as one with addressB, addressA, and addressC. Signing a multisignature transaction does not require any specific order.
Wallets as defined here are the wallets managed by Algorand’s Key Management Daemon (kmd) process. A wallet stores a collection of accounts. kmd stores collections of wallets and allows users to perform operations using the keys stored within these wallets. You can export and import keys into this wallet using goal. However, only keys that are derived from the wallet's master seed will be recoverable with just the wallet mnemonic. Account-level keys generated outside of the kmd wallet (e.g., with the SDKs, mobile wallet apps) and imported into the wallet will not be retained when the wallet is recovered elsewhere.
Algorand also provides another set of keys for voting and proposing blocks separate from account spending keys. These are called participation keys. From a high-level perspective, participation keys are a specialized set of keys located on a specific node. Once this participation key set is associated with an account, the account has the ability to participate in consensus. This key set is generated using goal for a range of rounds, and is only valid for rounds in that range. Once the range of rounds expires, a new participation key (i.e., another set of keys) must be generated and registered. This method of participation ensures that an account’s tokens are secure even if its node is compromised, as these keys are not generated using an account’s spending keys. For security, the individual keys for each round are deleted from the key file as each round is completed. It is critical for the safety of the Algorand blockchain to avoid storing backups of participation key files that have been registered for an account.
These keys can be generated using the
goal account addpartkey command. This command takes an account and a range of rounds as parameters. The account’s private spending key does not need to be on the server that goal is running on as it is not used at all to generate participation keys. The node will generate a VRF key pair at this point (see for more info) and essentially (we use optimizations) a set of single-round voting keys for each round of the range that is specified in the
addpartkey command. The VRF private key is what is passed into the VRF to determine if you are selected to propose or vote on a block in any given round. As each round passes, voting keys are removed from the system. This prevents past votes from being modified if the node is ever compromised. Technically, the voting keys will never be used if an account has not been taken online. For an account to be taken online it first must have tokens in the account, participation keys generated for it and a “take online” transaction completed on the blockchain. To take an account online you can use the
goal account changeonlinestatus command to create the transaction. This command provides a -t option that allows the transactions to be written to a file and signed offline (see signing offline). Once the changeonlinestatus transaction is processed by the blockchain, the VRF public key is written into the account’s data and the account will start participating in consensus with that key. This VRF public key is how the account is associated with the specific participation keys. Changing an account’s status takes 320 rounds after the transaction is processed by the blockchain.
Signing Transactions Online/Offline
This section deals with signing transactions online or offline. By offline, here, we mean either a computer disconnected entirely from any network or a node not connected to any Algorand blockchain network.
Transactions can be signed on an online or offline computer. To sign a transaction, you must have your private spending key. You can create a transaction in various ways. You can create it on an online node and save to a file, or create them offline on an offline computer. Creating them offline is a bit more difficult as you will have to manually enter things like the genesis hash. Transactions can be created with any of the SDKs or using tools like goal, which provides the ability to write a transaction to a file. You can sign a transaction online or offline using tools like goal or algokey or by using any of the SDKs. Once a transaction is signed, you can submit it to the Algorand network from any online node using any of the SDKs, or by using the
goal clerk rawsend command, which takes a filename as a parameter. See the individual SDKs for examples on how to do this or see the algokey or goal docs for more information on the command line tools.