# Developer guide
This document covers tips and guidelines to help you to understand how Terra works and efficiently navigate the codebase of Terra Core, the official Golang reference implementation of the Terra node software.
It is highly recommended that you review these projects before diving into the Terra developer documentation, as they assume familiarity with concepts such as ABCI, Validators, Keepers, Message Handlers, etc.
# How to use the docs
As a developer, you will likely find the Module Specifications section the most informative. Each specification starts out with a short description of the module's main function within the architecture of the system, and how it contributes in implementing Terra's features.
Beyond the introduction, each module will lay out a more detailed description of its main process and algorithms, alongside any concepts you may need to know. It is recommended that you start here to understand a module, as it is usually cross-referenced with more specific sections deeper in the spec such as specific state variables, message handlers and functions that may be of interest.
The current function documentation is not an exhaustive reference, but has been written to be a reference companion for those needing to work directly with the Terra Core codebase or understand it. The important functions in each module have been covered, and many of the trivial ones (such as getters and setters) have been left out for economy. Other places where module logic can be found is within either the message handler, or block transitions (begin-blocker and end-blocker).
At the end, the specification lists out various module parameters alongside their default values with a brief explanation of their purpose, and associated events / tags and errors emitted by the module.
# Module architecture
The node software is organized into the following individual modules that implement different parts of the Terra protocol. They are listed in the order in which they are initialized during genesis:
genaccounts- import & export genesis account
distribution: distribute rewards between validators and delegators
- tax and reward distribution
- community pool
staking: validators and Luna
auth: ante handler
- vesting accounts
- stability layer fee
bank- sending funds from account to account
slashing- low-level Tendermint slashing (double-signing, etc)
oracle- exchange rate feed oracle
- vote tallying weighted median
- ballot rewards
- slashing misbehaving oracles
treasury: miner incentive stabilization
- macroeconomic monitoring
- monetary policy levers (Tax Rate, Reward Weight)
- seigniorage settlement: all seigniorage is burned as of Columbus-5
gov: on-chain governance
- parameter updating
- Terra<>Terra spot-conversion, Tobin Tax
- Terra<>Luna market-maker, Constant-Product spread
crisis- reports consensus failure state with proof to halt the chain
- filter and handle
- filter and handle
# Inherited modules
Many of the modules in Terra Core are inherited from Cosmos SDK and are configured to work with Terra through customization in either genesis parameters or by augmenting their functionality with additional code.
# Block lifecycle
The following processes get executed during each block transition:
# Begin block
- Distribute rewards for the previous block
- Checking of infraction evidence or downtime of validators for double-signing and downtime penalties.
# Process messages
- Messages are routed to the modules that are responsible for working them and then processed by the appropriate Message Handlers.
# End block
- Check all registered invariants and assert they remain true
- Get rid of inactive proposals, check active proposals whose voting periods have ended for passes, and run registered proposal handler of the passed proposal.
- Replenish liquidity pools, allowing spread fees to decrease.
- At the end of
epoch, update indicators, burn seigniorage, and recalibrate monetary policy levers (tax-rate, reward-weight) for the next epoch.
- At the end of
- The new set of active validators is determined from the top 130 Luna stakers. Validators that lose their spot within the set start the unbonding process.
# Currency denominations
There are two types of tokens that can be held by accounts and wallets in the Terra protocol:
Terra stablecoins track the exchange rate of various fiat currencies. Each Terra stablecoin is named for its corresponding 3 letter ISO 4217 fiat currency code (opens new window), written as
Terra<currencycode>. When used as a value, the last letter of each currency code abbreviation is replaced with T to signify it as a Terra stablecoin. For example, the Terra stablecoin pegged to the Korean Won, KRW, is named TerraKRW, and its abbreviation is KRT.
The Terra protocol's standard base currency is TerraSDR, or SDT, which pegs to the IMF's Special Drawing Rights. The Terra protocol uses SDT to make calcualtions and set rate standards.
Luna is the Terra protocol's native staking asset. Delegators earn mining rewards when they stake their Luna to an active validator. Luna stabilizes the Terra economy by absorbing the price volatility of Terra stablecoins and is also used to make governance proposals.
The micro-unit (
|Luna||µLuna|| ||0.000001 Luna|
|TerraSDR||µSDR|| ||0.000001 SDT|
|TerraKRW||µKRW|| ||0.000001 KRT|
|TerraUSD||µUSD|| ||0.000001 UST|
|TerraMNT||µMNT|| ||0.000001 MNT|
Note that the Terra protocol is only aware of the value of fiat currencies through their Terra stablecoin counterparts, which are assumed to trade relatively close to the value of the fiat currency they are pegged to, due to arbitrage activity.