perp

README

Perp Design

cli commands

To see the list of query and transaction commands:

nibid tx perp --help
nibid query perp --help

cli code is within /perp/client/cli

Perp Data Structures

type Position (on a virtual pool)

• size (sdk.Dec): Denominated in vpool.base (y)
• margin (sdk.Dec): Isolated margin
• openNotional (sdk.Dec): Quote asset (x) value of position when opening. The cost of the position.
• lastUpdatedCumulativePremiumFraction (sdk.Dec): For calculating funding payment. Recorded every time a trader opens, reduces, or closes a position
• liquidityHistoryIndex (sdk.Int):
• blockNumber (sdk.Int): Blocker number of the last position.

type LiquidityChangedSnapshot (of a virtual pool)

• cumulativeNotional (sdk.Dec):
• X (sdk.Dec): Quote assets of the virtual pool just before liquidity changed.
• Y (sdk.Dec): Base assets of the virtual pool just before liquidity changed.
• totalPositionSize (sdk.Dec): Total position sized owned by the virtual pool after the last snapshot was taken. Equal to currentBaseReserve - lastLiquidityChangedHistoryItem.baseReserve + prevTotalPositionSize

Clearing House

The ClearingHouse can take several actions that affect the reserves of a virtual pool. Here's a brief description

• AddMargin(vpool string, trader sdk.AccAddress, margin sdk.Int) -> nil: Increase the margin ratio of position by adding margin.
• RemoveMargin(vpool string, trader sdk.AccAddress, margin sdk.Int) -> nil: Decrease the margin ratio of position by removing margin.
• SettlePosition
• OpenPosition(vpool string, isLong bool, yIn sdk.Int, lev sdk.Dec):
• ClosePosition
• Liquidate(vpool string, trader sdk.AccAddress)
• PayFunding
• UnrealizedPnL(vpool string, trader sdk.AccAddress) -> (pnl sdk.Dec)

Virtual Pools (Vpools)

Fields:

• x sdk.DecCoin: Quote reserves. x.Denom is the identifier for the token.
• y sdk.DecCoin: Base reserves. y.Denom is the identifier for the token.
• xAmtLimit:
• yAmtLimit:

Pool creation and annhilation functions:

• CreatePool
• ShutdownPool

Main functions:

• SwapQuoteForBase() -> sdk.Dec
• SwapBaseForQuote() -> sdk.Dec
• SettleFunding() -> sdk.Dec

"Get" functions:

• InputTruePrice() -> (sdk.Dec):
• OutputTruePrice() -> (sdk.Dec):
• InputPrice() -> (sdk.Dec):
• OutputPrice() -> (sdk.Dec):
• InputPriceAtReserves(x, y, inY) -> (sdk.Dec):
• OutputPriceAtReserves(x, y, outX) -> ( sdk.Dec):

Perp Ecosystem Fund (PerpEF)

The PerpEF is a module account on Nibiru Protocol. All of its interactions can be encapsulated in two keeper methods.

• WithdrawFromPerpEF()
• DepositToPerpEF()

Queries

QueryPositionInfo

Given the vpool and trader, one could query the QueryPositionInfo(vpool string, trader sdk.AccAddress) -> PositionInfo

// A single trader's position information on a given Vpool.
type PositionInfo struct {
  MarginRatio sdk.Dec
  Position perptypes.Position
}

QueryAllVpools

QueryAllVpools() -> []string: Returns a list of all of the pool names.

QueryVpoolPrices

QueryVpoolPrices() -> map[string]sdk.Dec: Returns ech virtual pool and its corresponding price.

Documentation

Index

• func ExportGenesis(ctx sdk.Context, k keeper.Keeper) *types.GenesisState
• func InitGenesis(ctx sdk.Context, k keeper.Keeper, genState types.GenesisState)
• func NewHandler(k keeper.Keeper) sdk.Handler
• type AppModule
  • func NewAppModule(cdc codec.Codec, keeper keeper.Keeper, ak types.AccountKeeper, ...) AppModule
  • func (am AppModule) BeginBlock(_ sdk.Context, _ abci.RequestBeginBlock)
  • func (AppModule) ConsensusVersion() uint64
  • func (am AppModule) EndBlock(ctx sdk.Context, _ abci.RequestEndBlock) []abci.ValidatorUpdate
  • func (am AppModule) ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec) json.RawMessage
  • func (am AppModule) InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, gs json.RawMessage) []abci.ValidatorUpdate
  • func (am AppModule) LegacyQuerierHandler(legacyQuerierCdc *codec.LegacyAmino) sdk.Querier
  • func (am AppModule) Name() string
  • func (AppModule) QuerierRoute() string
  • func (am AppModule) RegisterInvariants(_ sdk.InvariantRegistry)
  • func (am AppModule) RegisterServices(cfg module.Configurator)
  • func (am AppModule) Route() sdk.Route
• type AppModuleBasic
  • func NewAppModuleBasic(binaryCodec codec.BinaryCodec) AppModuleBasic
  • func (AppModuleBasic) DefaultGenesis(cdc codec.JSONCodec) json.RawMessage
  • func (AppModuleBasic) GetQueryCmd() *cobra.Command
  • func (a AppModuleBasic) GetTxCmd() *cobra.Command
  • func (AppModuleBasic) Name() string
  • func (AppModuleBasic) RegisterCodec(aminoCodec *codec.LegacyAmino)
  • func (AppModuleBasic) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *runtime.ServeMux)
  • func (AppModuleBasic) RegisterInterfaces(interfaceRegistry codectypes.InterfaceRegistry)
  • func (AppModuleBasic) RegisterLegacyAminoCodec(aminoCodec *codec.LegacyAmino)
  • func (AppModuleBasic) RegisterRESTRoutes(clientCtx client.Context, rtr *mux.Router)
  • func (AppModuleBasic) ValidateGenesis(cdc codec.JSONCodec, config client.TxEncodingConfig, bz json.RawMessage) error

Functions

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/perp" 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.PricefeedKeeper,
) 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) 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) QuerierRoute

func (AppModule) QuerierRoute() string

QuerierRoute returns the capability module's query routing key.

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) Route

func (am AppModule) Route() sdk.Route

Route returns the capability module's message routing key.

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 perp 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.