• Name

• Description

• Website URL

• If a market accepts orders, it is responsible (off-chain) for identifying order matches and triggering (on-chain) settlement

• Markets can restrict who can create orders by defining required account attributes

• Markets can control whether user-settlement is allowed

• Markets can control whether orders can be created for it

• If a market accepts commitments, it is able to manage committed funds and is responsible for releasing commitments as needed

• Markets can separately control whether funds can be committed to it

• A market receives fees for order creation and order settlement

• It also defines what fees are required and what is acceptable as payments

• The fees collected by a market are kept in the market's account, and can be accessed using the MarketWithdraw endpoint

• There is a separate list of attributes required to create each order type and commitments

• If one or more attributes are required for an action, the associated account must have all of them

• Required attributes can have a wildcard at the start to indicate pattern matching

• The only place a wildcard (*) is allowed is at the start of the string and must be immediately followed by a period

• Example: A required attribute of .kyc.pb would match buyer.kyc.pb or special.seller.kyc.pb, but not buyer.xkyc.pb or kyc.pb

• Hold is placed on the applicable funds

• Funds remain in user's account until settlement or cancellation

• Orders cannot be modified except in specific ways

• When an order is partially filled, the amounts in it will be reduced accordingly

• An order's external ID can be changed by the market

• Cancelling an order will release the held funds and delete the order

• Settling an order in full will delete the order

• Orders can be cancelled by either the user or the market

• Cancellation releases held funds and deletes the order

• When an ask order is created, a hold is placed on the assets being sold

• If the seller_settlement_flat_fee denom differs from the price denom, a hold is placed on that flat fee too

• Ask orders can be filled at a larger price than initially defined

• The seller_settlement_flat_fee is verified at creation but only paid during settlement

• Assets are transferred directly to the buyer(s) and the price is transferred directly from the buyer(s)

• Seller settlement fees are transferred from the seller to the market

1. 2cow transferred from seller to buyer

2. 16chicken transferred from buyer to seller

3. 2chicken transferred from seller to market

4. Seller ends up with 14chicken for their 2cow

• When a bid order is created, a hold is placed on the order's price and buyer_settlement_fees

• Price is transferred directly to the seller(s) and the assets are transferred directly from the seller(s)

• Buyer settlement fees are transferred from the buyer to the market

• The buyer_settlement_fees are verified at creation but only paid during settlement

• Fees are paid in addition to the price the buyer is paying

• Order must allow partial settlement (defined at order creation)

• Order must be evenly divisible

• The following calculations must result in whole numbers:
• <order price> * <assets filled> / <order assets>
• <settlement fees> * <assets filled> / <order assets>

• When an order is partially filled, the order's same assets:price and assets:settlement-fees ratios are maintained

• Order amounts are updated to reflect what hasn't yet been filled

• An order can be partially filled multiple times (as long as the numbers allow for it)

• Can be provided during order creation in the external_id field

• Can be set by the market after order creation using MarketSetOrderExternalID

• Each external ID is unique inside a market

• Multiple orders in different markets can have the same external ID

• External IDs are optional (multiple orders can have empty external IDs)

• Limited to 100 characters

• Orders with external IDs can be looked up using GetOrderByExternalID query

• At most one order can be partially filled, and it must be the last order in its list

• That order must allow partial settlement and be evenly divisible

• The market must set the expect_partial field to true in the request

• If all orders are being filled in full, the expect_partial field must be false

• All orders in a settlement must have the same assets denoms

• All orders must have the same price denoms

• Fees can be anything

• The total bid price must be at least the total ask price

1. The assets are transferred directly from the seller(s) to the buyer(s)

2. The price funds are transferred directly from the buyer(s) to the seller(s)

3. All settlement fees are transferred directly from the seller(s) and buyer(s) to the market

4. The exchange's portion of the fees is transferred from the market to the chain's fee collector

• Transfers of the assets and price bypass the quarantine module since order creation can be viewed as acceptance of those funds

• No other send-restrictions are bypassed (e.g. x/marker or x/sanction module restrictions)

• If an order's funds are in a sanctioned account, settlement will fail

• Committed funds are not usable by the account they are in; only the market can move them

• The funds stay in the account until the market either moves them using MarketCommitmentSettle or cancels the commitment

• Commitments can only be cancelled by the market (or a governance proposal)

• A settlement bips, or

• A commitment creation flat fee defined

1. Holds are released on the funds to be transferred

2. The funds are transferred

3. The funds are re-committed in the destination accounts

• The market can collect fees as part of this settlement, but is also charged extra fees for the tx

• The funds are re-committed regardless of the market's accepting_commitments value

• The accounts these funds are being re-committed to also are not required to have the create-commitment required attributes

• Source: The account that creates the payment

• Target: The account that can accept or reject the payment (does not need to be declared when payment is created)

• source_amount: The amount that the source is providing

• target_amount: The amount that the target is providing

• Both amounts are optional, but at least one must be provided

• A hold is placed the source_amount funds in the source account

• A payment is uniquely identified by its source and external_id

• It is up to the source to choose an external_id that they are not already using

• When a payment is accepted, the hold is released

• The source_amount is sent from the source to the target

• The target_amount is sent from the target to the source

• All the details of the payment must be provided in the acceptance request

• Once a payment has been accepted, rejected, or cancelled, its external ID can be reused by the source

• Two different sources can use the same external ID

• fee_create_ask_flat: The available Coin fee options for creating an ask order

• fee_create_bid_flat: The available Coin fee options for creating a bid order

• fee_seller_settlement_flat: The available Coin fee options that are paid by the seller during settlement

• fee_buyer_settlement_flat: The available Coin fee options that are paid by the buyer during settlement

• The ask order's seller_settlement_flat_fee must be at least one of the available fee_seller_settlement_flat options

• The bid order's buyer_settlement_fees must be enough to cover one of the fee_buyer_settlement_flat options plus one of the buyer settlement ratio fee options

• fee_seller_settlement_ratios: The available FeeRatio options that are applied to the price received

• fee_buyer_settlement_ratios: The available FeeRatio options that are applied to the bid order's price

• An order settling for 400chicken: 400 * 3 / 1000 = 1.2, which is rounded up to 2chicken

• An order settling for 3000chicken: 3000 * 3 / 1000 = 9, which doesn't need rounding

• fee_create_commitment_flat: The available Coin fee options that are paid by the committer when committing funds

1. Sum the settlement inputs

2. Use Marker Net-Asset-Value (NAV) entries to convert the total into the market's intermediary denom

3. A NAV is used to convert the intermediary total to the fee denom

4. The market's commitment_settlement_bips is applied to the fee denom total

5. That total is divided by two to get the final fee amount

• For hen: 1500 * 500 / 10,000 = 75hen

• For rooster: 710 * 100 / 10,000 = 7.1 which gets rounded up to 8rooster

• Markets for organizing and facilitating trades

• Orders for expressing trading intent

• Settlement mechanisms for executing trades

• Commitments for managed fund control

• Payments for direct fund transfers

• Flexible permission systems for market delegation

• Attribute-based access controls

• Partial order fulfillment capabilities

• External ID tracking for off-chain integration

• Comprehensive fee structures

• Multiple fee types for different operations

• Configurable fee options per market

• Exchange fee sharing mechanisms

• Basis point calculations with proper rounding

plain text
0x00 | "split" (5 bytes)

plain text
<split (2 bytes)>

plain text
0x00 | "split" (5 bytes) | <denom (string)>

plain text
<split (2 bytes)>

plain text
0x01 | <market id (4 bytes)> | 0x00 | <denom (string)>

plain text
<amount (string)>

plain text
0x01 | <market id (4 bytes)> | 0x01 | <denom (string)>

plain text
<amount (string)>

plain text
0x01 | <market id (4 bytes)> | 0x11 | <denom (string)>

plain text
<amount (string)>

plain text
0x01 | <market id (4 bytes)> | 0x02 | <denom (string)>

plain text
<amount (string)>

plain text
0x01 | <market id (4 bytes)> | 0x03 | <price denom (string)> | 0x1E | <fee denom (string)>

plain text
<price amount (string)> | 0x1E | <fee amount (string)>

plain text
0x01 | <market id (4 bytes)> | 0x04 | <denom (string)>

plain text
<amount (string)>

plain text
0x01 | <market id (4 bytes)> | 0x05 | <price denom (string)> | 0x1E | <fee denom (string)>

plain text
<price amount (string)> | 0x1E | <fee amount (string)>

plain text
0x01 | <market id (4 bytes)> | 0x06

plain text
<nil (0 bytes)>

plain text
0x01 | <market id (4 bytes)> | 0x07

plain text
<nil (0 bytes)>

plain text
0x01 | <market id (4 bytes)> | 0x10

plain text
<nil (0 bytes)>

plain text
0x01 | <market id (4 bytes)> | 0x08 | <addr len (1 byte)> | <addr> | <permission type byte (1 byte)>

plain text
<nil (0 bytes)>

plain text
0x01 | <market id (4 bytes)> | 0x09 | 0x00

plain text
<list of strings separated by 0x1E>

plain text
0x01 | <market id (4 bytes)> | 0x09 | 0x01

plain text
<list of strings separated by 0x1E>

plain text
0x01 | <market id (4 bytes)> | 0x09 | 0x63

plain text
<list of strings separated by 0x1E>

plain text
0x01 | <market id (4 bytes)> | 0x12

plain text
<bips (2 bytes)>

plain text
0x01 | <market id (4 bytes)> | 0x13

plain text
<denom>

protobuf
message MarketAccount {
  option (gogoproto.equal) = false;
  option (gogoproto.goproto_getters) = false;
  option (gogoproto.goproto_stringer) = false;

  cosmos.auth.v1beta1.BaseAccount base_account = 1 [(gogoproto.embed) = true];
  uint32 market_id = 2;
  MarketDetails market_details = 3;
}

plain text
0x07 | <market id (4 bytes)>

plain text
<nil (0 bytes)>

plain text
0x06

plain text
<market id (4 bytes)>

1. Starting with the number after what's in this state entry, each market id is sequentially checked until an available one is found

2. The new market gets that id

3. This entry is then updated to indicate what that was

plain text
0x02 | <order id (8 bytes)>

plain text
<order type byte> | protobuf(order type)

plain text
0x02 | <order id (8 bytes)>

plain text
0x00 | protobuf(AskOrder)

plain text
0x02 | <order id (8 bytes)>

plain text
0x01 | protobuf(BidOrder)

plain text
0x08

plain text
<order id (8 bytes)>

plain text
0x63 | <market_id> (4 bytes) | <addr len (1 byte)> | <addr>

plain text
<coins string>

plain text
0x70 | <source len (1 byte)> | <source> | <external id>

plain text
protobuf(Payment)

plain text
0x03 | <market id (4 bytes)> | <order id (8 bytes)>

plain text
<order type byte (1 byte)>

plain text
0x04 | <addr len (1 byte)> | <addr> | <order id (8 bytes)>

plain text
<order type byte (1 byte)>

plain text
0x05 | <asset denom> | <order id (8 bytes)>

plain text
<order type byte (1 byte)>

plain text
0x09 | <market id (4 bytes)> | <external id (string)>

plain text
<order id (8 bytes)>

plain text
0x10 | <target len (1 byte)> | <target> | <source len (1 byte)> | <source> | <external id>

plain text
<nil (0 bytes)>

• Type bytes enable quick filtering of data categories

• Market IDs allow direct access to market-specific data

• Order IDs provide unique identification for all orders

• Market-to-order mapping for market-specific queries

• Address-to-order mapping for user portfolio views

• Asset-to-order mapping for asset-specific searches

• External ID mapping for off-chain integration

• Each market aspect stored independently

• Fee configurations stored per denom

• Permissions stored per address-permission pair

• Efficient storage using nil values for true conditions

• Absence of entry indicates false condition

• Minimal storage overhead for status flags

• Last Market ID ensures unique market identification

• Last Order ID prevents order ID collisions

• Sequential allocation with gap detection

• Order type bytes distinguish ask from bid orders

• Permission type bytes enforce access control

• Structured protobuf serialization for complex data

• Consistent byte ordering for numeric values

• Predictable key sorting for range queries

• Efficient prefix-based iterations

• 0x1E byte for multi-part value separation

• Clean parsing of compound data structures

• Support for list-based attribute storage

protobuf
// MsgCreateAskRequest structure
message MsgCreateAskRequest {
  AskOrder ask_order = 1;
  uint64 order_creation_fee = 2;
}

• AskOrder: orders.proto#L28-L53

• MsgCreateAskResponse: tx.proto#L126-L130

• Market does not exist or disallows order creation

• Seller lacks required attributes or assets

• Insufficient fees or invalid denomination

• External ID already in use

protobuf
// MsgCreateBidRequest structure
message MsgCreateBidRequest {
  BidOrder bid_order = 1;
  uint64 order_creation_fee = 2;
}

• BidOrder: orders.proto#L55-L78

• MsgCreateBidResponse: tx.proto#L142-L146

protobuf
// MsgCommitFundsRequest structure
message MsgCommitFundsRequest {
  string account = 1;
  uint32 market_id = 2;
  repeated cosmos.base.v1beta1.Coin amount = 3;
  cosmos.base.v1beta1.Coin creation_fee = 4;
}

protobuf
// MsgCancelOrderRequest structure
message MsgCancelOrderRequest {
  string signer = 1;
  uint64 order_id = 2;
}

protobuf
// MsgFillBidsRequest structure
message MsgFillBidsRequest {
  string seller = 1;
  uint32 market_id = 2;
  repeated uint64 bid_order_ids = 3;
  repeated cosmos.base.v1beta1.Coin total_assets = 4;
  // Additional fee fields...
}

protobuf
// MsgFillAsksRequest structure
message MsgFillAsksRequest {
  string buyer = 1;
  uint32 market_id = 2;
  repeated uint64 ask_order_ids = 3;
  cosmos.base.v1beta1.Coin total_price = 4;
  // Additional fee fields...
}

protobuf
// MsgMarketSettleRequest structure
message MsgMarketSettleRequest {
  string admin = 1;
  uint32 market_id = 2;
  repeated uint64 ask_order_ids = 3;
  repeated uint64 bid_order_ids = 4;
  bool expect_partial = 5;
}

protobuf
// MsgMarketCommitmentSettleRequest structure
message MsgMarketCommitmentSettleRequest {
  string admin = 1;
  uint32 market_id = 2;
  repeated AccountAmount inputs = 3;
  repeated AccountAmount outputs = 4;
  repeated NetAssetValue navs = 5;
}

protobuf
// MsgCreatePaymentRequest structure
message MsgCreatePaymentRequest {
  Payment payment = 1;
}

• Payment: payments.proto#L13-L43

• Response: tx.proto#L499-L500

protobuf
// MsgGovCreateMarketRequest structure
message MsgGovCreateMarketRequest {
  string authority = 1;
  Market market = 2;
}

• Market: market.proto#L52-L148

• MarketDetails: market.proto#L28-L40

• FeeRatio: market.proto#L150-L158

• AccessGrant: market.proto#L160-L166

• Permission: market.proto#L168-L186

• The assets, price, and fees reflect the funds that were actually transferred

• When an ask order is settled for a higher price than set in the order, the price reflects what the seller actually received

• The fees reflect the actual settlement fees paid (both flat and ratio) by the order's owner

• If an order was previously partially filled, but now the rest is being filled, this event is emitted

• The assets, price, and fees reflect the funds that were actually transferred

• If an order was previously partially filled, but now the rest is being filled, an EventOrderFilled is emitted

plain text
Order Lifecycle Events:

1. EventOrderCreated
   ↓
2. (Optional) EventOrderExternalIDUpdated
   ↓
3. Settlement Options:
   - EventOrderFilled (complete settlement)
   - EventOrderPartiallyFilled → EventOrderFilled (partial then complete)
   - EventOrderCancelled (cancelled before settlement)

plain text
Market Management Events:

Creation:
- EventMarketCreated

Configuration Changes:
- EventMarketDetailsUpdated
- EventMarketPermissionsUpdated
- EventMarketReqAttrUpdated
- EventMarketIntermediaryDenomUpdated

Operational Status:
- EventMarketOrdersEnabled/Disabled
- EventMarketUserSettleEnabled/Disabled
- EventMarketCommitmentsEnabled/Disabled

Financial Operations:
- EventMarketWithdraw
- EventMarketFeesUpdated (governance only)

plain text
Commitment Lifecycle:

1. EventFundsCommitted
   ↓
2. (Market manages committed funds)
   ↓
3. EventCommitmentReleased

plain text
Payment Lifecycle:

1. EventPaymentCreated
   ↓
2. (Optional) EventPaymentUpdated (target changes)
   ↓
3. Resolution:
   - EventPaymentAccepted (successful completion)
   - EventPaymentRejected (rejected by target)
   - EventPaymentCancelled (cancelled by source)

• Order Lifecycle: Creation, modification, settlement, and cancellation

• Market Operations: Administrative changes and operational status updates

• Financial Operations: Fund movements, fee collection, and withdrawals

• Payment Processing: Direct payment lifecycle management

• Identity Information: Account addresses and identifiers for all participants

• Financial Details: Exact amounts transferred, fees paid, and prices received

• Administrative Context: Who made changes and when they occurred

• External Integration: External IDs and tags for off-chain system integration

• Real-time Tracking: Immediate notification of all exchange activities

• Audit Trails: Complete history of all operations and changes

• Performance Monitoring: Data for analyzing system performance and usage

• Compliance Support: Detailed records for regulatory requirements

• External System Integration: Rich event data for connecting to external systems

• Business Intelligence: Comprehensive data for analytics and reporting

• Automated Responses: Events enable automated reaction to system changes

• User Interfaces: Real-time updates for user-facing applications

• Either an ask_order or a bid_order must be provided, but not both

• Each response field is a list of options available for the requested order

• If a response field is empty, then no fee of that type is required

• Choose one entry from creation_fee_options to provide as the order_creation_fee

• Choose one entry from settlement_flat_fee_options and provide that as the seller_settlement_flat_fee

• The settlement_ratio_fee_options is purely informational and is the minimum seller's settlement ratio fee for the order

• Choose one entry from creation_fee_options to provide as the order_creation_fee

• Choose one entry from each of settlement_flat_fee_options and settlement_ratio_fee_options, add them together, and provide that as the buyer_settlement_fees

protobuf
message QueryOrderFeeCalcRequest {
  // ask_order is the ask order to calculate fees for.
  AskOrder ask_order = 1;
  // bid_order is the bid order to calculate fees for.
  BidOrder bid_order = 2;
}

protobuf
message QueryOrderFeeCalcResponse {
  // creation_fee_options are the choices of fees that must be paid when creating this order.
  repeated cosmos.base.v1beta1.Coin creation_fee_options = 1;
  // settlement_flat_fee_options are the choices of flat fees that will be added to the settlement.
  repeated cosmos.base.v1beta1.Coin settlement_flat_fee_options = 2;
  // settlement_ratio_fee_options are the choices of ratio fees that will be applied during settlement.
  repeated cosmos.base.v1beta1.Coin settlement_ratio_fee_options = 3;
}

protobuf
message QueryCommitmentSettlementFeeCalcRequest {
  // settlement is the settlement to calculate the fees for.
  MsgMarketCommitmentSettleRequest settlement = 1;
  // include_breakdown_fields is a flag for whether to include the
  // breakdown_* fields in the response.
  bool include_breakdown_fields = 2;
}

protobuf
message QueryCommitmentSettlementFeeCalcResponse {
  // exchange_fees are the fees that the exchange will pay for this settlement.
  repeated cosmos.base.v1beta1.Coin exchange_fees = 1;
  // breakdown_intermediary_amount is the sum of the inputs converted to the intermediary denom.
  repeated cosmos.base.v1beta1.Coin breakdown_intermediary_amount = 2;
  // breakdown_conversion_navs are the NAVs used to convert the intermediary amounts to the fee denom.
  repeated NetAssetPrice breakdown_conversion_navs = 3;
  // breakdown_converted_total is the intermediary amounts converted to the fee denom.
  repeated cosmos.base.v1beta1.Coin breakdown_converted_total = 4;
  // breakdown_conversion_fee_total is the fee denom amounts that the bips will be applied to.
  repeated cosmos.base.v1beta1.Coin breakdown_conversion_fee_total = 5;
}

protobuf
message QueryPaymentFeeCalcRequest {
  // payment is the payment to calculate fees for.
  Payment payment = 1;
}

protobuf
message QueryPaymentFeeCalcResponse {
  // creation_fee_total is the total amount required for the create payment tx fee.
  repeated cosmos.base.v1beta1.Coin creation_fee_total = 1;
  // acceptance_fee_total is the total amount required for the accept payment tx fee.
  repeated cosmos.base.v1beta1.Coin acceptance_fee_total = 2;
}

protobuf
message QueryGetOrderRequest {
  // order_id is the id of the order to look up.
  uint64 order_id = 1;
}

protobuf
message QueryGetOrderResponse {
  // order is the order with the given id.
  Order order = 1;
}

protobuf
message Order {
  // order_id is the numerical identifier for this order.
  uint64 order_id = 1;
  // ask_order is defined if this order is an ask order.
  AskOrder ask_order = 2;
  // bid_order is defined if this order is a bid order.
  BidOrder bid_order = 3;
}

protobuf
message QueryGetOrderByExternalIDRequest {
  // market_id is the id of the market the order is in.
  uint32 market_id = 1;
  // external_id is the external id of the order to look up.
  string external_id = 2;
}

protobuf
message QueryGetOrderByExternalIDResponse {
  // order is the order with the given external id.
  Order order = 1;
}

protobuf
message QueryGetMarketOrdersRequest {
  // market_id is the id of the market to get orders for.
  uint32 market_id = 1;
  // order_type is optional and can be used to only get orders of the given type.
  string order_type = 2;
  // after_order_id is optional. If provided, only orders with an id >= this value will be included.
  uint64 after_order_id = 3;
  // pagination defines optional pagination parameters for the request.
  cosmos.base.query.v1beta1.PageRequest pagination = 99;
}

protobuf
message QueryGetMarketOrdersResponse {
  // orders are the orders in the given market.
  repeated Order orders = 1;
  // pagination provides the pagination information of this query.
  cosmos.base.query.v1beta1.PageResponse pagination = 99;
}

protobuf
message QueryGetOwnerOrdersRequest {
  // owner is the bech32 address of the owner to get orders for.
  string owner = 1;
  // order_type is optional and can be used to only get orders of the given type.
  string order_type = 2;
  // after_order_id is optional. If provided, only orders with an id >= this value will be included.
  uint64 after_order_id = 3;
  // pagination defines optional pagination parameters for the request.
  cosmos.base.query.v1beta1.PageRequest pagination = 99;
}

protobuf
message QueryGetOwnerOrdersResponse {
  // orders are the orders for the given owner.
  repeated Order orders = 1;
  // pagination provides the pagination information of this query.
  cosmos.base.query.v1beta1.PageResponse pagination = 99;
}

protobuf
message QueryGetAssetOrdersRequest {
  // asset is the denom of the asset to get orders for.
  string asset = 1;
  // order_type is optional and can be used to only get orders of the given type.
  string order_type = 2;
  // after_order_id is optional. If provided, only orders with an id >= this value will be included.
  uint64 after_order_id = 3;
  // pagination defines optional pagination parameters for the request.
  cosmos.base.query.v1beta1.PageRequest pagination = 99;
}

protobuf
message QueryGetAssetOrdersResponse {
  // orders are the orders for the given asset.
  repeated Order orders = 1;
  // pagination provides the pagination information of this query.
  cosmos.base.query.v1beta1.PageResponse pagination = 99;
}

protobuf
message QueryGetAllOrdersRequest {
  // pagination defines optional pagination parameters for the request.
  cosmos.base.query.v1beta1.PageRequest pagination = 99;
}

protobuf
message QueryGetAllOrdersResponse {
  // orders are all the orders.
  repeated Order orders = 1;
  // pagination provides the pagination information of this query.
  cosmos.base.query.v1beta1.PageResponse pagination = 99;
}

protobuf
message QueryGetCommitmentRequest {
  // account is the bech32 address of the account to get the commitment for.
  string account = 1;
  // market_id is the numerical identifier of the market to get the commitment for.
  uint32 market_id = 2;
}

protobuf
message QueryGetCommitmentResponse {
  // amount is the total amount committed to the market by the account.
  repeated cosmos.base.v1beta1.Coin amount = 1;
}

protobuf
message QueryGetAccountCommitmentsRequest {
  // account is the bech32 address of the account to get commitments for.
  string account = 1;
}

protobuf
message QueryGetAccountCommitmentsResponse {
  // commitments are the commitments of the account.
  repeated MarketAmount commitments = 1;
}

protobuf
message QueryGetMarketCommitmentsRequest {
  // market_id is the numerical identifier of the market to get commitments for.
  uint32 market_id = 1;
  // pagination defines optional pagination parameters for the request.
  cosmos.base.query.v1beta1.PageRequest pagination = 99;
}

protobuf
message QueryGetMarketCommitmentsResponse {
  // commitments are the commitments for the market.
  repeated AccountAmount commitments = 1;
  // pagination provides the pagination information of this query.
  cosmos.base.query.v1beta1.PageResponse pagination = 99;
}

protobuf
message QueryGetAllCommitmentsRequest {
  // pagination defines optional pagination parameters for the request.
  cosmos.base.query.v1beta1.PageRequest pagination = 99;
}

protobuf
message QueryGetAllCommitmentsResponse {
  // commitments are all the commitments.
  repeated MarketAccountAmount commitments = 1;
  // pagination provides the pagination information of this query.
  cosmos.base.query.v1beta1.PageResponse pagination = 99;
}

protobuf
message QueryGetMarketRequest {
  // market_id is the id of the market to look up.
  uint32 market_id = 1;
}

protobuf
message QueryGetMarketResponse {
  // address is the bech32 address string of the market's account.
  string address = 1;
  // market is the market with the given id.
  Market market = 2;
}

protobuf
message QueryGetAllMarketsRequest {
  // pagination defines optional pagination parameters for the request.
  cosmos.base.query.v1beta1.PageRequest pagination = 99;
}

protobuf
message QueryGetAllMarketsResponse {
  // markets are brief information about all markets.
  repeated MarketBrief markets = 1;
  // pagination provides the pagination information of this query.
  cosmos.base.query.v1beta1.PageResponse pagination = 99;
}

protobuf
message MarketBrief {
  // market_id is the numerical identifier for this market.
  uint32 market_id = 1;
  // market_details contains information about this market.
  MarketDetails market_details = 2;
  // market_account is the bech32 address string of this market's account.
  string market_account = 3;
}

protobuf
message QueryParamsRequest {}

protobuf
message QueryParamsResponse {
  // params are the parameters of the exchange module.
  Params params = 1;
}

protobuf
message QueryValidateCreateMarketRequest {
  // create_market_request is the msg to validate.
  MsgGovCreateMarketRequest create_market_request = 1;
}

protobuf
message QueryValidateCreateMarketResponse {
  // error is any problems or errors found in the create market request.
  string error = 1;
  // gov_prop_will_pass is whether the proposal will pass if submitted as-is.
  bool gov_prop_will_pass = 2;
}

protobuf
message QueryValidateMarketRequest {
  // market_id is the id of the market to validate.
  uint32 market_id = 1;
}

protobuf
message QueryValidateMarketResponse {
  // error is any problems or errors found in the market.
  string error = 1;
}

protobuf
message QueryValidateManageFeesRequest {
  // manage_fees_request is the msg to validate.
  MsgGovManageFeesRequest manage_fees_request = 1;
}

protobuf
message QueryValidateManageFeesResponse {
  // error is any problems or errors found in the manage fees request.
  string error = 1;
  // gov_prop_will_pass is whether the proposal will pass if submitted as-is.
  bool gov_prop_will_pass = 2;
}

protobuf
message QueryGetPaymentRequest {
  // source is the bech32 address of the source account.
  string source = 1;
  // external_id is the external id of the payment.
  string external_id = 2;
}

protobuf
message QueryGetPaymentResponse {
  // payment is the payment with the given source and external id.
  Payment payment = 1;
}

protobuf
message QueryGetPaymentsWithSourceRequest {
  // source is the bech32 address to get payments for.
  string source = 1;
  // pagination defines optional pagination parameters for the request.
  cosmos.base.query.v1beta1.PageRequest pagination = 99;
}

protobuf
message QueryGetPaymentsWithSourceResponse {
  // payments are the payments with the given source.
  repeated Payment payments = 1;
  // pagination provides the pagination information of this query.
  cosmos.base.query.v1beta1.PageResponse pagination = 99;
}

protobuf
message QueryGetPaymentsWithTargetRequest {
  // target is the bech32 address to get payments for.
  string target = 1;
  // pagination defines optional pagination parameters for the request.
  cosmos.base.query.v1beta1.PageRequest pagination = 99;
}

protobuf
message QueryGetPaymentsWithTargetResponse {
  // payments are the payments with the given target.
  repeated Payment payments = 1;
  // pagination provides the pagination information of this query.
  cosmos.base.query.v1beta1.PageResponse pagination = 99;
}

protobuf
message QueryGetAllPaymentsRequest {
  // pagination defines optional pagination parameters for the request.
  cosmos.base.query.v1beta1.PageRequest pagination = 99;
}

protobuf
message QueryGetAllPaymentsResponse {
  // payments are all the payments.
  repeated Payment payments = 1;
  // pagination provides the pagination information of this query.
  cosmos.base.query.v1beta1.PageResponse pagination = 99;
}

plain text
Order Query Flow:

1. OrderFeeCalc → Calculate required fees
2. CreateAsk/CreateBid → Submit order with fees
3. GetOrder → Monitor order status
4. GetMarketOrders → View market activity
5. GetOwnerOrders → Track personal orders

plain text
Market Analysis Flow:

1. GetAllMarkets → Discover available markets
2. GetMarket → Get detailed market information
3. ValidateMarket → Check market health
4. GetMarketOrders → Analyze trading activity
5. GetMarketCommitments → Review fund commitments

plain text
Fee Planning Flow:

1. OrderFeeCalc → Calculate order fees
2. CommitmentSettlementFeeCalc → Calculate settlement fees
3. PaymentFeeCalc → Calculate payment fees
4. Execute operations with proper fee amounts

plain text
Commitment Tracking Flow:

1. GetCommitment → Check specific commitment
2. GetAccountCommitments → View all account commitments
3. GetMarketCommitments → Monitor market commitments
4. CommitmentSettlementFeeCalc → Plan settlements

• Order Information: Access orders by ID, market, owner, asset, and external ID

• Market Data: Retrieve market configuration, status, and brief information

• Commitment Tracking: Query fund commitments by account, market, or globally

• Payment Management: Access payment data with flexible filtering options

• Order Fees: Calculate creation and settlement fees before order submission

• Commitment Fees: Determine settlement fees for commitment operations

• Payment Fees: Calculate creation and acceptance fees for payments

• Market Validation: Check market configuration for problems

• Operation Validation: Validate governance proposals before submission

• Error Prevention: Identify issues before executing operations

• Consistent Patterns: Similar request/response structures across queries

• Pagination Support: Handle large datasets efficiently

• Flexible Filtering: Multiple ways to query the same data

• Rich Responses: Complete data structures with all relevant information

• External ID Support: Query orders by external identifiers

• Batch Operations: Retrieve multiple items efficiently

• Real-time Data: Current state information for all entities

• Comprehensive Coverage: Every aspect of the exchange module is queryable

1. Specific DenomSplit - If defined for the denom, this value is used

2. Default Split - If no specific DenomSplit exists, the default_split is used

• Asset-Based Pricing - Different fee structures for different asset types

• Market Incentives - Lower splits for preferred denominations

• Revenue Optimization - Higher splits for premium assets

• Flexibility - Customizable per market needs

• When Charged - During payment creation transaction

• Who Pays - The source account creating the payment

• Fee Type - Flat fee added to transaction costs

• Purpose - Covers network costs for payment processing

• When Charged - During payment acceptance transaction

• Who Pays - The target account accepting the payment

• Fee Type - Flat fee added to transaction costs

• Purpose - Covers network costs for payment settlement

• Sustainable Revenue - Provides exchange with operational funding

• Market Incentive - Markets retain 95% of fees as incentive

• Competitive Balance - Reasonable split for market participation

• Network Support - Funds exchange infrastructure and development

• Simple Structure - Same fee for creation and acceptance

• Fair Distribution - Both parties pay equivalent costs

• Network Efficiency - Covers transaction processing costs

• Predictable Costs - Fixed fees for budgeting purposes

1. Proposal Creation - Submit GovUpdateParams governance proposal

2. Community Review - Public discussion and analysis period

3. Voting Period - HASH token holders vote on the proposal

4. Implementation - If passed, parameters are automatically updated

protobuf
message MsgGovUpdateParamsRequest {
  string authority = 1;  // Governance module account
  Params params = 2;     // New parameter values
}

• Minimum Value - 0 basis points (0%)

• Maximum Value - 10,000 basis points (100%)

• Valid Range - Any integer between 0 and 10,000 inclusive

• Non-negative - Fees cannot be negative

• Reasonable Limits - Fees should not be excessive

• Denom Validation - Must be valid denomination strings

plain text
provenanced query exchange params

protobuf
message Params {
  // default_split is the split value to use for fees when a specific split is not defined for the given denom.
  uint32 default_split = 1;
  // denom_splits are the denom specific splits.
  repeated DenomSplit denom_splits = 2;
  // fee_create_payment_flat is the flat fee charged for creating a payment.
  repeated cosmos.base.v1beta1.Coin fee_create_payment_flat = 3;
  // fee_accept_payment_flat is the flat fee charged for accepting a payment.
  repeated cosmos.base.v1beta1.Coin fee_accept_payment_flat = 4;
}

protobuf
message DenomSplit {
  // denom is the denomination this split applies to.
  string denom = 1;
  // split is the basis points this denom split uses.
  uint32 split = 2;
}

• denom - The cryptocurrency denomination (e.g., "nhash", "uusdc")

• split - The basis points value for this specific denomination

• default_split: 500 (5%)

• denom_splits: empty

• All denominations use 5% split

• Exchange receives 5% of all market fees

• Markets retain 95% of all fees collected

• default_split: 500 (5%)

• denom_splits: [{"nhash": 300}, {"uusdc": 750}]

• HASH fees: 3% to exchange, 97% to market

• USDC fees: 7.5% to exchange, 92.5% to market

• Other denoms: 5% to exchange, 95% to market

• default_split: 2000 (20%)

• denom_splits: [{"premium_token": 5000}]

• Premium tokens: 50% to exchange, 50% to market

• Other denoms: 20% to exchange, 80% to market

• Higher exchange revenue for sustainability

• Creation fee: 0.1 HASH

• Acceptance fee: 0.1 HASH

• Source pays 0.1 HASH to create payment

• Target pays 0.1 HASH to accept payment

• Total system cost: 0.2 HASH per payment

• Creation fee: 0.1 HASH (0.01% of payment)

• Acceptance fee: 0.1 HASH (0.01% of payment)

• Lower Splits - Encourage market participation and growth

• Higher Splits - Generate more revenue for exchange operations

• Denom-Specific - Customize incentives by asset type

• Exchange Revenue - Funds continued development and operations

• Market Revenue - Incentivizes market creation and management

• Balance Point - Optimal split maintains both aspects

• Predictable Costs - Users can budget payment expenses

• Large Payment Efficiency - Percentage cost decreases with size

• Network Protection - Prevents spam through minimum cost

• Small Payment Impact - High percentage cost for small payments

• Fee Adjustment - May need updates with HASH price changes

• User Experience - Should remain reasonable for typical use

• Market Adoption - Lower splits may increase market creation

• Exchange Needs - Higher splits provide more operational funding

• Competition - Competitive splits attract market operators

• Asset Types - Different splits for different asset categories

• Network Usage - Fees should cover actual network costs

• User Adoption - Reasonable fees encourage payment usage

• Spam Prevention - Sufficient fees deter abuse

• Value Proposition - Fees should be justified by utility

• Total Fees Collected - Overall market fee generation

• Exchange Share - Amount retained by exchange system

• Market Share - Amount retained by individual markets

• Denom Breakdown - Fee distribution by denomination

• Split Effectiveness - Whether current splits achieve goals

• Market Behavior - How splits affect market creation and operation

• Revenue Trends - Growth patterns in fee collection

• Denom Performance - Which assets generate most fees

• Payment Volume - Number of payments created and accepted

• Fee Revenue - Total fees collected from payment operations

• User Behavior - How fees affect payment adoption

• Cost Effectiveness - Fee-to-value ratios for different payment sizes

• Fee Sensitivity - How fee changes affect usage

• Market Feedback - User and market operator responses

• Network Efficiency - Whether fees cover actual costs

• Competitive Position - Fee comparison with alternatives

• Flexible Split System - Default and denomination-specific fee splits

• Basis Point Precision - Fine-grained control over fee distribution

• Market Incentives - Balanced revenue sharing between exchange and markets

• Governance Control - Community oversight of fee structure changes

• Fixed Fee Model - Predictable costs for payment operations

• Dual Fee System - Separate fees for creation and acceptance

• Network Sustainability - Fees cover operational costs

• User Experience - Reasonable fees for typical usage

• Revenue Generation - Sustainable funding for exchange operations

• Market Participation - Attractive fee structures for market operators

• Flexibility - Customizable parameters for different scenarios

• Transparency - Clear, queryable parameter configuration

• Balanced Incentives - Fair distribution between stakeholders

• Market Dynamics - Parameters that encourage healthy market activity

• Network Effects - Fee structures that support ecosystem growth

• Adaptability - Governance-controlled parameters for changing needs

protobuf
// MsgCreateAskRequest structure
message MsgCreateAskRequest {
  AskOrder ask_order = 1;
  uint64 order_creation_fee = 2;
}

• AskOrder: orders.proto#L28-L53

• MsgCreateAskResponse: tx.proto#L126-L130

• Market does not exist or disallows order creation

• Seller lacks required attributes or assets

• Insufficient fees or invalid denomination

• External ID already in use

protobuf
// MsgCreateBidRequest structure
message MsgCreateBidRequest {
  BidOrder bid_order = 1;
  uint64 order_creation_fee = 2;
}

• BidOrder: orders.proto#L55-L78

• MsgCreateBidResponse: tx.proto#L142-L146

protobuf
// MsgCommitFundsRequest structure
message MsgCommitFundsRequest {
  string account = 1;
  uint32 market_id = 2;
  repeated cosmos.base.v1beta1.Coin amount = 3;
  cosmos.base.v1beta1.Coin creation_fee = 4;
}

protobuf
// MsgCancelOrderRequest structure
message MsgCancelOrderRequest {
  string signer = 1;
  uint64 order_id = 2;
}

protobuf
// MsgFillBidsRequest structure
message MsgFillBidsRequest {
  string seller = 1;
  uint32 market_id = 2;
  repeated uint64 bid_order_ids = 3;
  repeated cosmos.base.v1beta1.Coin total_assets = 4;
  // Additional fee fields...
}

protobuf
// MsgFillAsksRequest structure
message MsgFillAsksRequest {
  string buyer = 1;
  uint32 market_id = 2;
  repeated uint64 ask_order_ids = 3;
  cosmos.base.v1beta1.Coin total_price = 4;
  // Additional fee fields...
}

protobuf
// MsgMarketSettleRequest structure
message MsgMarketSettleRequest {
  string admin = 1;
  uint32 market_id = 2;
  repeated uint64 ask_order_ids = 3;
  repeated uint64 bid_order_ids = 4;
  bool expect_partial = 5;
}

protobuf
// MsgMarketCommitmentSettleRequest structure
message MsgMarketCommitmentSettleRequest {
  string admin = 1;
  uint32 market_id = 2;
  repeated AccountAmount inputs = 3;
  repeated AccountAmount outputs = 4;
  repeated NetAssetValue navs = 5;
}

protobuf
// MsgCreatePaymentRequest structure
message MsgCreatePaymentRequest {
  Payment payment = 1;
}

• Payment: payments.proto#L13-L43

• Response: tx.proto#L499-L500

protobuf
// MsgGovCreateMarketRequest structure
message MsgGovCreateMarketRequest {
  string authority = 1;
  Market market = 2;
}

• Market: market.proto#L52-L148

• MarketDetails: market.proto#L28-L40

• FeeRatio: market.proto#L150-L158

• AccessGrant: market.proto#L160-L166

• Permission: market.proto#L168-L186