Merge pull request #1034 from vegaprotocol/enhancements

Proposal enhancements

docs/api/building-blocks.md

@@ -1,5 +1,5 @@
 ---
-title: Building blocks
+title: Basic endpoints
 sidebar_position: 4
 hide_title: false
 description: Building blocks of data and their APIs.
@@ -8,6 +8,29 @@ vega_network: TESTNET
 
 While there are hundreds of available endpoints, the categories below cover the basics to get you started with understanding what you need to interact with Vega. 
 
+## Markets
+Markets use accounts, are created with proposals, and allow parties to place orders with assets.
+
+| Description | Documentation | Call |
+| ----------- | ----------- | ----------- |
+| See all markets on the network | [List markets](../api/rest/data-v2/trading-data-service-list-markets.api.mdx) | `GET /api/v2/markets`
+| Get information about a single market using the market's ID |[Market](../api/rest/data-v2/trading-data-service-get-market.api.mdx) |  `GET /api/v2/market/:marketId`
+| List the latest data for every market | [Markets data](../api/rest/data-v2/trading-data-service-list-latest-market-data.api.mdx) | `GET /api/v2/markets/data`
+|||
+| Understanding the concepts: market lifecycle | [Market lifecycle](../concepts/trading-on-vega/market-lifecycle.md) | 
+
+## Orders and positions
+An order is an instruction to buy or sell on a specific market, and it can go long or short on the market's price. Placing an order does not guarantee it gets filled, but if it is filled, it will result in a position, which will require collateral to use for margin to keep that position open.
+
+| Description | Documentation | Call |
+| ----------- | ----------- | ----------- |
+| Get information about an order using its ID | [Order](../api/rest/data-v2/trading-data-service-get-order.api.mdx) | `GET /api/v2/order/:orderId` |
+| Get a list of orders that have been filtered based on information you provide |[List orders](../api/rest/data-v2/trading-data-service-list-orders.api.mdx) | `GET /api/v2/orders`
+| Get a list of all positions for a specific party ID | [List positions](../api/rest/data-v2/trading-data-service-list-all-positions.api.mdx) | `GET /api/v2/positions` 
+| Get a paginated list of all trades, optionally filtered by party, market, or order | [List trades](/api/rest/data-v2/trading-data-service-list-trades.api.mdx) | `GET /api/v2/trades`
+|||
+| Understand the concepts: orders | [Orders](../concepts/trading-on-vega/orders.md) |
+
 ## Parties
 A party is a single user, defined as a Vega public key. As one person or entity can have many public keys, this is a unique identifier as far as an individual key's actions.  Party ID and public key (pubkey) are all names for the same thing.
 
@@ -55,29 +78,6 @@ Vega relies on accounts to ensure funds are never lost or double spent. The amou
 |||
 | Understanding the concepts: accounts | [Accounts](../concepts/assets/accounts.md) | 
 
-## Markets
-Markets have accounts, are created with proposals, and allow parties to place orders with assets.
-
-| Description | Documentation | Call |
-| ----------- | ----------- | ----------- |
-| See all markets on the network | [List markets](../api/rest/data-v2/trading-data-service-list-markets.api.mdx) | `GET /api/v2/markets`
-| Get information about a single market using the market's ID |[Market](../api/rest/data-v2/trading-data-service-get-market.api.mdx) |  `GET /api/v2/market/:marketId`
-| List the latest data for every market | [Markets data](../api/rest/data-v2/trading-data-service-list-latest-market-data.api.mdx) | `GET /api/v2/markets/data`
-|||
-| Understanding the concepts: market lifecycle | [Market lifecycle](../concepts/trading-on-vega/market-lifecycle.md) | 
-
-## Orders and positions
-An order is an instruction to buy or sell on a specific market, and it can go long or short on the market's price. Placing an order does not guarantee it gets filled, but if it is filled, it will result in a position, which will require collateral to use for margin to keep that position open.
-
-| Description | Documentation | Call |
-| ----------- | ----------- | ----------- |
-| Get information about an order using its ID | [Order](../api/rest/data-v2/trading-data-service-get-order.api.mdx) | `GET /api/v2/order/:orderId` |
-| Get a list of orders that have been filtered based on information you provide |[List orders](../api/rest/data-v2/trading-data-service-list-orders.api.mdx) | `GET /api/v2/orders`
-| Get a list of all positions for a specific party ID | [List positions](../api/rest/data-v2/trading-data-service-list-all-positions.api.mdx) | `GET /api/v2/positions` 
-| Get a paginated list of all trades, optionally filtered by party, market, or order | [List trades](/api/rest/data-v2/trading-data-service-list-trades.api.mdx) | `GET /api/v2/trades`
-|||
-| Understand the concepts: orders | [Orders](../concepts/trading-on-vega/orders.md) |
-
 ## Governance proposals and voting
 Governance proposals used to add new assets and markets, as well as to suggest changes to assets, markets, and network parameters, as well as off-chain suggestions. VEGA tokens need to be associated to the Vega public key that wants to take part in governance.
 

docs/api/overview.md

@@ -48,8 +48,8 @@ If you have a client that you want use to send a transaction using the Vega wall
 
 :::note Go deeper
 * **[Guide: How to build and send transactions](../tutorials/build-send-transactions.md)**: See how to build and send transactions using the Vega Wallet.
-* **[Concept: Transactions](./../concepts/vega-chain/transactions.md)**: Learn about the concepts of transactions, commands, validation, and ordering.
 * **[API: Commands](./grpc/vega/commands/v1/commands.proto)** See a full list of transaction types. 
+* **[Concept: Transactions](./../concepts/vega-chain/transactions.md)**: Learn about the concepts of transactions, commands, validation, and ordering.
 :::
 
 ### Transaction hashes

docs/api/public-endpoints.md

@@ -1,8 +1,8 @@
 ---
 sidebar_position: 5
-title: Public endpoints
+title: Public API servers
 hide_title: false
-description: Vega's APIs are served over public endpoints.
+description: Vega's APIs are served over public addresses.
 vega_network: TESTNET
 ---
 
@@ -11,6 +11,7 @@ import DataNodes from '@site/src/components/DataNodes';
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
+## Servers for Vega APIs
 Due to the distributed nature of Vega, most of the APIs are served from a data node, and a few from a core node. This means there is no single API server, and users will need to choose a node to connect to.
 
 This differs from centralised services, as you can't connect to an API server run by a single company, nor does it require a specific access token. When you want to perform an action on the network you'll need to sign the message containing the transaction details with a [wallet app](../tools/vega-wallet/index.md) or a signer library.
@@ -23,10 +24,10 @@ Below, find a list of all the known public servers available for this network, a
 [Data nodes](../concepts/vega-chain/data-nodes.md): Find out what a data node is, and if setting one up for yourself is right for you.
 :::
 
-## Node API endpoints: Fairground
+## Node API servers: Fairground
 <DataNodes frontMatter={frontMatter} />
 
-## Node API endpoints: Validator testnet
+## Node API servers: Validator testnet
 
 <Tabs groupId="servers">
 <TabItem value="REST" label="REST">

docs/api/using-the-apis.md

@@ -12,7 +12,9 @@ import EthAddresses from '@site/src/components/EthAddresses';
 <Topic />
 
 ## Connecting to the APIs
-As most of the APIs are designed to be used for trading-related queries, the best place to try them out is on the testnet network, also known as Fairground. The public endpoints differ between testnet and mainnet, as do the network configurations your Vega-compatible wallet needs in order to connect. See the [public endpoints page](./public-endpoints.md) for details. 
+As most of the APIs are designed to be used for trading-related queries, the best place to try them out is on the testnet network, also known as Fairground. 
+
+The public endpoints differ between testnet and mainnet, as do the network configurations your Vega-compatible wallet needs in order to connect. See the [public endpoints page](./public-endpoints.md) for details. 
 
 To use the Vega APIs, a developer will need access to a network-compatible instance of the relevant software, depending on their goals: core node, data node, and/or Vega Wallet.
 
@@ -27,7 +29,7 @@ Some rate limiting is implemented with default limitations on the APIs.
 
 For the specifics on WebSocket connections, see [WebSocket streams](./websocket.md) page.
 
-To prevent abuse of the APIs provided by data nodes, there are limitations to the rate of API requests that can be enabled by data node operators. Rate limiting is applied on a per-remote-IP-address basis.
+Data node operators can limit the rate of API requests. Rate limiting is applied on a per-remote-IP-address basis.
 
 Each IP address that connects to a data node is assigned a bucket of tokens. That bucket has a maximum capacity, and begins full of tokens. Each API request costs one token, which is removed from the bucket when the call is made. The data node adds a number of tokens every second (the rate of the limiter) to the bucket up to its maximum capacity.
 
@@ -50,7 +52,9 @@ If a client continues to make requests despite having no tokens available, the r
 * REST: `HTTP 429 StatusTooManyRequests for HTTP APIs`
 * gRPC: `14 Unavailable`
 
-Each unsuccessful response will deduct a token from a separate bucket with the same refill rate and capacity as the requests bucket. Exhausting the supply of tokens in this second bucket will result in the client's IP address being banned for a period of time determined by the data node operators, with 10 minutes as the default.
+Each unsuccessful response will deduct a token from a separate bucket with the same refill rate and capacity as the requests bucket. 
+
+Exhausting the supply of tokens in this second bucket will result in the client's IP address being banned for a period of time determined by the data node operators, with 10 minutes as the default.
 
 If banned, the response will be `HTTP 403 Forbidden for HTTP APIs`.
 
@@ -59,16 +63,16 @@ Read more about rate limiting in the [rate limiting README ↗](https://github.c
 ## Formatting and field conventions
 
 ### Strings vs numbers format
-When using an API, in many cases the field is described as requiring a number but the data type is a string. Numerical fields are passed in string format so that there is no loss of precision, or risk of integer overflow for large numbers.
+Often when an API requires a number, it uses the `string` data type. Numerical fields are passed in string format so that there is no loss of precision, or risk of integer overflow for large numbers.
 
 ### Decimal precision
 The APIs don't provide or accept decimal points in numbers or strings, so the decimal precision must be calculated and the number represented in integers, depending on what decimal precision the number needs. 
 
-* For quotes and prices, use the *market decimal places* to calculate, which can be found by [querying for a market's parameters](../api/rest/data-v2/trading-data-service-get-market.api.mdx) and using `decimalPlaces`
-* For fees, margin, and liquidity, use the *settlement asset decimal places* to calculate, which can be found by [querying an asset's parameters](../api/rest/data-v2/trading-data-service-get-asset.api.mdx) and using `decimals`
+* For quotes and prices, use the *market decimal places* to calculate, which can be found by [querying for a market's parameters](../api/rest/data-v2/trading-data-service-get-market.api.mdx) and using `decimalPlaces`.
+* For fees, margin, and liquidity, use the *settlement asset decimal places* to calculate, which can be found by [querying an asset's parameters](../api/rest/data-v2/trading-data-service-get-asset.api.mdx) and using `decimals`.
 
 ### Timestamps
-Unless otherwise specified, response timestamps, are encoded as a Unix timestamp, which is counted from midnight on 1 January, 1970. Requests that require timestamps will also need to be submitted in Unix time. Whether it's a nanosecond, second, or other, is signposted in the tutorial or API reference documentation.
+Unless otherwise specified, response timestamps are encoded as a Unix timestamp, which is counted from midnight on 1 January, 1970. Requests that require timestamps will also need to be submitted in Unix time. Whether it's a nanosecond, second, or other, is signposted in the tutorial or API reference documentation.
 
 ## Available frameworks
 
@@ -90,12 +94,13 @@ REST is easy to get started with, and Vega supports nearly all the functionality
 
 Try out queries and learn the structure with the [GraphQL playground ↗](https://api.testnet.vega.xyz/graphql/)
 
-## Vega Wallet integration
+<!--## Vega Wallet integration
 To integrate the Vega Wallet with a dApp or bots, you'll likely need to use the wallet API.
 
 The **Wallet API** uses JSON-RPC with an HTTP wrapper. Find out [how to use the API](./vega-wallet/before-you-start.md) before jumping into the reference docs. 
 
 [Download a Vega Wallet](../tools/vega-wallet/index.md) to use the Wallet API to programmatically interact with the network for your own transactions.
+-->
 
 ## Asset bridges
 Vega uses ERC-20 assets from Ethereum and Arbitrum, and to facilitate inter-chain interactions between Vega and other chains, those assets are then transferred through a series of smart contract bridges. These bridges let participants use ERC-20 and other assets on the (non-Ethereum) Vega chain.

docs/concepts/trading-on-vega/fees.md

@@ -25,6 +25,13 @@ The amount a trader pays in fees for each order is the same regardless of how ma
 
 During a market's opening auction, no fees are collected. If a market is in a price monitoring auction, each side of a matched trade contributes 50% of the infrastructure and liquidity fees. Maker fees are not collected.
 
+### Asset fees are paid in
+Derivatives markets' fees are charged in the market's settlement asset. 
+
+Spot markets' fees are charged in the market's quote asset. 
+
+The aggressor *buying* the base asset for the quote asset pays more in their trade to cover the fees. The aggressor *selling* the base asset has the fees deducted from the quote asset amount they receive.
+
 ### Fee distribution and breakdown
 Fees are calculated when a trade is filled, and paid in the market's settlement currency. The fees due are taken from the collateral in the trader's general account. 
 

docs/tutorials/assets-tokens/transferring-assets.md

@@ -157,7 +157,7 @@ You will need to define the dispatch strategy, which includes the  metric, the l
 | Dispatch strategy field | Description | Accepted values |
 | ----------- | ----------- | ----------- |
 | `assetForMetric` | Asset that's used to evaluate how someone performs, such as the settlement asset for the market(s) relevant to the reward | Any asset enabled on Vega |
-| `metric` | Specific reward category the transfer is funding | DISPATCH_METRIC_MAKER_FEES_PAID; DISPATCH_METRIC_MAKER_FEES_RECEIVED; DISPATCH_METRIC_LP_FEES_RECEIVED; DISPATCH_METRIC_MARKET_VALUE; DISPATCH_METRIC_AVERAGE_POSITION; DISPATCH_METRIC_RELATIVE_RETURN; DISPATCH_METRIC_RETURN_VOLATILITY; DISPATCH_METRIC_VALIDATOR_RANKING |
+| `metric` | Specific reward category the transfer is funding | DISPATCH_METRIC_MAKER_FEES_PAID; DISPATCH_METRIC_MAKER_FEES_RECEIVED; DISPATCH_METRIC_LP_FEES_RECEIVED; DISPATCH_METRIC_MARKET_VALUE; DISPATCH_METRIC_AVERAGE_POSITION; DISPATCH_METRIC_RELATIVE_RETURN; DISPATCH_METRIC_RETURN_VOLATILITY; DISPATCH_METRIC_REALISED_RETURN; DISPATCH_METRIC_VALIDATOR_RANKING |
 | `markets` | Optional: Used to choose which market(s) are in scope | Any trading market's ID |
 | `stakingRequirement` | Optional: Sets a minimum number of VEGA tokens that need to be staked for a party to be considered eligible for the reward | Number, if omitted it defaults to 0 |
 | `notionalTimeWeightedAveragePositionRequirement` | Optional: Sets a minimum notional TWAP required for a party to be considered eligible to receive rewards | Defaults to 0 | 

docs/tutorials/index.md

@@ -32,10 +32,11 @@ Take a look at the tutorials for help with using the Vega software.
 | 🛍️ [Propose a new futures market](./proposals/new-market-proposal.md)        | How to propose a new futures market |
 | 💹 [Propose a new spot market](./proposals/new-spot-market.md)        | How to propose a new spot market |
 | ⇒ [Propose a new successor futures market](./proposals/new-successor-market-proposal.md)        | How to propose a new successor futures market |
-| 🛒 [Propose a change to a market](./proposals/update-market-proposal.md)        | How to propose an update to market parameters |
+| 🛒 [Propose changing a futures market](./proposals/update-market-proposal.md)        | How to propose changing futures market parameters |
+| 🛒 [Propose changing a spot market](./proposals/update-spot-market.md)        | How to propose changing spot market parameters |
 | 🪙 [Propose a new asset](./proposals/new-asset-proposal.md)        | How to propose a new asset |
 | 🌉 [Update the asset bridge](./proposals/update-asset-bridge.md)        | How to add the asset to the bridge after proposing it |
-| 💱 [Propose a change to an asset](./proposals/update-asset-proposal.md)        | How to propose an update to an asset |
+| 💱 [Propose changing an asset](./proposals/update-asset-proposal.md)        | How to propose changing an asset's parameters |
 | 💡 [Create a freeform proposal](./proposals/freeform-proposal.md)                     | How to create a freeform proposal |
 
 ## Community-created projects

docs/tutorials/proposals/_batch-sample.md

@@ -1,5 +1,3 @@
-
-## Submitting proposals in a batch
 If you want to submit this proposal as part of a larger batch of proposals, follow this sample structure:
 
 ```

docs/tutorials/proposals/asset-transfer-proposal.md

@@ -66,7 +66,7 @@ You will need to define the dispatch strategy, which includes the metric, the le
 | Dispatch strategy field | Description | Accepted values |
 | ----------- | ----------- | ----------- |
 | `assetForMetric` | Asset that's used to evaluate how someone performs. Use the settlement asset for the market(s) relevant to the reward. Not required for market creation and validator ranking rewards | Any asset enabled on Vega |
-| `metric` | Specific reward category the transfer is funding | DISPATCH_METRIC_MAKER_FEES_PAID; DISPATCH_METRIC_MAKER_FEES_RECEIVED; DISPATCH_METRIC_LP_FEES_RECEIVED; DISPATCH_METRIC_MARKET_VALUE; DISPATCH_METRIC_AVERAGE_POSITION; DISPATCH_METRIC_RELATIVE_RETURN; DISPATCH_METRIC_RETURN_VOLATILITY; DISPATCH_METRIC_VALIDATOR_RANKING |
+| `metric` | Specific reward category the transfer is funding | DISPATCH_METRIC_MAKER_FEES_PAID; DISPATCH_METRIC_MAKER_FEES_RECEIVED; DISPATCH_METRIC_LP_FEES_RECEIVED; DISPATCH_METRIC_MARKET_VALUE; DISPATCH_METRIC_AVERAGE_POSITION; DISPATCH_METRIC_RELATIVE_RETURN; DISPATCH_METRIC_RETURN_VOLATILITY; DISPATCH_METRIC_REALISED_RETURN; DISPATCH_METRIC_VALIDATOR_RANKING |
 | `markets` | Optional: Used to choose which market(s) are in scope. If left blank, all markets that are settled in the asset are included | Any trading market's ID |
 | `stakingRequirement` | Optional: Sets a minimum number of VEGA tokens that need to be staked for a party to be considered eligible for the reward | Number, if omitted it defaults to 0 |
 | `notionalTimeWeightedAveragePositionRequirement` | Optional: Sets a minimum notional TWAP, measured for the asset metric, that's required for a party to be considered eligible to receive rewards | Defaults to 0 | 
@@ -105,6 +105,7 @@ You will need to define the dispatch strategy, which includes the metric, the le
   "distributionStrategy": "DISTRIBUTION_STRATEGY_PRO_RATA"
 ```
 
+## Submitting proposals in a batch
 <Batch />
 
 ## Templates and submitting

docs/tutorials/proposals/freeform-proposal.md

@@ -36,6 +36,8 @@ You will need:
 
 <!-- You should also share your proposal idea in the [_Freeform Proposals_ forum section ↗](https://community.vega.xyz/c/governance/free-form-proposals/31) before submitting it to the network.
 -->
+
+## Submitting proposals in a batch
 <Batch />
 
 ## Templates and submitting