Skip to content

Commit

Permalink
Merge pull request #11707 from vegaprotocol/integration-docs
Browse files Browse the repository at this point in the history 
Integration docs
  • Loading branch information
@jeremyletang
jeremyletang authored Oct 2, 2024
2 parents d365b99 + cb2a62a commit a623d5a
Show file tree
Hide file tree
Showing 15 changed files with 1,790 additions and 64 deletions.
45 changes: 16 additions & 29 deletions core/integration/docs/AMM.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,56 +26,41 @@ Lastly, cancelling an existing AMM can be done through:

```
And the parties cancel the following AMM:
| party | market id | method | error |
| party id | market ID | cancellation method | OPTIONAL: error expected |
| party | market id | method | error |
| party id | market ID | CancelAMM_Method | OPTIONAL: error expected |
```

The possible values for `method` are `METHOD_IMMEDIATE` or `METHOD_REDUCE_ONLY`. Technically `METHOD_UNSPECIFIED` is also a valid value for `method`, but doesn't apply for integration tests.
Details on the [`CancelAMM_Method` type](types.md#Cancel-AMM-Method)

### Checking AMM pools

To see what's going on with an existing AMM, we can check the AMM pool events with the following steps:

```
Then the AMM pool status should be:
| party | market id | amount | status | reason | base | lower bound | upper bound | lower leverage | upper leverage |
| party ID | market ID | commitment amout | AMM pool status | OPTIONAL: AMM status reason | uint | uint | uint | float | float |
| party | market id | amount | status | reason | base | lower bound | upper bound | lower leverage | upper leverage |
| party ID | market ID | commitment amout | AMM_Status | AMM_StatusReason | uint | uint | uint | float | float |
```

Required fields are `party`, `market id`, `amount`, and `status`. All others are optional. possible values for AMM pool status are:
Required fields are `party`, `market id`, `amount`, and `status`. All others are optional.

```
STATUS_UNSPECIFIED (not applicable)
STATUS_ACTIVE
STATUS_REJECTED
STATUS_CANCELLED
STATUS_STOPPED
STATUS_REDUCE_ONLY
```

The possible `AMM status reason` values are:

```
STATUS_REASON_UNSPECIFIED
STATUS_REASON_CANCELLED_BY_PARTY
STATUS_REASON_CANNOT_FILL_COMMITMENT
STATUS_REASON_PARTY_ALREADY_OWNS_A_POOL
STATUS_REASON_PARTY_CLOSED_OUT
STATUS_REASON_MARKET_CLOSED
STATUS_REASON_COMMITMENT_TOO_LOW
STATUS_REASON_CANNOT_REBASE
```
Details on the [`AMM_Status` type](types.md#AMM-Status)
Details on the [`AMM_StatusReason` type](types.md#AMM-Status-Reason)

Checking the status for a given AMM only checks the most recent AMMPool event that was emitted. If we need to check all statuses a given AMM passed through during a scenario, use the following step:

```
And the following AMM pool events should be emitted:
| party | market id | amount | status | reason | base | lower bound | upper bound | lower leverage | upper leverage |
| party ID | market ID | commitment amout | AMM pool status | OPTIONAL: AMM status reason | uint | uint | uint | float | float |
| party | market id | amount | status | reason | base | lower bound | upper bound | lower leverage | upper leverage |
| party ID | market ID | commitment amout | AMM_Status | AMM_StatusReason | uint | uint | uint | float | float |
```

The table data is identical to that used in the previous step, with the same optional/required fields. The difference here is that we can check whether the correct events were emitted in a scenario like this:

Details on the [`AMM_Status` type](types.md#AMM-Status)
Details on the [`AMM_StatusReason` type](types.md#AMM-Status-Reason)


```
When
When the parties submit the following AMM:
Expand Down Expand Up @@ -154,6 +139,8 @@ And the following transfers should happen:
| vamm1-id | ACCOUNT_TYPE_GENERAL | vamm1-id | ACCOUNT_TYPE_MARGIN | ETH/MAR22 | 274 | USD | true | TRANSFER_TYPE_MARGIN_LOW |
```

For more details on how to check transfer data [see here](transfers.md).

### Checking AMM trades

Because the parties who created the vAMM don't actually trade directly, the derived party ID will appear as the buyer or seller. The account owner alias created above should therefore be used to check the buyer/seller of trades involving the vAMM pools:
Expand Down
97 changes: 97 additions & 0 deletions core/integration/docs/delegation_validator.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
## Integration test framework for delegation and validators.

### Registering/setting up validators.

To create/register a validator, the following step should be used:

```cucumber
Given the validators:
| id | staking account balance | pub_key |
| node1 | 10000 | n1pk |
| node 2 | 20000 | n2pk |
```

Where `id` and `staking account balance` are required, the `pub_key` is optional. The types are as follows:

```
| id | string |
| staking account balance | uint |
| pub_key | string |
```

The step _must_ match the pattern `^the validators:$`.

### Verifying the delegation balances for a given epoch.

To validate what the delegation balance is given a party and epoch sequence number, use the following step:

```cucumber
Then the parties should have the following delegation balances for epoch 3:
| party | node id | amount |
| node1 | node1 | 1000 |
| party1 | node1 | 123 |
| node2 | node2 | 2000 |
| party2 | node2 | 100 |
| party2 | node1 | 100 |
```
All fields in the table are required and are of the following types:

```
| party | string |
| node id | string |
| amount | uint |
```
The step _must_ match the pattern `^the parties should have the following delegation balances for epoch (\d+):$`.

### Verifying the validator scores per epoch.

To check whether or not the validator scores are what we'd expect, use the following step:

```cucumber
Then the validators should have the following val scores for epoch 1:
| node id | validator score | normalised score |
| node1 | 0.35 | 0.45 |
| node2 | 0.65 | 0.55 |
```
All fields are required, and have the following types:

```
| node id | string |
| validator score | decimal [up to 16 decimals] |
| normalised score | decimal [up to 16 decimals] |
```
The step _must_ match the pattern `^the validators should have the following val scores for epoch (\d+):$`

### Verify the rewards received per epoch.

To validate whether the parties receive the expected rewards for a given epoch, use:

```cucumber
Then the parties receive the following reward for epoch 5:
| party | asset | amount |
| party1 | TOKEN | 12 |
| party2 | TOKEN | 20 |
| node1 | TOKEN | 100 |
| node2 | TOKEN | 200 |
```

All fields are required and of the following types:

```
| party | string |
| asset | string |
| amount | uint |
```
The step _must_ match the pattern `^the parties receive the following reward for epoch (\d+):$`

### Ensure we are in the expected epoch.

To make sure the scenario is indeed in the epoch we expect to be in:

```cucumber
When the current epoch is "2"
```

The step _must_ match the pattern `^the current epoch is "([^"]+)"$`.
**NOTE**: the matched, quoted value should be a `uint`, otherwise the scenario will trigger a panic.

177 changes: 177 additions & 0 deletions core/integration/docs/governance.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,177 @@
## Governance placeholders

The integration test framework does not bootstrap the governance engine, but rather replaces it. It submits proposals directly to the execution engine as though it were a proposal that has gone through governance. This document will cover these quasi governance steps to:

- [Update a market](#Updating-markets)
- [De-/Re-activate markets](#Governance-auctions)
- [Suspend a market](#Suspending-markets)
- [Resume a market](#Resuming-markets)
- [Terminate a market](#Terminating-markets)
- [Set or change network parameters](#Network-parameters)
- [Update assets](#Updating-assets)

### Updating markets

Markets can be updated throughout, some of the paramters that can be changed (things like price monitoring) require setting up new price monitoring paramters (or using a default). How this can be done is outlined in the documentation detailing [setting up markets](markets.md).

```cucumber
When the markets are updated:
| id | price monitoring | linear slippage factor | sla params | liquidity fee settings | risk model | liquidation strategy |
| ETH/MAR22 | new-pm | 1e-3 | new-sla | new-fee-conf | new-risk-mdl | new-liquidation-strat |
```

All fields, bar the ID are treated as optional, and are defined as follows:

```
| name | type | NOTE |
| id | string (market ID) | |
| linear slippage factor | float64 | |
| quadratic slippage factor | float64 | deprecated |
| data source config | string (oracle name) | not possible to update the product in all cases |
| price monitoring | string (price monitoring name) | |
| risk model | string (risk model name) | |
| liquidity monitoring | string (liquidity monitoring name) | deprecated |
| sla params | string (sla params name) | |
| liquidity fee settings | string (fee config name) | |
| liquidation strategy | string (liquidation strategy name) | |
| price type | Price_Type | |
| decay weight | decimal | |
| decay power | decimal | |
| cash amount | Uint | |
| source weights | Source_Weights | |
| source staleness tolerance | Staleness_Tolerance | |
| oracle1 | string (composite price oracle name) | |
| oracle2 | string (composite price oracle name) | |
| oracle3 | string (composite price oracle name) | |
| oracle4 | string (composite price oracle name) | |
| oracle5 | string (composite price oracle name) | |
| tick size | uint | |
```

Details on the [`Price_Type` type](types.md#Price-type).
Details on the [`Source_Weights` type](types.md#Source-weights)
Details on the [`Staleness_Tolerance` type](types.md#Staleness-tolerance)

Any field that is not set means that aspect of the market configuration is not to be updated.

### Governance auctions

Markets can be put into governance auctions, which can be ended through governance, too.

#### Suspending markets

To start a governance auction, the following step is used:

```cucumber
When the market states are updated through governance:
| market id | state |
| ETH/DEC20 | MARKET_STATE_UPDATE_TYPE_SUSPEND |
```

Where the relevant fields are:

```
| market id | string (market ID) | required |
| state | MarketStateUpdate | required |
| error | expected error | optional |
```

Details on the [`MarketStateUpdate` type](types.md#Market-state-update)

#### Resuming markets

To end a goverance auction, the same step is used like so:

```cucumber
When the market states are updated through governance:
| market id | state |
| ETH/DEC20 | MARKET_STATE_UPDATE_TYPE_RESUME |
```

Where the relevant fields are:

```
| market id | string (market ID) | required |
| state | MarketStateUpdate | required |
| error | expected error | optional |
```

Details on the [`MarketStateUpdate` type](types.md#Market-state-update)

### Terminating markets

A market can be terminated through governace, too. This can be done with or without a settlement price:

```cucumber
When the market states are updated through governance:
| market id | state | settlement price |
| ETH/DEC19 | MARKET_STATE_UPDATE_TYPE_TERMINATE | 976 |
```

Where the relevant fields are:

```
| market id | string (market ID) | required |
| state | MarketStateUpdate | required |
| settlement price | Uint | optional |
| error | expected error | optional |
```

Details on the [`MarketStateUpdate` type](types.md#Market-state-update)

### Network parameters

Setting network parameters is typically done as part of the `Background` part of a feature file, or at the start of a scenario. However, changing some network paramters may have an effect on active markets. In that case, a transaction that failed or succeeded previously is expected to behave differently after the network parameters have been updated. This can be useful to test whether or not network paramter changes are correctly propagated. Setting or updating network paramters is done using this step:

```cucumber
Background:
# setting network parameter to an initial value
Given the following network parameters are set:
| name | value |
| limits.markets.maxPeggedOrders | 2 |
Scenario:
When the parties place the following pegged orders:
| party | market id | side | volume | pegged reference | offset | error |
| party1 | ETH/DEC24 | buy | 100 | BEST_BID | 5 | |
| party1 | ETH/DEC24 | buy | 200 | BEST_BID | 10 | |
| party1 | ETH/DEC24 | buy | 250 | BEST_BID | 15 | error: too many pegged orders |
Then the following network parameters are set:
| name | value |
| limits.markets.maxPeggedOrders | 2 |
When the parties place the following pegged orders:
| party | market id | side | volume | pegged reference | offset | error |
| party1 | ETH/DEC24 | buy | 250 | BEST_BID | 15 | |
```

_Note: the error is not necessarily the correct value._


The fields are both required and defined as follows:

```
| name | string (the network paramter key name) |
| value | string (must be compatible with the parameter type) |
```

### Updating assets

Similarly to registering assets, it is possible to re-define an existing asset, though this is a rather niche thing to do, using this step:

```cucumber
When the following assets are updated:
| id | decimal places | quantum |
| BTC | 5 | 20 |
```

Where the fields are defined as follows:

```
| id | string | required |
| decimal places | uint64 | required |
| quantum | decimal | optional |
```

Should this cause an error, the test will fail.
Loading

0 comments on commit a623d5a

Please sign in to comment.