proto - perp

Table of Contents

• nibiru/perp/v2/event.proto

  • AmmUpdatedEvent

  • EventShiftPegMultiplier

  • EventShiftSwapInvariant

  • FundingRateChangedEvent

  • LiquidationFailedEvent

  • MarketUpdatedEvent

  • PositionChangedEvent

  • PositionLiquidatedEvent

  • PositionSettledEvent

  • LiquidationFailedEvent.LiquidationFailedReason

• nibiru/perp/v2/genesis.proto

  • GenesisMarketLastVersion
  • GenesisPosition
  • GenesisState
  • GenesisState.CustomDiscount
  • GenesisState.Discount
  • GenesisState.GlobalVolume
  • GenesisState.TraderVolume

• nibiru/perp/v2/query.proto

  • AccountWithBalance

  • AmmMarket

  • QueryCollateralRequest

  • QueryCollateralResponse

  • QueryMarketsRequest

  • QueryMarketsResponse

  • QueryModuleAccountsRequest

  • QueryModuleAccountsResponse

  • QueryPositionRequest

  • QueryPositionResponse

  • QueryPositionStoreRequest

  • QueryPositionStoreResponse

  • QueryPositionsRequest

  • QueryPositionsResponse

  • Query

• nibiru/perp/v2/state.proto

  • AMM

  • DNRAllocation

  • Market

  • MarketLastVersion

  • Position

  • ReserveSnapshot

  • Direction

  • TwapCalcOption

• nibiru/perp/v2/tx.proto

  • MsgAddMargin

  • MsgAddMarginResponse

  • MsgAllocateEpochRebates

  • MsgAllocateEpochRebatesResponse

  • MsgChangeCollateralDenom

  • MsgChangeCollateralDenomResponse

  • MsgClosePosition

  • MsgClosePositionResponse

  • MsgDonateToEcosystemFund

  • MsgDonateToEcosystemFundResponse

  • MsgMarketOrder

  • MsgMarketOrderResponse

  • MsgMultiLiquidate

  • MsgMultiLiquidate.Liquidation

  • MsgMultiLiquidateResponse

  • MsgMultiLiquidateResponse.LiquidationResponse

  • MsgPartialClose

  • MsgPartialCloseResponse

  • MsgRemoveMargin

  • MsgRemoveMarginResponse

  • MsgSettlePosition

  • MsgShiftPegMultiplier

  • MsgShiftPegMultiplierResponse

  • MsgShiftSwapInvariant

  • MsgShiftSwapInvariantResponse

  • MsgWithdrawEpochRebates

  • MsgWithdrawEpochRebatesResponse

  • Msg

• Scalar Value Types

Top

nibiru/perp/v2/event.proto

AmmUpdatedEvent

This event is emitted when the amm is updated, which can be triggered by the following events:

• swap
• edit price multiplier
• edit depth

Field	Type	Label	Description
final_amm	AMM		the final state of the AMM
mark_price_twap	string		The mark price of the pair.
index_price_twap	string		The oracle index price of the pair.

EventShiftPegMultiplier

EventShiftPegMultiplier: ABCI event emitted from MsgShiftPegMultiplier

Field	Type	Label	Description
old_peg_multiplier	string
new_peg_multiplier	string
cost_paid	cosmos.base.v1beta1.Coin

EventShiftSwapInvariant

EventShiftSwapInvariant: ABCI event emitted from MsgShiftSwapInvariant

Field	Type	Label	Description
old_swap_invariant	string
new_swap_invariant	string
cost_paid	cosmos.base.v1beta1.Coin

FundingRateChangedEvent

Emitted when the funding rate changes for a market.

Field	Type	Label	Description
pair	string		The pair for which the funding rate was calculated.
mark_price_twap	string		The mark price of the pair.
index_price_twap	string		The oracle index price of the pair.
premium_fraction	string		The latest premium fraction just calculated.
cumulative_premium_fraction	string		The market's latest cumulative premium fraction. The funding payment a position will pay is the difference between this value and the latest cumulative premium fraction on the position, multiplied by the position size.

LiquidationFailedEvent

Emitted when liquidation fails.

Field	Type	Label	Description
pair	string		The pair for which we are trying to liquidate.
trader	string		owner of the position.
liquidator	string		Address of the account that executed the tx.
reason	LiquidationFailedEvent.LiquidationFailedReason		Reason for the liquidation failure.

MarketUpdatedEvent

This event is emitted at the end of every block for persisting market changes off-chain

Market changes are triggered by the following actions:

• disabling market
• changing market fees
• bad debt is prepaid by the ecosystem fund

Field	Type	Label	Description
final_market	Market		the final state of the market

PositionChangedEvent

Emitted when a position changes.

Field	Type	Label	Description
final_position	Position
position_notional	string		Position notional (in quote units) after the change. In general, 'notional = baseAmount * priceQuotePerBase', where size is the baseAmount.
transaction_fee	cosmos.base.v1beta1.Coin		Transaction fee paid. A "taker" fee.
realized_pnl	string		realize profits and losses after the change
bad_debt	cosmos.base.v1beta1.Coin		Amount of bad debt cleared by the PerpEF during the change. Bad debt is negative net margin past the liquidation point of a position.
funding_payment	string		A funding payment made or received by the trader on the current position. 'fundingPayment' is positive if 'owner' is the sender and negative if 'owner' is the receiver of the payment. Its magnitude is abs(size * fundingRate). Funding payments act to converge the mark price and index price (average price on major exchanges).
block_height	int64		The block number at which this position was changed.
margin_to_user	string		margin_to_user is the amount of collateral received by the trader during the position change. A positve value indicates that the trader received funds, while a negative value indicates that the trader spent funds.
change_reason	string		change_reason describes the reason for why the position resulted in a change. Change type can take the following values:

• CHANGE_REASON_UNSPECIFIED: Unspecified change reason. - CHANGE_REASON_ADD_MARGIN: Margin was added to the position. - CHANGE_REASON_REMOVE_MARGIN: Margin was removed from the position. - CHANGE_REASON_OPEN_POSITION: A new position was opened. - CHANGE_REASON_CLOSE_POSITION: An existing position was closed. | | exchanged_size | string | | exchanged_size represent the change in size for an existing position after the change. A positive value indicates that the position size increased, while a negative value indicates that the position size decreased. | | exchanged_notional | string | | exchanged_notional represent the change in notional for an existing position after the change. A positive value indicates that the position notional increased, while a negative value indicates that the position notional decreased. |

PositionLiquidatedEvent

Emitted when a position is liquidated. Wraps a PositionChanged event since a liquidation causes position changes.

Field	Type	Label	Description
position_changed_event	PositionChangedEvent
liquidator_address	string		Address of the account that executed the tx.
fee_to_liquidator	cosmos.base.v1beta1.Coin		Commission (in margin units) received by 'liquidator'.
fee_to_ecosystem_fund	cosmos.base.v1beta1.Coin		Commission (in margin units) given to the ecosystem fund.

PositionSettledEvent

Emitted when a position is settled.

Field	Type	Label	Description
pair	string		Identifier for the virtual pool of the position.
trader_address	string		Owner of the position.
settled_coins	cosmos.base.v1beta1.Coin	repeated	Settled coin as dictated by the settlement price of the perp.amm.

LiquidationFailedEvent.LiquidationFailedReason

Name	Number	Description
UNSPECIFIED	0
POSITION_HEALTHY	1	the position is healthy and does not need to be liquidated.
NONEXISTENT_PAIR	2	the pair does not exist.
NONEXISTENT_POSITION	3	the position does not exist.

Top

nibiru/perp/v2/genesis.proto

GenesisMarketLastVersion

GenesisMarketLastVersion is the last version including pair only used for genesis

Field	Type	Label	Description
pair	string
version	uint64

GenesisPosition

Field	Type	Label	Description
pair	string
version	uint64
position	Position

GenesisState

GenesisState defines the perp module's genesis state. Thge genesis state is used not only to start the network but also useful for exporting and importing state during network upgrades.

Field	Type	Label	Description
markets	Market	repeated
amms	AMM	repeated
positions	GenesisPosition	repeated
reserve_snapshots	ReserveSnapshot	repeated
dnr_epoch	uint64
collateral_denom	string		For testing purposes, we allow the collateral to be set at genesis
trader_volumes	GenesisState.TraderVolume	repeated
global_discount	GenesisState.Discount	repeated
custom_discounts	GenesisState.CustomDiscount	repeated
market_last_versions	GenesisMarketLastVersion	repeated
global_volumes	GenesisState.GlobalVolume	repeated
rebates_allocations	DNRAllocation	repeated
dnr_epoch_name	string

GenesisState.CustomDiscount

Field	Type	Label	Description
trader	string
discount	GenesisState.Discount

GenesisState.Discount

Field	Type	Label	Description
fee	string
volume	string

GenesisState.GlobalVolume

Field	Type	Label	Description
epoch	uint64
volume	string

GenesisState.TraderVolume

Field	Type	Label	Description
trader	string
epoch	uint64
volume	string

Top

nibiru/perp/v2/query.proto

AccountWithBalance

Field	Type	Label	Description
name	string
address	string
balance	cosmos.base.v1beta1.Coin	repeated

AmmMarket

Field	Type	Label	Description
market	Market
amm	AMM

QueryCollateralRequest

QueryCollateralRequest: Request type for the "nibiru.perp.v2.Query/Collateral" gRPC service method

QueryCollateralResponse

QueryCollateralRequest: Response type for the "nibiru.perp.v2.Query/Collateral" gRPC service method

Field	Type	Label	Description
collateral_denom	string

QueryMarketsRequest

Field	Type	Label	Description
versioned	bool

QueryMarketsResponse

Field	Type	Label	Description
amm_markets	AmmMarket	repeated

QueryModuleAccountsRequest

QueryModuleAccountsRequest: Request type for the "nibiru.perp.v2.Query/ModuleAccounts" gRPC service method

QueryModuleAccountsResponse

QueryModuleAccountsResponse: Response type for the "nibiru.perp.v2.Query/ModuleAccounts" gRPC service method

Field	Type	Label	Description
accounts	AccountWithBalance	repeated

QueryPositionRequest

QueryPositionRequest: Request type for the "nibiru.perp.v2.Query/Position" gRPC service method

Field	Type	Label	Description
pair	string
trader	string

QueryPositionResponse

QueryPositionResponse: Response type for the "nibiru.perp.v2.Query/Position" gRPC service method

Field	Type	Label	Description
position	Position		The position as it exists in the blockchain state
position_notional	string		The position's current notional value, if it were to be entirely closed (in margin units).
unrealized_pnl	string		The position's unrealized PnL.
margin_ratio	string		margin ratio of the position based on the spot price

QueryPositionStoreRequest

QueryPositionStoreRequest: Request type for the "nibiru.perp.v2.Query/PositionStore" gRPC service method

Field	Type	Label	Description
pagination	cosmos.base.query.v1beta1.PageRequest		pagination defines a paginated request

QueryPositionStoreResponse

QueryPositionStoreResponse: Response type for the "nibiru.perp.v2.Query/PositionStore" gRPC service method

Field	Type	Label	Description
positions	Position	repeated	Position responses: collection of all stored positions (with pagination)
pagination	cosmos.base.query.v1beta1.PageResponse		pagination defines a paginated response

QueryPositionsRequest

QueryPositionsRequest: Request type for the "nibiru.perp.v2.Query/Positions" gRPC service method

Field	Type	Label	Description
trader	string

QueryPositionsResponse

QueryPositionsResponse: Response type for the "nibiru.perp.v2.Query/Positions" gRPC service method

Field	Type	Label	Description
positions	QueryPositionResponse	repeated

Query

Query defines the gRPC querier service.

Method Name	Request Type	Response Type	Description
QueryPosition	QueryPositionRequest	QueryPositionResponse	QueryPosition: Query one position on the given market for a user
QueryPositions	QueryPositionsRequest	QueryPositionsResponse	QueryPositions: Query all positions for a user
QueryPositionStore	QueryPositionStoreRequest	QueryPositionStoreResponse	QueryPositionStore queries all of the positions in the KV store.
ModuleAccounts	QueryModuleAccountsRequest	QueryModuleAccountsResponse	Queries the module accounts for x/perp
QueryMarkets	QueryMarketsRequest	QueryMarketsResponse	QueryMarkets: Query all markets
QueryCollateral	QueryCollateralRequest	QueryCollateralResponse	QueryCollateral: Queries info about the collateral

Top

nibiru/perp/v2/state.proto

AMM

Field	Type	Label	Description
pair	string		identifies the market this AMM belongs to
version	uint64		the version of the AMM, only one AMM can exist per pair, when one is closed it cannot be reactivated, so a new AMM must be created, this is the version of the AMM
base_reserve	string		the amount of base reserves this AMM has
quote_reserve	string		the amount of quote reserves this AMM has
sqrt_depth	string		sqrt(k)
price_multiplier	string		the price multiplier of the dynamic AMM
total_long	string		Total long refers to the sum of long open notional in base.
total_short	string		Total short refers to the sum of short open notional in base.
settlement_price	string		The settlement price if the AMM is settled.

DNRAllocation

DNRAllocation represents a rebates allocation for a given epoch.

Field	Type	Label	Description
epoch	uint64		epoch defines the reference epoch for the allocation.
amount	cosmos.base.v1beta1.Coin	repeated	amount of DNR allocated for the epoch.

Market

Field	Type	Label	Description
pair	string		the trading pair represented by this market always BASE:QUOTE, e.g. BTC:NUSD or ETH:NUSD
enabled	bool		whether or not the market is enabled
version	uint64		the version of the Market, only one market can exist per pair, when one is closed it cannot be reactivated, so a new market must be created, this is the version of the market
maintenance_margin_ratio	string		the minimum margin ratio which a user must maintain on this market
max_leverage	string		the maximum leverage a user is able to be taken on this market
latest_cumulative_premium_fraction	string		Latest cumulative premium fraction for a given pair. Calculated once per funding rate interval. A premium fraction is the difference between mark and index, divided by the number of payments per day. (mark - index) / # payments in a day
exchange_fee_ratio	string		the percentage of the notional given to the exchange when trading
ecosystem_fund_fee_ratio	string		the percentage of the notional transferred to the ecosystem fund when trading
liquidation_fee_ratio	string		the percentage of liquidated position that will be given to out as a reward. Half of the liquidation fee is given to the liquidator, and the other half is given to the ecosystem fund.
partial_liquidation_ratio	string		the portion of the position size we try to liquidate if the available margin is higher than liquidation fee
funding_rate_epoch_id	string		specifies the interval on which the funding rate is updated
twap_lookback_window	google.protobuf.Duration		amount of time to look back for TWAP calculations
prepaid_bad_debt	cosmos.base.v1beta1.Coin		the amount of collateral already credited from the ecosystem fund
max_funding_rate	string		the maximum funding rate payment per epoch, this represents the maximum amount of funding that can be paid out per epoch as a percentage of the position size

MarketLastVersion

MarketLastVersion is used to store the last version of the market

Field	Type	Label	Description
version	uint64		version of the market

Position

Field	Type	Label	Description
trader_address	string		address identifies the address owner of this position
pair	string		pair identifies the pair associated with this position
size	string		the position size
margin	string		amount of margin remaining in the position
open_notional	string		value of position in quote assets when opened
latest_cumulative_premium_fraction	string		The most recent cumulative premium fraction this position has. Used to calculate the next funding payment.
last_updated_block_number	int64		last block number this position was updated

ReserveSnapshot

a snapshot of the perp.amm's reserves at a given point in time

Field	Type	Label	Description
amm	AMM
timestamp_ms	int64		milliseconds since unix epoch

Direction

The direction that the user is trading in LONG means the user is going long the base asset (e.g. buy BTC) SHORT means the user is shorting the base asset (e.g. sell BTC)

Name	Number	Description
DIRECTION_UNSPECIFIED	0
LONG	1
SHORT	2

TwapCalcOption

Enumerates different options of calculating twap.

Name	Number	Description
TWAP_CALC_OPTION_UNSPECIFIED	0
SPOT	1	Spot price from quote asset reserve / base asset reserve
QUOTE_ASSET_SWAP	2	Swapping with quote assets, output denominated in base assets
BASE_ASSET_SWAP	3	Swapping with base assets, output denominated in quote assets

Top

nibiru/perp/v2/tx.proto

MsgAddMargin

MsgAddMargin: Msg to remove margin.

Field	Type	Label	Description
sender	string
pair	string
margin	cosmos.base.v1beta1.Coin

MsgAddMarginResponse

Field	Type	Label	Description
funding_payment	string
position	Position

MsgAllocateEpochRebates

-------------------------- AllocateEpochRebates --------------------------

Field	Type	Label	Description
sender	string
rebates	cosmos.base.v1beta1.Coin	repeated	rebates to allocate

MsgAllocateEpochRebatesResponse

Field	Type	Label	Description
total_epoch_rebates	cosmos.base.v1beta1.Coin	repeated

MsgChangeCollateralDenom

MsgChangeCollateralDenom: Changes the collateral denom for the module. [Admin] Only callable by sudoers.

Field	Type	Label	Description
sender	string
new_denom	string

MsgChangeCollateralDenomResponse

MsgClosePosition

Field	Type	Label	Description
sender	string
pair	string

MsgClosePositionResponse

Field	Type	Label	Description
exchanged_notional_value	string		The amount of quote assets exchanged.
exchanged_position_size	string		The amount of base assets exchanged.
funding_payment	string		The funding payment applied on this position change, measured in quote units.
realized_pnl	string		The amount of PnL realized on this position changed, measured in quote units.
margin_to_trader	string		The amount of margin the trader receives after closing the position, from the vault. Should never be negative.

MsgDonateToEcosystemFund

Field	Type	Label	Description
sender	string
donation	cosmos.base.v1beta1.Coin		donation to the EF

MsgDonateToEcosystemFundResponse

MsgMarketOrder

Field	Type	Label	Description
sender	string
pair	string
side	Direction
quote_asset_amount	string
leverage	string
base_asset_amount_limit	string

MsgMarketOrderResponse

Field	Type	Label	Description
position	Position
exchanged_notional_value	string		The amount of quote assets exchanged.
exchanged_position_size	string		The amount of base assets exchanged.
funding_payment	string		The funding payment applied on this position change, measured in quote units.
realized_pnl	string		The amount of PnL realized on this position changed, measured in quote units.
unrealized_pnl_after	string		The unrealized PnL in the position after the position change, measured in quote units.
margin_to_vault	string		The amount of margin the trader has to give to the vault. A negative value means the vault pays the trader.
position_notional	string		The position's notional value after the position change, measured in quote units.

MsgMultiLiquidate

Field	Type	Label	Description
sender	string
liquidations	MsgMultiLiquidate.Liquidation	repeated

MsgMultiLiquidate.Liquidation

Field	Type	Label	Description
pair	string
trader	string

MsgMultiLiquidateResponse

Field	Type	Label	Description
liquidations	MsgMultiLiquidateResponse.LiquidationResponse	repeated

MsgMultiLiquidateResponse.LiquidationResponse

Field	Type	Label	Description
success	bool
error	string
liquidator_fee	cosmos.base.v1beta1.Coin		nullable since no fee is taken on failed liquidation
perp_ef_fee	cosmos.base.v1beta1.Coin		perp ecosystem fund
trader	string
pair	string

MsgPartialClose

Field	Type	Label	Description
sender	string
pair	string
size	string

MsgPartialCloseResponse

Field	Type	Label	Description
exchanged_notional_value	string		The amount of quote assets exchanged.
exchanged_position_size	string		The amount of base assets exchanged.
funding_payment	string		The funding payment applied on this position change, measured in quote units.
realized_pnl	string		The amount of PnL realized on this position changed, measured in quote units.
margin_to_trader	string		The amount of margin the trader receives after closing the position, from the vault. Should never be negative.

MsgRemoveMargin

MsgRemoveMargin: Msg to remove margin.

Field	Type	Label	Description
sender	string
pair	string
margin	cosmos.base.v1beta1.Coin

MsgRemoveMarginResponse

Field	Type	Label	Description
margin_out	cosmos.base.v1beta1.Coin		tokens transferred back to the trader
funding_payment	string		the funding payment applied on this position interaction
position	Position		The resulting position

MsgSettlePosition

MsgSettlePosition: Msg to remove margin.

Field	Type	Label	Description
sender	string
pair	string
version	uint64

MsgShiftPegMultiplier

ShiftPegMultiplier: gRPC tx msg for changing the peg multiplier. Admin-only.

Field	Type	Label	Description
sender	string
pair	string
new_peg_mult	string

MsgShiftPegMultiplierResponse

MsgShiftSwapInvariant

ShiftSwapInvariant: gRPC tx msg for changing the swap invariant. Admin-only.

Field	Type	Label	Description
sender	string
pair	string
new_swap_invariant	string

MsgShiftSwapInvariantResponse

MsgWithdrawEpochRebates

-------------------------- WithdrawEpochRebates --------------------------

Field	Type	Label	Description
sender	string
epochs	uint64	repeated

MsgWithdrawEpochRebatesResponse

Field	Type	Label	Description
withdrawn_rebates	cosmos.base.v1beta1.Coin	repeated

Msg

Msg defines the x/perp Msg service.

Method Name	Request Type	Response Type	Description
RemoveMargin	MsgRemoveMargin	MsgRemoveMarginResponse
AddMargin	MsgAddMargin	MsgAddMarginResponse
MultiLiquidate	MsgMultiLiquidate	MsgMultiLiquidateResponse
MarketOrder	MsgMarketOrder	MsgMarketOrderResponse
ClosePosition	MsgClosePosition	MsgClosePositionResponse
PartialClose	MsgPartialClose	MsgPartialCloseResponse
SettlePosition	MsgSettlePosition	MsgClosePositionResponse
DonateToEcosystemFund	MsgDonateToEcosystemFund	MsgDonateToEcosystemFundResponse
ChangeCollateralDenom	MsgChangeCollateralDenom	MsgChangeCollateralDenomResponse	ChangeCollateralDenom: Updates the collateral denom. A denom is valid if it is possible to make an sdk.Coin using it. [Admin] Only callable by sudoers.
AllocateEpochRebates	MsgAllocateEpochRebates	MsgAllocateEpochRebatesResponse
WithdrawEpochRebates	MsgWithdrawEpochRebates	MsgWithdrawEpochRebatesResponse
ShiftPegMultiplier	MsgShiftPegMultiplier	MsgShiftPegMultiplierResponse	ShiftPegMultiplier: gRPC tx msg for changing a market's peg multiplier. [Admin] Only callable by sudoers.
ShiftSwapInvariant	MsgShiftSwapInvariant	MsgShiftSwapInvariantResponse	ShiftSwapInvariant: gRPC tx msg for changing a market's swap invariant. [Admin] Only callable by sudoers.

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)