Merge pull request #105 from provenance-io/update-sdk-docs

Updated SDK spec changes from provenance/x
provenance-io · Feb 2, 2024 · 015d900 · 015d900
2 parents b39e6c8 + f915d54
commit 015d900
Show file tree

Hide file tree

Showing 10 changed files with 49,443 additions and 34,180 deletions.
diff --git a/docs/sdk/README.md b/docs/sdk/README.md
@@ -1,3 +1,7 @@
+---
+sidebar_position: 0
+---
+
 # List of Modules
 
 Modules are the code components of the Provenance Blockchain that execute the majority of the business logic for applications. The [Cosmos SDK](https://docs.cosmos.network/v0.47) enables developers to build modules that utilize the core structure of the SDK to allow the modules to function together. To read more about creating modules, refer to the [Cosmos documentation on modules](https://docs.cosmos.network/v0.47/building-modules/intro).

diff --git a/docs/sdk/exchange/01_concepts.md b/docs/sdk/exchange/01_concepts.md
@@ -12,15 +12,18 @@ The exchange module defines a portion of market fees to be paid to the chain (di
     - [Required Attributes](#required-attributes)
     - [Market Permissions](#market-permissions)
     - [Settlement](#settlement)
+    - [Commitment Settlement](#commitment-settlement)
   - [Orders](#orders)
     - [Ask Orders](#ask-orders)
     - [Bid Orders](#bid-orders)
     - [Partial Orders](#partial-orders)
     - [External IDs](#external-ids)
+  - [Commitments](#commitments)
   - [Fees](#fees)
     - [Order Creation Fees](#order-creation-fees)
     - [Settlement Flat Fees](#settlement-flat-fees)
     - [Settlement Ratio Fees](#settlement-ratio-fees)
+    - [Commitment Fees](#commitment-fees)
     - [Exchange Fees](#exchange-fees)
 
 
@@ -33,35 +36,41 @@ Fees can only be managed with a governance proposal using the [MsgGovManageFeesR
 
 Each market has a set of optional details designed for human-use, e.g. name, description, website url.
 
-A market is responsible (off-chain) for identifying order matches and triggering (on-chain) settlement.
+If a market accepts orders, it is responsible (off-chain) for identifying order matches and triggering (on-chain) settlement.
+If a market accepts commitments, it is able to manage committed funds and is responsible for releasing commitments as needed.
 
 A market receives fees for order creation and order settlement. It also defines what fees are required and what is acceptable as payments.
 
 A market can delegate various [permissions](#market-permissions) to other accounts, allowing those accounts to use specific endpoints on behalf of the market.
 
-Markets can restrict who can create orders with them by defining account attributes that are required to create orders. See [Required Attributes](#required-attributes).
+Markets can restrict who can create orders or commitments with them by defining account attributes that are required to create orders. See [Required Attributes](#required-attributes).
 
 Markets can control whether user-settlement is allowed.
 When user-settlement is allowed, the [FillBids](03_messages.md#fillbids) and [FillAsks](03_messages.md#fillasks) endpoints can be used for orders in the market.
 
 A market can also control whether orders can be created for it.
 When order creation is not allowed, any existing orders can still be settled or cancelled, but no new ones can be made (in that market).
 
+A market can separately control whether funds can be committed to it.
+When commitments are not allowed, any existing commitments can still be settled or cancelled, but no new funds can be committed (to that market).
+
 The fees collected by a market are kept in the market's account, and can be accessed using the [MarketWithdraw](03_messages.md#marketwithdraw) endpoint.
 
 See also: [Market](03_messages.md#market).
 
+
 ### Required Attributes
 
-There is a separate list of attributes required to create each order type.
-If one or more attributes are required to create an order of a certain type, the order creator (buyer or seller) must have all of them on their account.
+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 (e.g. buyer, seller, or committer) must have all of them on their account.
 
 Required attributes can have a wildcard at the start to indicate that any attribute with the designated base and one (or more) level(s) is applicable.
 The only place a wildcard `*` is allowed is at the start of the string and must be immediately followed by a period.
 For example, a required attribute of `*.kyc.pb` would match an account attribute of `buyer.kyc.pb` or `special.seller.kyc.pb`, but not `buyer.xkyc.pb` (wrong base) or `kyc.pb` (no extra level).
 
 Attributes are defined using the [x/name](/x/name/spec/README.md) module, and are managed on accounts using the [x/attributes](/x/attribute/spec/README.md) module.
 
+
 ### Market Permissions
 
 The different available permissions are defined by the [Permission](03_messages.md#permission) proto enum message.
@@ -71,9 +80,9 @@ Each market manages its own set of [AccessGrants](03_messages.md#accessgrant), w
 * `PERMISSION_UNSPECIFIED`: it is an error to try to use this permission for anything.
 * `PERMISSION_SETTLE`: accounts with this permission can use the [MarketSettle](03_messages.md#marketsettle) endpoint for a market.
 * `PERMISSION_SET_IDS`: accounts with this permission can use the [MarketSetOrderExternalID](03_messages.md#marketsetorderexternalid) endpoint for a market.
-* `PERMISSION_CANCEL`: accounts with this permission can use the [CancelOrder](03_messages.md#cancelorder) endpoint to cancel orders in a market.
+* `PERMISSION_CANCEL`: accounts with this permission can use the [CancelOrder](03_messages.md#cancelorder) and [MarketReleaseCommitments](03_messages.md#marketreleasecommitments) endpoints to cancel orders and release commitments in a market.
 * `PERMISSION_WITHDRAW`: accounts with this permission can use the [MarketWithdraw](03_messages.md#marketwithdraw) endpoint for a market.
-* `PERMISSION_UPDATE`: accounts with this permission can use the [MarketUpdateDetails](03_messages.md#marketupdatedetails), [MarketUpdateEnabled](03_messages.md#marketupdateenabled), and [MarketUpdateUserSettle](03_messages.md#marketupdateusersettle) endpoints for a market.
+* `PERMISSION_UPDATE`: accounts with this permission can use the [MarketUpdateDetails](03_messages.md#marketupdatedetails), [MarketUpdateAcceptingOrders](03_messages.md#marketupdateacceptingorders), [MarketUpdateUserSettle](03_messages.md#marketupdateusersettle), [MarketUpdateAcceptingCommitments](03_messages.md#marketupdateacceptingcommitments), and [MarketUpdateIntermediaryDenom](03_messages.md#marketupdateintermediarydenom) endpoints for a market.
 * `PERMISSION_PERMISSIONS`: accounts with this permission can use the [MarketManagePermissions](03_messages.md#marketmanagepermissions) endpoint for a market.
 * `PERMISSION_ATTRIBUTES`: accounts with this permission can use the [MarketManageReqAttrs](03_messages.md#marketmanagereqattrs) endpoint for a market.
 
@@ -109,6 +118,23 @@ E.g. If an order's funds are in a sanctioned account, settlement of that order w
 Or, if a marker has required attributes, but the recipient does not have those attributes, settlement will fail.
 
 
+### Commitment Settlement
+
+A market can move funds committed to it by using the [MarketCommitmentSettle](03_messages.md#marketcommitmentsettle) endpoint.
+
+During commitment settlement:
+
+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.
+See also: [Commitment Fees](#commitment-fees).
+
+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.
+
+
 ## Orders
 
 Orders are created by users that want to trade assets in a market.
@@ -208,18 +234,36 @@ Orders with external ids can be looked up using the [GetOrderByExternalID](05_qu
 External ids are limited to 100 characters.
 
 
+
+## Commitments
+
+A Commitment allows an account to give control of some of its funds to a market.
+
+When funds are committed to a market, they remain in the source account and a [hold](../../hold/spec/01_concepts.md#holds) is placed on them.
+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 the [MarketCommitmentSettle](03_messages.md#marketcommitmentsettle) endpoint or cancels the commitment in part or full.
+Commitments can only be cancelled by the market (or a governance proposal).
+
+For a market to start accepting commitments, it must have either a settlement bips, or a commitment creation flat fee defined.
+If a settlement bips is defined, an intermediary denom must also be defined and a NAV must exist from the intermediary denom to the chain's fee denom.
+
+Management of the settlement bips and commitment creation fee options is part of the fee-management governance proposal.
+The `accepting_commitments` flag and intermediary denom are managed using the [MarketUpdateAcceptingCommitments](03_messages.md#marketupdateacceptingcommitments) and [MarketUpdateIntermediaryDenom](03_messages.md#marketupdateintermediarydenom) endpoints.
+
+
 ## Fees
 
 Markets dictate the minimum required fees. It's possible to pay more than the required fees, but not less.
 
 A portion of the fees that a market collects are sent to the blockchain and distributed similar to gas fees.
 This portion is dictated by the exchange module in its [params](06_params.md).
 
-There are three types of fees:
+There are several types of fees:
 
 * Order creation: Flat fees paid at the time that an order is created.
 * Settlement flat fees: A fee paid during settlement that is the same for each order.
 * Settlement ratio fees: A fee paid during settlement that is based off of the order's price.
+* Commitment fees: Fees paid in relation to commitments.
 
 For each fee type, there is a configuration for each order type.
 E.g. the ask-order creation fee is configured separately from the bid-order creation fee.
@@ -309,6 +353,54 @@ The buyer settlement ratio fee should be added to the buyer settlement flat fee
 The ratio and flat fees can be in any denoms allowed by the market, and do not have to be the same.
 
 
+### Commitment Fees
+
+A market can collect commitment fees at commitment creation and/or during settlement.
+
+A market is also charged an extra Tx fee when doing a settlement.
+
+#### Commitment Creation Fees
+
+Similar to order creation fees, these are paid by the committer at the time of committal.
+A portion of these fees are given to the exchange.
+This can only be defined as a flat fee: `fee_create_commitment_flat`: The available `Coin` fee options that are paid by the committer when committing funds.
+The commitment's `creation_fee` must be at least one of the available `fee_create_commitment_flat` options.
+
+#### Commitment Settlement Fee Collection
+
+During a commitment settlement, a market can collect fees by populating the `fees` field in the [MsgMarketCommitmentSettleRequest](03_messages.md#msgmarketcommitmentsettlerequest).
+The exchange does **NOT** keep any portion of these fees.
+Only fees that have been committed to the market can be collected in this way.
+
+#### Commitment Settlement Fee Charge
+
+An additional fee is charged (similar to a msg-based fee) for commitment settlements that is based on the total funds being moved.
+The [CommitmentSettlementFeeCalc](05_queries.md#commitmentsettlementfeecalc) query can be used to find out how much the fee will be for a commitment settlement.
+This fee is provided as a portion of the tx fees (in addition to any gas or other fees).
+
+The fee is calculated as such:
+
+1. Sum the settlement inputs.
+2. Use Marker Net-Asset-Value (NAV) entries (or provided NAV entries) to convert the total into the market's intermediary denom (any amounts in the fee denom are not converted).
+3. A NAV is used to convert the intermediary total to the fee denom (which is added to any fee denom amount in the inputs).
+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.
+
+During step 2, the amount of the intermediary denom is tracked as a real number (not limited to integers).
+At the end of that step, the sum is rounded up to the next integer.
+
+Technically both steps 4 and 5 are done together by doing `amount * bips / 20,000`. If that is not an integer, the result is rounded up.
+
+If a NAV is needed for fee calculation, but does not exist (or wasn't provided), commitment settlement will fail.
+To help, NAVs can be provided as part of a commitment settlement and the marker module will be updated with any NAV info provided.
+NAVs are **NOT** updated in the query, only when provided as part of a settlement.
+NAVs provided to the query are still used for that query, though.
+
+The total is divided by two because the sum of the inputs is effectively double what we usually think of as the "value of a trade".
+E.g. If buying  `1candybar` for `99cusd`, we think of the value of that trade as $0.99.
+Without the halving, though, we might have ended up with a total of $1.98 by converting the `1candybar` into `cusd` (hopefully `99cusd`) and adding that to the other `99cusd`.
+
+
 ### Exchange Fees
 
 A portion of the fees collected by a market, are given to the exchange.

diff --git a/docs/sdk/exchange/02_state.md b/docs/sdk/exchange/02_state.md
@@ -12,15 +12,20 @@ Big-endian ordering is used for all conversions between numbers and byte arrays.
   - [Markets](#markets)
     - [Market Create-Ask Flat Fee](#market-create-ask-flat-fee)
     - [Market Create-Bid Flat Fee](#market-create-bid-flat-fee)
+    - [Market Create-Commitment Flat Fee](#market-create-commitment-flat-fee)
     - [Market Seller Settlement Flat Fee](#market-seller-settlement-flat-fee)
     - [Market Seller Settlement Ratio Fee](#market-seller-settlement-ratio-fee)
     - [Market Buyer Settlement Flat Fee](#market-buyer-settlement-flat-fee)
     - [Market Buyer Settlement Ratio Fee](#market-buyer-settlement-ratio-fee)
-    - [Market Inactive Indicator](#market-inactive-indicator)
+    - [Market Not-Accepting-Orders Indicator](#market-not-accepting-orders-indicator)
     - [Market User-Settle Indicator](#market-user-settle-indicator)
+    - [Market Accepting Commitments Indicator](#market-accepting-commitments-indicator)
     - [Market Permissions](#market-permissions)
     - [Market Create-Ask Required Attributes](#market-create-ask-required-attributes)
     - [Market Create-Bid Required Attributes](#market-create-bid-required-attributes)
+    - [Market Create-Commitment Required Attributes](#market-create-commitment-required-attributes)
+    - [Market Commitment Settlement Bips](#market-commitment-settlement-bips)
+    - [Market Intermediary Denom](#market-intermediary-denom)
     - [Market Account](#market-account)
     - [Market Details](#market-details)
     - [Known Market ID](#known-market-id)
@@ -29,6 +34,7 @@ Big-endian ordering is used for all conversions between numbers and byte arrays.
     - [Ask Orders](#ask-orders)
     - [Bid Orders](#bid-orders)
     - [Last Order ID](#last-order-id)
+    - [Commitments](#commitments)
   - [Indexes](#indexes)
     - [Market to Order](#market-to-order)
     - [Owner Address to Order](#owner-address-to-order)
@@ -92,6 +98,14 @@ One entry per configured denom.
 * Value: `<amount (string)>`
 
 
+### Market Create-Commitment Flat Fee
+
+One entry per configured denom.
+
+* Key: `0x01 | <market id (4 bytes)> | 0x11 | <denom (string)>`
+* Value: `<amount (string)>`
+
+
 ### Market Seller Settlement Flat Fee
 
 One entry per configured denom.
@@ -128,7 +142,7 @@ One entry per configured price:fee denom pair.
 See also: [FeeRatio](03_messages.md#feeratio).
 
 
-### Market Inactive Indicator
+### Market Not-Accepting-Orders Indicator
 
 When a market has `accepting_orders = false`, this state entry will exist.
 When it has `accepting_orders = true`, this entry will not exist.
@@ -146,6 +160,15 @@ When it has `allow_user_settlement = false`, this entry will not exist.
 * Value: `<nil (0 bytes)>`
 
 
+### Market Accepting Commitments Indicator
+
+When a market has `accepting_commitments = true`, this state entry will exist.
+When it has `accepting_commitments = false`, this entry will not exist.
+
+* Key: `0x01 | <market id (4 bytes)> | 0x10`
+* Value: `<nil (0 bytes)>`
+
+
 ### Market Permissions
 
 When an address has a given permission in a market, the following entry will exist.
@@ -170,12 +193,32 @@ See also: [AccessGrant](03_messages.md#accessgrant) and [Permission](03_messages
 * Value: `<list of strings separated by 0x1E>`
 
 
+### Market Create-Commitment Required Attributes
+
+* Key: `0x01 | <market id (4 bytes)> | 0x09 | 0x63`
+* Value: `<list of strings separated by 0x1E>`
+
+
+### Market Commitment Settlement Bips
+
+Commitment Settlement Bips is stored as a uint16.
+
+* Key: `0x01 | <market id (4 bytes)> | 0x12`
+* Value: `<bips (2 bytes)>`
+
+
+### Market Intermediary Denom
+
+* Key: `0x01 | <market id (4 bytes)> | 0x13`
+* Value: `<denom>`
+
+
 ### Market Account
 
 Each market has an associated `MarketAccount` with an address derived from the `market_id`.
 Each `MarketAccount` is stored using the `Accounts` module.
 
-+++ https://github.com/provenance-io/provenance/blob/v1.17.0/proto/provenance/exchange/v1/market.proto#L14-L26
++++ https://github.com/provenance-io/provenance/blob/v1.18.0/proto/provenance/exchange/v1/market.proto#L14-L26
 
 
 ### Market Details
@@ -244,6 +287,11 @@ Then this entry is updated to reflect the new order.
 * Value: `<order id (8 bytes)>`
 
 
+### Commitments
+
+* Key: `0x63 | <market_id> (4 bytes) | <addr len (1 byte)> | <addr>`
+* Value: `<coins string>`
+
 ## Indexes
 
 Several index entries are maintained to help facilitate look-ups.