Terra Classic Ecosystem

The Treasury module acts as the "central bank" of the Terra economy, measuring macroeconomic activity by observing indicators and adjusting monetary policy levers to modulate miner incentives toward stable, long-term growth.

Concepts

Observed indicators

The treasury observes three macroeconomic indicators for each epoch and keeps indicators of their values during previous epochs:

Tax Rewards: $T$, the income generated from transaction and stability fees during an epoch.
Seigniorage Rewards: $S$, the amount of seigniorage generated from LUNC swaps to Terra during an epoch which is destined for ballot rewards inside the OracleCopy Oracle rewards. As of Columbus-5, all seigniorage is burned.
Total Staked LUNC: $\lambda$, the total amount of LUNC staked by users and bonded to their delegated validators.

These indicators can be used to derive two other values, the Tax Reward per unit LUNC represented by $\tau = T / \lambda$, used in Updating Tax Rate, and total mining rewards $R = T + S$: the sum of the Tax Rewards and the Seigniorage Rewards, used in Updating Reward Weight.

The protocol can compute and compare the short-term (WindowShortCopy WindowShort) and the long-term (WindowLongCopy WindowLong) rolling averages of the above indicators to determine the relative direction and velocity of the Terra economy.

Monetary policy levers

Tax Rate: $r$, adjusts the amount of income gained from Terra transactions, limited by tax cap.

Reward Weight: $w$, the portion of seigniorage allocated to the reward pool for OracleCopy Oracle vote winners. This is given to validators who vote within the reward band of the weighted median exchange rate.

Updating policies

Both Tax Rate and Reward Weight are stored as values in the KVStoreCopy KVStore and can have their values updated through governance proposals after they have passed. The Treasury recalibrates each lever once per epoch to stabilize unit returns for LUNC, ensuring predictable mining rewards from staking:

For tax rate, to ensure that unit-mining rewards do not stay stagnant, the treasury adds a MiningIncrementCopy MiningIncrement so mining rewards increase steadily over time, as described in k.updatetaxpolicy.
For reward weight, the treasury observes the portion of seigniorage needed to bear the overall reward profile, SeigniorageBurdenTargetCopy SeigniorageBurdenTarget and raises rates accordingly, as described in k.updaterewardpolicy. The current reward weight is 1Copy 1.

Probation

A probationary period specified by the WindowProbationCopy WindowProbation prevents the network from updating the tax rate and reward weight during the first epochs after genesis to allow the blockchain to first obtain a critical mass of transactions and a mature, reliable history of indicators.

Data

Policy constraints

Policy updates from governance proposals and automatic calibration are constrained by the TaxPolicyCopy TaxPolicy and RewardPolicyCopy RewardPolicy parameters, respectively. PolicyConstraintsCopy PolicyConstraints specifies the floor, ceiling, and max periodic changes for each variable.

GO// PolicyConstraints defines constraints around updating a key Treasury variable
type PolicyConstraints struct {
    RateMin       sdk.Dec  `json:"rate_min"`
    RateMax       sdk.Dec  `json:"rate_max"`
    Cap           sdk.Coin `json:"cap"`
    ChangeRateMax sdk.Dec  `json:"change_max"`
}

The logic for constraining a policy lever update is done by pc.Clamp()Copy pc.Clamp().

GO// Clamp constrains a policy variable update within the policy constraints
func (pc PolicyConstraints) Clamp(prevRate sdk.Dec, newRate sdk.Dec) (clampedRate sdk.Dec) {
    if newRate.LT(pc.RateMin) {
        newRate = pc.RateMin
    } else if newRate.GT(pc.RateMax) {
        newRate = pc.RateMax
    }

    delta := newRate.Sub(prevRate)
    if newRate.GT(prevRate) {
        if delta.GT(pc.ChangeRateMax) {
            newRate = prevRate.Add(pc.ChangeRateMax)
        }
    } else {
        if delta.Abs().GT(pc.ChangeRateMax) {
            newRate = prevRate.Sub(pc.ChangeRateMax)
        }
    }
    return newRate
}

Proposals

The Treasury module defines special proposals which allow the Tax Rate and Reward Weight values in the KVStoreCopy KVStore to be voted on and changed accordingly, subject to the policy constraints imposed by pc.Clamp()Copy pc.Clamp().

TaxRateUpdateProposal

GOtype TaxRateUpdateProposal struct {
    Title       string  `json:"title" yaml:"title"`             // Title of the Proposal
    Description string  `json:"description" yaml:"description"` // Description of the Proposal
    TaxRate     sdk.Dec `json:"tax_rate" yaml:"tax_rate"`       // target TaxRate
}

State

Tax rate

type: DecCopy Dec
min: .1%
max: 1%

The value of the tax rate policy lever for the current epoch.

Reward Weight

type: DecCopy Dec
default: 1Copy 1

The value of the reward weight policy lever for the current epoch. As of Columbus-5, the reward weight is 1Copy 1.

Tax caps

type: map[string]IntCopy map[string]Int

The treasury keeps a KVStoreCopy KVStore that maps a denomination denomCopy denom to an sdk.IntCopy sdk.Int, which represents the maximum income that can be generated from taxes on a transaction in that same denomination. It is updated every epoch with the equivalent value of TaxPolicy.CapCopy TaxPolicy.Cap at the current exchange rate.

For example, if a transaction's value is 100 SDT with a tax rate of 5% and a tax cap of 1 SDT, the income generated is 1 SDT, not 5 SDT.

Tax Proceeds

type: CoinsCopy Coins

The tax rewards $T$ for the current epoch.

Epoch initial issuance

type: CoinsCopy Coins

The total supply of LUNC at the beginning of the current epoch. This value is used in k.SettleSeigniorage()Copy k.SettleSeigniorage() to calculate the seigniorage distributed at the end of each epoch. As of Columbus 5, all seigniorage is burned.

Recording the initial issuance automatically uses the supply module to determine the total issuance of LUNC. Peeking returns the epoch's initial issuance of µLuna (ulunaCopy uluna) as sdk.IntCopy sdk.Int instead of sdk.CoinsCopy sdk.Coins for clarity.

Indicators

The Treasury keeps track of the following indicators for the present and previous epochs:

Tax rewards

type: DecCopy Dec

The Tax Rewards $T$ for each epochCopy epoch.

Seigniorage Rewards

type: DecCopy Dec

The seigniorage rewards $S$ for each epochCopy epoch.

Total Staked LUNC

type: IntCopy Int

The total staked LUNC $\lambda$ for each epochCopy epoch.

Functions

k.UpdateIndicators()Copy k.UpdateIndicators()

GOfunc (k Keeper) UpdateIndicators(ctx sdk.Context)

At the end of each epoch $t$, this function records the current values of tax rewards $T$, seigniorage rewards $S$, and total staked LUNC $\lambda$ before moving to the next epoch $t+1$.

$T_t$ is the current value in TaxProceedsCopy TaxProceeds.
$S_t = \Sigma * w$, with epoch seigniorage $\Sigma$ and reward weight $w$.
$\lambda_t$ is the result of staking.TotalBondedTokens()Copy staking.TotalBondedTokens().

k.UpdateTaxPolicy()Copy k.UpdateTaxPolicy()

GOfunc (k Keeper) UpdateTaxPolicy(ctx sdk.Context) (newTaxRate sdk.Dec)

At the end of each epoch, this function calculates the next value of the tax rate monetary lever.

Using $r_t$ as the current tax rate and $n$ as the MiningIncrementCopy MiningIncrement parameter:

Calculate the rolling average $\tau_y$ of tax rewards per unit LUNC over the last year WindowLongCopy WindowLong.
Calculate the rolling average $\tau_m$ of tax rewards per unit LUNC over the last month WindowShortCopy WindowShort.
If $\tau_m = 0$, no tax revenue occurred in the last month. The tax rate should be set to the maximum permitted by the tax policy, subject to the rules of pc.Clamp()Copy pc.Clamp(). For more information, see constraints.
If $\tau_m > 0$, the new Tax Rate is $r_{t+1} = (n r_t \tau_y)/\tau_m$, subject to the rules of pc.Clamp()Copy pc.Clamp(). For more information, see constraints.

When monthly tax revenues dip below the yearly average, the treasury increases the tax rate. When monthly tax revenues go above the yearly average, the treasury decreases the tax rate.

k.UpdateRewardPolicy()Copy k.UpdateRewardPolicy()

GOfunc (k Keeper) UpdateRewardPolicy(ctx sdk.Context) (newRewardWeight sdk.Dec)

At the end of each epoch, this function calculates the next value of the Reward Weight monetary lever.

Using $w_t$ as the current reward weight, and $b$ as the SeigniorageBurdenTargetCopy SeigniorageBurdenTarget parameter:

Calculate the sum $S_m$ of seigniorage rewards over the last month WindowShortCopy WindowShort.
Calculate the sum $R_m$ of total mining rewards over the last month WindowShortCopy WindowShort.
If $R_m = 0$ and $S_m = 0$, no mining or seigniorage rewards occurred in the last month. The reward weight should be set to the maximum permitted by the reward policy, subject to the rules of pc.Clamp()Copy pc.Clamp(). For more information, see constraints.
If $R_m > 0$ or $S_m > 0$, the new Reward Weight is $w_{t+1} = b w_t S_m / R_m$, subject to the rules of pc.Clamp()Copy pc.Clamp(). For more information, see constraints.

k.UpdateTaxCap()Copy k.UpdateTaxCap()

GOfunc (k Keeper) UpdateTaxCap(ctx sdk.Context) sdk.Coins

This function is called at the end of an epoch to compute the Tax Caps for every denomination for the next epoch.

For every denomination in circulation, the new Tax Cap for each denomination is set to be the global Tax Cap defined in the TaxPolicyCopy TaxPolicy parameter, at current exchange rates.

k.SettleSeigniorage()Copy k.SettleSeigniorage()

GOfunc (k Keeper) SettleSeigniorage(ctx sdk.Context)

This function is called at the end of an epoch to compute seigniorage and forwards the funds to the oracle module module for ballot rewards and the distribution module for the community pool.

The seigniorage $\Sigma$ of the current epoch is calculated by taking the difference between the LUNC supply at the start of the epoch (epoch initial issuance) and the LUNC supply at the time of calling.

$\Sigma > 0$ when the current LUNC supply is lower than it was at the start of the epoch because LUNC had been burned from LUNC swaps into Terra. For more information, see seigniorage.
The reward weight $w$ is the percentage of the seigniorage designated for ballot rewards. Amount $S$ of new LUNC is minted, and the oracle module receives $S = \Sigma * w$ of the seigniorage.
The remainder of the coins $\Sigma - S$ is sent to the distribution module , where it is allocated into the community pool.

::: {Important} As of Columbus-5, all seigniorage is burned and no longer funds the community pool or the oracle reward pool. Validators are rewarded for faithful oracle votes through swap fees. :::

Transitions

End-Block

If the blockchain is at the final block of the epoch, the following procedure is run:

Update all the indicators with k.UpdateIndicators()Copy k.UpdateIndicators()
If the current block is under probation, skip to step 6.
Settle seigniorage accrued during the epoch and make funds available to ballot rewards and the community pool during the next epoch. As of Columbus-5, all seigniorage is burned.
Calculate the Tax Rate, Reward Weight, and Tax Cap for the next epoch. As of Columbus-5, all seigniorage is burned, and the reward weight is 1Copy 1.
Emit the policy_updateCopy policy_update event, recording the new policy lever values.
Finally, record the LUNC issuance with k.RecordEpochInitialIssuance()Copy k.RecordEpochInitialIssuance(). It will be used to calculate the seigniorage for the next epoch.

Type	Attribute Key	Attribute Value
policy_update	tax_rate	{taxRate}
policy_update	reward_weight	{rewardWeight}
policy_update	tax_cap	{taxCap}

Parameters

The subspace for the Treasury module is treasuryCopy treasury.

GOtype Params struct {
    TaxPolicy               PolicyConstraints `json:"tax_policy" yaml:"tax_policy"`
    RewardPolicy            PolicyConstraints `json:"reward_policy" yaml:"reward_policy"`
    SeigniorageBurdenTarget sdk.Dec           `json:"seigniorage_burden_target" yaml:"seigniorage_burden_target"`
    MiningIncrement         sdk.Dec           `json:"mining_increment" yaml:"mining_increment"`
    WindowShort             int64             `json:"window_short" yaml:"window_short"`
    WindowLong              int64             `json:"window_long" yaml:"window_long"`
    WindowProbation         int64             `json:"window_probation" yaml:"window_probation"`
}

TaxPolicy

type: PolicyConstraintsCopy PolicyConstraints
default:

GODefaultTaxPolicy = PolicyConstraints{
    RateMin:       sdk.NewDecWithPrec(5, 4), // 0.05%
    RateMax:       sdk.NewDecWithPrec(1, 2), // 1%
    Cap:           sdk.NewCoin(core.MicroSDRDenom, sdk.OneInt().MulRaw(core.MicroUnit)), // 1 SDR Tax cap
    ChangeRateMax: sdk.NewDecWithPrec(25, 5), // 0.025%
}

Constraints for updating the tax rate monetary policy lever.

RewardPolicy

type: PolicyConstraintsCopy PolicyConstraints
default:

GODefaultRewardPolicy = PolicyConstraints{
    RateMin:       sdk.NewDecWithPrec(5, 2), // 5%
    RateMax:       sdk.NewDecWithPrec(90, 2), // 90%
    ChangeRateMax: sdk.NewDecWithPrec(25, 3), // 2.5%
    Cap:           sdk.NewCoin("unused", sdk.ZeroInt()), // UNUSED
}

Constraints for updating the reward weight monetary policy lever.

SeigniorageBurdenTarget

type: sdk.DecCopy sdk.Dec
default: 67%

Multiplier specifying the portion of burden seigniorage needed to bear the overall reward profile for Reward Weight updates during epoch transition.

MiningIncrement

type: sdk.DecCopy sdk.Dec
default: 1.07 growth rate, 15% CAGR of $\tau$

Multiplier determining an annual growth rate for tax rate policy updates during epoch transition.

WindowShort

type: int64Copy int64
default: 4Copy 4 (month = 4 weeks)

A number of epochs that specifies a time interval for calculating the short-term moving average.

WindowLong

type: int64Copy int64
default: 52Copy 52 (year = 52 weeks)

A number of epochs that specifies a time interval for calculating the long-term moving average.

WindowProbation

type: int64Copy int64
default: 18Copy 18

A number of epochs that specifies a time interval for the probationary period.