LaconicNetwork/vega-frontend-monorepo
3
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity

chore: add specs (#4497)

Browse Source
This commit is contained in:
Matthew Russell 2023-08-07 08:41:25 +01:00 committed by GitHub
parent a70a7bcc8e
commit 0874314d2a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
45 changed files with 2787 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

138
specs/0001-WALL-wallet.md Normal file
View File

@ -0,0 +1,138 @@
# Wallet
A Vega wallet is required to prepare and submit transaction on Vega (place, cancel, orders etc). See the [wallet docs](https://docs.vega.xyz/docs/mainnet/concepts/vega-wallet) for more on how "crypto" wallets work.
A wallet can contain many public/private key pairs. The public part of each key pair is known the [Party](../protocol/0017-PART-party.md) sometimes just referred to as a key or public key.
The primary job(s) of a wallet is to [sign/encrypt transaction](../protocol/0022-AUTH-auth.md) (so the network can be sure they were sent by a given party) and to broadcast these transactions to a node on the network.
## Set up wallet / Restore wallet
When opening the wallet for the first time, I...
- if the wallet sends telemetry/analytics: **must** be prompted to opt into (or stay out of) analytics (<a name="0001-WALL-003" href="#0001-WALL-003">0001-WALL-003</a>)
- I can restore a wallet from a seed phrase (<a name="0001-WALL-004" href="#0001-WALL-004">0001-WALL-004</a>)
- I can create a new wallet (<a name="0001-WALL-005" href="#0001-WALL-005">0001-WALL-005</a>)
- I can view the back up phrase (<a name="0001-WALL-006" href="#0001-WALL-006">0001-WALL-006</a>)
- I can see the first key without having to "add key". (i.e. The wallet auto generates the first key from the seed phrase) (<a name="0001-WALL-008" href="#0001-WALL-008">0001-WALL-008</a>)
...so I can sign transactions
## Configure network
When using the wallet on a network, I...
- I can have Mainnet and Fairground (testnet) pre-configured (with Mainnet being the default network) (<a name="0001-WALL-009" href="#0001-WALL-009">0001-WALL-009</a>)
- I can create a new network configuration (<a name="0001-WALL-010" href="#0001-WALL-010">0001-WALL-010</a>)
- I can refine the configuration for existing networks (including the ones that come pre-configured) (<a name="0001-WALL-011" href="#0001-WALL-011">0001-WALL-011</a>)
- I can remove networks (<a name="0001-WALL-013" href="#0001-WALL-013">0001-WALL-013</a>)
...so I can broadcast transactions to, and read information from a vega network in my wallet
## Update wallet
When using an older version of a Vega wallet than the current official release, I...
- I am warned if the version I am using is not compatible with the version of Vega on the selected network, and I am given a link to get latest compatible version on github (<a name="0001-WALL-015" href="#0001-WALL-015">0001-WALL-015</a>)
... so the version of the wallet app I am using works with the network I am using
## Log in to a wallet
When using a given wallet, I...
- I can select a wallet and enter the passphrase only once per "session" (<a name="0001-WALL-016" href="#0001-WALL-016">0001-WALL-016</a>)
... so that other users of my machine can not use my wallet, and I am not asked to re-enter frequently
## Connecting to Dapps
When a dapp requests use of a wallet, I...
- I am prompted to either select a wallet or dismiss the prompt (<a name="0001-WALL-017" href="#0001-WALL-017">0001-WALL-017</a>)
- I can select whole wallet (so that new keys are automatically shared) (<a name="0001-WALL-019" href="#0001-WALL-019">0001-WALL-019</a>)
- I can enter wallet passphrase before wallet details are shared (assuming a password has not recently been entered)(<a name="0001-WALL-022" href="#0001-WALL-022">0001-WALL-022</a>)
- I can retrospectively revoke Dapp's access to a Wallet (<a name="0001-WALL-023" href="#0001-WALL-023">0001-WALL-023</a>)
... so that I can control what public keys are shared with a dapp and what dapps can prompt me to sign transactions
## Approving transactions
When a dapp sends a transaction to the wallet for signing and broadcast, I...
- I am prompted to confirm, reject or ignore the transaction (if auto-confirm is not on) (<a name="0001-WALL-024" href="#0001-WALL-024">0001-WALL-024</a>)
- I can see the details of the transaction. See [details of transaction](#transaction-detail). (<a name="0001-WALL-025" href="#0001-WALL-025">0001-WALL-025</a>)
... so I can verify that the transaction being sent is the one I want
## Transaction log
When thinking about a recent or specific transaction, I ...
- I can find a single list of all transactions, completed and ongoing, from all keys and wallets, from my current desktop session and network (<a name="0001-WALL-034" href="#0001-WALL-034">0001-WALL-034</a>)
- I can see transactions that were confirmed by the wallet user (me) (<a name="0001-WALL-035" href="#0001-WALL-035">0001-WALL-035</a>)
- I can see transactions that were rejected by the wallet user (me) (<a name="0001-WALL-036" href="#0001-WALL-036">0001-WALL-036</a>)
- If I switch network, transactions list changes to show the transactions for that network (<a name="0001-WALL-037" href="#0001-WALL-037">0001-WALL-037</a>)
- I can click a transaction in the list to see the transaction details (<a name="0001-WALL-038" href="#0001-WALL-038">0001-WALL-038</a>)
- I can see empty state when there are no transactions for this session (<a name="0001-WALL-039" href="#0001-WALL-039">0001-WALL-039</a>)
... so that I can ensure my wallet is being used appropriately and find transaction I made
## Transaction details
when looking at a specific transaction...
- I can see details of specific transactions I opened (<a name="0001-WALL-041" href="#0001-WALL-041">0001-WALL-041</a>)
- I can find my way to the transaction on block explorer (<a name="0001-WALL-042" href="#0001-WALL-042">0001-WALL-042</a>)
- I can find my way to the complete transaction history for that key on block explorer (<a name="0001-WALL-043" href="#0001-WALL-043">0001-WALL-043</a>)
- I can see [status of broadcasted transactions](0003-WTXN-submit_vega_transaction.md#track-transaction-on-network)
.. so I can find all the information about what has happened with mined and un-mined transactions
## Key management
When using a Vega wallet, I...
- I can create new keys (derived from the source of wallet) (<a name="0001-WALL-052" href="#0001-WALL-052">0001-WALL-052</a>)
- I can see full public key or be able to copy it to clipboard (<a name="0001-WALL-054" href="#0001-WALL-054">0001-WALL-054</a>)
- I can change key name/alias (<a name="0001-WALL-055" href="#0001-WALL-055">0001-WALL-055</a>)
... so I can manage risk (e.g. isolate margin), mitigate the damage of a key being compromised, or use multiple trading strategies
## Taint keys
When protecting myself from use of keys that may be compromised, I..
- I can select a key I wish to taint (<a name="0001-WALL-057" href="#0001-WALL-057">0001-WALL-057</a>)
- I am prompted to enter wallet password to taint key (<a name="0001-WALL-058" href="#0001-WALL-058">0001-WALL-058</a>)
- I can see tainted keys flagged as tainted (<a name="0001-WALL-060" href="#0001-WALL-060">0001-WALL-060</a>)
... so that tainted keys must not be used
When I have accidentally tainted a key I...
- I can select a key to un-taint and be required to enter wallet password (<a name="0001-WALL-061" href="#0001-WALL-061">0001-WALL-061</a>)
...so that I must use the key again
## Manually sign a message
When wishing to use my wallet to sign arbitrary messages, I...
- I can enter content to be signed with key (<a name="0001-WALL-062" href="#0001-WALL-062">0001-WALL-062</a>)
- I can submit/sign the content (<a name="0001-WALL-065" href="#0001-WALL-065">0001-WALL-065</a>)
- I can [track progress](0003-WTXN-submit_vega_transaction.md#track-transaction-on-network) of broadcast transaction either by being given a hash that I can use in block explorer, or see the transaction status
.. so I can control of the message being signed, and can use the message elsewhere (for example to prove I own a wallet)
## Wallet management
When seeking to reduce risk of compromise I...
- I can create multiple wallets (<a name="0001-WALL-066" href="#0001-WALL-066">0001-WALL-066</a>)
- I can switch between wallets (<a name="0001-WALL-067" href="#0001-WALL-067">0001-WALL-067</a>)
- I can remove a wallet (<a name="0001-WALL-068" href="#0001-WALL-068">0001-WALL-068</a>)
- I can change wallet name (<a name="0001-WALL-069" href="#0001-WALL-069">0001-WALL-069</a>)
... so that I must administrate my wallets

64
specs/0002-WCON-connect_vega_wallet.md Normal file
View File

@ -0,0 +1,64 @@
# Connect Vega wallet & select keys
## Connect wallet
When looking to use Vega via a user interface e.g. Dapp (Decentralized web App), I...
- If the app loads and already has a connection it can restore "eagerly" (without the user having to click connect) it **could** do so
- **must** select a connection method / wallet type: (<a name="0002-WCON-002" href="#0002-WCON-002">0002-WCON-002</a>)
- if Rest:
- **must** have the option to input a non-default Wallet location (<a name="0002-WCON-003" href="#0002-WCON-003">0002-WCON-003</a>)
- **must** submit attempt to connect to wallet (<a name="0002-WCON-005" href="#0002-WCON-005">0002-WCON-005</a>)
- if the dapp DOES already have a permission with the wallet: **must** see that wallet is connected (<a name="0002-WCON-007" href="#0002-WCON-007">0002-WCON-007</a>) note: if the user want to connect to a different wallet to the one that they were previously connected with, they will have to hit logout.
- if the app uses one key at a time: **should** show what key is active (re-use the last active key) (<a name="0002-WCON-008" href="#0002-WCON-008">0002-WCON-008</a>)
- if the wallet does NOT have an existing permission with the wallet: **must** prompt user to check wallet app to approve the request to connect wallet: See [Connecting to Dapps](0002-WCON-connect_vega_wallet.md#connect-wallet) for what should happen in wallet app (<a name="0002-WCON-009" href="#0002-WCON-009">0002-WCON-009</a>)
- if new keys are given permission: **must** show the user the keys have been approved (<a name="0002-WCON-010" href="#0002-WCON-010">0002-WCON-010</a>)
- if the dapp uses one key at a time: **should** prompt me to select key. See [select/switch keys](#select-and-switch-keys). (<a name="0002-WCON-014" href="#0002-WCON-014">0002-WCON-014</a>)
- if user rejects connection: **must** see a message saying that the request to connect was denied (<a name="0002-WCON-015" href="#0002-WCON-015">0002-WCON-015</a>)
- if the dapp is unable to connect for technical reason (e.g. CORS): **must** see an explanation of the error, and a method of fixing the issue (<a name="0002-WCON-016" href="#0002-WCON-016">0002-WCON-016</a>)
- ~~Browser wallet~~ `not available yet`
- Fairground hosted wallet
- **must** only be be shown this option if the dapp is connected to fairground (<a name="0002-WCON-039" href="#0002-WCON-039">0002-WCON-039</a>)
- **must** input a wallet name (<a name="0002-WCON-017" href="#0002-WCON-017">0002-WCON-017</a>)
- **must** input a password (<a name="0002-WCON-018" href="#0002-WCON-018">0002-WCON-018</a>)
- if success: **must** see that the wallet is connected and details of connected key (<a name="0002-WCON-019" href="#0002-WCON-019">0002-WCON-019</a>)
- if failure: **must** see reason for failure (<a name="0002-WCON-020" href="#0002-WCON-020">0002-WCON-020</a>)
- _note: the fairground hosted wallet is configured to automatically approve connections from dapps so there is no need for key selection._
- **must** have the option to select a different method / wallet type if I change my mind (<a name="0002-WCON-021" href="#0002-WCON-021">0002-WCON-021</a>)
... so I can use the interface to read data about my key/party or request my wallet to broadcast transactions to a Vega network.
## Disconnect wallet
When wishing to disconnect my wallet, I...
- **must** see an option to disconnect wallet (<a name="0002-WCON-022" href="#0002-WCON-022">0002-WCON-022</a>)
- **must** see confirmation that wallet has been disconnected (<a name="0002-WCON-023" href="#0002-WCON-023">0002-WCON-023</a>)
... so that I can protect my wallet from malicious use or select a different wallet to connect to
## Select and switch keys
when looking to do something with a specific key (or set of keys) from my wallet, I...
- **must** see what key is currently selected (if any) (<a name="0002-WCON-025" href="#0002-WCON-025">0002-WCON-025</a>)
- **must** see a list of keys that are approved from the connected wallet (<a name="0002-WCON-026" href="#0002-WCON-026">0002-WCON-026</a>)
- for each key:
- **must** see the first and last 6 digits of the [public key](DATA-data_display.md#public-keys). (<a name="0002-WCON-027" href="#0002-WCON-027">0002-WCON-027</a>)
- **must** be able to copy to clipboard the whole public key (<a name="0002-WCON-029" href="#0002-WCON-029">0002-WCON-029</a>)
- **must** see the key name/alias (meta data) (<a name="0002-WCON-030" href="#0002-WCON-030">0002-WCON-030</a>)
- **must** see the option to trigger a re-authenticate so I can use newly created keys (<a name="0002-WCON-035" href="#0002-WCON-035">0002-WCON-035</a>)
...so that I can select the key(s) that I want to use.

49
specs/0003-WTXN-submit_vega_transaction.md Normal file
View File

@ -0,0 +1,49 @@
# Submit Vega transaction
A dapp sends a transaction to a wallet, that wallet then broadcasts the transaction to a network. Therefore the following is broken up into two steps. The transaction could fail at either. Generally: Once the transaction has gone to the network a user can use block explorer to track the transaction, but some tracking in Dapp or wallet will help.
When submitting a Vega transaction of any kind, I...
## Track transaction to wallet
if not connected to a Vega wallet:
- **must** be told that I am not connected, so can not submit a transaction, and given the [option to connect](0012-WCON-connect_vega_wallet.md). (Note: this may have happened if the wallet has become disconnected without the user knowing) (<a name="0003-WTXN-001" href="#0003-WTXN-001">0003-WTXN-001</a>)
if transaction not auto approved by wallet:
- **must** see a prompt to check connected vega wallet to approve transaction (<a name="0003-WTXN-002" href="#0003-WTXN-002">0003-WTXN-002</a>)
- **could** see the transaction details that has been passed to the wallet for broadcast
if transaction is approved by wallet:
- **must** see A [transaction hash](DATA-data_display.md#transaction-hash) (<a name="0003-WTXN-003" href="#0003-WTXN-003">0003-WTXN-003</a>)
- **must** see the public key that this transaction was submitted for (<a name="0003-WTXN-004" href="#0003-WTXN-004">0003-WTXN-004</a>)
- **should** see the alias for the key that submitted this transaction
- **could** see a prompt to set this app to [auto approve](0001-WALL-wallet.md#approving-transactions) in wallet app
if transaction is rejected by wallet:
- **could** see that the order was rejected by the connected wallet (closing the window automatically may be appropriate) (<a name="0003-WTXN-007" href="#0003-WTXN-007">0003-WTXN-007</a>)
if the wallet does not respond:
- **must** not be able prevented from using the app, e.g. you can (<a name="0003-WTXN-008" href="#0003-WTXN-008">0003-WTXN-008</a>)
- **would** like to be able to cancel the transaction from the dapp so that the wallet is no longer in the state where it is asking user to confirm
if the wallet highlights an issue with the transaction:
- **must** show that the transaction was marked as invalid by the wallet and not broadcast (aka an error was returned from Wallet) (<a name="0003-WTXN-009" href="#0003-WTXN-009">0003-WTXN-009</a>)
- **should** see the error returned highlighted in context of the form that submitted the transaction in Dapp
- **must** show error returned by wallet (<a name="0003-WTXN-011" href="#0003-WTXN-011">0003-WTXN-011</a>)
## Track transaction on network
- **must** see a link to that transaction in a block explorer for the appropriate network (<a name="0003-WTXN-012" href="#0003-WTXN-012">0003-WTXN-012</a>)
- **should** see an indication transaction status
- **should** see the network the transaction was broadcast to
- **should** see the block the transaction was processed in
- **should** show the node the transaction was broadcast to
- **could** see the validator that processed the block the transaction was processed in
... so I am aware of the transactions status of the transactions my wallet is sending and that are being processed by the network

34
specs/0004-EWAL-connect_ethereum_wallet.md Normal file
View File

@ -0,0 +1,34 @@
# Connect Ethereum wallet
Dapps can connect to an Ethereum wallet to complete Ethereum transactions such as Deposits and withdraws to/from Vega, Association and more.
## Connecting wallet
When wanting or needing to write to Ethereum, I...
- will have seen a link to connect that opens connection options (this always happens in context so should be covered by WITH, DEPO, ASSO ACS)
- if first time:
- **must** select a connection method / wallet type: (e.g. wallet connect, injected / metamask) (<a name="0004-EWAL-001" href="#0004-EWAL-001">0004-EWAL-001</a>)
- **must** be prompt to check eth wallet (while the dapp waits for a response) (<a name="0004-EWAL-002" href="#0004-EWAL-002">0004-EWAL-002</a>)
- **must** see an option to cancel the attempted connection (if the wallet fails to respond) (<a name="0004-EWAL-003" href="#0004-EWAL-003">0004-EWAL-003</a>)
- if the app gets multiple keys: the user:
- **should** be shown the keys returned and given a UI to select a key for use (but the pattern is often just to select the first in the array)
- **should** be prompted to select one (in many cases Dapps default to key 0 in the array)
- after first use (if there is a connection to restore):
- **must** prompt wallet to grant access (<a name="0004-EWAL-004" href="#0004-EWAL-004">0004-EWAL-004</a>)
- **should** see previous connection has been recovered
- **should** see a link to trigger a fresh connection / fetch new keys (in in the case where I now want to use a different wallet to the one I was connected with)
- once connected:
- **must** see the connected ethereum wallet Public key (<a name="0004-EWAL-005" href="#0004-EWAL-005">0004-EWAL-005</a>)
... so I can sign and broadcast Ethereum transactions, use a key address as in input, or read data from ethereum via my connected wallet
## Disconnecting
When I'm finished using a connected Ethereum wallet I may wish to disconnect...
- **must** see a link to disconnect (<a name="0004-EWAL-006" href="#0004-EWAL-006">0004-EWAL-006</a>)
- **must** destroy dapp -> ETH wallet session so that hitting connect again triggers the modal that asks what method you'd like to use to connect to an ETH wallet, (note: it is not possible to invalidate the permission the metamask wallet has granted the app, therefore users will need to know that if they want to connect to a new ETH key they will have to do so from the wallet) (<a name="0004-EWAL-007" href="#0004-EWAL-007">0004-EWAL-007</a>)
... so that I can use a different wallet, or ensure may wallet can not be used by other apps

60
specs/0005-ETXN-submit_ethereum_transaction.md Normal file
View File

@ -0,0 +1,60 @@
# Submit Ethereum transaction
## Know what transaction I'm signing
When about to click to prompt Ethereum wallet to sign a transaction, I...
- **should** see the contract address I am about to interact with
- **should** see the function name I am about to interact with
...so I know what to expect when my wallet asks me to sign
## Track transactions to wallet
after clicking to submit an eth transaction to a connected wallet, I...
- **could** see an estimate for gas prices compared to a recent history
- **could** see an estimated gas price for the function in question
- **must** see prompt to check Ethereum wallet to approve transactions
... so I know I need to go to my wallet app to approve the transaction
## ERC20 approval/permit
> The approval/permit step is part of the [ERC20 standard](https://ethereum.org/en/developers/docs/standards/tokens/erc-20/). It's intention is to provide additional security when interacting with smart contracts / using Dapps. It sets a maximum amount that the given eth key can send to a given address. It means that before end "spend" of ERC20 tokens I will have need to submit a "approve" transaction to tell the network how much is approved. An attempt to spend more than the approved amount will fail.
> For example: In my approve transaction, I approve 10, I then spend 5. In my next transaction I attempt to spend 6, this will fail as my approve amount was reduced by the first transaction.
> It is common for dapps to have a approve button that simply asks to approve a massive amount and leave it up to the wallet UI (e.g. metamask) to ask the user if they would like to change this.
> Some ERC20 contracts have an additional function that runs both the approve and deposit function in one, but this is not standard.
If the transaction in question requires an ERC20 approval, I...
- if the current approved amount is less than the amount being "spent": **must** see be prompt to approve
- **could** see the current approved amount
- **must** be able to set the amount to be approved (in case the connected wallet does not handle this) (<a name="0005-ETXN-006" href="#0005-ETXN-006">0005-ETXN-006</a>)
- **must** send an approve transaction with either a user specified amount or a very large number (<a name="0005-ETXN-001" href="#0005-ETXN-001">0005-ETXN-001</a>)
- **must** see feedback of the state of approve transaction see "tracking ethereum transactions" below. (<a name="0005-ETXN-002" href="#0005-ETXN-002">0005-ETXN-002</a>)
... so I can control the maximum permitted transfer to the contract in question
## Tracking Ethereum transactions on network
After approving a transaction in my wallet app, I...
- **should** see link to the transaction on etherscan
- **must** see the transactions status (Pending, confirmed, etc) on Ethereum by reading Ethereum (via connected wallet or the back up node specified in the app) (<a name="0005-ETXN-003" href="#0005-ETXN-003">0005-ETXN-003</a>)
- if failed: **must** see why the transaction failed (e.g. didn't pay enough gas) (<a name="0005-ETXN-004" href="#0005-ETXN-004">0005-ETXN-004</a>)
- if success: **should** see how many blocks ago the transaction was confirmed by the eth node being read
... so I can see the status of the transaction and debug as appropriate
## Tracking Ethereum transactions having their affect on Vega
Note: it is common for inter-blockchain applications to wait a certain amount of blocks before crediting money, as this reduces the risk of double spend in the case of forks or chain roll backs. There is a Vega environment variable the defines how long Vega waits.
If the ethereum transaction I've just submitted changes the state of the Vega network (e.g. a deposit from eth appearing as credited to my vega key on vega), I...
- **should** see how many Ethereum blocks Vega needs to wait before changing the state of Vega
- **should** see how many blocks have passed or remain until the required number has been met
- **must** see whether the expect action has taken place on Vega (e.g. credited Vega key) (<a name="0005-ETXN-005" href="#0005-ETXN-005">0005-ETXN-005</a>)
... so I know vega has been updated as appropriate

36
specs/0006-NETW-network-and-nodes.md Normal file
View File

@ -0,0 +1,36 @@
# Select network and nodes
## Startup
- **Must** automatically select a node from the environments network config stored in the [networks repo](https://github.com/vegaprotocol/networks) (<a name="0006-NETW-001" href="#0006-NETW-001">0006-NETW-001</a>)
## Network switcher
- **Must** see current network (<a name="0006-NETW-002" href="#0006-NETW-002">0006-NETW-002</a>)
- **Must** be able to change network (<a name="0006-NETW-003" href="#0006-NETW-003">0006-NETW-003</a>)
## Node health
- **Must** see node status
- Operational if node is less than 3 blocks behind (<a name="0006-NETW-004" href="#0006-NETW-004">0006-NETW-004</a>)
- Warning if greater than 3 blocks behind (<a name="0006-NETW-005" href="#0006-NETW-005">0006-NETW-005</a>)
- Warning if vega time is 3 seconds behind current time (<a name="0006-NETW-006" href="#0006-NETW-006">0006-NETW-006</a>)
- Prominent error if vega time is 10 seconds behind current time (<a name="0006-NETW-007" href="#0006-NETW-007">0006-NETW-007</a>)
- **Must** see current connected node (<a name="0006-NETW-008" href="#0006-NETW-008">0006-NETW-008</a>)
- **Must** see current block height (<a name="0006-NETW-009" href="#0006-NETW-009">0006-NETW-009</a>)
- **Must** see block height progressing (<a name="0006-NETW-010" href="#0006-NETW-010">0006-NETW-010</a>)
- **Must** see link to status and incidents site (<a name="0006-NETW-011" href="#0006-NETW-011">0006-NETW-011</a>)
## Node switcher
- **Must** be able to click on current node to open node switcher dialog (<a name="0006-NETW-012" href="#0006-NETW-012">0006-NETW-012</a>)
- In the node dialog
- **Must** must see all nodes provided by the [network config](https://github.com/vegaprotocol/networks) (<a name="0006-NETW-013" href="#0006-NETW-013">0006-NETW-013</a>)
- For each node
- **Must** see the response time of the node (<a name="0006-NETW-014" href="#0006-NETW-014">0006-NETW-014</a>)
- **Must** see the current block height (<a name="0006-NETW-015" href="#0006-NETW-015">0006-NETW-015</a>)
- **Must** see if subscriptions are working for that node (<a name="0006-NETW-016" href="#0006-NETW-016">0006-NETW-016</a>)
- **Must** be able to select and connect to any node, regardless of response time, block height or subscription status (<a name="0006-NETW-017" href="#0006-NETW-017">0006-NETW-017</a>)
- **Must** be able to select 'other' to input a node address and connect to it (<a name="0006-NETW-018" href="#0006-NETW-018">0006-NETW-018</a>)
- **Must** have disabled connect button if 'other' is selected but no url has been entered (<a name="0006-NETW-019" href="#0006-NETW-019">0006-NETW-019</a>)
- **Must** have disabled connect button if selected node is the current node (<a name="0006-NETW-020" href="#0006-NETW-020">0006-NETW-020</a>)

40
specs/1001-DEPO-desposit.md Normal file
View File

@ -0,0 +1,40 @@
# Deposit
The Vega network has no native assets. All settlement assets exist on another chain and are "bridged" to Vega in one way or another.
In the case of [ERC20 tokens](https://ethereum.org/en/developers/docs/standards/tokens/erc-20/) there is a smart contract on the Ethereum network that acts as a vault (aka bridge) for the tokens that are deposited to Vega. The Vega network then reads the information from this vault about what Vega key to credit these tokens to. While in the Vault the Vega key that owns them (and consequently the ethereum key) may change. The vault then manages how much each ethereum key is able to withdraw from the vault given then changes in ownership that may have happened on Vega. The keys to this vault and managed by the different nodes that make up the Vega network. They verify the the appropriate amounts can be withdrawn by each Ethereum key. At time of writing only ERC20 tokens have been implemented but the pattern is likely the same for other assets/networks.
## ERC20 deposits
Note: ERC20 assets require an approval transaction to be finalised before funds can be credited to another key. Read more about approvals [link 1](https://medium.com/ethex-market/erc20-approve-allow-explained-88d6de921ce9), [link 2](https://hackernoon.com/erc20-infinite-approval-a-battle-between-convenience-and-security-lk60350r).
When making to deposit ERC20 assets to an Vega key, I...
- **should** be able to follow a link from an asset (e.g. on a market page) to the deposit form pre-populated with the given asset
- **must** see a link to [connect an ethereum wallet](0004-EWAL-connect_ethereum_wallet.md) that I want to deposit from (<a name="1001-DEPO-001" href="#1001-DEPO-001">1001-DEPO-001</a>)
- **must** select the [asset](9001-DATA-data_display.md#asset) that I want to deposit (<a name="1001-DEPO-002" href="#1001-DEPO-002">1001-DEPO-002</a>)
- **should** easily see the assets that I have a non-zero balance for (in the connected eth wallet)
- **should** see the ERC20 token address of the asset
- **should** see the [Vega asset symbol](9001-DATA-data_display.md#asset-symbol)
- **should** see the [Vega asset name](9001-DATA-data_display.md#asset-name)
- **must** select the [amount of the asset](9001-DATA-data_display.md#asset-balances) that I want to deposit (<a name="1001-DEPO-003" href="#1001-DEPO-003">1001-DEPO-003</a>)
- **should** see an ability to populate the input with the full balance in the connected wallet
- **must** be warned if the amount being deposited is greater than the balance of the token in the connected Eth wallet (<a name="1001-DEPO-004" href="#1001-DEPO-004">1001-DEPO-004</a>)
- **must** select the [Vega key](9001-DATA-data_display.md#public-keys) that I wish to deposit to (<a name="1001-DEPO-005" href="#1001-DEPO-005">1001-DEPO-005</a>)
- **should** be able to [connect to a Vega wallet and select a key](0002-WCON-connect_vega_wallet.md#select-and-switch-keys)
- **should** be easily (if not automatically) pre-populated with a [currently connected and active Vega key](0002-WCON-connect_vega_wallet.md#select-and-switch-keys)
- **should** be able to input a Vega key other than one I am connected with (even without being connected)
- if approved amount is less than deposit:
- **must** see that an approval is needed and be prompted to approve more (<a name="1001-DEPO-006" href="#1001-DEPO-006">1001-DEPO-006</a>)
- **should** see the approved [asset amount](9001-DATA-data_display.md#asset-balances)
- **should** be able to input an amount to approve
- **must** [submit eth transaction to approve](0005-ETXN-submit_ethereum_transaction.md) (<a name="1001-DEPO-007" href="#1001-DEPO-007">1001-DEPO-007</a>)
- **must** see feedback for the approve transaction
- if approved amount is more than deposit amount:
- **could** see the approved [asset amount](9001-DATA-data_display.md#asset-balances)
- **could** set a submit a new [eth transaction to approve more or less](0005-ETXN-submit_ethereum_transaction.md)
- **must** submit the Deposit [eth transaction](0005-ETXN-submit_ethereum_transaction.md) (<a name="1001-DEPO-008" href="#1001-DEPO-008">1001-DEPO-008</a>)
- **must** see feedback on the deposit [ETH transaction](0003-WTXN-submit_vega_transaction.md) (<a name="1001-DEPO-009" href="#1001-DEPO-009">1001-DEPO-009</a>)
- **must** see feedback that the deposit has or has not been credited to the Vega key (<a name="1001-DEPO-010" href="#1001-DEPO-010">1001-DEPO-010</a>)
...so that my Vega key can use these assets on Vega

117
specs/1002-WITH-withdraw.md Normal file
View File

@ -0,0 +1,117 @@
# Withdraw
Withdrawing funds is a two step process.
First the Vega network needs to approve that the funds can be released (not required for margin on open positions or in liquidity bond etc). If they are not, a withdraw is prepared and set aside so that it can not be used for positions etc. This also define what ethereum address will be credited the funds in step 2.
Second the user will need to run an ethereum function on the bridge contract to release the funds (and pay the gas to do so). They do this using a signature supplied by nodes of the Vega network in Step 1.
Although this is a two step process technically effort should be put into making it feel like one, then handle exceptions (like delays on withdrawals) as required.
See [Specs for eth bridge](../protocol/0031-ETHB-ethereum_bridge_spec.md) and [docs](https://docs.vega.xyz/docs/mainnet/concepts/vega-protocol#withdrawals) on withdrawals. See also the [specs on delays to withdrawals](../non-protocol-specs/0003-NP-LIMI-limits_aka_training_wheels.md#withdrawal-limits).
## Prepare an ERC20 withdraw from Vega
When wishing to withdraw some of an ERC20 asset from Vega, I...
- **should** be prompted to complete any existing incomplete withdrawals that exist for connected keys (see [complete withdrawal](#complete-erc20-withdraw-from-ethereum-bridge))
Note: It is better to encourage the completion of started withdraws as soon as possible after preparing them. This is because the validator set could theoretically change enough to make the node signatures that authorize the withdrawal invalid.
- **should** be warned that they will need to pay gas on the withdrawal before starting
- **could** show the current gas fees BEFORE preparing the withdrawal (note: shows gas estimate is a general should for all [ethereum transactions](0005-ETXN-submit_ethereum_transaction.md) but this is so a user gets to see the gas costs at step 1 assuming they will do step 2 immediately. )
Note: A user may want to delay preparing a withdrawal if gas fees on the network are particularly high at the time
- **must** select the asset to withdraw (<a name="1002-WITH-001" href="#1002-WITH-001">1002-WITH-001</a>)
- **should not** see option to select assets where I a zero [total balance](9001-DATA-data_display.md#asset-balances) (note this should also avoid `Pending` assets from appearing in the list)
- **must** see the general balance I have for that asset (<a name="1002-WITH-002" href="#1002-WITH-002">1002-WITH-002</a>)
- **should** see balances to the full number of decimal places possible for that asset
- **should** see the total balances of the assets I have
- **could** see a breakdown of other accounts I have in this asset and their balances
- **must** select the [amount](9001-DATA-data_display.md#asset-balances) of the asset I wish to withdraw (<a name="1002-WITH-003" href="#1002-WITH-003">1002-WITH-003</a>)
- **should** have an easy option (link/button) to input the full amount in general balance
- **must** be able to specify as many decimal places as the asset supports (<a name="1002-WITH-004" href="#1002-WITH-004">1002-WITH-004</a>)
- **must** be warned if the amount is greater than general balance (including if the general balance amount changes while the user is looking at the form) (<a name="1002-WITH-005" href="#1002-WITH-005">1002-WITH-005</a>)
- **must** be warned if the amount is lesser than the minimum allowed, where the minimum amount is the selected asset's quantum multiplied by the value of `spam.protection.minimumWithdrawalQuantumMultiple` network parameter (<a name="1002-WITH-026" href="#1002-WITH-026">1002-WITH-026</a>)
- **should** see a link to a faucet on the selected asset (only if there is one)
- **must** specify the Ethereum address that can claim the withdrawal (e.g. where you are withdrawing too) (<a name="1002-WITH-006" href="#1002-WITH-006">1002-WITH-006</a>)
- **should** be able to easily select an Ethereum key the app is already connected to
- **should** be able to withdraw to a different Ethereum key to the one the app is connected to
- **should** be warned if the input does not look like an ethereum address (wrong number of characters, not starting with 0x etc)
- if there is a withdraw delay on the selected asset:
- **should** see how large a withdrawal (or sum of withdrawals) needs to be to hit the `withdraw delay threshold`
- **should** see what the withdraw delay is in hours and mins (if hit)
- **should** see how much I have withdrawn in the last `withdraw delay period`
- **must** be warned if this withdraw will hit a the delay before hitting withdraw (<a name="1002-WITH-007" href="#1002-WITH-007">1002-WITH-007</a>)
- **must** be warned if there are known reasons that the prepared withdrawal will not work (<a name="1002-WITH-008" href="#1002-WITH-008">1002-WITH-008</a>)
- **must** submit a withdraw [vega transaction](0003-WTXN-submit_vega_transaction.md) (<a name="1002-WITH-009" href="#1002-WITH-009">1002-WITH-009</a>)
- if the preparing the withdraw on Vega fails:
- **must** be directed back to the withdraw form (containing the submitted values) and see an explanation of why the transaction failed, so I can fix and resubmit (<a name="1002-WITH-010" href="#1002-WITH-010">1002-WITH-010</a>)
- if the preparing the withdraw on Vega is successful:
- **must** see that withdraw is prepared (<a name="1002-WITH-011" href="#1002-WITH-011">1002-WITH-011</a>)
- if this withdraw will not hit the withdrawal threshold:
- **should** be prompted to complete the transaction on ethereum (see [complete ERC20 withdraw](#complete-erc20-withdraw-from-ethereum-bridge))
- **could** be directed to a list of incomplete withdrawals
- if this withdraw will hit withdrawal threshold:
- **must** see that the withdraw has been complete and is in the list waiting for the delay to pass (<a name="1002-WITH-024" href="#1002-WITH-024">1002-WITH-024</a>)
...so that I can get the details required to release my funds from the the Ethereum ERC20 bridge.
## Withdraws list / history
When looking to either complete a withdraw or view past withdraws, I...
- **must** be able to navigate to a list prepared withdrawals for the [connected to a vega wallet + key(s)](0002-WCON-connect_vega_wallet.md)
- for each prepared withdraw:
- **must** see the asset being withdrawn (<a name="1002-WITH-012" href="#1002-WITH-012">1002-WITH-012</a>)
- **must** see the [amount](9001-DATA-data_display.md#asset-balances) being withdrawn (<a name="1002-WITH-013" href="#1002-WITH-013">1002-WITH-013</a>)
- **must** see the destination of the withdrawal (e.g. Recipient Eth address) (<a name="1002-WITH-014" href="#1002-WITH-014">1002-WITH-014</a>)
- **should** see the date with withdraw was prepared
- **could** see the full signature bundle from Vega node (for use on Ethereum)
- for withdraws that are in progress:
- **must** see the status of the withdraw (e.g. pending) (<a name="1002-WITH-015" href="#1002-WITH-015">1002-WITH-015</a>)
- for completed withdraws:
- **could** see when it was completed on native chain (e.g. ethereum)
- **must** see a link to the transaction on native block explorer (e.g. etherscan) (<a name="1002-WITH-016" href="#1002-WITH-016">1002-WITH-016</a>)
- for withdraws that have not been completed on the external chain, but are not delayed (e.g. Ethereum):
- **must** see a link to complete the withdraw. See [complete ERC20 withdrawal](#complete-erc20-withdraw-from-ethereum-bridge) (<a name="1002-WITH-017" href="#1002-WITH-017">1002-WITH-017</a>)
- for withdrawals that have a delay in place before the transaction can be completed:
- **should** see much of the delay remains before it can be completed
- for withdraws that failed to be prepared (e.g. there was not enough in the general account):
- **must** show that the withdraw preparation failed (<a name="1002-WITH-025" href="#1002-WITH-025">1002-WITH-025</a>)
... so I can complete withdrawals or find details of previous ones
## Complete ERC20 withdraw from Ethereum bridge
When looking to submit the Ethereum transaction to release funds from the Vega bridge into my Ethereum wallet, I...
- **must** see a link to [connect an ethereum wallet](0004-EWAL-connect_ethereum_wallet.md) if not already connected (<a name="1002-WITH-018" href="#1002-WITH-018">1002-WITH-018</a>)
- **must** see a link to [submit the ethereum transaction to finish withdrawal](0005-ETXN-submit_ethereum_transaction.md) (<a name="1002-WITH-019" href="#1002-WITH-019">1002-WITH-019</a>)
- **could** be warned if the connected ethereum wallet is different to the one that the withdraw is going to credit (this is permitted but is a good reminder to the user about what to expect)
- if successful:
- **must** see asset balances have been updated post withdrawal (<a name="1002-WITH-020" href="#1002-WITH-020">1002-WITH-020</a>)
- **must** see the list of withdrawals (with updated status) (<a name="1002-WITH-021" href="#1002-WITH-021">1002-WITH-021</a>)
- **could** see prompt to start another transaction or complete another incomplete one
- if failed:
- **must** see a description of why the transaction failed, and advised what to do (e.g. bad signature) (<a name="1002-WITH-022" href="#1002-WITH-022">1002-WITH-022</a>)
- **must** be returned to a state where I can correct anything that is wrong, and attempt to submit the transaction again (<a name="1002-WITH-023" href="#1002-WITH-023">1002-WITH-023</a>)
- **should** see a link to docs about withdrawals for trouble shooting (e.g. if the signer set has changed significantly since the withdraw was prepared)
- **should** see status of incomplete withdrawals (so I can confirm the withdraw I attempted to complete is incomplete)
... so the funds I withdrew from Vega are credited to my Ethereum key

59
specs/1003-TRAN-transfer.md Normal file
View File

@ -0,0 +1,59 @@
# Transfer
## Transfer Window
- **Must** be able to open transfer window through transfer button under key, account history page and collateral options (<a name="1003-TRAN-001" href="#1003-TRAN-001">1003-TRAN-001</a>)
- **Must** be able to close the window with the x (<a name="1003-TRAN-002" href="#1003-TRAN-002">1003-TRAN-002</a>)
- **Must** display a message showing obfuscated key that funds will be transferred from (<a name="1003-TRAN-003" href="#1003-TRAN-003">1003-TRAN-003</a>)
- **Must** each field has their label. Vega key, Asset, Amount (<a name="1003-TRAN-004" href="#1003-TRAN-004">1003-TRAN-004</a>)
## Vega Key
- **Must**
if the user has multiple keys they must be able to swap between dropdown and manual entry (<a name="1003-TRAN-005" href="#1003-TRAN-005">1003-TRAN-005</a>)
- **Must**
if the user has multiple keys they must be able to select from their list of keys(<a name="1003-TRAN-006" href="#1003-TRAN-006">1003-TRAN-006</a>)
## Asset
- **Must** display a drop down with all assets in the portfolio (<a name="1003-TRAN-007" href="#1003-TRAN-007">1003-TRAN-007</a>)
- **Must** the holdings of each asset is displayed (<a name="1003-TRAN-008" href="#1003-TRAN-008">1003-TRAN-008</a>)
- **Must** i can select any available assets and selected asset is displayed (<a name="1003-TRAN-009" href="#1003-TRAN-009">1003-TRAN-009</a>)
- **Must** selected asset shortname is displayed in the amount field (<a name="1003-TRAN-010" href="#1003-TRAN-010">1003-TRAN-010</a>)
## Validation
- **Must** cannot choose amount over current collateral. Message is displayed (<a name="1003-TRAN-011" href="#1003-TRAN-011">1003-TRAN-011</a>)
- **Must** display "required" message on each field if left blank when clicking button "Confirm Transfer" (<a name="1003-TRAN-012" href="#1003-TRAN-012">1003-TRAN-012</a>)
- **Must** display "Invalid vega key" message on Vega Key field if entered key doesn't pass validation(<a name="1003-TRAN-013" href="#1003-TRAN-013">1003-TRAN-013</a>)
- **Must** "Value below minimum" message is shown if amount is lower than minimum(<a name="1003-TRAN-014" href="#1003-TRAN-014">1003-TRAN-014</a>)
## Transfer
- **Must** can select include transfer fee (<a name="1003-TRAN-015" href="#1003-TRAN-015">1003-TRAN-015</a>)
- **Must** display tooltip for "Include transfer fee" when hovered over.(<a name="1003-TRAN-016" href="#1003-TRAN-016">1003-TRAN-016</a>)
- **Must** display tooltip for "Transfer fee when hovered over.(<a name="1003-TRAN-017" href="#1003-TRAN-017">1003-TRAN-017</a>)
- **Must** display tooltip for "Amount to be transferred" when hovered over.(<a name="1003-TRAN-018" href="#1003-TRAN-018">1003-TRAN-018</a>)
- **Must** display tooltip for "Total amount (with fee)" when hovered over.(<a name="1003-TRAN-019" href="#1003-TRAN-019">1003-TRAN-019</a>)
- **Must** amount to be transferred and transfer fee update correctly when include transfer fee is selected (<a name="1003-TRAN-020" href="#1003-TRAN-020">1003-TRAN-020</a>)
- **Must** total amount with fee is correct with and without "Include transfer fee" selected (<a name="1003-TRAN-021" href="#1003-TRAN-021">1003-TRAN-021</a>)
- **Must** i cannot select include transfer fee unless amount is entered (<a name="1003-TRAN-022" href="#1003-TRAN-022">1003-TRAN-022</a>)
- **Must** With all fields entered correctly, clicking "confirm transfer" button will start transaction(<a name="1003-TRAN-023" href="#1003-TRAN-023">1003-TRAN-023</a>)

70
specs/1004-ASSO-associate.md Normal file
View File

@ -0,0 +1,70 @@
# Associate and disassociate governance tokens with a Vega key
The Governance token on a Vega network is an ERC20 ethereum token. It has two utilities on Vega,
- Staking the Proof of stake network,
- Participating in Governance.
To use the Governance token on a Vega network it first needs to be associated with a Vega key/party. This Vega key can then stake, propose and vote.
The word "associate" is used in some user interfaces, as apposed the word "stake" in function names. Stake can be avoided to prevent users thinking they would get a return only after the staking step. On Vega `Staking = Association + Nomination`, as in you need to run the "stake " function on Ethereum but then the nominate step on Vega before you get staking income. See [Glossary](../glossaries/staking-and-governance.md).
Associated tokens also count as vote weight in on-Vega governance (new markets etc), A parties vote weight is backed by the number of Governance tokens associated with that Vega key/party.
Associating tokens to a Vega key is a little like depositing, except, a deposit can only be released by the Vega network, where as an association can be revoked on ethereum by the the eth key that did the association.
Governance tokens may be held by a [Vesting contract](1005-VEST-vesting.md).
## Token discovery
When looking to acquire governance tokens, I...
- **must** see the contract address for the governance token of the Vega network <a name="1004-ASSO-001" href="#1004-ASSO-001">1004-ASSO-001</a>
...so I can participate in governance and staking.
## Associate
When looking to stake validators or participate in governance, I first need to associate governance tokens with a Vega wallet/key, I...
- **must** [connect an Ethereum wallet/key](0004-EWAL-connect_ethereum_wallet.md) to see tokens it may have in wallet or attributed to it in the vesting contract <a name="1004-ASSO-002" href="#1004-ASSO-002">1004-ASSO-002</a>
- **must** select a Vega key to associate to <a name="1004-ASSO-003" href="#1004-ASSO-003">1004-ASSO-003</a>
- **must** be able use a [connected Vega wallet](0002-WCON-connect_vega_wallet.md) as instead of manually inputting a public key <a name="1004-ASSO-004" href="#1004-ASSO-004">1004-ASSO-004</a>
- **should** be able to populate field with a string, so I can associate to a wallet I without connecting it
- if the connected ethereum wallet has vesting tokens: **must** be able to select to associate from either the vesting contract or the wallet (The default should be wallet and the option to use vesting tokens should only appear if there are tokens in a tranche (associated or not)) <a name="1004-ASSO-006" href="#1004-ASSO-006">1004-ASSO-006</a>
- **must** see the number of associated and un-associated tokens in the selected wallet/vesting contract <a name="1004-ASSO-007" href="#1004-ASSO-007">1004-ASSO-007</a>
- **must** select the amount of tokens to associate <a name="1004-ASSO-008" href="#1004-ASSO-008">1004-ASSO-008</a>
- **must** be able to populate the input with the amount of un-associated tokens for the selected wallet/vesting contract <a name="1004-ASSO-009" href="#1004-ASSO-009">1004-ASSO-009</a>
- **must** be warned if the amount being associated is greater than the amount available in the connected ethereum wallet <a name="1004-ASSO-010" href="#1004-ASSO-010">1004-ASSO-010</a>
- **must** submit the association on [Ethereum transaction(s) inc ERC20 approval if required](0005-ETXN-submit_ethereum_transaction.md) <a name="1004-ASSO-011" href="#1004-ASSO-011">1004-ASSO-011</a>
- **must** see feedback whether my association has been registered on Ethereum <a name="1004-ASSO-012" href="#1004-ASSO-012">1004-ASSO-012</a>
- **must** see feedback that the association has been registered by Vega and that it can be used after the number of Ethereum block confirmations required (typically 50, check network param) <a name="1004-ASSO-013" href="#1004-ASSO-013">1004-ASSO-013</a>
- **should** be able to see a balance for the number of tokens associated that are ready for use <a name="1004-ASSO-014" href="#1004-ASSO-014">1004-ASSO-014</a>
- **should** be able to see a balance for the number of tokens for each pending association <a name="1004-ASSO-015" href="#1004-ASSO-015">1004-ASSO-015</a>
- on completion: **should** be prompted to go on to [nominate](2001-STKE-staking.md) and/or participate in [Governance](1004-GOVE-governance_list.md)
- **must** see the balances of tokens available in Ethereum wallet updated (both associated and un-associated) <a name="1004-ASSO-030" href="#1004-ASSO-030">1004-ASSO-030</a>
- **must** see the balances of tokens available in vesting contract updated (both associated and un-associated) <a name="1004-ASSO-032" href="#1004-ASSO-032">1004-ASSO-032</a>
...so I can then use the Vega wallet to use my tokens.
## Disassociate
When wanting to remove governance tokens, I...
- **must** [connect an Ethereum wallet/key](0004-EWAL-connect_ethereum_wallet.md) to see tokens it may have in wallet or attributed to it in the vesting contract <a name="1004-ASSO-018" href="#1004-ASSO-018">1004-ASSO-018</a>
- **must** see a list Vega keys that the connected Ethereum wallet has associated too <a name="1004-ASSO-019" href="#1004-ASSO-019">1004-ASSO-019</a>
- **must** see an amount associated with each key <a name="1004-ASSO-020" href="#1004-ASSO-020">1004-ASSO-020</a>
- **must** see the full Vega public key associated too <a name="1004-ASSO-021" href="#1004-ASSO-021">1004-ASSO-021</a>
- **must** see the the origin of the association: wallet or vesting contract <a name="1004-ASSO-022" href="#1004-ASSO-022">1004-ASSO-022</a>
- **should** be able to select one row (vega key + amount) to populate disassociate form with the key you want to disassociate from and how much <a name="1004-ASSO-023" href="#1004-ASSO-023">1004-ASSO-023</a>
- If some of the tokens for the given Eth key are held by the vesting contract: **must** select to return tokens to Vesting contract <a name="1004-ASSO-024" href="#1004-ASSO-024">1004-ASSO-024</a>
- **must** select an amount of tokens to disassociate <a name="1004-ASSO-031" href="#1004-ASSO-031">1004-ASSO-031</a>
- **must** be able to populate the input with the amount of associated tokens for the selected Vega wallet/contract <a name="1004-ASSO-025" href="#1004-ASSO-025">1004-ASSO-025</a>
- **should** be warned that disassociating will forfeit and rewards for the current epoch and reduce the Vote weigh on any open proposals
- **must** be warned if the inputs on the form will result in an invalid withdraw, before submitting <a name="1004-ASSO-026" href="#1004-ASSO-026">1004-ASSO-026</a>
- **must** action the disassociation [Ethereum transaction](0005-ETXN-submit_ethereum_transaction.md) <a name="1004-ASSO-027" href="#1004-ASSO-027">1004-ASSO-027</a>
- **must** see feedback on the progress of the disassociation on ethereum <a name="1004-ASSO-028" href="#1004-ASSO-028">1004-ASSO-028</a>
- **must** see new associated balances in Vega (theses should be applied instantly, rather than wait for the 50 eth blocks like associate) <a name="1004-ASSO-029" href="#1004-ASSO-029">1004-ASSO-029</a>
- on completion (if tokens were returned to vesting contract): **could** be prompted to go on to [redeem](1001-VEST-vesting.md).
...so that I can transfer them to another Ethereum wallet (e.g. sell them on an exchange).

80
specs/1005-VEST-vesting.md Normal file
View File

@ -0,0 +1,80 @@
# Vesting
Some governance tokens may be held by a Vesting contract. This means that can be "owned" by an Ethereum key but not freely transferred until a vesting terms are complete.
## list of tranches
When looking to understand to overall vesting schedule for tokens, I...
- **must** see a list of tranches <a name="1005-VEST-001" href="#1005-VEST-001">1005-VEST-001</a>
- **should** see a visualization of the vesting schedule with a break down of the type of token holders (e.g. team, investors, community) <a name="1005-VEST-002" href="#1005-VEST-002">1005-VEST-002</a>
For each tranche:
- **must** see a tranche number <a name="1005-VEST-003" href="#1005-VEST-003">1005-VEST-003</a>
- **could** see any annotation of what this tranche is about (e.g. community schedule A)
- **must** see a sum of tokens in the tranche <a name="1005-VEST-005" href="#1005-VEST-005">1005-VEST-005</a>
- **must** see how many tokens in the tranche are locked <a name="1005-VEST-006" href="#1005-VEST-006">1005-VEST-006</a>
- **must** see how how many tokens in the tranche are redeemable <a name="1005-VEST-007" href="#1005-VEST-007">1005-VEST-007</a>
- **must** see the vesting terms for each tranche (when unlocking stats and ends) <a name="1005-VEST-008" href="#1005-VEST-008">1005-VEST-008</a>
... so I can understand how circulating supply could change over time.
## Details of a tranche
When looking into a specific tranche, I...
- **must** see all the same details as the [list of tranches](#details-of-a-tranche)
- **should** see a list of ethereum wallets with tokens in this tranche
for each ethereum wallet:
- **should** see the full eth address of the wallet
- **should** see the total tokens this address holds in this tranche
- **should** see how many tokens in the tranche are locked
- **should** see how how many tokens in the tranche are redeemable
... so I can see the details of how tokens are distributed in this tranche
## See summary for a given Ethereum key
When looking to see how many tokens I have in total, and how many I might be able to redeem, I...
- **must** be able to [Connect and ethereum wallet](0004-EWAL-connect_ethereum_wallet.md) <a name="1005-VEST-018" href="#1005-VEST-018">1005-VEST-018</a>
- **should** be able input an ethereum address
for the a given Ethereum wallet/address/key:
- **must** see a total of tokens across all tranches <a name="1005-VEST-020" href="#1005-VEST-020">1005-VEST-020</a>
- **must** see how many tokens across all tranches are locked <a name="1005-VEST-021" href="#1005-VEST-021">1005-VEST-021</a>
- **must** see how many tokens across all tranches are redeemable <a name="1005-VEST-022" href="#1005-VEST-022">1005-VEST-022</a>
- **must** see a list of tranches this key has tokens in <a name="1005-VEST-023" href="#1005-VEST-023">1005-VEST-023</a>
- **must** see a total of tokens in each tranche <a name="1005-VEST-024" href="#1005-VEST-024">1005-VEST-024</a>
- **must** see how many tokens in each tranche are locked <a name="1005-VEST-025" href="#1005-VEST-025">1005-VEST-025</a>
- **must** see how many tokens in each tranche are redeemable <a name="1005-VEST-026" href="#1005-VEST-026">1005-VEST-026</a>
- **must** see an option to redeem from tranche <a name="1005-VEST-027" href="#1005-VEST-027">1005-VEST-027</a>
- **must** be warned if amount that can be redeemed from that tranche is greater than the un-associated balance for that Eth key (because this will cause the redeem function to fail) <a name="1005-VEST-028" href="#1005-VEST-028">1005-VEST-028</a>
- **should** see how many tokens I'd need to disassociate to be able to run the redeem function (this should be rounded up to avoid the transaction failing due to more tokens having unlocked since the user looked at the form)
- **should** see link to [disassociate](1004-ASSO-associate.md)
... so I can easily see how many tokens I have, and can redeem.
## Redeem tokens from a tranche
Note: it is not possible to choose how many tokens you redeem from a tranche, instead you select a tranche and the smart contract will attempt to redeem all. However, it will fail if some of the amount it attempts to redeem have been associated to a Vega key. Therefore the job of this page is to help the user work out how many tokens to disassociate before they can successfully redeem.
When looking to redeem tokens, I...
- **must** [connect the ethereum wallet](0004-EWAL-connect_ethereum_wallet.md) that holds tokens <a name="1005-VEST-029" href="#1005-VEST-029">1005-VEST-029</a>
- must see see all tranches that you have tokens in (including tranche 0) <a name="1005-VEST-036" href="#1005-VEST-036">1005-VEST-036</a>
- must see a total of tokens across all tranches (including tranche 0) <a name="1005-VEST-037" href="#1005-VEST-037">1005-VEST-037</a>
- **must** select a tranche to redeem from <a name="1005-VEST-030" href="#1005-VEST-030">1005-VEST-030</a>
- **must** see the number of tokens that can be redeemed <a name="1005-VEST-031" href="#1005-VEST-031">1005-VEST-031</a>
- **must** be warned if the number of tokens you would be attempting to redeem is greater than you have unassociated <a name="1005-VEST-035" href="#1005-VEST-035">1005-VEST-035</a>
- **should** tell you how many tokens to disassociate for the redeem function to work (should round up to create a buffer for the tokens that may unlock between now and when the user gets to the disassociate form)
- **should** see a link to disassociate
- **must** submit the redeem from tranche [ethereum transaction](0005-ETXN-submit_ethereum_transaction.md) <a name="1005-VEST-032" href="#1005-VEST-032">1005-VEST-032</a>
- **must** get feedback on the progress of the Ethereum transaction <a name="1005-VEST-033" href="#1005-VEST-033">1005-VEST-033</a>
- **must** see updated balances (in the trance and my eth wallet) after redemption <a name="1005-VEST-034" href="#1005-VEST-034">1005-VEST-034</a>
... so that I can use this tokens more generally on Ethereum (transfer to another key etc)

121
specs/2001-STKE-staking.md Normal file
View File

@ -0,0 +1,121 @@
# Staking
Staking is the act of securing a Vega network by nominating good validators with the [governance token](../protocol/0071-STAK-erc20_governance_token_staking.md). Staking is rewarded with a share of trading fees (and [treasury rewards](../0056-REWA-rewards_overview.md)). See the [glossary](../glossaries/staking-and-governance.md) and [these specs](../protocol#delegation-staking-and-rewards) for more on staking.
When staking a user may be motivated to select validators to maximize the rewards they get for the tokens they hold, this means selecting validator(s) who are less likely to be penalized (e.g. over staked, poor performance). Users may wish to stake more than one validator to diversify. Users will want/need to manage their stake over time to ensure they are getting a good return, e.g. move stake between validators. Staking is also important for facilitating protocol upgrades.
## Understand staking on Vega
When considering whether to stake on Vega, I...
- **should** see information to help inform me what return I might expect from staking (other protocols might show a typical APY)
- **must** see that the governance token is an ethereum ERC20 token and needs to attributed (or associated) to a Vega wallet for use on Vega <a name="1002-STKE-002" href="#1002-STKE-002">1002-STKE-002</a>
- **must** see detailed documentation on how staking works on Vega <a name="1002-STKE-003" href="#1002-STKE-003">1002-STKE-003</a>
...so I can decide if I want to stake on Vega, and how to go about doing it.
Note: There are many ways that "understanding the return" can be done, and this does not impose a particular solution. Solutions could...
- look at previous epochs,
- average this over a period,
- select a range of validators or just one,
- could have a calculator that allows the user to enter some values or just show this on the list of validators
Note: Income may come in a range of different tokens, as markets can settle in different assets, and there may be rewards paid out by the treasury.
## Associate tokens
Before I stake, I need to [Associate tokens](./1000-ASSO-associate.md) with a Vega wallet/key...
- **must** see link[Associate tokens](./1000-ASSO-associate.md)
- **should** see that if no further action is taken, newly associated tokens will be nominated to validators based on existing distribution
...so that I can nominate validators.
## Select validator(s)
When selecting what validators to nominate with my stake, I...
- **should** be able to select any data that is available on Validators in a table
- **must** see all validator information without having to connect Vega wallet <a name="1002-STKE-050" href="#1002-STKE-050">1002-STKE-050</a>
- see "static" information about the validator (these can change, just not frequently)
- **must** see name <a name="1002-STKE-006" href="#1002-STKE-006">1002-STKE-006</a>
- **must** see Vega public key <a name="1002-STKE-008" href="#1002-STKE-008">1002-STKE-008</a>
- **should** see a URL where to find more information about the validator (if there is one)
- **must** see Ethereum address<a name="1002-STKE-010" href="#1002-STKE-010">1002-STKE-010</a>
- can see data for the current/next epoch, for each validator
- **must** see the current "status" (consensus, Ersatz, New etc) <a name="1002-STKE-011" href="#1002-STKE-011">1002-STKE-011</a>
- **must** see a total stake (inc self stake) <a name="1002-STKE-012" href="#1002-STKE-012">1002-STKE-012</a>
- **must** see self stake <a name="1002-STKE-013" href="#1002-STKE-013">1002-STKE-013</a>
- **must** see nominated stake <a name="1002-STKE-014" href="#1002-STKE-014">1002-STKE-014</a>
- **must** see total stake as a % of total staked across all nodes <a name="1002-STKE-051" href="#1002-STKE-051">1002-STKE-051</a>
- **must** see total stake change next epoch <a name="1002-STKE-015" href="#1002-STKE-015">1002-STKE-015</a>
- **must** see self stake <a name="1002-STKE-016" href="#1002-STKE-016">1002-STKE-016</a>
- **must** see nominated stake <a name="1002-STKE-017" href="#1002-STKE-017">1002-STKE-017</a>
- **must** see total stake as a % change <a name="1002-STKE-052" href="#1002-STKE-052">1002-STKE-052</a>
- **should** see the version of Vega they are currently running
- **should** see the version of Vega they propose running
- can see data for the previous epoch
- **must** see the overall "score" for a validator for the previous epoch <a name="1002-STKE-020" href="#1002-STKE-020">1002-STKE-020</a>
- can see all the inputs to that "score"
- **must** see Ranking score <a name="1002-STKE-021" href="#1002-STKE-021">1002-STKE-021</a>
- **must** see stake score <a name="1002-STKE-022" href="#1002-STKE-022">1002-STKE-022</a>
- **must** see performance score <a name="1002-STKE-023" href="#1002-STKE-023">1002-STKE-023</a>
- **must** see voting score <a name="1002-STKE-024" href="#1002-STKE-024">1002-STKE-024</a>
- can see data for previous epochs
- **should** see the the overall "score" for all previous epochs for each validator <a name="1002-STKE-025" href="#1002-STKE-025">1002-STKE-025</a>
- can see a breakdown of all the inputs to that "score" for all previous epochs
- **should** see Ranking score
- **should** see stake score
- **should** see performance score
- **should** see voting score
...so I can select validators that should give me the biggest return.
## Nominate a validator
Note: User interfaces may use the term "Nominate", technically the function is called "delegate". Delegating tokens to a validator may imply that you also give that validator your vote on proposals, at time of writing, it does not. It only gives them the potential for more "voting power" in the production of blocks.
Within a staking epoch (typically 24 hours) a user can change their nominations many times, however the changes are only effective at the end of the epoch. You will only get rewards for a full epoch staked.
When attributing some (or all of my governance tokens to a given validator), I...
- **must** select a validator I want to nominate <a name="1002-STKE-031" href="#1002-STKE-031">1002-STKE-031</a>
- **must** see link to [connect to a Vega wallet/key](0002-WCON-connect_vega_wallet.md) (if not already) that has associated Vega (or Pending association) <a name="1002-STKE-032" href="#1002-STKE-032">1002-STKE-032</a>
- **must** select an amount of tokens <a name="1002-STKE-033" href="#1002-STKE-033">1002-STKE-033</a>
- **must** be able to populate this with the amount of governance tokens that will be associated but not nominated at the beginning of the next epoch <a name="1002-STKE-034" href="#1002-STKE-034">1002-STKE-034</a>
- **must** be warned if the amount I am about to nominate is below a minimum amount (spam protection) <a name="1002-STKE-035" href="#1002-STKE-035">1002-STKE-035</a>
- **must** be warned if the amount I am about to nominate is more than I have associated + un-nominated at the end of current epoch/beginning of next <a name="1002-STKE-036" href="#1002-STKE-036">1002-STKE-036</a>
- **must** submit the nomination [Vega transactions](0003-WTXN-submit_vega_transaction.md) <a name="1002-STKE-037" href="#1002-STKE-037">1002-STKE-037</a>
- **must** see feedback that my nomination has been registered, and will be processed at the next epoch <a name="1002-STKE-038" href="#1002-STKE-038">1002-STKE-038</a>
- **must** see all my pending nomination changes for the next epoch <a name="1002-STKE-039" href="#1002-STKE-039">1002-STKE-039</a>
...so that I am rewarded for a share based on this validators performance.
## Monitor staking rewards
When checking if im getting the staking return that I was expecting, I...
- See [Staking income](2002-SINC-staking-income.md)
...so that I can make decisions about my staking, e.g. whether to re-distribute my stake.
## Un-nominate validator
When removing stake from a validator, I...
- **must** select a validator I want to un-nominate <a name="1002-STKE-040" href="#1002-STKE-040">1002-STKE-040</a>
- **must** [connect to a Vega wallet/key](0002-WCON-connect_vega_wallet.md) with nominated stake, if not already <a name="1002-STKE-041" href="#1002-STKE-041">1002-STKE-041</a>
- - **must** have the option of withdrawing nominated amount at the end of the epoch (and maintain the staking income for the current epoch) <a name="1002-STKE-053" href="#1002-STKE-053">1002-STKE-053</a>
- **should** have the option of withdrawing nomination amount now immediately (and forfeit the staking income)
- **must** set an amount to remove from a validator <a name="1002-STKE-044" href="#1002-STKE-044">1002-STKE-044</a>
- **must** be able populate with the total delegated amount at the time where un-nominate will happen <a name="1002-STKE-045" href="#1002-STKE-045">1002-STKE-045</a>
- **must** be warned if amount is greater than the amount that will be on that validator at the end of the epoch <a name="1002-STKE-046" href="#1002-STKE-046">1002-STKE-046</a>
<a name="1002-STKE-047" href="#1002-STKE-047">1002-STKE-047</a>
- **must** submit un-nominate [Vega transaction](0003-WTXN-submit_vega_transaction.md) <a name="1002-STKE-048" href="#1002-STKE-048">1002-STKE-048</a>
- **must** see feedback that the un-nomination has been registered, and that the un-nominated amount is now available for re-nomination <a name="1002-STKE-049" href="#1002-STKE-049">1002-STKE-049</a>
... so that I can use this stake for another validator etc.
note: if a user just wishes to seel their tokens and not wait for the end of an epoch they could simply [disassociate](1004-ASSO-associate.md#disassociate) (as long as tokens are not held by vesting contract)

31
specs/2002-SINC-staking-income.md Normal file
View File

@ -0,0 +1,31 @@
# Staking income
## Monitor staking rewards
When checking the staking rewards, I...
- must be [connected to a Vega wallet](0002-WCON-connect_vega_wallet.md)
- **must** see when the current epoch ends <a name="2002-SINC-001" href="#2002-SINC-001">2002-SINC-001</a>
- **should** see when the current epoch started
- **should** see how much the connected wallet might earn at the end of the epoch (with some assumptions)
- **should** see the balance of all infrastructure fee accounts for the current epoch
- **should** see real time validator score for the current epoch
- **should** see if any validators have had a penalty this epoch
- **must** see the sum of Tokens I have nominated to each validator in the current epoch <a name="2002-SINC-007" href="#2002-SINC-007">2002-SINC-007</a>
- **should** see what percentage of my Tokens I have nominated to each validator in the current epoch
- **must** see the staking income I have received for each epoch previous <a name="2002-SINC-009" href="#2002-SINC-009">2002-SINC-009</a>
- **must** see asset name <a name="2002-SINC-010" href="#2002-SINC-010">2002-SINC-010</a>
- **must** see balance of asset <a name="2002-SINC-011" href="#2002-SINC-011">2002-SINC-011</a>
- **must** see type (organic or treasury) <a name="2002-SINC-012" href="#2002-SINC-012">2002-SINC-012</a>
- **should** see the staking income by epoch, broken down by validator
- **should** see the staking income by epoch, broken down by market
- **should** see all income values expressed in a single currency
- **must** see current asset balances for connected wallets <a name="2002-SINC-016" href="#2002-SINC-016">2002-SINC-016</a>
- **must** see link to [withdraw](1002-WITH-withdraw.md) assets <a name="2002-SINC-017" href="#2002-SINC-017">2002-SINC-017</a>
- **must** see where I can see where I did not receive full income because the validator suffered penalties <a name="2002-SINC-018" href="#2002-SINC-018">2002-SINC-018</a>
...so that I can make decisions about my staking

174
specs/3001-VOTE-vote.md Normal file
View File

@ -0,0 +1,174 @@
# Vote
Background: [Governance spec](../protocol/0028-GOVE-governance.md)
and [docs](https://s.vega.xyz/s/mainnet/concepts/vega-protocol#governance).
There are a few things that can be governed on Vega...
- Network parameters (variables used by the network)
- Markets (creation and changes to existing)
- Assets (creation on changes to existing)
- "Freeform", which has no affect on the network but can be used to to measure token holders views
To make proposal: a user will require an amount of the Governance token [associated](1004-ASSO-associate.md) with their key.
To vote: a user will require [associated](1004-ASSO-associate.md) Governance tokens (or in the case of market change proposals they could have an active liquidity provision).
Each vote has a weight behind it based on the number of associate tokens or the liquidity provision's equity like share at the point in time that the vote closes.
Each proposal type will have a majority required (vote weight in favour) and a participation required (the turn out for the vote needs to be sufficient to be valid).
A proposal has a life cycle and various statuses to track it's progress. proposals that accept votes can have a few different statuses. A short hand is used in these ACs:
- Open = Accepting votes (includes `waitingForNodeVote`)
- To enact = passed but not yet enacted (`pending)
- Closed = was accepting votes but deadline has passed (e.g. `passed`, `rejected` etc)
- `Failed` = did not get to the point of accepting votes.
## list of proposals
When looking for a particular proposal or wanting to see what proposals are open, soon to enact or closed, I...
- **must** see link to details on how governance works in docs (<a name="3001-VOTE-001" href="#3001-VOTE-001">3001-VOTE-001</a>)
- **must** see link(s) to make proposals (<a name="3001-VOTE-002" href="#3001-VOTE-002">3001-VOTE-002</a>)
- **must** if there are no proposals, see that there have been no proposals since the last chain checkpoint restore (<a name="3001-VOTE-003" href="#3001-VOTE-003">3001-VOTE-003</a>)
- **must** see open proposals (and ones due for enactment) distinct from others (e.g grouped by "open", "to enact" "closed") (note: freeform proposals do not enact so should be shown as "closed" when "passed") (<a name="3001-VOTE-004" href="#3001-VOTE-004">3001-VOTE-004</a>)
- **should** see proposals sorted with the ones closest to enactment first (within each group)
- **must** see a history of all "closed" proposals (<a name="3001-VOTE-006" href="#3001-VOTE-006">3001-VOTE-006</a>)
- can search for a proposal by:
- **should** be able to search by proposal ID
- **should** be able to search by public key of the proposer
- **should** be abel to search by market ID/name/code (ID may be the same as proposal ID)
- **should** be able to search by asset name/symbol
- **should** be able to search by network parameter
- **should** be able to search by content of proposal description
- **must** see how long is left to vote (<a name="3001-VOTE-018" href="#3001-VOTE-018">3001-VOTE-018</a>)
- **must** see colourful / shouty things that prompt me to vote urgently on things "CLOSING SOON" (<a name="3001-VOTE-019" href="#3001-VOTE-019">3001-VOTE-019</a>)
- **must** see the current voting status and whether it will pass (<a name="3001-VOTE-020" href="#3001-VOTE-020">3001-VOTE-020</a>)
- **must** see the current participation and whether it will pass (<a name="3001-VOTE-021" href="#3001-VOTE-021">3001-VOTE-021</a>)
for each proposal:
- **must** see the proposal ID (<a name="3001-VOTE-008" href="#3001-VOTE-008">3001-VOTE-008</a>)
- **must** see who the proposer is (e.g. their public address) (<a name="3001-VOTE-009" href="#3001-VOTE-009">3001-VOTE-009</a>)
- **must** see the type of proposal (<a name="3001-VOTE-007" href="#3001-VOTE-007">3001-VOTE-007</a>)
- **must** see the proposal title (<a name="3001-VOTE-097" href="#3001-VOTE-097">3001-VOTE-097</a>)
- **should** see a summary of what the type of proposed change is, without looking at details (network, new market etc)
- for network parameters: **should** see what parameter is being changed and new value
- for network parameters: **could** see what the current values are for that parameter
- for network parameters: **could** see if there are other open proposals for the same parameter
- for new markets: **should** see the type of market (e.g. Future)
- for new markets: **could** see the type trading mode of the market (e.g. auction, continuous)
- for new markets: **should** see the name of the new market
- for new markets: **should** see the code of the new market
- for new markets: **should** see the settlement asset of the new market (not just asset ID but asset Symbol)
- for new markets: **could** see a summary of the oracle used for settlement
- for market changes: **should** see the name of the market being changed
- for market changes: **should** see a summary of what parameters are being changed
- for market changes: **should** see a the proposed values for parameters
- for market changes: **should** see a the current values for that parameter
- for market changes: **could** see if there are other open proposals for the same market
- for new assets: **must** see the name of the new asset (<a name="3001-VOTE-026" href="#3001-VOTE-026">3001-VOTE-026</a>)
- for new assets: **must** see the code of the new asset (<a name="3001-VOTE-027" href="#3001-VOTE-027">3001-VOTE-027</a>)
- for new assets: **must** see the source of the new asset (e.g. ERC20) (<a name="3001-VOTE-028" href="#3001-VOTE-028">3001-VOTE-028</a>)
- for new assets (if source is ERC20): **must** see contract address (<a name="3001-VOTE-095" href="#3001-VOTE-095">3001-VOTE-095</a>)
- for new assets (if source is ERC20): **must** see if the Asset has been whitelisted on the bridge (<a name="3001-VOTE-096" href="#3001-VOTE-096">3001-VOTE-096</a>)
- for asset changes: **must** see name of asset being changed (<a name="3001-VOTE-029" href="#3001-VOTE-029">3001-VOTE-029</a>)
- for asset changes: **must** see the parameter(s) being changed (<a name="3001-VOTE-030" href="#3001-VOTE-030">3001-VOTE-030</a>)
- for asset changes; **must** see the new value for the parameters being changed (<a name="3001-VOTE-031" href="#3001-VOTE-031">3001-VOTE-031</a>)
- for asset changes: **could** see if there are other open proposals for the same parameter(s)
- for asset changes: **should** see the current values for these parameters
- for freeform: **must** see a summary of the proposal (suggest the first x characters of the proposal blob)
- **must** see the proposal status e.g. passed, open, waiting for node to vote) (<a name="3001-VOTE-035" href="#3001-VOTE-035">3001-VOTE-035</a>)
- for new asset proposals: **must** see if an asset has not yet been whitelisted on the bridge (<a name="3001-VOTE-036"
href="#3001-VOTE-036">3001-VOTE-036</a>)
- **must** see the proposal's terms in JSON
(<a name="3001-VOTE-010" href="#3001-VOTE-010">3001-VOTE-010</a>)
- for open proposals: **must** see a summary of how the vote count stands and if it looks like proposal will pass or not (note some of these are repeated in more details in the [details section](#details-of-a-proposal)) (<a name="3001-VOTE-037" href="#3001-VOTE-037">3001-VOTE-037</a>)
- if the proposal failed (had the status of "failed", because it was an invalid on submission) they **should not** appear in the list (instead the proposer will see this after submission)
- if the proposal looks like it will fail due to insufficient participation: **should** see "participation not reached"
- else if: proposal looks like it might fail due to insufficient majority (and is not a market change proposal): **should** see "Majority not reached"
- else if (is a market change proposal) and is likely to pass because of liquidity providers vote: **should** see "set to pass by Liquidity provider vote"
- else if: proposal is likely to pass: **should** see "set to pass"
- **must** see when (date/time) voting closes on proposal (<a name="3001-VOTE-043" href="#3001-VOTE-043">3001-VOTE-043</a>)
- for (non-freefrom) proposals that have passed but not enacted: **must** see when they will enact (<a name="3001-VOTE-044" href="#3001-VOTE-044">3001-VOTE-044</a>)
- for (non-freefrom) proposals that have passed but not enacted: **should** see when (date/time) voting closed
- for (non-freeform) proposals that enacted: **must** see when they enacted (<a name="3001-VOTE-046" href="#3001-VOTE-046">3001-VOTE-046</a>)
- for freeform proposals that have passed: **must** see when they passed (<a name="3001-VOTE-047" href="#3001-VOTE-047">3001-VOTE-047</a>)
- for proposals that did not pass due to lack of participation: **must** see "Participation not reached" (<a name="3001-VOTE-048" href="#3001-VOTE-048">3001-VOTE-048</a>)
- for proposals that did not pass due to lack of majority: **must** see "Majority not reached" (<a name="3001-VOTE-049" href="#3001-VOTE-049">3001-VOTE-049</a>)
- for proposals that did not pass due to failure: **must** see "Failed" (<a name="3001-VOTE-050" href="#3001-VOTE-050">3001-VOTE-050</a>)
- for proposals that I ([connected Vega](./0002-WCON-connect_vega_wallet.md) key) have voted on: **should** see my vote (for or against)
...so I can see select one to view and vote, or view outcome.
## Details of a proposal
When looking at a particular proposal, I...
- see [the same details in the list of proposals](#list-of-proposals) and:
- **must** have option to see raw JSON of proposal (<a name="3001-VOTE-052" href="#3001-VOTE-052">3001-VOTE-052</a>)
- **should** display the proposed change details displayed in a human readable format (e.g. with market id, shown along with that market name)
- **must** see the rationale title (<a name="3001-VOTE-054" href="#3001-VOTE-054">3001-VOTE-054</a>)
- **must** see the full rationale description if there is one (<a name="3001-VOTE-055" href="#3001-VOTE-055">3001-VOTE-055</a>)
- **must** see rationale description rendered with markdown (<a name="3001-VOTE-101" href="#3001-VOTE-101">3001-VOTE-101</a>)
For open proposals:
- **must** show a summary of vote status (base on the current total amount associated tokens, note this could change before the vote ends) (<a name="3001-VOTE-057" href="#3001-VOTE-057">3001-VOTE-057</a>)
- **must** see if the token vote has met a required participation threshold (<a name="3001-VOTE-058" href="#3001-VOTE-058">3001-VOTE-058</a>)
- **must** see the sum of tokens that have voted so far (<a name="3001-VOTE-059" href="#3001-VOTE-059">3001-VOTE-059</a>)
- **must** see sum of tokens that have voted as a percentage of total voted (<a name="3001-VOTE-011" href="#3001-VOTE-011">3001-VOTE-011</a>)
- **should** see what the participation threshold is for this proposal (note this is set per proposal once the proposal hits the chain based on the current network params, incase a proposal is set to enact that changes threshold)
- **must** see if the Token vote has met the required majority threshold (<a name="3001-VOTE-062" href="#3001-VOTE-062">3001-VOTE-062</a>)
- **must** see the sum of tokens that have voted in favour of the proposal (<a name="3001-VOTE-064" href="#3001-VOTE-064">3001-VOTE-064</a>)
- **should** see sum of tokens that have votes in favour of proposal as percentage of total associated
- **should** see what the majority threshold is for this proposal (note this is see per proposal, incase a proposal is set to enact that changes threshold)
For open market change proposals, all of the above and:
- **must** show a summary of vote status (base on the current equality like share, note this could change before the vote ends) (<a name="3001-VOTE-067" href="#3001-VOTE-067">3001-VOTE-067</a>)
- **must** see if the equity like share vote has met the required participation threshold (<a name="3001-VOTE-068" href="#3001-VOTE-068">3001-VOTE-068</a>)
- **must** see the equity like share % that has voted so far (<a name="3001-VOTE-069" href="#3001-VOTE-069">3001-VOTE-069</a>)
- **should** see what the equity like share threshold is for this proposal (note this is see per proposal, incase a proposal is set to enact that changes threshold)
- **must** see if the equity like share vote has met the required majority threshold (<a name="3001-VOTE-071" href="#3001-VOTE-071">3001-VOTE-071</a>)
- **must** see the equity like share as percentage that has voted in favour of the proposal (<a name="3001-VOTE-072" href="#3001-VOTE-072">3001-VOTE-072</a>)
- **must** see what the majority threshold is for this proposal (note this is see per proposal, incase a proposal is set to enact that changes threshold) (<a name="3001-VOTE-073" href="#3001-VOTE-073">3001-VOTE-073</a>)
For update market proposals:
- As a liquidity provider, **must** be able to participate in a liquidity vote on an update market proposal, when the token vote has not reached required participation level in time (<a name="3001-VOTE-015" href="#3001-VOTE-015">3001-VOTE-015</a>)
- **must** be able to to understand why a liquidity vote has been incurred (<a name="3001-VOTE-016" href="#3001-VOTE-016">3001-VOTE-016</a>)
- **must** be able to to understand that the result in the end may differ (as the outcome of the vote is based on the number of tokens held by the voters at time of vote close) (<a name="3001-VOTE-017" href="#3001-VOTE-017">3001-VOTE-017</a>)
For `closed` market change proposals, all of the above and:
- **must** see all of above but values at time of vote close (<a name="3001-VOTE-074" href="#3001-VOTE-074">3001-VOTE-074</a>)
... so I can see what I am voting for and the status of the vote.
## Can vote on an open proposals
When looking to vote on the proposal, I...
- **must** see an option to [connect to a Vega wallet/key](./0002-WCON-connect_vega_wallet.md) (<a name="3001-VOTE-075" href="#3001-VOTE-075">3001-VOTE-075</a>)
- **must** be [connected to a Vega wallet/key](./0002-WCON-connect_vega_wallet.md) (<a name="3001-VOTE-076" href="#3001-VOTE-076">3001-VOTE-076</a>)
- **must** see sum of tokens I have [associated](1027-ASSO-associate.md) (<a name="3001-VOTE-100" href="#3001-VOTE-100">3001-VOTE-100</a>)
- **should** see what percentage of the total [associated](1027-ASSO-associate.md) tokens I hold
- **must**, if I have 0 tokens, see link to [associate](1027-ASSO-associate.md) (<a name="3001-VOTE-012" href="#3001-VOTE-012">3001-VOTE-012</a>)
- **must** see my current vote for, against, or not voted (<a name="3001-VOTE-079" href="#3001-VOTE-079">3001-VOTE-079</a>)
- **must** see option to vote for or against (<a name="3001-VOTE-080" href="#3001-VOTE-080">3001-VOTE-080</a>)
- **must** trigger a transaction that needs to be confirmed in users wallet (<a name="3001-VOTE-013" href="#3001-VOTE-013">3001-VOTE-013</a>)
- **must** see that I need to confirm the transaction in my wallet to continue (<a name="3001-VOTE-014" href="#3001-VOTE-014">3001-VOTE-014</a>)
- **must** see option to change my vote (vote again in same or different direction) (<a name="3001-VOTE-090" href="#3001-VOTE-090">3001-VOTE-090</a>)
For open market change proposals, all of the above and:
- **must** see your equity like share on the market you are voting on (<a name="3001-VOTE-092" href="#3001-VOTE-092">3001-VOTE-092</a>)
for both:
- **must** see feedback of my vote [Vega transaction](0003-WTXN-submit_vega_transaction.md) (<a name="3001-VOTE-093" href="#3001-VOTE-093">3001-VOTE-093</a>)
...so that I can cast my vote and see the impact it might have.

63
specs/3002-PROP-propose.md Normal file
View File

@ -0,0 +1,63 @@
# Propose
Background: [Governance spec](../protocol/0028-GOVE-governance.md)
and [docs](https://docs.vega.xyz/docs/mainnet/concepts/vega-protocol#governance).
## Associate tokens
When looking to propose something, I...
- **must** see see a link to detailed explanation of Governance in the docs (<a name="3002-PROP-001" href="#3002-PROP-001">3002-PROP-001</a>)
- **must** see that the governance token is an ethereum ERC20 token and needs to attributed (or [associated](1004-ASSO-associate.md)) to a Vega wallet for use on Vega (<a name="3002-PROP-002" href="#3002-PROP-002">3002-PROP-002</a>)
- **must** see that I need some associated tokens, and a link to [associate](1004-ASSO-associate.md) (<a name="3002-PROP-003" href="#3002-PROP-003">3002-PROP-003</a>)
... so I have a sufficient vote weight to propose.
## Select proposal type
When making a proposal, I...
- **must** select a proposal type (<a name="3002-PROP-005" href="#3002-PROP-005">3002-PROP-005</a>)
...so I get the appropriate form and information about rules for that type of proposal. e.g. min enactment and vote duration.
## Populate a proposal form
When making a proposal, I...
- **must** be able to see what they are to be used for on this site i.e. "Create proposal and download JSON to share" (<a name="3002-PROP-023" href="#3002-PROP-023">3002-PROP-023</a>)
- **must** input a rationale title and description (<a name="3002-PROP-006" href="#3002-PROP-006">3002-PROP-006</a>)
- **must** see the rules (min vote duration and enactment delay) for this proposal type (<a name="3002-PROP-008" href="#3002-PROP-008">3002-PROP-008</a>)
- **should** see the minimum required tokens or LP vote required to make a proposal Spam protection and network parameters
- if anything except market change: **must** be warned if the amount I have associated is less the the minimum required to propose for this proposal type (due to Spam protection or network parm, whichever is greater) (<a name="3002-PROP-009" href="#3002-PROP-009">3002-PROP-009</a>)
- if market change: **must** be warned if the amount of tokens I have less than the minimum tokens required to propose a change (due to Spam protection or network params) (<a name="3002-PROP-020" href="#3002-PROP-020">3002-PROP-020</a>)
- **must** see whether I have already voted or not on the card / list view (s) (<a name="3002-PROP-021" href="#3002-PROP-021">3002-PROP-021</a>)
- **should** see the balance of associated Governance tokens
### Detail on specific proposals
Go to the following for detail on each proposal type:
- [Propose new Market](./1006-PMARK-propose_new_market.md)
- [Propose change(s) to market](./1007-PMAC-propose_market_change.md)
- [Propose new asset](1008-PASN-propose_new_asset.md)
- [Propose change(s) to asset](1009-PASC-propose_asset_change.md)
- [Propose change to network parameter(s)](1010-PNEC-propose_network.md)
- [Propose something "Freeform"](1011-PFRO-propose_freeform.md)
### Submit proposal
- **must** submit the proposal [Vega transaction](0003-WTXN-submit_vega_transaction.md) (<a name="3002-PROP-011" href="#3002-PROP-011">3002-PROP-011</a>)
- **must** see the feedback on the [Vega transaction](0003-WTXN-submit_vega_transaction.md) (<a name="3002-PROP-012" href="#3002-PROP-012">3002-PROP-012</a>)
- If there is an error on the proposal:
- **must** be shown an error message will all of the error details from the API (<a name="3002-PROP-013" href="#3002-PROP-013">3002-PROP-013</a>)
- **must** see the proposal form populated with all the same values just submitted (<a name="3002-PROP-014" href="#3002-PROP-014">3002-PROP-014</a>)
- **should** see error messages highlighted on the inputs that require user attention
- If the proposal was successful:
- **must** be shown it was successful (<a name="3002-PROP-016" href="#3002-PROP-016">3002-PROP-016</a>)
- **should** be prompted to vote on the proposal
- **should** be prompted to share the proposal detail page to encourage others to vote
- **must** see a link to the proposal detail page (<a name="3002-PROP-019" href="#3002-PROP-019">3002-PROP-019</a>)
...so that the proposal is listed on the chain and I and others can vote for or against it.

35
specs/3003-PMAN-propose_new_market.md Normal file
View File

@ -0,0 +1,35 @@
# Propose new Market
**must** be a way to create a new proposal
(<a name="3003-PMAN-001" href="#3003-PMAN-001">3003-PMAN-001</a>)
- **must** be directed to the docs in order to create my proposal where I can see the instructions and steps I need to go through
(<a name="3003-PMAN-002" href="#3003-PMAN-002">3003-PMAN-002 </a>)
- **should** be directed to submit my proposal on the governance site where I can paste in my raw JSON
(<a name="3003-PMAN-003" href="#3003-PMAN-003">3003-PMAN-003</a>)
- **must** be able to see how many VEGA I must have associated with a validator in order to submit a proposal
(<a name="3003-PMAN-004" href="#3003-PMAN-004">3003-PMAN-004 </a>)
- **must** be a way to find more information on submitting a proposal (a link to docs) and explorer (a link to explorer / governance)
(<a name="3003-PMAN-005" href="#3003-PMAN-005">3003-PMAN-005 </a>)
- **must** error when submitting a proposal without entering anything, telling me JSON is required
(<a name="3003-PMAN-006" href="#3003-PMAN-006">3003-PMAN-006</a>)
- **must** error when submitting a proposal in anything other than JSON, telling me the proposal must be valid JSON
(<a name="3003-PMAN-007" href="#3003-PMAN-007">3003-PMAN-007</a>)
# Successor Market
- **must** On the home page and proposal listing page summary, I can see which market proposals are successor markets (<a name="3003-PMAN-008" href="#3003-PMAN-008">3003-PMAN-008</a>)
- **must** On a proposal details view that is a successor market, I can see the Parent market ID and Insurance pool fraction in the market specification (<a name="3003-PMAN-009" href="#3003-PMAN-009">3003-PMAN-009</a>)
- **must** On a proposal details view that is a successor market, I can see the Parent market ID and Insurance pool fraction in the proposal JSON (<a name="3003-PMAN-010" href="#3003-PMAN-010">3003-PMAN-009</a>)
- **must** I can see an explanation of what "Parent market ID" using a tooltip (<a name="3003-PMAN-011" href="#3003-PMAN-011">3003-PMAN-011</a>)
If the proposal has been enacted, I can see the status of the market i.e. opening auction, continuous trading, rejected
back to [Propose](./3002-PROP-propose.md) for details on proposing

24
specs/3004-PMAC-propose_market_change.md Normal file
View File

@ -0,0 +1,24 @@
## Propose market change
- **must** be a way to create a new proposal
(<a name="3004-PMAC-001" href="#3004-PMAC-001">3004-PMAC-001</a>)
- **must** be directed to the docs in order to create my proposal where I can see the instructions and steps I need to go through
(<a name="3004-PMAC-002" href="#3004-PMAC-002">3004-PMAC-002 </a>)
- **should** be directed to submit my proposal on the governance site where I can paste in my raw JSON
(<a name="3004-PMAC-003" href="#3004-PMAC-003">3004-PMAC-003</a>)
- **must** be able to see how many VEGA I must have associated with a validator in order to submit a proposal
(<a name="3004-PMAC-004" href="#3004-PMAC-004">3004-PMAC-004 </a>)
- **must** be a way to find more information on submitting a proposal (a link to docs) and explorer (a link to explorer / governance)
(<a name="3004-PMAC-005" href="#3004-PMAC-005">3004-PMAC-005 </a>)
- **must** error when submitting a proposal without entering anything, telling me JSON is required
(<a name="3004-PMAC-006" href="#3004-PMAC-006">3004-PMAC-006</a>)
- **must** error when submitting a proposal in anything other than JSON, telling me the proposal must be valid JSON
(<a name="3004-PMAC-007" href="#3004-PMAC-007">3004-PMAC-007</a>)
back to [Propose](./3002-PROP-propose.md) for details on proposing

24
specs/3005-PASN-propose_new_asset.md Normal file
View File

@ -0,0 +1,24 @@
# Propose new Asset
- **must** be a way to create a new proposal
(<a name="3005-PASN-001" href="#3005-PASN-001">3005-PASN-001</a>)
- **must** be directed to the docs in order to create my proposal where I can see the instructions and steps I need to go through
(<a name="3005-PASN-002" href="#3005-PASN-002">3005-PASN-002 </a>)
- **should** be directed to submit my proposal on the governance site where I can paste in my raw JSON
(<a name="3005-PASN-003" href="#3005-PASN-003">3005-PASN-003</a>)
- **must** be able to see how many VEGA I must have associated with a validator in order to submit a proposal
(<a name="3005-PASN-004" href="#3005-PASN-004">3005-PASN-004 </a>)
- **must** be a way to find more information on submitting a proposal (a link to docs) and explorer (a link to explorer / governance)
(<a name="3005-PASN-005" href="#3005-PASN-005">3005-PASN-005 </a>)
- **must** error when submitting a proposal without entering anything, telling me JSON is required
(<a name="3005-PASN-006" href="#3005-PASN-006">3005-PASN-006</a>)
- **must** error when submitting a proposal in anything other than JSON, telling me the proposal must be valid JSON
(<a name="3005-PASN-007" href="#3005-PASN-007">3005-PASN-007</a>)
back to [Propose](./3002-PROP-propose.md) for details on proposing

26
specs/3006-PASC-propose_asset_change.md Normal file
View File

@ -0,0 +1,26 @@
## Propose asset change
- **must** be a way to create a new proposal
(<a name="3006-PASC-001" href="#3006-PASC-001">3006-PASC-001</a>)
- **must** be directed to the docs in order to create my proposal where I can see the instructions and steps I need to go through
(<a name="3006-PASC-002" href="#3006-PASC-002">3006-PASC-002 </a>)
- **should** be directed to submit my proposal on the governance site where I can paste in my raw JSON
(<a name="3006-PASC-003" href="#3006-PASC-003">3006-PASC-003</a>)
- **must** be able to see how many VEGA I must have associated with a validator in order to submit a proposal
(<a name="3006-PASC-004" href="#3006-PASC-004">3006-PASC-004 </a>)
- **must** be a way to find more information on submitting a proposal (a link to docs) and explorer (a link to explorer / governance)
(<a name="3006-PASC-005" href="#3006-PASC-005">3006-PASC-005 </a>)
- **must** error when submitting a proposal without entering anything, telling me JSON is required
(<a name="3006-PASC-006" href="#3006-PASC-006">3006-PASC-006</a>)
- **must** error when submitting a proposal in anything other than JSON, telling me the proposal must be valid JSON
(<a name="3006-PASC-007" href="#3006-PASC-007">3006-PASC-007</a>)
## Submit proposal
back to [Propose](./3002-PROP-propose.md) for details on proposing

72
specs/3007-PNEC-propose_network.md Normal file
View File

@ -0,0 +1,72 @@
# Propose change to network parameter(s)
- **must** be a way to create a new proposal
(<a name="3007-PNEC-001" href="#3007-PNEC-001">3007-PNEC-001</a>)
- **must** be directed to the docs in order to create my proposal where I can see the instructions and steps I need to go through
(<a name="3007-PNEC-002" href="#3007-PNEC-002">3007-PNEC-002 </a>)
- **should** be directed from the docs to use the Governance dApp to help put together a Network Parameter proposal
(<a name="3007-PNEC-003" href="#3007-PNEC-003">3007-PNEC-003</a>)
- **must** be able to give my proposal a title
(<a name="3007-PNEC-004" href="#3007-PNEC-004">3007-PNEC-004</a>)
- **must** be able to see what the title would be used for
(<a name="3007-PNEC-005" href="#3007-PNEC-005">3007-PNEC-005</a>)
- **must** be constrained to a character limit and can understand what that limit is
(<a name="3007-PNEC-006" href="#3007-PNEC-006">3007-PNEC-006</a>)
- **must** be a way to add a proposal description
(<a name="3007-PNEC-007" href="#3007-PNEC-007">3007-PNEC-007</a>)
- **must** see what the description would be used for
(<a name="3007-PNEC-008" href="#3007-PNEC-008">3007-PNEC-008</a>)
- **must** be constrained to a character limit and can understand what that limit is
(<a name="3007-PNEC-009" href="#3007-PNEC-009">3007-PNEC-009</a>)
- **must** be able to select the parameter I want to change
(<a name="3007-PNEC-010" href="#3007-PNEC-010">3007-PNEC-010</a>)
- **must** see the current value and enter a proposed value (the change I want)
(<a name="3007-PNEC-011" href="#3007-PNEC-011">3007-PNEC-011</a>)
- **must** be a way to set when voting will close and a way to set when the proposal should be enacted
(<a name="3007-PNEC-012" href="#3007-PNEC-012">3007-PNEC-012</a>)
- **must** a way to set voting close to the maximum or minimum amount of time
(<a name="3007-PNEC-013" href="#3007-PNEC-013">3007-PNEC-013</a>)
- **must** a way to understand when that will be (date, time)
(<a name="3007-PNEC-014" href="#3007-PNEC-014">3007-PNEC-014</a>)
- **must** a way to set proposal enactment to the maximum or minimum amount of time
(<a name="3007-PNEC-015" href="#3007-PNEC-015">3007-PNEC-015</a>)
- **must** a way to understand when that will be (date, time)
(<a name="3007-PNEC-016" href="#3007-PNEC-016">3007-PNEC-016</a>)
- **must** a way to understand how the deadline and enactment times must relate i.e. must be equal to or after vote close
(<a name="3007-PNEC-017" href="#3007-PNEC-017">3007-PNEC-017</a>)
- **must** be able to download the proposal as JSON ready to share with the community on the forum
(<a name="3007-PNE-018" href="#3007-PNE-018">3007-PNE-018</a>)
- When I have received feedback from the community, I **should** be directed to submit my proposal on the governance site where I can paste in my raw JSON
(<a name="3007-PNE-019" href="#3007-PNE-019">3007-PNE-019</a>)
- **must** be able to see how many VEGA I must have associated with a validator in order to submit a proposal
(<a name="3007-PNE-020" href="#3007-PNE-020">3007-PNE-020</a>)
- **must** be a way to find more information on submitting a proposal (a link to docs) and explorer (a link to explorer / governance)
(<a name="3007-PNE-021" href="#3007-PNE-021">3007-PNE-021</a>)
- **must** error when submitting a proposal without entering anything, telling me JSON is required
(<a name="3007-PNE-022" href="#3007-PNE-022">3007-PNE-022</a>)
- **must** error when submitting a proposal in anything other than JSON, telling me the proposal must be valid JSON
(<a name="3007-PNE-023" href="#3007-PNE-023">3007-PNE-023</a>)
back to [Propose](./3002-PROP-propose.md) for details on proposing

59
specs/3008-PFRO-propose_freeform.md Normal file
View File

@ -0,0 +1,59 @@
# Propose freeform
- **must** not see anything enactment field(because freeform do not enact) (<a name="3008-PFRO-001" href="#3008-PFRO-001">3008-PFRO-001</a>)
- **must** be a way to create a new proposal
(<a name="3008-PFRO-002" href="#3008-PFRO-002">3008-PFRO-002</a>)
- **must** be directed to the docs in order to create my proposal where I can see the instructions and steps I need to go through
(<a name="3008-PFRO-003" href="#3008-PFRO-003">3008-PFRO-003</a>)
- **should** be directed from the docs to use the Governance dApp to help put together a freeform proposal
(<a name="3008-PFRO-004" href="#3008-PFRO-004">3008-PFRO-004</a>)
- **must** be able to give my proposal a title
(<a name="3008-PFRO-005" href="#3008-PFRO-005">3008-PFRO-005</a>)
- **must** be able to see what the title would be used for
(<a name="3008-PFRO-006" href="#3008-PFRO-006">3008-PFRO-006</a>)
- **must** be constrained to a character limit and can understand what that limit is
(<a name="3008-PFRO-007" href="#3008-PFRO-007">3008-PFRO-007</a>)
- **must** be a way to add a proposal description
(<a name="3008-PFRO-008" href="#3008-PFRO-008">3008-PFRO-008</a>)
- **must** see what the description would be used for
(<a name="3008-PFRO-009" href="#3008-PFRO-009">3008-PFRO-009</a>)
- **must** be constrained to a character limit and can understand what that limit is
(<a name="3008-PFRO-010" href="#3008-PFRO-010">3008-PFRO-010</a>)
- **must** be a way to set when voting will close
(<a name="3008-PFRO-011" href="#3008-PFRO-011">3008-PFRO-011</a>)
- **must** a way to set voting close to the maximum or minimum amount of time
(<a name="3008-PFRO-012" href="#3008-PFRO-012">3008-PFRO-012</a>)
- **must** a way to understand when that will be (date, time)
(<a name="3008-PFRO-013" href="#3008-PFRO-013">3008-PFRO-013</a>)
- **must** be able to download the proposal as JSON ready to share with the community on the forum
(<a name="3008-PFRO-014" href="#3008-PFRO-014">3008-PFRO-014</a>)
- When I have received feedback from the community, I **should** be directed to submit my proposal on the governance site where I can paste in my raw JSON
(<a name="3008-PFRO-015" href="#3008-PFRO-015">3008-PFRO-015</a>)
- **must** be able to see how many VEGA I must have associated with a validator in order to submit a proposal
(<a name="3008-PFRO-016" href="#3008-PFRO-016">3008-PFRO-016</a>)
- **must** be a way to find more information on submitting a proposal (a link to docs) and explorer (a link to explorer / governance)
(<a name="3008-PFRO-017" href="#3008-PFRO-017">3008-PFRO-017</a>)
- **must** error when submitting a proposal without entering anything, telling me JSON is required
(<a name="3008-PFRO-018" href="#3008-PFRO-018">3008-PFRO-018</a>)
- **must** error when submitting a proposal in anything other than JSON, telling me the proposal must be valid JSON
(<a name="3008-PFRO-019" href="#3008-PFRO-019">3008-PFRO-019</a>)
back to [Propose](./3002-PROP-propose.md) for details on proposing

21
specs/3009-NTWU-network-upgrade.md Normal file
View File

@ -0,0 +1,21 @@
# Network upgrade proposal
- **must** be able to see the network upgrade announcement from anywhere on the governance dapp (<a name="3009-NTWU-001" href="#3009-NTWU-001">3009-NTWU-001</a>)
- **must** be able to see 'what' version of the protocol the network is planned to be upgraded to (<a name="3009-NTWU-002" href="#3009-NTWU-002">3009-NTWU-002</a>)
- **must** be able to see what block height the upgrade will run at (<a name="3009-NTWU-003" href="#3009-NTWU-003">3009-NTWU-003</a>)
- **must** be able to see the current block height (<a name="3009-NTWU-004" href="#3009-NTWU-004">3009-NTWU-004</a>)
- **must** understand the impact(s) of the upgrade i.e. how long the network might be offline etc. (<a name="3009-NTWU-005" href="#3009-NTWU-005">3009-NTWU-005</a>)
- **must** be able to see an up to date estimate of / countdown to 'when' the planned upgrade is estimated to take place (<a name="3009-NTWU-006" href="#3009-NTWU-006">3009-NTWU-006</a>)
- **must** be able to see all the details of the upgrade proposal (dependent on this ticket is done Basic network upgrade proposal details page) (<a name="3009-NTWU-007" href="#3009-NTWU-007">3009-NTWU-007</a>)
- **must** be able to see in detail view of a network upgrade proposal, the estimated time to upgrade i.e. Estimated time to upgrade: 1h56m (13:00 UTC) (<a name="3009-NTWU-008" href="#3009-NTWU-008">3009-NTWU-008</a>)
- **must** be able to see when a network upgrade proposal block number has been passed.
i.e. the time to upgrade is replaced with Estimated upgrade complete: 24 May 2023 13:00UTC
(<a name="3009-NTWU-009" href="#3009-NTWU-009">3009-NTWU-009</a>)

1
specs/4001-TRES-view_treasury_rewards.md Normal file
View File

@ -0,0 +1 @@
# View treasury rewards

1
specs/5001-LIQF-liquidity_opportunities.md Normal file
View File

@ -0,0 +1 @@
# Find liquidity provision opportunities

37
specs/5002-LIQP-liquidity.md Normal file
View File

@ -0,0 +1,37 @@
# Liquidity
## Trading and liquidity view
- **Must** be able to view liquidity table (<a name="5002-LIQP-001" href="#5002-LIQP-001">5002-LIQP-001</a>)
- **Must** be able to see the following columns (<a name="5002-LIQP-002" href="#5002-LIQP-002">5002-LIQP-002</a>):
- party
- commitment
- share
- proposed fee
- market valuation at entry
- obligation
- supplied
- status
- created
- updated
- **Must** be able to sort each column by asc and dsc (<a name="5002-LIQP-003" href="#5002-LIQP-003">5002-LIQP-003</a>)
## Liquidity view
- **Must** be able to see the following sections
- name (<a name="5002-LIQP-004" href="#5002-LIQP-004">5002-LIQP-004</a>)
- trading page link (<a name="5002-LIQP-005" href="#5002-LIQP-005">5002-LIQP-005</a>)
- target stake (<a name="5002-LIQP-006" href="#5002-LIQP-006">5002-LIQP-006</a>)
- supplied stake (<a name="5002-LIQP-007" href="#5002-LIQP-007">5002-LIQP-007</a>)
- liquidity supplied (<a name="5002-LIQP-008" href="#5002-LIQP-008">5002-LIQP-008</a>)
- market id (<a name="5002-LIQP-009" href="#5002-LIQP-009">5002-LIQP-009</a>)
- learn more (<a name="5002-LIQP-010" href="#5002-LIQP-010">5002-LIQP-010</a>)
- **Must** be able to see the following tabs
- active (<a name="5002-LIQP-011" href="#5002-LIQP-011">5002-LIQP-011</a>)
- inactive (<a name="5002-LIQP-012" href="#5002-LIQP-012">5002-LIQP-012</a>)
- **Must** be able to see the number values formatted using quantum and asset decimals, on hover full value should be displayed (<a name="5002-LIQP-013" href="#5002-LIQP-013">5002-LIQP-013</a>)

1
specs/5003-LIQI-liquidity_income.md Normal file
View File

@ -0,0 +1 @@
# Review liquidity income

88
specs/6001-MARK-find_markets.md Normal file
View File

@ -0,0 +1,88 @@
# Find markets
## Closed Markets
- **Must** see market's instrument code (<a name="6001-MARK-001" href="#6001-MARK-001">6001-MARK-001</a>)
- **Must** see market's instrument name (sometimes labelled 'description') (<a name="6001-MARK-002" href="#6001-MARK-002">6001-MARK-002</a>)
- **Must** see status (<a name="6001-MARK-003" href="#6001-MARK-003">6001-MARK-003</a>)
- **Must** see the settlement date (<a name="6001-MARK-004" href="#6001-MARK-004">6001-MARK-004</a>)
- **Must** use `marketTimestamps.closed` field if market is indeed closed (<a name="6001-MARK-005" href="#6001-MARK-005">6001-MARK-005</a>)
- **Must** fallback to using the `settlement-expiry-date:<date>` if market is not fully settled but trading is terminated (<a name="6001-MARK-006" href="#6001-MARK-006">6001-MARK-006</a>)
- **Must** indicate if the date shown is 'expected' (metadata value) or if it is the true closed datetime (`marketTimestamps.closed`) (<a name="6001-MARK-007" href="#6001-MARK-007">6001-MARK-007</a>)
- **Must** show the date formatted for the user's locale (<a name="6001-MARK-008" href="#6001-MARK-008">6001-MARK-008</a>)
- **Must** link to the trading termination oracle spec (<a name="6001-MARK-009" href="#6001-MARK-009">6001-MARK-009</a>)
- **Could** show the settlement date as words relative to now (E.G. '2 days ago') (<a name="6001-MARK-010" href="#6001-MARK-010">6001-MARK-010</a>)
- **Must** show the last best bid price (<a name="6001-MARK-011" href="#6001-MARK-011">6001-MARK-011</a>)
- **Must** show the last best offer price (<a name="6001-MARK-012" href="#6001-MARK-012">6001-MARK-012</a>)
- **Must** show the final mark price (<a name="6001-MARK-013" href="#6001-MARK-013">6001-MARK-013</a>)
- **Must** show the settlement price (<a name="6001-MARK-014" href="#6001-MARK-014">6001-MARK-014</a>)
- **Must** link to the settlement data oracle spec (<a name="6001-MARK-015" href="#6001-MARK-015">6001-MARK-015</a>)
- **Must** retrieve settlement data from corresponding oracle spec (<a name="6001-MARK-016" href="#6001-MARK-016">6001-MARK-016</a>)
- **Must** show the settlement asset (<a name="6001-MARK-018" href="#6001-MARK-018">6001-MARK-018</a>)
- **Must** be able to view full asset details (<a name="6001-MARK-019" href="#6001-MARK-019">6001-MARK-019</a>)
- **Must** provide a way to copy the market ID (<a name="6001-MARK-020" href="#6001-MARK-020">6001-MARK-020</a>)
- **Must** show when a closed market has a successor market (<a name="6001-MARK-068" href="#6001-MARK-068">6001-MARK-068</a>)
- **Must** get to a successor market from a closed market i.e. there is a link (<a name="6001-MARK-069" href="#6001-MARK-069">6001-MARK-069</a>)
- if there is no markets:
- **Must** show No markets info (<a name="6001-MARK-034" href="#6001-MARK-034">6001-MARK-034</a>)
## Market Selector
- **Must** see market's instrument code (<a name="6001-MARK-021" href="#6001-MARK-021">6001-MARK-021</a>)
- **Must** see market's instrument name (sometimes labelled 'description') (<a name="6001-MARK-022" href="#6001-MARK-022">6001-MARK-022</a>)
- **Must** see 24hr price change (<a name="6001-MARK-023" href="#6001-MARK-023">6001-MARK-023</a>)
- **Must** see current price (<a name="6001-MARK-024" href="#6001-MARK-024">6001-MARK-024</a>)
- **Must** price movements over last 24hr (sparkline) (<a name="6001-MARK-025" href="#6001-MARK-025">6001-MARK-025</a>)
- **Must** be linked to all markets page (<a name="6001-MARK-026" href="#6001-MARK-026">6001-MARK-026</a>)
- **Must** be able to filter by product type (<a name="6001-MARK-027" href="#6001-MARK-027">6001-MARK-027</a>)
- **Must** be able to filter by settlement asset (<a name="6001-MARK-028" href="#6001-MARK-028">6001-MARK-028</a>)
- **Must** be able to search by instrument code and instrument name (<a name="6001-MARK-029" href="#6001-MARK-029">6001-MARK-029</a>)
- **Must** be able to sort
- by top gaining market (<a name="6001-MARK-030" href="#6001-MARK-030">6001-MARK-030</a>)
- by top losing market (<a name="6001-MARK-031" href="#6001-MARK-031">6001-MARK-031</a>)
- by newest markets (opening timestamp) (<a name="6001-MARK-032" href="#6001-MARK-032">6001-MARK-032</a>)
- **Must** be able to close and open the market selector (<a name="6001-MARK-066" href="#6001-MARK-066">6001-MARK-066</a>)
- **Must** must change color and have + or negative suffix of the price change and change color for the sparkline (<a name="6001-MARK-067" href="#6001-MARK-067">6001-MARK-067</a>)
## All Markets
- **Must** see market's instrument code (<a name="6001-MARK-035" href="#6001-MARK-035">6001-MARK-035</a>)
- **Must** see market's instrument name (sometimes labelled 'description') (<a name="6001-MARK-036" href="#6001-MARK-036">6001-MARK-036</a>)
- **Must** see Trading mode (<a name="6001-MARK-037" href="#6001-MARK-037">6001-MARK-037</a>)
- **Must** see status (<a name="6001-MARK-038" href="#6001-MARK-038">6001-MARK-038</a>)
- **Must** show the last best bid price (<a name="6001-MARK-039" href="#6001-MARK-039">6001-MARK-039</a>)
- **Must** show the last best offer price (<a name="6001-MARK-040" href="#6001-MARK-040">6001-MARK-040</a>)
- **Must** show the final mark price (<a name="6001-MARK-041" href="#6001-MARK-041">6001-MARK-041</a>)
- **Must** show the settlement asset (<a name="6001-MARK-042" href="#6001-MARK-042">6001-MARK-042</a>)
- **Must** be able to view full asset details (<a name="6001-MARK-043" href="#6001-MARK-043">6001-MARK-043</a>)
- **Must** see status action menu (<a name="6001-MARK-044" href="#6001-MARK-044">6001-MARK-044</a>)
- **Must** provide a way to copy the market ID (<a name="6001-MARK-045" href="#6001-MARK-045">6001-MARK-045</a>)
- **Must** provide a way to view on Explorer (<a name="6001-MARK-046" href="#6001-MARK-046">6001-MARK-046</a>)
- **Must** provide a way to view asset (<a name="6001-MARK-047" href="#6001-MARK-047">6001-MARK-047</a>)
- **Must** be able to sort each column by asc and dsc (<a name="6001-MARK-064" href="#6001-MARK-064">6001-MARK-064</a>)
- **Must** be able to drag and drop column names to re order (<a name="6001-MARK-065" href="#6001-MARK-065">6001-MARK-065</a>)
- if there is no markets:
- **Must** show No markets info (<a name="6001-MARK-048" href="#6001-MARK-048">6001-MARK-048</a>)
## Proposed markets
- **Must** see market's instrument code (<a name="6001-MARK-049" href="#6001-MARK-049">6001-MARK-049</a>)
- **Must** see market's instrument name (sometimes labelled 'description') (<a name="6001-MARK-050" href="#6001-MARK-050">6001-MARK-050</a>)
- **Must** show the settlement asset (<a name="6001-MARK-051" href="#6001-MARK-051">6001-MARK-051</a>)
- **Must** see state (<a name="6001-MARK-052" href="#6001-MARK-052">6001-MARK-052</a>)
- **Must** see if proposal is set to pass or fail (<a name="6001-MARK-053" href="#6001-MARK-053">6001-MARK-053</a>)
- **Must** see voting (<a name="6001-MARK-054" href="#6001-MARK-054">6001-MARK-054</a>)
- **Must** see if proposal has enough votes (<a name="6001-MARK-055" href="#6001-MARK-055">6001-MARK-055</a>)
- **Must** see closing date (<a name="6001-MARK-056" href="#6001-MARK-056">6001-MARK-056</a>)
- **Must** see enactment date (<a name="6001-MARK-057" href="#6001-MARK-057">6001-MARK-057</a>)
- **Must** see status action menu (<a name="6001-MARK-058" href="#6001-MARK-058">6001-MARK-058</a>)
- **Must** provide a way to view proposal (<a name="6001-MARK-059" href="#6001-MARK-059">6001-MARK-059</a>)
- **Must** provide a way to propose a new market (<a name="6001-MARK-060" href="#6001-MARK-060">6001-MARK-060</a>)
- **Must** be able to sort each column by asc and dsc (<a name="6001-MARK-062" href="#6001-MARK-062">6001-MARK-062</a>)
- **Must** be able to drag and drop column names to re order (<a name="6001-MARK-063" href="#6001-MARK-063">6001-MARK-063</a>)
- if there is no markets:
- **Must** show No data info (<a name="6001-MARK-061" href="#6001-MARK-061">6001-MARK-061</a>)

131
specs/6002-MDET-market-details.md Normal file
View File

@ -0,0 +1,131 @@
# Market
As a trading platform user I want to see all possible information about market.
<i>IMPORTANT: Available entries may vary depending on market specifics (e.g. oracle related). Separate ACs may be created for more detailed information.</i>
## Market details
When I am on trading platform I **Must** see following market details summary on the top of trading page:
<i> Depending on the market data, tooltips may be available for some records when hovered on.</i>
- Market name (<a name="6002-MDET-001" href="#6002-MDET-001">6002-MDET-001</a>)
- Expiry (<a name="6002-MDET-002" href="#6002-MDET-002">6002-MDET-002</a>)
- Price (<a name="6002-MDET-003" href="#6002-MDET-003">6002-MDET-003</a>)
- Change (24h) (<a name="6002-MDET-004" href="#6002-MDET-004">6002-MDET-004</a>)
- Volume (24h) (<a name="6002-MDET-005" href="#6002-MDET-005">6002-MDET-005</a>)
- Trading mode (<a name="6002-MDET-006" href="#6002-MDET-006">6002-MDET-006</a>)
- Status (<a name="6002-MDET-007" href="#6002-MDET-007">6002-MDET-007</a>)
- Settlement asset (<a name="6002-MDET-008" href="#6002-MDET-008">6002-MDET-008</a>)
- Liquidity supplied (<a name="6002-MDET-009" href="#6002-MDET-009">6002-MDET-009</a>)
## Market data
When I look into market info I **Must** see following data:
- Current fees: (<a name="6002-MDET-101" href="#6002-MDET-101">6002-MDET-101</a>)
- Maker Fee
- Infrastracture Fee
- Liquidity Fee
- Total Fees
- Market price: (<a name="6002-MDET-102" href="#6002-MDET-102">6002-MDET-102</a>)
- Mark Price
- Best Bid Price
- Best Offer Price
- Quote Unit
- Market volume: (<a name="6002-MDET-103" href="#6002-MDET-103">6002-MDET-103</a>)
- 24 Hour Volume
- Open Interest
- Best Bid Volume
- Best Offer Volume
- Best Static Bid Volume
- Best Static Offer Volume
- Insurance pool: (<a name="6002-MDET-104" href="#6002-MDET-104">6002-MDET-104</a>)
- Balance
## Market specification
When I look into market info I **Must** see following specification:
- Key details: (<a name="6002-MDET-201" href="#6002-MDET-201">6002-MDET-201</a>)
- Name
- Market ID
- Trading Mode
- Market Decimal Places
- Position Decimal Places
- Settlement Asset Decimal Places
- Instrument: (<a name="6002-MDET-202" href="#6002-MDET-202">6002-MDET-202</a>)
- Market Name
- Code
- Product Type
- Quote Name
- Oracle: (<a name="6002-MDET-203" href="#6002-MDET-203">6002-MDET-203</a>)
- <i>content may vary</i>
- Settlement Oracle: (<a name="6002-MDET-204" href="#6002-MDET-204">6002-MDET-204</a>)
- <i>content may vary</i>
- Termination Oracle: (<a name="6002-MDET-205" href="#6002-MDET-205">6002-MDET-205</a>)
- <i>content may vary</i>
- Settlement asset: (<a name="6002-MDET-206" href="#6002-MDET-206">6002-MDET-206</a>)
- ID
- Type
- Name
- Symbol
- Decimals
- Quantum
- Status
- Contract address (link)
- Withdrawal threshold
- Lifetime limit
- Infrastracture fee account balance
- Global reward pool account balance
- Metadata: (<a name="6002-MDET-207" href="#6002-MDET-207">6002-MDET-207</a>)
- Expiry Date
- Base
- Quote
- Class
- Sector
- Enactment
- Settlement
- Risk model: (<a name="6002-MDET-208" href="#6002-MDET-208">6002-MDET-208</a>)
- Tau
- Risk Aversion Parameter
- Risk parameters: (<a name="6002-MDET-209" href="#6002-MDET-209">6002-MDET-209</a>)
- Sigma
- Risk factors: (<a name="6002-MDET-210" href="#6002-MDET-210">6002-MDET-210</a>)
- Short
- Long
- price monitoring bounds <i>(multiple bounds possible)</i>: (<a name="6002-MDET-211" href="#6002-MDET-211">6002-MDET-211</a>)
- Highest Price
- Lowest Price
- Liquidity monitoring parameters: (<a name="6002-MDET-212" href="#6002-MDET-212">6002-MDET-212</a>)
- Triggering Ratio
- Time Window
- Scaling Factor
- Liquidity: (<a name="6002-MDET-213" href="#6002-MDET-213">6002-MDET-213</a>)
- Target Stake
- Supplied Stake
- Market Value Proxy
- link to liquidity provision table
- Liquidity price range: (<a name="6002-MDET-214" href="#6002-MDET-214">6002-MDET-214</a>)
- Liquidity Price Range
- Lowest Price
- Highest Price
## Market governance
When I look into market info I **Must** see following governance information:
- Proposal: (<a name="6002-MDET-301" href="#6002-MDET-301">6002-MDET-301</a>)
- link to governance proposal
- link to propose a change to market
## Market successor
When I'm tranding on the market, I **Must** see there are:
- Market successor: (<a name="6002-MDET-401" href="#6002-MDET-401">6002-MDET-401</a>)
- link to the successor market
- 24 h volume of the successor market
- Remaining time until parent market expires
- Proposal for the market successor : (<a name="6002-MDET-402" href="#6002-MDET-402">6002-MDET-402</a>)
- link to governance proposal
- name of the proposed market

14
specs/6003-ORDB-order_book.md Normal file
View File

@ -0,0 +1,14 @@
# Order book
As a market user I want to see information about orders existing in the market.
- I **Must** see Orders tab (<a name="6003-ORDB-001" href="#6003-ORDB-001">6003-ORDB-001</a>)
- I **Must** see table filled with existing orders data (<a name="6003-ORDB-002" href="#6003-ORDB-002">6003-ORDB-002</a>)
- I **Must** see prices of orders (<a name="6003-ORDB-003" href="#6003-ORDB-003">6003-ORDB-003</a>)
- I **Must** see bid/ask volume for each price (<a name="6003-ORDB-004" href="#6003-ORDB-004">6003-ORDB-004</a>)
- I **Must** see cumulative volume for each price (<a name="6003-ORDB-005" href="#6003-ORDB-005">6003-ORDB-005</a>)
- I **Must** see mid price in the middle of the table (<a name="6003-ORDB-006" href="#6003-ORDB-006">6003-ORDB-006</a>)
- I **Must** see prices sorted descending (<a name="6003-ORDB-007" href="#6003-ORDB-007">6003-ORDB-007</a>)
- I **Must** be able to set a resolution of data (<a name="6003-ORDB-008" href="#6003-ORDB-008">6003-ORDB-008</a>)
- When I click specific price, it **Must** be copied to deal ticket form (<a name="6003-ORDB-009" href="#6003-ORDB-009">6003-ORDB-009</a>)
- Order is removed from orderbook if traded away(<a name="6003-ORDB-010" href="#6003-ORDB-010">6003-ORDB-010</a>)

11
specs/6005-THIS-trade_history.md Normal file
View File

@ -0,0 +1,11 @@
# Trade history
As a market user I want to be aware about trades that are being made in the market.
- I **Must** see Trades tab (<a name="6005-THIS-001" href="#6005-THIS-001">6005-THIS-001</a>)
- I **Must** see Trades table filled with trades that were done in the market (<a name="6005-THIS-002" href="#6005-THIS-002">6005-THIS-002</a>)
- I **Must** see Price of each trade (<a name="6005-THIS-003" href="#6005-THIS-003">6005-THIS-003</a>)
- I **Must** see Size of each trade (<a name="6005-THIS-004" href="#6005-THIS-004">6005-THIS-004</a>)
- I **Must** see date and time of each trade (<a name="6005-THIS-005" href="#6005-THIS-005">6005-THIS-005</a>)
- I **Must** see most recent trades on the top of the table (<a name="6005-THIS-006" href="#6005-THIS-006">6005-THIS-006</a>)
- When I click specific price, it **Must** be copied to deal ticket form (<a name="6005-THIS-007" href="#6005-THIS-007">6005-THIS-007</a>)

12
specs/6006-DEPC-chart_depth.md Normal file
View File

@ -0,0 +1,12 @@
# Depth chart
As a market user, I want to be aware of the depth of the market using a chart.
- **Must** see Depth tab on trading page (<a name="6006-DEPC-001" href="#6006-DEPC-001">6006-DEPC-001</a>)
- **Must** see green bid wall and red ask wall filled with limit orders (<a name="6006-DEPC-002" href="#6006-DEPC-002">6006-DEPC-002</a>)
- **Must** see mid market price in the center of chart (<a name="6006-DEPC-003" href="#6006-DEPC-003">6006-DEPC-003</a>)
- **Must** see bid and ask line on mouse hover (<a name="6006-DEPC-004" href="#6006-DEPC-004">6006-DEPC-004</a>)
- **Must** see X-axis - buy or sell price (<a name="6006-DEPC-005" href="#6006-DEPC-005">6006-DEPC-005</a>)
- **Must** see Y-axis - cumulative volume (<a name="6006-DEPC-006" href="#6006-DEPC-006">6006-DEPC-006</a>)
- **Must** be able to zoom in and zoom out chart (<a name="6006-DEPC-007" href="#6006-DEPC-007">6006-DEPC-007</a>)
- **Must** see on mouse hover opposite ask or bid price (<a name="6006-DEPC-008" href="#6006-DEPC-008">6006-DEPC-008</a>)

144
specs/6007-CHAR-chart.md Normal file
View File

@ -0,0 +1,144 @@
# Chart
## Display options
- **Must** be able to change time interval from a list of intervals (<a name="6007-CHAR-001" href="#6007-CHAR-001">6007-CHAR-001</a>)
- 1m
- 5m
- 15m
- 1H
- 6H
- 1D
- **Must** be able to change display type from a list of display types (<a name="6007-CHAR-002" href="#6007-CHAR-002">6007-CHAR-002</a>)
- Mountain
- Candlestick
- Line
- OHLC
- **Must** icon will change depending on the display type selected (<a name="6007-CHAR-003" href="#6007-CHAR-003">6007-CHAR-003</a>)
- Mountain
- Candlestick
- Line
- OHLC
- **Must** be able to add overlays by selecting from a list of overlays (<a name="6007-CHAR-004" href="#6007-CHAR-004">6007-CHAR-004</a>)
- Bollinger bands
- Envelope
- EMA
- Moving Average
- Price monitoring bounds
- **Must** be able to add studies by selecting from a list of studies (<a name="6007-CHAR-005" href="#6007-CHAR-005">6007-CHAR-005</a>)
- Eldar-ray
- Force index
- MACD
- RSI
- Volume
- **Must** be able to add multiple studies at the same time (<a name="6007-CHAR-006" href="#6007-CHAR-006">6007-CHAR-006</a>)
- **Must** be able to close any studies selected (<a name="6007-CHAR-007" href="#6007-CHAR-007">6007-CHAR-007</a>)
- **Must** be able to add multiple overlays at the same time (<a name="6007-CHAR-008" href="#6007-CHAR-008">6007-CHAR-008</a>)
- **Must** be able to close any overlays selected (<a name="6007-CHAR-009" href="#6007-CHAR-009">6007-CHAR-009</a>)
## Price and Time
- **Must** see details of price from where my mouse cursor is on the chart(<a name="6007-CHAR-010" href="#6007-CHAR-010">6007-CHAR-010</a>)
- Time (24h)
- Date (dd/MMM/yyyy)
- O
- H
- L
- C
- Change
- **Must** see crosshair on the chart where my mouse cursor is(<a name="6007-CHAR-011" href="#6007-CHAR-011">6007-CHAR-011</a>)
- **Must** be able to mousewheel scroll to extend/reduce time range(<a name="6007-CHAR-012" href="#6007-CHAR-012">6007-CHAR-012</a>)
- **Must** x axis shows time range(<a name="6007-CHAR-013" href="#6007-CHAR-013">6007-CHAR-013</a>)
- **Must** y axis shows price range(<a name="6007-CHAR-014" href="#6007-CHAR-014">6007-CHAR-014</a>)
- **Must** show the last price line on the Y axis (<a name="6007-CHAR-015" href="#6007-CHAR-015">6007-CHAR-015</a>)
# Display Types
## Mountain
- **Must** show area line chart with the line being at the last price (<a name="6007-CHAR-016" href="#6007-CHAR-016">6007-CHAR-016</a>)
## Candlestick
- **Must** body is green if the close is higher than the open (<a name="6007-CHAR-017" href="#6007-CHAR-017">6007-CHAR-017</a>)
- **Must** body is red if the close is lower than the open (<a name="6007-CHAR-018" href="#6007-CHAR-018">6007-CHAR-018</a>)
- **Must** show open price (<a name="6007-CHAR-019" href="#6007-CHAR-019">6007-CHAR-019</a>)
- **Must** show high price (<a name="6007-CHAR-020" href="#6007-CHAR-020">6007-CHAR-020</a>)
- **Must** show low price (<a name="6007-CHAR-021" href="#6007-CHAR-021">6007-CHAR-021</a>)
- **Must** show close price (<a name="6007-CHAR-022" href="#6007-CHAR-022">6007-CHAR-022</a>)
## Line
- **Must** show line on the chart with the line being the the last price (<a name="6007-CHAR-023" href="#6007-CHAR-023">6007-CHAR-023</a>)
## OHLC
- **Must** show open price (<a name="6007-CHAR-024" href="#6007-CHAR-024">6007-CHAR-024</a>)
- **Must** show high price (<a name="6007-CHAR-025" href="#6007-CHAR-025">6007-CHAR-025</a>)
- **Must** show low price (<a name="6007-CHAR-026" href="#6007-CHAR-026">6007-CHAR-026</a>)
- **Must** show close price (<a name="6007-CHAR-027" href="#6007-CHAR-027">6007-CHAR-027</a>)
- **Must** show in green if the close is higher than the open (<a name="6007-CHAR-028" href="#6007-CHAR-028">6007-CHAR-028</a>)
- **Must** show in red if the close is lower than the open (<a name="6007-CHAR-029" href="#6007-CHAR-029">6007-CHAR-029</a>)
# Overlays
## Bollinger bands
- **Must** show upper band (<a name="6007-CHAR-030" href="#6007-CHAR-030">6007-CHAR-030</a>)
- **Must** show lower band (<a name="6007-CHAR-031" href="#6007-CHAR-031">6007-CHAR-031</a>)
- **Must** show band values at time of cursor position (<a name="6007-CHAR-032" href="#6007-CHAR-032">6007-CHAR-032</a>)
## Envelope
- **Must** show upper line (<a name="6007-CHAR-033" href="#6007-CHAR-033">6007-CHAR-033</a>)
- **Must** show lower line (<a name="6007-CHAR-034" href="#6007-CHAR-034">6007-CHAR-034</a>)
- **Must** show line values at time of cursor position (<a name="6007-CHAR-035" href="#6007-CHAR-035">6007-CHAR-035</a>)
## EMA
- **Must** show line (<a name="6007-CHAR-036" href="#6007-CHAR-036">6007-CHAR-036</a>)
- **Must** show line value at time of cursor position (<a name="6007-CHAR-037" href="#6007-CHAR-037">6007-CHAR-037</a>)
## Moving Average
- **Must** show line (<a name="6007-CHAR-038" href="#6007-CHAR-038">6007-CHAR-038</a>)
- **Must** show line value at time of cursor position (<a name="6007-CHAR-039" href="#6007-CHAR-039">6007-CHAR-039</a>)
## Price monitoring bounds
- **Must** show min line (<a name="6007-CHAR-040" href="#6007-CHAR-040">6007-CHAR-040</a>)
- **Must** show max line (<a name="6007-CHAR-041" href="#6007-CHAR-041">6007-CHAR-041</a>)
- **Must** show reference line (<a name="6007-CHAR-042" href="#6007-CHAR-042">6007-CHAR-042</a>)
- **Must** show line values at time of cursor position (<a name="6007-CHAR-043" href="#6007-CHAR-043">6007-CHAR-043</a>)
# Studies
## Eldar-ray
- **Must** show bear power line (<a name="6007-CHAR-044" href="#6007-CHAR-044">6007-CHAR-044</a>)
- **Must** show bull power line (<a name="6007-CHAR-045" href="#6007-CHAR-045">6007-CHAR-045</a>)
- **Must** show line values at time of cursor position (<a name="6007-CHAR-046" href="#6007-CHAR-046">6007-CHAR-046</a>)
## Force index
- **Must** show force line (<a name="6007-CHAR-047" href="#6007-CHAR-047">6007-CHAR-047</a>)
- **Must** show line value at time of cursor position (<a name="6007-CHAR-048" href="#6007-CHAR-048">6007-CHAR-048</a>)
## MACD
- **Must** show MACD line (<a name="6007-CHAR-049" href="#6007-CHAR-049">6007-CHAR-049</a>)
- **Must** show signal line (<a name="6007-CHAR-050" href="#6007-CHAR-050">6007-CHAR-050</a>)
- **Must** show histogram (<a name="6007-CHAR-051" href="#6007-CHAR-051">6007-CHAR-051</a>)
- **Must** show line values at time of cursor position (<a name="6007-CHAR-052" href="#6007-CHAR-052">6007-CHAR-052</a>)
## RSI
- **Must** show RSI line (<a name="6007-CHAR-053" href="#6007-CHAR-053">6007-CHAR-053</a>)
- **Must** show line value at time of cursor position (<a name="6007-CHAR-054" href="#6007-CHAR-054">6007-CHAR-054</a>)
## Volume
- **Must** show volume bars (<a name="6007-CHAR-055" href="#6007-CHAR-055">6007-CHAR-055</a>)
- **Must** show bar value at time of cursor position (<a name="6007-CHAR-056" href="#6007-CHAR-056">6007-CHAR-056</a>)

35
specs/6501-ASSE-assets.md Normal file
View File

@ -0,0 +1,35 @@
# Assets
## Asset detail dialog
- **Must** see asset ID (<a name="6501-ASSE-001" href="#6501-ASSE-001">6501-ASSE-001</a>)
- **Must** see asset type (only ERC20 for now) (<a name="6501-ASSE-002" href="#6501-ASSE-002">6501-ASSE-002</a>)
- **Must** see full asset name (<a name="6501-ASSE-003" href="#6501-ASSE-003">6501-ASSE-003</a>)
- **Must** see asset symbol (<a name="6501-ASSE-004" href="#6501-ASSE-004">6501-ASSE-004</a>)
- **Must** see asset decimals (<a name="6501-ASSE-005" href="#6501-ASSE-005">6501-ASSE-005</a>)
- **Must** see asset quantum value (<a name="6501-ASSE-006" href="#6501-ASSE-006">6501-ASSE-006</a>)
- **Must** see asset status (Proposed, Rejected, Pending listing, Enabled) (<a name="6501-ASSE-007" href="#6501-ASSE-007">6501-ASSE-007</a>)
- **Must** see withdrawal threshold (<a name="6501-ASSE-008" href="#6501-ASSE-008">6501-ASSE-008</a>)
- **Must** see lifetime withdrawal limit (<a name="6501-ASSE-009" href="#6501-ASSE-009">6501-ASSE-009</a>)
- **Must** see infrastructure fee account balance (<a name="6501-ASSE-010" href="#6501-ASSE-010">6501-ASSE-010</a>)
- **Must** see global reward pool account balance (<a name="6501-ASSE-011" href="#6501-ASSE-011">6501-ASSE-011</a>)
- **Must** see tooltips on hover for
- Type (value)
- Decimals (label)
- Quantum (label)
- Status (label and value)
- Contract address (label)
- Withdrawal threshold (label)
- Lifetime limit (label)
- Infrastructure fee account balance (label)
- Global reward pool account balance (label)
- Maker paid fees account balance (label)
- Maker received fees account balance (label)
- Liquidity provision fee reward account balance (label)
- Market proposer reward account balance (label) (<a name="6501-ASSE-012" href="#6501-ASSE-012">6501-ASSE-012</a>)
- **Must** be able to close the dialog (<a name="6501-ASSE-013" href="#6501-ASSE-013">6501-ASSE-013</a>)
### Asset types
- ERC20
- **Must** see contract address (<a name="6501-ASSE-014" href="#6501-ASSE-014">6501-ASSE-014</a>)

29
specs/7001-COLL-collateral.md Normal file
View File

@ -0,0 +1,29 @@
# Collateral
## Collateral Data Grid
- **Must** be shown grouped by [asset](9001-DATA-data_display.md#asset-balances) (<a name="7001-COLL-001" href="#7001-COLL-001">7001-COLL-001</a>)
- For each asset:
- **Must** show used [amount](9001-DATA-data_display.md#asset-balances), which is the total of all Margin and Liquidity bond accounts (<a name="7001-COLL-002" href="#7001-COLL-002">7001-COLL-002</a>)
- **Must** show available [amount](9001-DATA-data_display.md#asset-balances), which is the total of your General account (<a name="7001-COLL-003" href="#7001-COLL-003">7001-COLL-003</a>)
- **Must** show total [amount](9001-DATA-data_display.md#asset-balances), which is the sum of your General account and all Margin accounts (<a name="7001-COLL-004" href="#7001-COLL-004">7001-COLL-004</a>)
- **Must** show amounts formatted by quantum (<a name="7001-COLL-012" href="#7001-COLL-012">7001-COLL-012</a>)
- **Must** provide a method for depositing asset (<a name="7001-COLL-005" href="#7001-COLL-005">7001-COLL-005</a>)
- **Must** provide a method for withdrawing asset (<a name="7001-COLL-006" href="#7001-COLL-006">7001-COLL-006</a>)
- **Must** show the asset symbol (<a name="7001-COLL-007" href="#7001-COLL-007">7001-COLL-007</a>)
- **Must** provide a way to see the [full asset details](6501-ASSE-assets.md) (<a name="7001-COLL-008" href="#7001-COLL-008">7001-COLL-008</a>)
- **Must** provide a way to see all accounts, their type, and their balance for a single asset (<a name="7001-COLL-009" href="#7001-COLL-009">7001-COLL-009</a>)
- **Could** have default sort order (<a name="7001-COLL-010" href="#7001-COLL-010">7001-COLL-010</a>)
- General
- Margin
- Bond
- Fees - Maker
- Fees - Liquidity
- Rewards - Maker Paid
- Rewards - Maker Received
- Rewards - Liquidity Provision Received Fees
- Rewards - Market Proposers
## Deal Ticket
- **Must** see your current total margin (General balance + Margin balance - Maintenance level) available (<a name="7001-COLL-011" href="#7001-COLL-011">7001-COLL-011</a>)

257
specs/7002-SORD-submit_orders.md Normal file
View File

@ -0,0 +1,257 @@
# Submit order
As a user I want change my exposure on a market (e.g. open a position, increase or decrease my open volume), I want to submit an order with instructions for how my order should be executed so I have some control over the price that I get, as well as if when/my order should stay on the book. See [specs about orders](../protocol#orders) for more info.
## Before seeing a "deal ticket"
When looking at a market, I...
- **must** see/select the [Market](./9001-DATA-data_display.md#market) I am submitting the order for (<a name="7002-SORD-001" href="#7002-SORD-001">7002-SORD-001</a>)
- **must** see the current `status` of the market (<a name="7002-SORD-061" href="#7002-SORD-061">7002-SORD-061</a>)
if the market is in a state of `rejected`, `canceled` or `closed`:
- **must** see that the market is not accepting orders and never will be (<a name="7002-SORD-062" href="#7002-SORD-062">7002-SORD-062</a>)
if the market is in a state of `tradingTerminated`:
- **must** see that the market is not accepting orders and never will be (<a name="7002-SORD-063" href="#7002-SORD-063">7002-SORD-063</a>)
- **should** see the [price](9001-DATA-data_display.md#quote-price) that was used to settle the market
- **should** see a link to oracle spec and data
if the market is in a state of `settled`:
- **must** see that the market is not accepting orders and never will be (<a name="7002-SORD-066" href="#7002-SORD-066">7002-SORD-066</a>)
- **should** see the oracle events that terminated the market
- **should** see a link to oracle spec and data
if the market is in a state of `suspended`:
- **should** see what suspended the market
- **should** see the conditioned required for the auction to end
- **should** see the current data values that the auction end is measured against (e.g. Supplied stake)
...so I know if the market is accepting orders.
The rest of this document only applies if the state of the market is `pending`, `active` or `suspended`:
## Deal ticket
When populating a deal ticket I...
- **must** see the current market trading mode (Continuous, Auction etc) (<a name="7002-SORD-002" href="#7002-SORD-002">7002-SORD-002</a>)
- If I have a 0 total balance of the settlement asset: **must** be warned that I have insufficient collateral (but also allow you to populate ticket because I might want to try before I deposit) (<a name="7002-SORD-003" href="#7002-SORD-003">7002-SORD-003</a>)
- **should** have a way to easily deposit the required collateral
- **must** select a side/direction e.g. long/short (note: some implementations may do this with two different submit buttons long/short rather than a toggle) (<a name="7002-SORD-004" href="#7002-SORD-004">7002-SORD-004</a>)
- **must** be able to select the [order type](../protocol/0014-ORDT-order_types.md) that I wish to submit (<a name="7002-SORD-005" href="#7002-SORD-005">7002-SORD-005</a>)
- **must** see limit order (<a name="7002-SORD-006" href="#7002-SORD-006">7002-SORD-006</a>)
- **must** see market order (<a name="7002-SORD-007" href="#7002-SORD-007">7002-SORD-007</a>)
- **must** see stop limit order (<a name="7002-SORD-008" href="#7002-SORD-008">7002-SORD-008</a>)
- **must** see stop market order (<a name="7002-SORD-009" href="#7002-SORD-009">7002-SORD-009</a>)
## Order size
...need to select a size, when selecting a size for my order, I...
- **must** input an order [size](9001-DATA-data_display.md#size) (aka amount or contracts) (<a name="7002-SORD-010" href="#7002-SORD-010">7002-SORD-010</a>)
- **should** have the previous value for the selected market available e.g. pre-populated (last submitted or last changed)
- **should** be able to quickly change the size by the market's min-contract size e.g. hit up/down on the keyboard to increase
- **should** be able to use modifier keys (SHIFT, ALT etc) to increase/decrease in larger increments with arrows
- **would** like to be able to enter a number followed be "k" or "m" or "e2" etc. to make it thousands or millions or hundreds, etc.
- **must** be warned (pre-submit) if input has too many digits after the decimal place for the market's ["position" decimal places](9001-DATA-data_display.md#size) (<a name="7002-SORD-016" href="#7002-SORD-016">7002-SORD-016</a>)
... so I get the size of exposure (open volume) that I want
## Price - Limit order
... if wanting to place a limit on the price that I trade at, I...
- **must** enter a [price](9001-DATA-data_display.md#quote-price). (<a name="7002-SORD-017" href="#7002-SORD-017">7002-SORD-017</a>)
- **must** see the price unit (as defined in market) (<a name="7002-SORD-018" href="#7002-SORD-018">7002-SORD-018</a>)
- **should** be able quickly pre-populate the price with the current mark price (if there is one, 0 if not) e.g. by focusing the input and hitting up/down
- **should** have the previous value for the selected market pre-populated (last submitted or last changed)
- **should** be able to hit up/down on the keyboard to increase the price by the market's tick size (if set, or smallest increment)
- **should** be able to use modifier keys (SHIFT, ALT etc) to increase/decrease in larger increments with arrows
- **would** like to be able to enter a number followed be "k" or "m" or "e2" etc. to make it thousands or millions or hundreds, etc.
- **must** be warned (pre-submit) if the input price has too many digits after the decimal place for the market ["quote"](9001-DATA-data_display.md#quote-price) (<a name="7002-SORD-059" href="#7002-SORD-059">7002-SORD-059</a>)
... so that my order only trades at up/down to a particular price
## Price - Limit stop order
... if wanting to place a stop limit on the price that I trade at, I...
- **must** enter a price (<a name="7002-SORD-020" href="#7002-SORD-020">7002-SORD-020</a>)
- **must** see the price unit (as defined in market) (<a name="7002-SORD-021" href="#7002-SORD-021">7002-SORD-021</a>)
- **must** have the previous value for the selected market pre-populated (last submitted or last changed) (<a name="7002-SORD-022" href="#7002-SORD-022">7002-SORD-022</a>)
- **must** be able to hit up/down on the keyboard to increase the price by the market's tick size (if set, or smallest increment) (<a name="7002-SORD-029" href="#7002-SORD-029">7002-SORD-029</a>)
- **must** be warned (pre-submit) if the input price has too many digits after the decimal place for the market "quote" (<a name="7002-SORD-032" href="#7002-SORD-032">7002-SORD-032</a>)
- **must** select a trigger direction (<a name="7002-SORD-033" href="#7002-SORD-033">7002-SORD-033</a>)
- **must** see rises above (<a name="7002-SORD-034" href="#7002-SORD-034">7002-SORD-034</a>)
- **must** see falls below (<a name="7002-SORD-035" href="#7002-SORD-035">7002-SORD-035</a>)
- if the user has not set a preference: trigger direction **must** default to `rises above` (<a name="7002-SORD-036" href="#7002-SORD-036">7002-SORD-036</a>)
- **must** enter a trigger value (<a name="7002-SORD-037" href="#7002-SORD-037">7002-SORD-037</a>)
- **must** select a trigger type (<a name="7002-SORD-038" href="#7002-SORD-038">7002-SORD-038</a>)
- **must** see a trigger price (<a name="7002-SORD-049" href="#7002-SORD-049">7002-SORD-049</a>)
- **must** see a trigger trailing percent offset (<a name="7002-SORD-050" href="#7002-SORD-050">7002-SORD-050</a>)
- if the user has not set a preference: trigger type **must** default to `price` (<a name="7002-SORD-051" href="#7002-SORD-051">7002-SORD-051</a>)
... so that my order only trades after reaching the trigger and at up/down to a particular price - it is reduce only order
## Market order
... if wanting to trade regardless of price (or assuming that the market is liquid enough that the current best prices are enough of an indication of the price I'll get)...
- **must not** see a price input (<a name="7002-SORD-019" href="#7002-SORD-019">7002-SORD-019</a>)
- **should** be warning if the market is in auction and the market order may be rejected
... so I can quickly submit an order without populating the ticket with elements I don't care about
## Market stop order
... if wanting to trade regardless of price with trigger (or assuming that the market is liquid enough that the current best prices are enough of an indication of the price I'll get)...
- **must not** see a price input (<a name="7002-SORD-052" href="#7002-SORD-052">7002-SORD-052</a>)
- **must** see a price input (<a name="7002-SORD-054" href="#7002-SORD-054">7002-SORD-054</a>)
- **must** select a trigger direction (<a name="7002-SORD-055" href="#7002-SORD-055">7002-SORD-055</a>)
- **must** see rises above (<a name="7002-SORD-056" href="#7002-SORD-056">7002-SORD-056</a>)
- **must** see falls below (<a name="7002-SORD-057" href="#7002-SORD-057">7002-SORD-057</a>)
- **must** enter a trigger value (<a name="7002-SORD-058" href="#7002-SORD-058">7002-SORD-058</a>)
- **must** select a trigger price (<a name="7002-SORD-064" href="#7002-SORD-064">7002-SORD-064</a>)
- **must** select a trigger trailing percent offset (<a name="7002-SORD-065" href="#7002-SORD-065">7002-SORD-065</a>)
- **must** copy a trigger value to the price field (<a name="7002-SORD-067" href="#7002-SORD-067">7002-SORD-067</a>)
... so that my order only trades after reaching the trigger and with market price - it is reduce only order
## Pegged
... submit an order where the price is offset from a price in system (best bid etc)
- TODO
... so my order will move with the market
## Time in force
... should to select a time in force, when selecting a time in force, I...
- **must** select a time in force
- Good till canceled `GTC` - not applicable to Market orders (<a name="7002-SORD-023" href="#7002-SORD-023">7002-SORD-023</a>)
- Good till time `GTT` - not applicable to Market orders (<a name="7002-SORD-024" href="#7002-SORD-024">7002-SORD-024</a>)
- Fill or kill `FOK` (<a name="7002-SORD-025" href="#7002-SORD-025">7002-SORD-025</a>)
- Immediate or cancel `IOC` (<a name="7002-SORD-026" href="#7002-SORD-026">7002-SORD-026</a>)
- Good for normal trading only `GFN` - not applicable to Market orders (<a name="7002-SORD-027" href="#7002-SORD-027">7002-SORD-027</a>)
- Good for auction only `GFA` - not applicable to Market orders (<a name="7002-SORD-028" href="#7002-SORD-028">7002-SORD-028</a>)
- **should** only be warned if the time in force is not applicable to the order type I have selected
- **should** only be warned if the time in force is not applicable to current period's trading mode
- if the user has not set a preference: market orders **must** default to `IOC` (<a name="7002-SORD-030" href="#7002-SORD-030">7002-SORD-030</a>)
- if the user has not set a preference: limit orders **must** default to `GTC` (<a name="7002-SORD-031" href="#7002-SORD-031">7002-SORD-031</a>)
- if it is stop order limit or stop order market then **must** select
- Fill or kill `FOK` (<a name="7002-SORD-068" href="#7002-SORD-068">7002-SORD-068</a>)
- Immediate or cancel `IOC` (<a name="7002-SORD-069" href="#7002-SORD-069">7002-SORD-069</a>)
- if the user has not set a preference: market orders **must** default to `FOK` (<a name="7002-SORD-070" href="#7002-SORD-070">7002-SORD-070</a>)
... so I can control if and how my order stays on the order book
## Execution flags
... could select some execution flags. When selecting execution flags (aka order conditions)...
- **must** see an option to select "Post only" (<a name="7003-SORD-054" href="#7003-SORD-054">7003-SORD-054</a>)
- **should** see explanation of what Post only is/does
- **must** see the post only option is unselected and disabled (can not be checked) if the time in force is set to IOC or FOK (<a name="7003-SORD-055" href="#7003-SORD-055">7003-SORD-055</a>)
- **must** see an explanation of why the option is disabled (<a name="7003-SORD-056" href="#7003-SORD-056">7003-SORD-056</a>)
- **must** see an option to select "Reduce only" (<a name="7003-SORD-057" href="#7003-SORD-057">7003-SORD-057</a>)
- **should** see explanation of what Reduce only is/does (<a name="7003-SORD-058" href="#7003-SORD-058">7003-SORD-058</a>)
- **must** see that selecting "Post only" or "reduce only" de-select the other (if selected). As is it not possibly to apply them both to an order (<a name="7003-SORD-059" href="#7003-SORD-059">7003-SORD-059</a>)
- **must** see an option to select expire for stop order limit and market (<a name="7002-SORD-071" href="#7002-SORD-071">7002-SORD-071</a>)
- **must** select strategy for stop order limit and market (<a name="7002-SORD-072" href="#7002-SORD-072">7002-SORD-072</a>)
- **must** see strategy submit (<a name="7002-SORD-073" href="#7002-SORD-073">7002-SORD-073</a>)
- **must** see strategy cancel (<a name="7002-SORD-074" href="#7002-SORD-074">7002-SORD-074</a>)
- **must** see expiry time/date (<a name="7002-SORD-075" href="#7002-SORD-075">7002-SORD-075</a>)
... so I can control in more detail how my order is executed
## Auto Populating a deal ticket non-manual methods
- TODO Populate by selecting a size/price in the order book
- TODO Populate by selecting a size/price in the chart
- TODO Populate by selecting a size/price in the depth chart
- TODO Input price as a % of account, given the current price field
- **should** be able to determine how much leverage I'd like (given general balance, and other inputs)
## See the potential consequences of an order before it is submit
... based on the current inputs I'd like an indication of the consequences of my order based on my position and the state of the market, I...
- **could** see my resulting open volume
- **could** see the amount this order might move the market in percentage terms
- **could** see what the new best prices of the market would be after placing this order (assuming my order moves the market)
- **could** see new volume weighted average entry price if not 0
- **could** see and indication the volume weighted price that this particular order
- **could** see an indication of how much of the order will trade when it hits the book and how much might remain passive
- **could** see a new liquidation level
- **could** see an estimate of the fees that will be paid (if any)
- **could** see my "position leverage" TODO - define this
- **could** see my "account leverage" TODO - define this
- **could** see an amount of realized Profit / Loss
- **could** see any change in margin requirements (if more or less margin will be required)
- **could** see the notional value of my order
... so that I can adjust my inputs before submitting
## Submit an order
... need to submit my order, when submitting my order, I...
- if not already connected: **must** see a prompt to [connect a Vega wallet](0002-WCON-connect_vega_wallet.md)
- **must** submit the [Vega submit order transaction](0013-WTXN-submit_vega_transaction.md). (<a name="7002-SORD-039" href="#7002-SORD-039">7002-SORD-039</a>)
- **must** always be able to submit regardless of market state, trading mode or account balances (<a name="7002-SORD-060" href="#7002-SORD-060">7002-SORD-060</a>)
- **must** see feedback on my order [status](https://docs.vega.xyz/docs/mainnet/grpc/vega/vega.proto#orderstatus) (not just transaction status above) (<a name="7002-SORD-040" href="#7002-SORD-040">7002-SORD-040</a>)
- Active (aka Open) (<a name="7002-SORD-041" href="#7002-SORD-041">7002-SORD-041</a>)
- Expired (<a name="7002-SORD-042" href="#7002-SORD-042">7002-SORD-042</a>)
- Cancelled. see the txn that cancelled it and a link to the block explorer, if cancelled by a user transaction. (<a name="7002-SORD-043" href="#7002-SORD-043">7002-SORD-043</a>)
- Stopped. see an explanation of why stopped (<a name="7002-SORD-044" href="#7002-SORD-044">7002-SORD-044</a>)
- Partially filled. **must** see how much of the [size](9001-DATA-data_display.md#size) if filled/remaining (<a name="7002-SORD-045" href="#7002-SORD-045">7002-SORD-045</a>)
- Filled. Must be able to see/link to all trades that were created from this order. (<a name="7002-SORD-046" href="#7002-SORD-046">7002-SORD-046</a>)
- Rejected: **must** see the reason it was rejected (<a name="7002-SORD-047" href="#7002-SORD-047">7002-SORD-047</a>)
- Parked: **must** see an explanation of why parked orders happen (<a name="7002-SORD-048" href="#7002-SORD-048">7002-SORD-048</a>)
- All feedback must be a subscription so is updated as the status changes (<a name="7002-SORD-053" href="#7002-SORD-053">7002-SORD-053</a>)
- **could** repeat the values that were submitted (order type + all fields)
... so that I am aware of the status of my order before seeing it in the [orders table](6002-MORD-manage_orders.md).
... so I get the sort of order, and price, I wish.
## Manage positions and order
After submitting orders I'll want to [manage orders](7003-MORD-manage_orders.md). If my orders resulted in a position I may wish to [manage positions](7004-POSI-positions.md)).
---
# Typical order scenarios to design/test for
Market in continuous trading:
- Limit order, Long, GTC, with a price that is lower than the current price
- Limit order, Short, GFN, that crosses the book but only gets a partial fill when order is processed
- Market order, IOC, that increases open volume (aka size of position)
- a limit order GFA when market is in Auction
- an limit that reduces exposure from something to 0
- a limit order, FOK, that squares and reverses e.g. I'm long 10, I short 20 to end short 10
Market in auction:
- Attempt Market order in Auction mode: should warn order is invalid
- Attempt limit order GFN when market is normally Continuous (but currently in auction), should warn that GFN will not work

210
specs/7003-MORD-manage_orders.md Normal file
View File

@ -0,0 +1,210 @@
# Manage orders
Users place orders to describe the trades they would like to make: buy or sell, at what price, how long it is valid for etc. In many cases they can [amend](#amend-order---price) or [cancel](#cancel-orders) these orders while they are still active, for example: changing price.
Once a user has placed an order they may wish to confirm it's [status](https://docs.vega.xyz/docs/mainnet/graphql/enums/order-status) in a [list](#orders-list) of other orders. e.g. whether it has been accepted, filled, how close it is to being filled etc. Users may be interested in the price of their orders relative to the price of the market and how much of the order's size has been filled.
Orders can also be placed on behalf of a user/party via [liquidity](#liquidity-order-shapes) or [pegged](#pegged-order-shapes) order shapes. These order cannot be amended on canceled in the same way as other orders.
Markets also have [statuses](https://docs.vega.xyz/docs/mainnet/graphql/enums/market-state) that may affect how a user perceives the state of an order, e.g if the order was placed while in "normal" continuous trading, but the market is now in auction.
## Orders list
User will have differing needs/preferences in terms of what they want to see about an order and how orders are grouped and listed. It is common for interfaces to allow users to customize how orders are displayed.
### Field customization
- **should** have the ability to select what [fields/data](#fields) are shown for each order in the list
- **should** have the ability to change the order of fields (e.g. table columns)
- **should** have the ability to give each column in the list more or less space
### Fields
When looking at a list of orders, I...
- **must** see [status](https://docs.vega.xyz/docs/mainnet/graphql/enums/order-status) of the order (<a name="7003-MORD-001" href="#7003-MORD-001">7003-MORD-001</a>), and therefore (nested bullets added for context, ACs are on fields that follow)...
- `Active​`
- How much of the order is filled / remains unfilled
- How close the mark price is to order
- If this order was filled at the limit price what would what effect would it have on realized PnL
- I may want to amend or cancel this order
- `Expired​`
- When did it expire
- How much was filled / remaining
- `Cancelled​`
- What canceled it? When did I cancel it TODO double check that "cancelled" only comes from user action
- `Stopped​`
- What stopped it (e.g. was it because an [FOC](9001-DATA-data_display.md#time-in-force) that was not filled, or because of margin availability)
- `Filled​`
- What was the average fill price I got for this order
- `Rejected​`
- Why was this order rejected (show `rejectedReason`)
- `PartiallyFilled​`
- How much was filled before the order was canceled
- What was the average fill price I got for this order
- `Parked​`
- Why is the market currently in auction
- Link to pegged shape (see below)
- **must** see any [reason (mainnet docs)](https://docs.vega.xyz/mainnet/api/graphql/enums/order-rejection-reason) that has been supplied by the API along with the order status e.g. "Rejected: Due to insufficient margin", "Stopped: Reduce only, would open new volume" (<a name="7003-MORD-018" href="#7003-MORD-018">7003-MORD-018</a>)
- **must** see what [market](9001-DATA-data_display.md#market) an order is related to (either code, ID or name, preferable name) (<a name="7003-MORD-002" href="#7003-MORD-002">7003-MORD-002</a>)
- **should** see what the `status` is of the market (particularly if it is not "normal")
- **must** see the [size](9001-DATA-data_display.md#size) of the order (<a name="7003-MORD-003" href="#7003-MORD-003">7003-MORD-003</a>)
- **must** see the [direction/side](9001-DATA-data_display.md#direction--side) (Long or Short) of the order (this can be implied with a + or negative suffix on the size, + for Long, - for short) (<a name="7003-MORD-004" href="#7003-MORD-004">7003-MORD-004</a>)
- **must** see [order type](9001-DATA-data_display.md#order-type) (<a name="7003-MORD-005" href="#7003-MORD-005">7003-MORD-005</a>)
- if order created by [pegged or liquidity provision shape](9001-DATA-data_display.md#order-origin): **should** see order origin
- **could** see what part of the liquidity shape or pegged order shape this relates to or it's offset+reference See [pegged orders](#pegged-order-shapes) and [liquidity provisions](#liquidity-order-shapes) shapes below.
- **could** see link to full shape
- **should** see how much of the order's [size](9001-DATA-data_display.md#size) has been filled e.g. if the order was for `50` but so far only 10 have traded I should see Filled = `10`. Note: this is marked as a should because in the case of Rejected order and some other scenarios it isn't relevant.
- **should** see how much of the order's [size](9001-DATA-data_display.md#size) remains.
- if order type = `Limit`: **must** see the Limit [price](9001-DATA-data_display.md#quote-price) that was set on the order
- if order type = `Market`: **must** not see a price for active or parked orders, a `-`, `Market` or `n/a` is more appropriate (API may return `0`).
- **must** see the [time in force](9001-DATA-data_display.md#time-in-force) applied to the order (can be abbreviated here) (<a name="7003-MORD-006" href="#7003-MORD-006">7003-MORD-006</a>)
- **must** see if any execution flags (aka conditions. e.g. Post only, Reduce only) were applied to the order (<a name="7003-MORD-019" href="#7003-MORD-019">7003-MORD-019</a>)
- **should** see "created at" [time](9001-DATA-data_display.md#time)
- **could** see updated at (this is used by the system when an order is amended, or repriced (in pegged and LP) not sure this in needed)
- **should** see time priority (how many orders are before mine at this price)
- if the order is `Active` &amp; **not** part of a liquidity or peg shape: **must** see an option to [amend](#amend-order---price) the individual order (<a name="7003-MORD-007" href="#7003-MORD-007">7003-MORD-007</a>)
- if the order is `Active` &amp; is part of a liquidity or peg shape: **must** **not** see an option to amend the individual order (<a name="7003-MORD-008" href="#7003-MORD-008">7003-MORD-008</a>)
- **could** see a link to amend shape
- if the order is `Active` &amp; **not** part of a liquidity or peg shape: **must** see an option to [cancel](#cancel-orders) the individual order
- if the order is `Active` &amp; is part of a liquidity or peg shape: **must** **not** see an option to cancel the individual order
- **could** see a link to cancel shape
... so I can understand the state of my orders and decide what to do next
### Filters
When looking at a list of orders, I...
- **should** have the ability to see all orders regardless of status in one list
- **should** have the ability to see only active &amp; parked orders
- **should** have the ability to see only non-active &amp; parked order (i.e. all orders that do not have the status of Active &amp; Parked)
- **could** have the ability to filter by any field(s)
- where a field is an enum: **should** be able to select one on or more values for a field that should be included
... so I can focus on the type of orders statuses etc that I want to at that time
### Sorting
When looking at a list of orders, I...
- **should** be able to sort the list (both directions) by any field in the order list
- **should** be able to add a secondary sort. e.g. by market then by date
- **should** have the default sorted by created time (or updated time if newer), with newest at the top
- **should** retain sorting preferences between switching views / browser reload
... so the sort order matches my mental model and or makes it easy for me to find the orders I am looking for
### Grouping
When looking at a list of orders, I...
- **should** be able to group orders by any field e.g. by market, lp etc
- **should** have default grouping by market
... so I can make decisions easily on a set of orders
## Cancel orders
When looking to take order out of the book, I...
- **must** select whether to cancel an individual order or all orders on a market (<a name="7003-MORD-009" href="#7003-MORD-009">7003-MORD-009</a>)
- **could** be able to cancel all orders for markets in a given settlement asset
- **would** like to cancel all orders for all markets
- **must** be able to submit the [Vega transaction](0003-WTXN-submit_vega_transaction.md) to cancel order(s) (<a name="7003-MORD-010" href="#7003-MORD-010">7003-MORD-010</a>)
- **could** show the margin requirement reduction/increase that will take place before submitting
- **must** see feedback on order status after the [Vega transaction](0003-WTXN-submit_vega_transaction.md) (<a name="7003-MORD-011" href="#7003-MORD-011">7003-MORD-011</a>)
... so that the order will not be filled and I don't end up with a change in my position that I was not expecting
## Amend order - price
Read more about [order amends](../protocol/0004-AMND-amends.md).
When looking to amend an order, I...
- **must** be able to amend the price of an order (<a name="7003-MORD-012" href="#7003-MORD-012">7003-MORD-012</a>)
- **could** be warned if the price change will, given the current market, fill the order right away
- **must** be warned (pre-submit) if the input price has too many digits after the decimal place for the market ["quote"](DATA-data_display.md#quote-price) (<a name="7003-MORD-013" href="#7003-MORD-013">7003-MORD-013</a>)
- **must** submit the Amend order [Vega transaction](0003-WTXN-submit_vega_transaction.md) (<a name="7003-MORD-014" href="#7003-MORD-014">7003-MORD-014</a>)
- **must** see the status after the transaction (see [submit order](7002-SORD-submit_orders.md#submit-an-order)) (<a name="7003-MORD-015" href="#7003-MORD-015">7003-MORD-015</a>)
... so the order is more likely to get filled or will be filled at a more competitive price
## Amend order - other than price
`TODO` - Acceptance criteria for other types of order amend
## On a price history chart
when looking at a price history chart, I...
- **would** like to see all my active orders shown on the vertical axis
- **would** like to drag orders to change their price
... so I can see my orders in context of price history
## On a depth chart
when looking at a depth chart, I...
- **would** like to see all my active orders shown on the horizontal axis
- **would** like to drag orders to change their price
... so I can see my orders in context of price history
## In order book
when looking at an order book, I...
- **would** like to see all my active orders shown next to the prices they have
... so I can see my orders in context of price history
## Pegged order shapes
When looking to understand the state of a pegged order shape...
- **should** see the whole shape of a pegged order
- **must** see the reference, offset and direction for each part pegged order (<a name="7003-MORD-016" href="#7003-MORD-016">7003-MORD-016</a>)
- **should** see the current price for each buy/sell
- **should** see the filled/remaining for each part of the order
- when order is not `Active`: **should** show the order status (perhaps instead of price)
- **should** be able to cancel the whole pegged order
- **would** like to see link to edit the shape of a pegged order
- **would** like to see the date submitted/updated
... so I can decide if I wish to amend or cancel my pegged order shape
## Cancel Pegged order shapes
`TODO`
## Liquidity order shapes
When looking to understand the state of a liquidity provision, with a provided shape...
- **would** like to see the liquidity commitment order status (`pending`, `active`, `parked`, `canceled` etc)
- **would** like to see the fee bid
- **should** see the whole shape of a liquidity order
- **must** see the reference, offset and direction for each part liquidity order order (<a name="7003-MORD-017" href="#7003-MORD-017">7003-MORD-017</a>)
- **should** see the current price for each buy/sell
- when order is not `Active`: **should** show the order status (perhaps instead of price)
- **should** see link to cancel the whole liquidity order shape (see [liquidity provision](5002-LIQP-provide_liquidity.md))
- **would** like to see link to edit the shape of a pegged order (see [liquidity provision](5002-LIQP-provide_liquidity.md))
- **would** like to see the date submitted/updated
... so I can decide if I wish to amend or cancel my shape
## Cancel or amend Pegged order shapes
See [liquidity provision](5002-LIQP-provide_liquidity.md),

39
specs/7004-POSI-positions.md Normal file
View File

@ -0,0 +1,39 @@
# View my Position(s)
- **Must** be able to view my positions from the trading and portfolio page (<a name="7004-POSI-001" href="#7004-POSI-001">7004-POSI-001</a>)
- **Must** be able to view the following columns (<a name="7004-POSI-002" href="#7004-POSI-002">7004-POSI-002</a>):
- market
- notional
- open volume
- mark price
- settlement asset
- entry price
- leverage
- margin allocated
- realised PNL
- unrealised PNL
- Updated
- **Must** be able to sort each column by asc and dsc (<a name="7004-POSI-003" href="#7004-POSI-003">7004-POSI-003</a>)
- **Must** be able to scroll horizontally to see all columns if screen resolution isn't wide enough (<a name="7004-POSI-004" href="#7004-POSI-004">7004-POSI-004</a>)
- **Must** be able to drag and drop column names to re order (<a name="7004-POSI-005" href="#7004-POSI-005">7004-POSI-005</a>)
- **Must** be able to resize the width of the columns (<a name="7004-POSI-006" href="#7004-POSI-006">7004-POSI-006</a>)
- **Must** The columns 'Open volume', 'realised PNL' and 'Unrealised PNL' must change color and have a + or - suffix depending on being positive/negative (<a name="7004-POSI-007" href="#7004-POSI-007">7004-POSI-007</a>)
- **Must** be able to select settlement asset to view asset details (<a name="7004-POSI-008" href="#7004-POSI-008">7004-POSI-008</a>)
- **Must** be able to select the 3 dots to view asset details (<a name="7004-POSI-009" href="#7004-POSI-009">7004-POSI-009</a>)
- **Must** be able to select the close button to close my position (<a name="7004-POSI-010" href="#7004-POSI-010">7004-POSI-010</a>)
- **Must** be able to see warnings for a market with a tooltip explanation (<a name="7004-POSI-011" href="#7004-POSI-011">7004-POSI-011</a>)
- **Must** retain previous column sizing on refresh (<a name="7004-POSI-012" href="#7004-POSI-012">7004-POSI-012</a>)
- **Must** notional column has a tooltip on hover (<a name="7004-POSI-013" href="#7004-POSI-013">7004-POSI-013</a>)

19
specs/7005-FILL-fills.md Normal file
View File

@ -0,0 +1,19 @@
# Fills
## Fills Data Grid
- **Must** see the [market](9001-DATA-data_display.md#market) the fill occurred in (<a name="7005-FILL-001" href="#7005-FILL-001">7005-FILL-001</a>)
- **Must** see the [size](9001-DATA-data_display.md#size) of the fill (<a name="7005-FILL-002" href="#7005-FILL-002">7005-FILL-002</a>)
- **Must** see indication if the current party was the buyer (<a name="7005-FILL-003" href="#7005-FILL-003">7005-FILL-003</a>)
- **Must** see indication if the current party was the seller (<a name="7005-FILL-004" href="#7005-FILL-004">7005-FILL-004</a>)
- **Must** see the [price](9001-DATA-data_display.md#quote-price) of the fill (<a name="7005-FILL-005" href="#7005-FILL-005">7005-FILL-005</a>)
- **Could** see the notional value of the fill (<a name="7005-FILL-006" href="#7005-FILL-006">7005-FILL-006</a>)
- **Must** see the [fee](9001-DATA-data_display.md#asset-balances) that applies for current party for the fill (<a name="7005-FILL-007" href="#7005-FILL-007">7005-FILL-007</a>)
### Continuous Trading
- **Must** see the role of the user (taker, maker or n/a) (<a name="7005-FILL-008" href="#7005-FILL-008">7005-FILL-008</a>)
### Auction
TBD. Currently any trade made during auction will result in the both parties having the role of 'taker'. This may be incorrect and is being investigated.

1
specs/7006-FEES-fees.md Normal file
View File

@ -0,0 +1 @@
# My Trading fees

1
specs/8001-BLOX-transaction_and_blocks.md Normal file
View File

@ -0,0 +1 @@
# Transaction and block content

103
specs/9001-DATA-data_display.md Normal file
View File

@ -0,0 +1,103 @@
# Data display
This is a definition of some common data types and the rules about the displaying them. These are referenced in other acceptance criteria to avoid repetition.
## Size
> aka contracts, volume, amount, quantities.
This is set per-market and represent the number of contracts that are being brought or sold.
`Market.positionDecimalPlaces` tells us where to put the decimal when displaying the number. Size can be a whole number if `Market.positionDecimalPlaces` = 0, or a [fractional order](../protocol/0052-FPOS-fractional_orders_positions.md) if > 0.
It **should** always be displayed to the full number of decimal places. however, there may be exceptions, e.g. when visualizing on a depth chart, where the precision is not required.
## Quote price
> aka. price, quote, level.
This is set per-market and represent the "price" of an asset. It can have a 1-1 relationship with the settlement asset but it is also possible that products will have different payoff methods, which is one of the reasons we don't just use settlement asset, another being in the future some markets could have multiple settlement assets, another being that we don't want 18DP quotes.
`Market.decimalPlaces` tells us where to put the decimal when displaying the number. It can be a whole number if `Market.decimalPlaces` = 0, but will not have more decimal places than the [settlement asset](#asset-balances) of a market.
`Market...quoteName` is used to tell us what to display next to the quote price. For example the `quoteName` could be `USD` but the settlement asset = `DAI`. The Market framework allows for other types of quote (e.g. %, cm and ETC). When looking at a single market it may not be necessary to show the quote name each time you show the price.
### Mark price
The term mark price is often displayed as the best possible price from which to base calculations on what the current price is of the market. It is used for margin calculations and unrealised Profit/loss estimates.
### Liquidation price
This is a value that is calculated as an indication of what price the market would be at for a position to be liquidated. To do this ti has to make a few assumptions and simulate the Vega topping up the margin balance each time the position hits the search level. More detail in the [this notebook](https://github.com/vegaprotocol/research/blob/master/notebooks/misc/Margin%20level%20price%20approximation.ipynb).
## Asset balances
> aka Collateral, account balance, Profit and loss, PnL fees, transfers, financial values.
The is set per Asset and represents the amount of an asset that is held in the bridge.
Once deposited assets appear in a `general account`. Other account types are created when opening positions, providing liquidity etc.
Vega does not return a `total balance` that is a sum of all accounts in a currency, but users will expect to see one. See the [Collateral spec](../protocol/0005-COLL-collateral.md) for other account types.
`Asset.decimals` tells the UIs where to put the decimal place. Ethereum assets often have 18 decimal places, but can have less. Forms where you deposit, withdraw or transfer assets must show all decimal places. It may be appropriate to truncate at a certain number of DP in many cases (e.g. `0.01` instead of `0.012345678912345678` event though `0.001 wBTC` may be worth as much as than `0.01 ETH`). At the moment Vega does not have a source of information that allows conversion of currencies or way of knowing that the significant value of an asset is.
## Profit and Loss
> aka PnL, P&L
The profit or loss is the difference between what a user paid for a thing and the value of it at any given moment. For future it is the difference between the price
### Unrealised Profit and Loss
### Realised Profit and Loss
## Quantum
The quantum is a value that is used to define "The minimum economically meaningful amount of this specific asset". It can be used to show only the number of decimal places that are meaningful in summary information. A quantum is defined on each asset.
## Market
Markets do not have names, technically it is the instrument within a market that has the name. Theoretically the same instrument can be traded in multiple markets. if/when this happens a user needs to be able to disambiguate between markets. Each market does have a unique ID, Note: this is a hash of the definition of the market when it was created.
Instruments have both a Name and Code, see [market framework](../protocol/0001-MKTF-market_framework.md) for how these are used. Generally the Code can save space once a user is familiar with the market. The Name is more descriptive and should be the default when discovering markets. It remains to be seen how the community will use these exactly.
Markets can have several statuses and it may be sensible when listing markets to highlight their status. e.g. if a market is usually in continuous trading mode, but is currently in an auction due to low liquidity. The market name field could be augmented to show the status (add an icon etc).
## Public keys
> aka Party
When looking at a public key it is important that the user can get the full public key but it is often appropriate just to show an abbreviated form. The first 6 and last 6 characters are preferable, with an indication that it is truncated e.g. `56d1e6739deac3c5c1ddc6fee876b3217e504a161b5b00fda96b40ed3e8f89b8` as `56d1e6...8f89b8` or just `8f89b8` if enough of a convention has been established. In cases where the key being shows comes from your connected wallet it should also show the name (aka alias) of the key.
Vega public keys are hexadecimal, but the convention is to display them without the preceding `0x` as this is what the Vega API returns.
## Party accounts
> aka account balances
A can have a number of different accounts for any given asset.
- General account - For assets that have not been deployed to one of the following
- Margin accounts - one for each market the part has orders/position
- Bond accounts - (aka liquidity commitment) one for each market the user has committed to providing liquidity on
- Locked for withdraw - one for each withdraw that is waiting to be finalised (e.g. where withdrawal limits/time locks are in place)
In the case of the Governance token the party may also have staked balances
When listing markets in a breakdown it may good to see a total exposure to a market, that is then broken down by Margin and Bond
All party accounts should be displayed as an [asset balance](#asset-balances) with the appropriate number of decimal places.
## Transaction hash
> aka Transaction ID, txn, tx
The transaction [hash](https://www.investopedia.com/terms/h/hash.asp) acts as an identifier for a transaction network. It is hexadecimal and should be displayed with the preceding `0x`.
## Asset
> aka Collateral
### Asset name
e.g. United states Dollar. Each asset has a name this should be shown (as well as symbol) in places where the user may need to distinguish one asset from another or if the symbol is ambiguous. Vega assets names aught to match their name on their native chain.
### Asset symbol
e.g USD. Symbols are short codes for an asset to be used in places low on space where the user is likely to be familiar with the asset. Often all caps but not always, so it is important to display upper and lower case. Vega assets codes aught to match their name on their native chain.

95
specs/README.md Normal file
View File

@ -0,0 +1,95 @@
# User interface acceptance criteria
This folder contains descriptions of things that users do when interacting with Vega. The information they need and why they are doing them. These can be referenced in testing and used as input for building new interfaces.
The acceptance criteria are organized into files, with each file representing a high level user task. These have been listed with the most "upstream" being first, and grouped into similar tasks.
Each file contains blocks that relate to a low level user task. The block states what the user is trying to do or the context they are in, has a bullet for each thing they need, then states why they are doing it...
> When doing a thing, I...
>
> - **must** be able to see some particular number [0000-CODE-000] ...so I can decide if I want to continue.
Each bullet is worded so that it contains a **must**, **should**, **could**, or **would like to**. This gives app developers some indication of the priority of user needs. At the end of each bullet is a code that can be referenced in tests etc.
These acceptance criteria are not final or intended to be "the truth" but a useful tool, they will be improved over time as more people feedback on using Vega.
A user is normally interacting with at least 2 applications when doing tasks on Vega, A **Dapp** or interface designed to help users complete specific tasks and a **Wallet** that is only used to authenticate a user's actions and broadcast them to the network.
## `0000` Wallets, signing transactions and network selection
- `0001-WALL` [Get and use a Vega wallet](0001-WALL-wallet.md) (This mostly relates to use of a wallet app, for cryptography and broadcast to network)
These files contain generic user needs for interacting with wallets that are true for all types of interactions that require a wallet. More specific requirements are mentioned where these are referenced. They describe what the user needs from the dapp not the wallet.
- `0002-WCON` [Connect Vega wallet to a Dapp & select keys](0002-WCON-connect_vega_wallet.md)
- `0003-WTXN` [Submit Vega transaction](0003-WTXN-submit_vega_transaction.md)
- `0004-EWAL` [Connect Ethereum wallet to a Dapp](0004-EWAL-connect_ethereum_wallet.md)
- `0005-ETXN` [Submit Ethereum transaction](0005-ETXN-submit_ethereum_transaction.md)
- `0006-NETW` [Network and node selection](0006-NETW-network-and-nodes.md)
## `1000` Bridges, Transfers and Vesting
- `1001-DEPO` [Deposit](1001-DEPO-desposit.md)
- `1002-WITH` [Withdraw](1002-WITH-withdraw.md)
- `1003-TRAN` [Transfer](1003-TRAN-transfer.md)
- `1004-ASSO` [Associate governance token with a Vega key](1004-ASSO-associate.md)
- `1005-VEST` [View and redeem vested tokens](1005-VEST-vesting.md)
## `1101` Browser Wallet
The specs no longer exist in this repo and can be found [here](https://github.com/vegaprotocol/vegawallet-browser/tree/main/specs)
## `2000` Staking
- `2001-STKE` [Staking validators](2001-STKE-staking.md)
- `2002-SINC` [Review staking income](2002-SINC-staking-income.md)
## `3000` Governance
- `3001-VOTE` [See proposals and Vote on changes](3001-VOTE-vote.md)
- `3002-PROP` [Select proposal type](3002-PROP-propose.md)
- `3003-PMAN` [Propose new Market](3003-PMAN-propose_new_market.md)
- `3004-PMAC` [Propose change(s) to market](3004-PMAC-propose_market_change.md)
- `3005-PASN` [Propose new asset](3005-PASN-propose_new_asset.md)
- `3006-PASC` [Propose change(s) to asset](3006-PASC-propose_asset_change.md)
- `3007-PNEC` [Propose change to network parameter(s)](3007-PNEC-propose_network.md)
- `3008-PFRO` [Propose something "Freeform"](3008-PFRO-propose_freeform.md)
## `4000` Treasury
- `4001-TRES` [View treasury rewards](4001-TRES-view_treasury_rewards.md) `TODO`
## `5000` Liquidity provision
- `5001-LIQF` [Find and understand liquidity provision opportunities](5001-LIQF-liquidity_opportunities.md) `TODO`
- `5002-LIQP` [Provide liquidity](5002-LIQP-provide_liquidity.md) `TODO`
- `5003-LIQI` [View liquidity provision rewards](5003-LIQI-liquidity_income.md) `TODO`
## `6000` Markets and analysis
- `6001-MARK` [Find markets](6001-MARK-find_markets.md)
- `6002-MARD` [View market specification](6002-MDET-market-details.md) `TODO`
- `6003-ORDB` [Analyze Order book](6003-ORDB-order_book.md) `TODO`
- `6004-PHIS` [Analyze price history](6004-PHIS-price_history.md) `TODO`
- `6005-THIS` [Analyze trade history](6005-THIS-trade_history.md) `TODO`
- `6006-DEPC` [View depth chart](6006-DEPC-chart.md)
- `6007-CHAR` [View chart](6007-CHAR-chart.md)
## `7000` Collateral, Orders, Positions and Fills
- `7001-COLL` [View my collateral / accounts](7001-COLL-collateral.md)
- `7002-SORD` [Submit an order](7002-SORD-submit_orders.md)
- `7003-MORD` [Manage my orders](7003-MORD-manage_orders.md)
- `7004-POSI` [View my positions](7004-POSI-positions.md) `TODO`
- `7005-FILL` [View my trades/fills](7005-FILL-fills.md)
- `7006-FEES` [View my trading fees](7006-FEES-fees.md) `TODO`
## `8000` Understand transactions and blocks
- `8001-BLOX` [Transaction and block content](8001-BLOX-transaction_and_blocks.md) `TODO`
-
## Appendixes
- [Display display rules](9001-DATA-data_display.md)

60
specs/apps.json Normal file
View File

@ -0,0 +1,60 @@
{
"Desktop-Wallet": {
"specs": ["0001-WALL"]
},
"Token": {
"specs": [
"9001-DATA",
"1002-WITH",
"1004-ASSO",
"1005-VEST",
"2001-STKE",
"2002-SINC",
"7001-COLL",
"3001-VOTE",
"3002-PROP",
"3003-PMAN",
"3004-PMAC",
"3005-PASN",
"3006-PASC",
"3007-PNEC",
"3008-PFRO",
"0002-WCON",
"0003-WTXN",
"0004-EWAL",
"0005-ETXN",
"0006-NETW"
]
},
"Console": {
"specs": [
"1001-DEPO",
"1002-WITH",
"1003-TRAN",
"6000-COLL",
"6001-MARK",
"6002-MDET",
"6003-ORDB",
"6005-THIS",
"6006-DEPC",
"6501-ASSE",
"7001-COLL",
"7002-SORD",
"7003-MORD",
"7004-POSI",
"7005-FILL",
"0002-WCON",
"0003-WTXN",
"0004-EWAL",
"5002-LIQP",
"0006-NETW",
"6007-CHAR"
]
},
"Block-explorer": {
"specs": ["8001-BLOX"]
},
"Vega.xyz": {
"specs": ["0001-WALL", "4001-TRES", "5001-LIQF"]
}
}

63
specs/categories.json Normal file
View File

@ -0,0 +1,63 @@
{
"Wallets & Signing Transactions & Network Selection": {
"specs": [
"0001-WALL",
"0002-WCON",
"0003-WTXN",
"0004-EWAL",
"0005-ETXN",
"0006-NETW"
]
},
"Bridges & Transfers & Vesting": {
"specs": ["1001-DEPO", "1002-WITH", "1003-TRAN", "1004-ASSO", "1005-VEST"]
},
"Staking": {
"specs": ["2001-STKE", "2002-SINC"]
},
"Governance": {
"specs": [
"3001-VOTE",
"3002-PROP",
"3003-PMAN",
"3004-PMAC",
"3005-PASN",
"3006-PASC",
"3007-PNEC",
"3008-PFRO"
]
},
"Treasury": {
"specs": ["4001-TRES"]
},
"Liquidity Provision": {
"specs": ["5001-LIQF", "5002-LIQP", "5003-LIQI"]
},
"Markets & Analysis": {
"specs": [
"6001-MARK",
"6002-MDET",
"6003-ORDB",
"6004-PHIS",
"6005-THIS",
"6006-DEPC",
"6007-CHAR"
]
},
"Collateral & Orders & Positions & Fills": {
"specs": [
"7001-COLL",
"7002-SORD",
"7003-MORD",
"7004-POSI",
"7005-FILL",
"7006-FEES"
]
},
"Block Exploring": {
"specs": ["8001-BLOX"]
},
"Data Display": {
"specs": ["9001-DATA"]
}
}

38
specs/increment.py Normal file
View File

@ -0,0 +1,38 @@
import re
def increment_spec_numbers(filepath, number):
with open(filepath, 'r+') as file:
content = file.read()
lines = content.splitlines()
# Find the line containing the given number
for i, line in enumerate(lines):
match = re.search(rf'(\bBWAL-){number}\b', line)
if match:
start_index = match.start()
break
else:
print(f"Number {number} not found in the file.")
return
# Increment the numbers from the given number onwards
for i in range(i, len(lines)):
line = lines[i]
matches = re.findall(r'(\bBWAL-)(\d{3})\b', line)
for prefix, next_number in matches:
if next_number >= number:
incremented_number = str(int(next_number) + 1).zfill(3)
line = line.replace(f'{prefix}{next_number}', f'{prefix}{incremented_number}')
lines[i] = line
file.seek(0)
file.write('\n'.join(lines))
file.truncate()
print(f"Numbers starting from {number} have been incremented.")
# Example usage
filepath = './user-interface/1101-BWAL-browser_wallet.md'
number = '060'
increment_spec_numbers(filepath, number)