Overview

The Marketmap module is responsible for managing and storing a configuration that informs the Connect oracle of which markets to fetch data for, and which providers to use to fetch them.

Concepts

Authority, Admin, And MarketAuthority

The Marketmap module contains three levels of access to interact with the module.

Authority

The Authority is the only account allowed to change the module’s Params. By default, this account is set to the governance address. However, you may edit the configuration of the module to be any address.

Admin

The Admin can only remove an address from the market authority list via RemoveMarketAuthorities.

MarketAuthority

A MarketAuthority is assigned by the module Authority. There can be any number of market authorities. The market authorities are able to create and update markets in the Marketmap. Specifically, only a MarketAuthority may send the following transactions:

  • CreateMarkets
  • UpdateMarkets
  • UpsertMarkets

Market

A market consists of a Ticker (i.e. BTC/USD) and a list of ProviderConfigs. A Ticker contains data about a specific currency pair. A ProviderConfig contains data that informs the Oracle of how to query for the currency pair in the Ticker.

// Market encapsulates a Ticker and its provider-specific configuration.
type Market struct {
	// Ticker represents a price feed for a given asset pair i.e. BTC/USD. The
	// price feed is scaled to a number of decimal places and has a minimum number
	// of providers required to consider the ticker valid.
	Ticker Ticker `protobuf:"bytes,1,opt,name=ticker,proto3" json:"ticker"`
	// ProviderConfigs is the list of provider-specific configs for this Market.
	ProviderConfigs []ProviderConfig `protobuf:"bytes,2,rep,name=provider_configs,json=providerConfigs,proto3" json:"provider_configs"`
}

ProviderConfig

The Name field refers to one of the providers listed in the Providers document.

type ProviderConfig struct {
	// Name corresponds to the name of the provider for which the configuration is
	// being set.
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// OffChainTicker is the off-chain representation of the ticker i.e. BTC/USD.
	// The off-chain ticker is unique to a given provider and is used to fetch the
	// price of the ticker from the provider.
	OffChainTicker string `protobuf:"bytes,2,opt,name=off_chain_ticker,json=offChainTicker,proto3" json:"off_chain_ticker,omitempty"`
	// NormalizeByPair is the currency pair for this ticker to be normalized by.
	// For example, if the desired Ticker is BTC/USD, this market could be reached
	// using: OffChainTicker = BTC/USDT NormalizeByPair = USDT/USD This field is
	// optional and nullable.
	NormalizeByPair *types.CurrencyPair `protobuf:"bytes,3,opt,name=normalize_by_pair,json=normalizeByPair,proto3" json:"normalize_by_pair,omitempty"`
	// Invert is a boolean indicating if the BASE and QUOTE of the market should
	// be inverted. i.e. BASE -> QUOTE, QUOTE -> BASE
	Invert bool `protobuf:"varint,4,opt,name=invert,proto3" json:"invert,omitempty"`
	// MetadataJSON is a string of JSON that encodes any extra configuration
	// for the given provider config.
	Metadata_JSON string `protobuf:"bytes,15,opt,name=metadata_JSON,json=metadataJSON,proto3" json:"metadata_JSON,omitempty"`
}

Ticker

// Ticker represents a price feed for a given asset pair i.e. BTC/USD. The price
// feed is scaled to a number of decimal places and has a minimum number of
// providers required to consider the ticker valid.
type Ticker struct {
	// CurrencyPair is the currency pair for this ticker.
	CurrencyPair types.CurrencyPair `protobuf:"bytes,1,opt,name=currency_pair,json=currencyPair,proto3" json:"currency_pair"`
	// Decimals is the number of decimal places for the ticker. The number of
	// decimal places is used to convert the price to a human-readable format.
	Decimals uint64 `protobuf:"varint,2,opt,name=decimals,proto3" json:"decimals,omitempty"`
	// MinProviderCount is the minimum number of providers required to consider
	// the ticker valid.
	MinProviderCount uint64 `protobuf:"varint,3,opt,name=min_provider_count,json=minProviderCount,proto3" json:"min_provider_count,omitempty"`
	// Enabled is the flag that denotes if the Ticker is enabled for price
	// fetching by an oracle.
	Enabled bool `protobuf:"varint,14,opt,name=enabled,proto3" json:"enabled,omitempty"`
	// MetadataJSON is a string of JSON that encodes any extra configuration
	// for the given ticker.
	Metadata_JSON string `protobuf:"bytes,15,opt,name=metadata_JSON,json=metadataJSON,proto3" json:"metadata_JSON,omitempty"`
}

Params

Params define the authenticated addresses that can mutate the state of the Marketmap.

// Params defines the parameters for the x/marketmap module.
type Params struct {
	// MarketAuthorities is the list of authority accounts that are able to
	// control updating the marketmap.
	MarketAuthorities []string `protobuf:"bytes,1,rep,name=market_authorities,json=marketAuthorities,proto3" json:"market_authorities,omitempty"`
	// Admin is an address that can remove addresses from the MarketAuthorities
	// list. Only governance can add to the MarketAuthorities or change the Admin.
	Admin string `protobuf:"bytes,2,opt,name=admin,proto3" json:"admin,omitempty"`
}

Messages

The following messages can be included in transactions to mutate the state of the Marketmap.

MsgCreateMarkets

MsgCreateMarket creates a new Market.

// MsgCreateMarkets defines a message carrying a payload for creating markets in
// the x/marketmap module.
type MsgCreateMarkets struct {
	// Authority is the signer of this transaction.  This authority must be
	// authorized by the module to execute the message.
	Authority string `protobuf:"bytes,1,opt,name=authority,proto3" json:"authority,omitempty"`
	// CreateMarkets is the list of all markets to be created for the given
	// transaction.
	CreateMarkets []Market `protobuf:"bytes,2,rep,name=create_markets,json=createMarkets,proto3" json:"create_markets"`
}

MsgUpdateMarkets

MsgUpdateMarkets updates an existing Market.

// MsgUpdateMarkets defines a message carrying a payload for updating the
// x/marketmap module.
type MsgUpdateMarkets struct {
	// Authority is the signer of this transaction.  This authority must be
	// authorized by the module to execute the message.
	Authority string `protobuf:"bytes,1,opt,name=authority,proto3" json:"authority,omitempty"`
	// UpdateMarkets is the list of all markets to be updated for the given
	// transaction.
	UpdateMarkets []Market `protobuf:"bytes,2,rep,name=update_markets,json=updateMarkets,proto3" json:"update_markets"`
}

MsgUpsertMarkets

MsgUpsertMarkets will update a Market if one already exists. If a Market does not exist, it will create one instead.

// MsgUpsertMarkets defines a message carrying a payload for performing market upserts (update or
// create if does not exist) in the x/marketmap module.
type MsgUpsertMarkets struct {
	// Authority is the signer of this transaction.  This authority must be
	// authorized by the module to execute the message.
	Authority string `protobuf:"bytes,1,opt,name=authority,proto3" json:"authority,omitempty"`
	// CreateMarkets is the list of all markets to be created for the given
	// transaction.
	Markets []Market `protobuf:"bytes,2,rep,name=markets,proto3" json:"markets"`
}

MsgParams

MsgParams updates the Marketmap parameters.

// MsgParams defines the Msg/Params request type. It contains the
// new parameters for the x/marketmap module.
type MsgParams struct {
	// Params defines the new parameters for the x/marketmap module.
	Params Params `protobuf:"bytes,1,opt,name=params,proto3" json:"params"`
	// Authority defines the authority that is updating the x/marketmap module
	// parameters.
	Authority string `protobuf:"bytes,2,opt,name=authority,proto3" json:"authority,omitempty"`
}

MsgRemoveMarketAuthorities

MsgRemoveMarketAuthorities removes a market authority from the Params.

// MsgRemoveMarketAuthorities defines the Msg/RemoveMarketAuthoritiesResponse
// request type. It contains the new addresses to remove from the list of
// authorities
type MsgRemoveMarketAuthorities struct {
	// RemoveAddresses is the list of addresses to remove.
	RemoveAddresses []string `protobuf:"bytes,1,rep,name=remove_addresses,json=removeAddresses,proto3" json:"remove_addresses,omitempty"`
	// Admin defines the authority that is the x/marketmap
	// Admin account.  This account is set in the module parameters.
	Admin string `protobuf:"bytes,2,opt,name=admin,proto3" json:"admin,omitempty"`
}

Queries

The following queries are available to retrieve data about the state of the Marketmap.

MarketMap

The Marketmap query returns the full Marketmap in state.

Request:

// MarketMapRequest is the query request for the MarketMap query.
// It takes no arguments.
type MarketMapRequest struct {}

Response:

// MarketMapResponse is the query response for the MarketMap query.
type MarketMapResponse struct {
	// MarketMap defines the global set of market configurations for all providers
	// and markets.
	MarketMap MarketMap `protobuf:"bytes,1,opt,name=market_map,json=marketMap,proto3" json:"market_map"`
	// LastUpdated is the last block height that the market map was updated.
	// This field can be used as an optimization for clients checking if there
	// is a new update to the map.
	LastUpdated uint64 `protobuf:"varint,2,opt,name=last_updated,json=lastUpdated,proto3" json:"last_updated,omitempty"`
	// ChainId is the chain identifier for the market map.
	ChainId string `protobuf:"bytes,3,opt,name=chain_id,json=chainId,proto3" json:"chain_id,omitempty"`
}

Market

Market returns a specific Market from the Marketmap.

Request:

// MarketRequest is the query request for the Market query.
// It takes the currency pair of the market as an argument.
type MarketRequest struct {
	// CurrencyPair is the currency pair associated with the market being
	// requested.
	CurrencyPair types.CurrencyPair `protobuf:"bytes,1,opt,name=currency_pair,json=currencyPair,proto3" json:"currency_pair"`
}

Response:

// MarketResponse is the query response for the Market query.
type MarketResponse struct {
	// Market is the configuration of a single market to be price-fetched for.
	Market Market `protobuf:"bytes,1,opt,name=market,proto3" json:"market"`
}

LastUpdated

LastUpdated returns the height at which the Marketmap was last updated.

Request:

// LastUpdatedRequest is the request type for the Query/LastUpdated RPC
// method.
type LastUpdatedRequest struct {}

Response:

// LastUpdatedResponse is the response type for the Query/LastUpdated RPC
// method.
type LastUpdatedResponse struct {
	LastUpdated uint64 `protobuf:"varint,1,opt,name=last_updated,json=lastUpdated,proto3" json:"last_updated,omitempty"`
}

Params

Params returns the Marketmap’s Params.

Request:

// ParamsRequest is the request type for the Query/Params RPC method.
type ParamsRequest struct {}

Response:

// ParamsResponse is the response type for the Query/Params RPC method.
type ParamsResponse struct {
	Params Params `protobuf:"bytes,1,opt,name=params,proto3" json:"params"`
}

Proto Definitions

Proto definitions for all types, queries, and messages can be found here.