bex

Abstract

This document specifies the x/bex module, which allows defining coin exchange pairs for Guru station.

This module has been designed to define exchange pairs with liquidity and exchange rates for coin exchange operation through Guru station.

For enabling the coin exchange through Guru station, the exchange pairs need to be registered in the x/bex module by the exchange admins and liquidity must be maintained.

Contents

1. Concepts
2. State
3. Keeper
4. Hooks
5. Events
6. Clients

Concepts

Exchanges

The Exchange defines the type for registering the coin pairs for enabling the inter-chain exchanges through Guru station.

Registering Exchanges

The admins can register new exchanges and maintain them. The basic exchange structure is as follows:

{
    "id": "1",
    "attributes": [
        {
            "key": "attributeKey",
            "value": "attrfibuteValue"
        }
        ...
    ]
}

Required attributes for registering a new exchange:

• admin_address: admin address hosuld be same as the sender
• reserve_address: account address for maintaining the liquidity for the pair
• coin_a_ibc_denom: IBC denom for the first coin (ibc/F3CAC1552411B7B2B093AE360B0AD88DD672B8E2DDB4EF055AC25F8FCC5308B3)
• coin_a_short_denom: short denom for the first coin (ausgx)
• coin_b_ibc_denom: IBC denom for the secodn coin
• coin_b_short_denom: short deno for the second coin
• coin_a_port: first coin IBC port (exchange)
• coin_b_port: first coin IBC channel (channel-0)
• coin_a_channel: second coin IBC port
• coin_b_channel: second coin IBC channel
• a_to_b_rate: exchange rate from first to second coin
• b_to_a_rate: exchange rate froms econd to first coin

Roles

• moderator: has right for registering and managing the admins
• admin: has the right for registering and managing the exchanges

State

The x/bex module keeps in the state variables for maintaining the exchanges history:

	Description	Key	Value	Store
ModeratorAddress	module moderator address	[]byte{1}	[]byte{string}	KV
Exchanges	List fo available exchanges	[]byte{2}	[]Exchnage	KV

Genesis

Moderator Address

If the moderator_address is not defined at the genesis state, the gov module address is defined as the default moderator.

Keeper

The x/bex module provides this exported keeper that can be passed to other modules, which require access to exchanges.

type Keeper interface {
    GetModeratorAddress(ctx sdk.Context) string
    GetRatemeter(ctx sdk.Context) (*types.Ratemeter, error)
    GetExchange(ctx sdk.Context, id math.Int) (*types.Exchange, error)
    GetPaginatedExchanges(ctx sdk.Context, pagination *query.PageRequest) ([]types.Exchange, *query.PageResponse, error)
    GetExchangeAttribute(ctx sdk.Context, id math.Int, key string) (types.Attribute, error)
    GetNextExchangeId(ctx sdk.Context) math.Int
    GetPaginatedAdmins(ctx sdk.Context, pagination *query.PageRequest) ([]string, *query.PageResponse, error)
    IsAdminRegistered(ctx sdk.Context, adminAddr string) bool
}

Hooks

The bex module implements the AfterOracleEnd hooks from the x/oracle module.

The hook is used to update the bex module state by resetting the exchange rates for the pairs.

Events

The x/bex module emits the following events:

MsgRegisterAdmin

Type	Attribute Key	Attribute Value
register_admin	moderator	{moderatorAddress}
register_admin	admin	{adminAddress}

MsgRemoveAdmin

Type	Attribute Key	Attribute Value
remove_admin	moderator	{moderatorAddress}
remove_admin	admin	{adminAddress}

MsgRegisterExchange

Type	Attribute Key	Attribute Value
register_exchange	admin	{adminAddress}
register_exchange	exchange_id	{exchangeId}

MsgUpdateExchange

Type	Attribute Key	Attribute Value
update_exchange	admin	{adminAddress}
update_exchange	exchange_id	{exchangeId}

MsgChangeModerator

Type	Attribute Key	Attribute Value
change_moderator_address	moderator	{moderatorAddress}
change_moderator_address	address	{newModeratorAddress}

Clients

CLI

A user can query and interact with the bex module using the CLI.

Queries

The query commands allow users to query bex state.

Command	Subcommand	Description
query bex	exchanges	Get all exchanges
query bex	admins	Get all admins
query bex	is_admins [address]	Check if the address is admin
query bex	next_exchange_id	Get next exchange id
query bex	moderator_address	Get current moderator address

Transactions

The tx commands allow the moderator ad admins to change the bex state.

Command	Subcommand	Description
tx bex	register_exchange	Register new exchange from json file
tx bex	update_exchange	update existing exhcnage
tx bex	register_admin	Register new admin
tx bex	remove_admin	Remove existing admin
tx bex	update_ratemeter	Update the ratemeter params
tx bex	change_moderator	Change the moderator address