stablecoin

package
v0.20.0-beta.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 20, 2023 License: Apache-2.0 Imports: 22 Imported by: 0

README

x/stablecoin

The stablecoin module is responsible for minting and burning NUSD, maintenance of NUSD's price stability, and orchestration of Nibiru Protocol's collateral ratio.

Table of Contents
  • CLI Usage Guide
  • Concepts
    • Recollateralize: Recollateralize is a function that incentivizes the caller to add up to the amount of collateral needed to reach some target collateral ratio (collRatioTarget).
    • Buybacks: A user can call Buyback when there's too much collateral in the protocol according to the target collateral ratio. The user swaps NIBI for UST at a 0% transaction fee and the protocol burns the NIBI it buys from the user.
  • Messages and Events: [description]
  • Keepers and Parameters: [description]
  • Module Accounts of x/stablecoin: [description]

CLI Usage Guide

Minting Stablecoins

In a new terminal, run the following command:

// send a transaction to mint stablecoin
$ nibid tx stablecoin mint 1000validatortoken --from validator --home data/localnet --chain-id localnet

// query the balance
$ nibid q bank balances cosmos1zaavvzxez0elundtn32qnk9lkm8kmcszzsv80v

Concepts

Recollateralize

Recollateralize is a function that incentivizes the caller to add up to the amount of collateral needed to reach some target collateral ratio (collRatioTarget). Recollateralize checks if the USD value of collateral in the protocol is below the required amount defined by the current collateral ratio. Here, Nibiru's NUSD stablecoin is taken to be the dollar that determines USD value.

collRatio: The collateral ratio, or 'collRatio' (sdk.Dec), is a value beteween 0 and 1 that determines what proportion of collateral and governance token is used during stablecoin mints and burns.

How much collateral is needed to reach a certain collRatio?

Suppose an amount supplyNUSD of NUSD is in circulation at $1 at some inital collateral ratio, collRatioStart. The total USD value of the collateral in Nibiru is denoted collUSDVal. If NUSD falls in price below the lower band, the collateral ratio will increase to collRatioTarget, which is the target ratio.

In order to reach the target collRatioTarget with a constant supplyNUSD, more collateral needs to be added to the system. This amount can be given by:

collUSDValEnd := supplyNUSD * collRatioEnd
collNeeded := collUSDValEnd - collUSDVal
Incentives for the caller of Recollateralize

The caller is given bonus NIBI for bringing the value of the protocol's collateral up to the appropriate value as defined by collRatioTarget. This bonus rate is some percentage of the collateral value provided.

Let:

  • collNeeded (sdk.Int): Amount of collateral needed to reach the target collRatio.
  • priceColl (sdk.Dec): USD price of the collateral
  • priceNIBI (sdk.Dec): USD price of NIBI.
  • bonusRate (sdk.Dec): Defaults to 0.2% (20 bps). The bonus rate gives the caller an incentive to recollateralize Nibiru to the target collRatioTarget.

Thus, the caller receives an amount of NIBI, nibiOut:

nibiOut * priceNIBI = (collNeeded * priceColl) * (1 + bonusRate)
nibiOut = (collNeeded * priceColl) * (1 + bonusRate) / priceNIBI
Implementation

See [collateral_ratio.go]

References:

Buybacks

TLDR: A user can call Buyback when there's too much collateral in the protocol according to the target collateral ratio. The user swaps NIBI for UST at a 0% transaction fee and the protocol burns the NIBI it buys from the user.

collRatio: The collateral ratio, or collRatio (sdk.Dec), is a value beteween 0 and 1 that determines what proportion of collateral and governance token is used during stablecoin mints and burns.

liqRatio: The liquidity ratio, or liqRatio (sdk.Dec), is a the proportion of the circulating NIBI liquidity relvative to the NUSD (stable) value.

When is a "buyback" possible?

The protocol has too much collateral. Here, "protocol" refers to the module account of the x/stablecoin module, and "too much" refers to the difference between the collRatio and liqRatio.

For example, if there's 10M NUSD in circulation, the price of UST collateral is 0.99 NUSD per UST, and the protocol has 5M UST, the liqRatio would be (5M * 0.99) / 10M = 0.495.
Thus, if the collateral ratio, or collRatio, is less than 0.495, the an address with sufficient funds can call Buyback.

How does a buyback work?

The protocol has an excess of collateral. Buybacks allow users to sell NIBI to the protocol in exchange for NUSD, meaning that Nibiru Chain is effectively buying back its shares. After this transfer, the NIBI purchased by protocol is burned. This raises the value of the NIBI token for all of its hodlers.

  • Unlike Recollateralize, there is no bonus rate for this transaction.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EndBlocker added in v0.1.0 

func EndBlocker(ctx sdk.Context, k keeper.Keeper)

EndBlocker updates the current oracle

func ExportGenesis 

func ExportGenesis(ctx sdk.Context, k keeper.Keeper) *types.GenesisState

ExportGenesis returns the capability module's exported genesis.

func InitGenesis 

func InitGenesis(ctx sdk.Context, k keeper.Keeper, genState types.GenesisState)

InitGenesis initializes the capability module's state from a provided genesis state.

func NewHandler 

func NewHandler(k keeper.Keeper) sdk.Handler

NewHandler returns an sdk.Handler for "x/stablecoin" messages. A handler defines the core state transition functions of an application. First, the handler performs stateful checks to make sure each 'msg' is valid. At this stage, the 'msg.ValidateBasic()' method has already been called, meaning stateless checks on the message (like making sure parameters are correctly formatted) have already been performed.

Types

type AppModule 

type AppModule struct {
	AppModuleBasic
	// contains filtered or unexported fields
}

AppModule implements the AppModule interface for the module.

func NewAppModule 

func NewAppModule(
	cdc codec.Codec,
	keeper keeper.Keeper,
	ak types.AccountKeeper,
	bk types.BankKeeper,
	pk types.OracleKeeper,
) AppModule

func (AppModule) BeginBlock 

func (am AppModule) BeginBlock(_ sdk.Context, _ abci.RequestBeginBlock)

BeginBlock executes all ABCI BeginBlock logic respective to the capability module.

func (AppModule) ConsensusVersion 

func (AppModule) ConsensusVersion() uint64

ConsensusVersion implements ConsensusVersion.

func (AppModule) EndBlock 

func (am AppModule) EndBlock(ctx sdk.Context, _ abci.RequestEndBlock) []abci.ValidatorUpdate

EndBlock executes all ABCI EndBlock logic respective to the capability module. It returns no validator updates.

func (AppModule) ExportGenesis 

func (am AppModule) ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec) json.RawMessage

ExportGenesis returns the capability module's exported genesis state as raw JSON bytes.

func (AppModule) GenerateGenesisState 

func (AppModule) GenerateGenesisState(simState *module.SimulationState)

GenerateGenesisState creates a randomized GenState of the module

func (AppModule) InitGenesis 

func (am AppModule) InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, gs json.RawMessage) []abci.ValidatorUpdate

InitGenesis performs the capability module's genesis initialization It returns no validator updates.

func (AppModule) LegacyQuerierHandler 

func (am AppModule) LegacyQuerierHandler(legacyQuerierCdc *codec.LegacyAmino) sdk.Querier

LegacyQuerierHandler returns the capability module's Querier.

func (AppModule) Name 

func (am AppModule) Name() string

Name returns the capability module's name.

func (AppModule) ProposalContents 

func (AppModule) ProposalContents(_ module.SimulationState) []simtypes.WeightedProposalContent

ProposalContents doesn't return any content functions for governance proposals

func (AppModule) QuerierRoute 

func (AppModule) QuerierRoute() string

QuerierRoute returns the capability module's query routing key.

func (AppModule) RandomizedParams 

func (am AppModule) RandomizedParams(_ *rand.Rand) []simtypes.ParamChange

RandomizedParams creates randomized param changes for the simulator

func (AppModule) RegisterInvariants 

func (am AppModule) RegisterInvariants(_ sdk.InvariantRegistry)

RegisterInvariants registers the capability module's invariants.

func (AppModule) RegisterServices 

func (am AppModule) RegisterServices(cfg module.Configurator)

RegisterServices registers a GRPC query service to respond to the module-specific GRPC queries.

func (AppModule) RegisterStoreDecoder 

func (am AppModule) RegisterStoreDecoder(_ sdk.StoreDecoderRegistry)

RegisterStoreDecoder registers a decoder

func (AppModule) Route 

func (am AppModule) Route() sdk.Route

Route returns the capability module's message routing key.

func (AppModule) WeightedOperations 

func (am AppModule) WeightedOperations(
	simState module.SimulationState,
) []simtypes.WeightedOperation

WeightedOperations returns the all the gov module operations with their respective weights.

type AppModuleBasic 

type AppModuleBasic struct {
	// contains filtered or unexported fields
}

func NewAppModuleBasic 

func NewAppModuleBasic(binaryCodec codec.BinaryCodec) AppModuleBasic

func (AppModuleBasic) DefaultGenesis 

func (AppModuleBasic) DefaultGenesis(cdc codec.JSONCodec) json.RawMessage

DefaultGenesis returns default genesis state as raw bytes for the erc20 module.

func (AppModuleBasic) GetQueryCmd 

func (AppModuleBasic) GetQueryCmd() *cobra.Command

GetQueryCmd returns the capability module's root query command.

func (AppModuleBasic) GetTxCmd 

func (a AppModuleBasic) GetTxCmd() *cobra.Command

GetTxCmd returns the capability module's root tx command.

func (AppModuleBasic) Name 

func (AppModuleBasic) Name() string

func (AppModuleBasic) RegisterCodec 

func (AppModuleBasic) RegisterCodec(aminoCodec *codec.LegacyAmino)

func (AppModuleBasic) RegisterGRPCGatewayRoutes 

func (AppModuleBasic) RegisterGRPCGatewayRoutes(
	clientCtx client.Context, mux *runtime.ServeMux,
)

RegisterGRPCGatewayRoutes registers the gRPC Gateway routes for the module.

func (AppModuleBasic) RegisterInterfaces 

func (AppModuleBasic) RegisterInterfaces(interfaceRegistry codectypes.InterfaceRegistry)

RegisterInterfaces registers interfaces and implementations of the stablecoin module.

func (AppModuleBasic) RegisterLegacyAminoCodec 

func (AppModuleBasic) RegisterLegacyAminoCodec(aminoCodec *codec.LegacyAmino)

func (AppModuleBasic) RegisterRESTRoutes 

func (AppModuleBasic) RegisterRESTRoutes(clientCtx client.Context, rtr *mux.Router)

RegisterRESTRoutes registers the capability module's REST service handlers.

func (AppModuleBasic) ValidateGenesis 

func (AppModuleBasic) ValidateGenesis(
	cdc codec.JSONCodec, config client.TxEncodingConfig, bz json.RawMessage,
) error

ValidateGenesis performs genesis state validation for the capability module.

Source Files

View all Source files

Directories

Path Synopsis
client
cli
Package keeper that mints Nibiru stablecoins, maintains their price stability, and ensures that the protocol remains collateralized enough for stablecoins to be redeemed.
 Package keeper that mints Nibiru stablecoins, maintains their price stability, and ensures that the protocol remains collateralized enough for stablecoins to be redeemed.
Package types is a reverse proxy.
 Package types is a reverse proxy.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.