code.vegaprotocol.io/vega@v0.79.0/core/integration/docs/markets.md (about) 1 ## Integration test framework setting up markets. 2 3 Markets are the cornerstone of integration tests, and are rather complex entities to set up. As such, there are a number of parameters that in turn need to be configured through distinct steps. 4 These sub-components are: 5 6 * [Risk model](#Risk-models) 7 * [Fee configuration](#Fees-configuration) 8 * [Oracles for settlement](#Settlement-data) 9 * [Settlement data oracles with specific decimal places.](#Oracle-decimal-places) 10 * [Oracles for termination.](#Trading-termination-oracle) 11 * [Oracles for perpetual markets](#Perpetual-oracles) 12 * [Oracles for composite price.](#Composite-price-oracles) 13 * [Price monitoring parameters](#Price-monitoring) 14 * [Liquidity SLA parameters](#Liquidity-SLA-parameters) 15 * [Liquidity monitoring parameters](#Liquidity-monitoring-parameters) [No longer used - DEPRECATED] 16 * [Margin calculators.](#Margin-calculator) 17 * [Liquidation strategies.](#Liquidation-strategies) 18 19 Arguably not a sub-component, but something that needs to be mentioned in this context: 20 21 * [Asset configuration](#Assets) 22 23 Before covering the actual configuration of a market, this document will first outline how these parameters can be configured. It's important to note that defaults are available for the following: 24 25 * [Fee configuration](#Fees-configuration) 26 * [Liquidation strats](#Liquidation-strategies) 27 * Liquidity monitoring [DEPRECATED] 28 * [Margin calculators](#Margin-calculator) 29 * [Oracles](#Data-source-configuration) (settlement data, perpetual markets, and market termination). 30 * [Price monintoring](#Price-monitoring) 31 * [Risk models](#Risk-models) 32 * [Liquidity SLA parameters](#Liquidity-SLA-parameters) 33 34 The available defaults will be mentioned under their respective sections, along with details on where the provided defaults can be found. 35 36 Once a market has been set up, the current market state should also be checked. This can be done through: 37 38 * [Market data](#Market-data) 39 * [Market state](#Market-state) 40 * [Last market state](#Last-market-state) may sometimes be needed to check markets that have reached a final state. 41 * [Mark price](#Mark-price) 42 43 The market lifecycle is largely determined through oracles. How to use oracles in integration tests is [covered here](oracles.md). Markets can, however be updated or closed through governance. The integration test framework essentially takes the chain and the governance engine out of the equation, but to test market changes through governance, some steps have been provided. These steps are [covered here](governance.md). 44 45 ### Risk models 46 47 There are a number of pre-defined risk models, but if a custom risk model is required, there are steps provided to create one. 48 49 #### Pre-configured risk models 50 51 The pre-configured risk models can be found under `core/integration/steps/market/defaults/risk-model`. The models themselves are split into _simple_ and _log-normal_ models. 52 The simple risk models only exist to simplify testing, in practice real markets will only use the _log-normal_ risk models. 53 Risk models (both pre-configured or manually registered) can then be used in a market definition by name. Manually registered risk models are scoped to the feature file (if defined in the `Background` section), or the `Scenario` if defined there. 54 55 The _log-normal_ risk models currently defined are: 56 57 * closeout-st-risk-model 58 * default-log-normal-risk-model 59 * default-st-risk-model 60 61 The _simple_ risk models proveded are: 62 63 * system-test-risk-model 64 * default-simple-risk-model 65 * default-simple-risk-model-2 66 * default-simple-risk-model-3 67 * default-simple-risk-model-4 68 69 #### Creating a risk model. 70 71 If the pre-configured risk models are not sufficient, or you're testing the impact of changes to a risk model, one or more risk models can be configured using one of the following step: 72 73 ```cucumber 74 Given the simple risk model named "my-custom-model": 75 | long | short | max move up | min move down | probability of trading | 76 | 0.2 | 0.1 | 100 | -100 | 0.1 | 77 ``` 78 79 Where the fields are all required and have the following types: 80 81 ``` 82 | long | decimal | 83 | short | decimal | 84 | max move up | uint | 85 | min move down | int (must be < 0) | 86 | probability of trading | decimal | 87 ``` 88 89 This will register a new simple risk model alongside the pre-existing ones with the name `my-custom-model`. To add a _log-normal_ risk model, the following step should be used: 90 91 ```cucumber 92 And the log normal risk model named "custom-logn-model": 93 | risk aversion | tau | mu | r | sigma | 94 | 0.0002 | 0.01 | 0 | 0.0 | 1.2 | 95 ``` 96 97 Where the fields are all required and have the following types: 98 99 ``` 100 | risk aversion | decimal | 101 | tau | decimal | 102 | mu | decimal | 103 | r | decimal | 104 | sigma | decimal | 105 ``` 106 107 ### Fees configuration 108 109 Analogous to risk models, fees configuration are pre-defined, but can be configured for specific tests if needed. 110 111 #### Pre-configured fees configuration 112 113 he pre-defined fees configurations can be found in `core/integration/steps/market/defaults/fees-config/`. 114 Pre-defined fees configurations available are: 115 116 * default-none 117 118 #### Creating custom fees configuration 119 120 To create a fees configuration specific to the feature or scenario, use the following step: 121 122 ```cucumber 123 Given the fees configuration named "custom-fee-config": 124 | maker fee | infrastructure fee | liquidity fee method | liquidity fee constant | buy back fee | treasury fee | 125 | 0.0004 | 0.001 | METHOD_CONSTANT | 0 | 0.0001 | 0.00002 | 126 ``` 127 128 Where the fields are defined as: 129 130 ``` 131 | maker fee | required | decimal/string | 132 | infrastructure fee | required | decimal/string | 133 | buy back fee | optional | decimal/string (default "0") | 134 | treasury fee | optional | decimal/string (default "0") | 135 | liquidity fee constant | optional | decimal/string | 136 | liquidity fee method | optional | LiquidityFeeMethod (default METHOD_UNSPECIFIED) | 137 ``` 138 139 Details on the [`LiquidityFeeMethod` type](types.md#LiquidityFeeMethod). 140 141 ### Price monitoring 142 143 Again, like risk models and fees config, some price monitoring settings are pre-defined, but custom configuration can be used. 144 145 #### Pre-configured price monitoring 146 147 The pre-configured price monitoring parameters can be found in `core/integration/steps/market/defaults/price-monitoring` 148 Available price monitoring settings are: 149 150 * default-none 151 * default-basic 152 153 #### Creating custom price monitoring 154 155 To create custom price monitoring config, use the following step: 156 157 ```cucumber 158 Given the price monitoring named "custom-price-monitoring": 159 | horizon | probability | auction extension | 160 | 3600 | 0.99 | 3 | 161 | 7200 | 0.95 | 30 | 162 ``` 163 164 Where fields are required, and the types are: 165 166 ``` 167 | horizon | integer (timestamp) | 168 | probability | decimal | 169 | auction extension | integer (seconds) | 170 ``` 171 172 ### Liquidity SLA parameters 173 174 Again, pre-defined SLA parameters can be used, or custom parameters can be defined. 175 176 #### Pre-configured liquidity SLA parameters 177 178 The pre-configured liquidity SLA parameters can be found in `core/integration/steps/market/defaults/liquidity-sla-params` 179 Existing SLA parameters are: 180 181 * default-basic 182 * default-futures 183 * default-st 184 185 #### Creating custom lquidity SLA parameters 186 187 To create custom liquidity SLA parameters, use the following step: 188 189 ```cucumber 190 Given the liquidity sla params named "custom-sla-params": 191 | price range | commitment min time fraction | performance hysteresis epochs | sla competition factor | 192 | 0.5 | 0.6 | 1 | 1.0 | 193 ``` 194 195 Where the fields are all required and defined as: 196 197 ``` 198 | price range | decimal/string | 199 | commitment min time fraction | decimal/string | 200 | performance hysteresis epochs | int64 | 201 | sla competition factor | decimal | 202 ``` 203 204 ### Liquidity monitoring parameters 205 206 Liquidity auctions have been deprecated. The defaults and steps have not yet been removed as they are referenced by some tests, but shouldn't be used in new tests. 207 208 ### Margin calculator 209 210 Margin calculators are provided as pre-configured settings, but can be customised like risk, SLA, price monitoring, etc... 211 212 #### Pre-configured margin calculators 213 214 The pre-configured margin calculaters can be found in `core/integration/steps/market/defaults/margin-calculator` 215 Existing margin calculators are: 216 217 * default-capped-margin-calculator 218 * default-margin-calculator 219 * default-overkill-margin-calculator 220 221 #### Creating custom margn calculator 222 223 To create a custom margin calculator, use the following step: 224 225 ```cucumber 226 Given the margin calculator named "custom-margin-calculator": 227 | search factor | initial factor | release factor | 228 | 1.2 | 1.5 | 1.7 | 229 ``` 230 231 All fields are required, and defined as `decimal` 232 233 ### Liquidation strategies 234 235 As any market sub-configuration type, there are pre-defined liquidation strategies, and custom strategies can be created: 236 237 #### Pre-configured liquidtaion strategies 238 239 The pre-configured liquidation strategies can be found in `core/integration/steps/market/defaults/liquidation-config` 240 Existing liquidation strategies are: 241 242 * AC-013-strat 243 * default-liquidation-strat 244 * legacy-liquidation-strategy 245 * slow-liquidation-strat 246 247 #### Creating custom liquidation strategies 248 249 Several liquidation strategies can be created using the following step: 250 251 ```cucumber 252 Given the liquidation strategies: 253 | name | disposal step | disposal fraction | full disposal size | max fraction consumed | disposal slippage range | 254 | cumstom-liquidation-1 | 10 | 0.1 | 20 | 0.05 | 0.5 | 255 | cumstom-liquidation-2 | 20 | 0.2 | 50 | 0.02 | 0.4 | 256 ``` 257 258 All fields are required and defined as follows: 259 260 ``` 261 | name | string | 262 | disposal step | int64 (duration in seconds) | 263 | disposal fraction | decimal | 264 | full disposal size | uint64 | 265 | max fraction consumed | decimal | 266 | disposal slippage range | decimal | 267 ``` 268 269 ### Data source configuration 270 271 Markets rely on oracles for things like settlement price data, or trading temrination (future markets specifically). To create a market, an oracle needs to be configured. quite often a default oracle can be used, but if the test needs to control the oracle, a custom oracle _must_ be configured. 272 273 #### Pre-configured oracles 274 275 Pre-configured oracles can be found in `core/integration/steps/market/defaults/oracle-config` 276 Existing oracles are: 277 278 * default-eth-for-future 279 * default-eth-for-perps 280 * default-dai-for-future 281 * default-dai-for-perps 282 * default-usd-for-future 283 * default-usd-for-perps 284 285 #### Creating custom oracles 286 287 Creating a custom oracle requires a bit more work: 288 289 ##### Settlement data 290 291 To create an oracle for settlement data, use the following step: 292 293 ```cucumber 294 Given the oracle spec for settlement data filtering data from "0xCAFECAFE1" named "myOracle": 295 | property | type | binding | decimals | condition | value | 296 | prices.ETH.value | TYPE_INTEGER | settlement data | 0 | OPERATOR_GREATER_THAN | 0 | 297 ``` 298 299 Where the fields are defined as: 300 301 ``` 302 | property | required | string | 303 | type | required | PropertyKey_Type | 304 | binding | required | string | 305 | decimals | optional | uint64 | 306 | condition | optional | Condition_Operator | 307 | value | optional (required if condition is set) | string (must match type) | 308 ``` 309 310 Details on the [`PropertyKey_Type` type](types.md#PropertyKey_Type). 311 Details on the [`Condition_Operator` type](types.md#Condition_Operator). 312 313 ##### Trading termination oracle 314 315 The same inputs are used for trading termination bindings, but the step looks like this: 316 317 ```cucmber 318 And the oracle spec for trading termination filtering data from "0xCAFECAFE1" named "myOracle": 319 | property | type | binding | 320 | trading.terminated | TYPE_BOOLEAN | trading termination | 321 ``` 322 323 Note that the `from` and `named` section of the step matches. This is required. 324 325 ##### Oracle decimal places 326 327 Oracles feed data to the system from an external source. The asset used might have 18 decimal places (e.g. ETH), the market could be limited to 10 decimals, and the oracle in turn could supply price data with 12 decimal places. To mimic this, the number of decimal for the oracle can be set using the following step: 328 329 ```cucumber 330 And the settlement data decimals for the oracle named "myOracle" is given in "1" decimal places 331 ``` 332 333 ## Creating a basic futures market 334 335 With these components covered/set up, a basic market can now be set up using the step: 336 337 ```cucumber 338 Given the markets: 339 | id | quote name | asset | risk model | margin calculator | auction duration | fees | price monitoring | data source config | linear slippage factor | quadratic slippage factor | sla params | liquidation-strategy | 340 | ETH/MAR24 | ETH | ETH | custom-logn-model | custom-margin-calculator | 1 | custom-fee-config | custom-price-monitoring | myOracle | 1e0 | 0 | custom-sla-params | custom-liquidation-1 | 341 ``` 342 343 Note that, when using one of the pre-configured data sources that has a perps counterpart, the test is expected to pass both as a future or a perpetual market. Should this not be the case for whatever reason, the test should be tagged with the `@NoPerp` tag. 344 345 Market configuration is extensive, and can be configured with a myriad of additional (optional) settings. The full list of fields is as follows: 346 347 ``` 348 | field name | required | type | deprecated | 349 |----------------------------|----------|-----------------------------------------------|------------| 350 | id | yes | string | | 351 | quote name | yes | string | | 352 | asset | yes | string | | 353 | risk model | yes | string (risk model name) | | 354 | fees | yes | string (fees-config name) | | 355 | data source config | yes | string (oracle name) | | 356 | price monitoring | yes | string (price monitoring name) | | 357 | margin calculator | yes | string (margin calculator name) | | 358 | auction duration | yes | int64 (opening auction duration in ticks) | | 359 | linear slippage factor | yes | float64 | | 360 | quadratic slippage factor | yes | float64 | yes | 361 | sla params | yes | string (sla params name) | | 362 | decimal places | no | integer (default 0) | | 363 | position decimal places | no | integer (default 0) | | 364 | liquidity monitoring | no | string (name of liquidity monitoring) | yes | 365 | parent market id | no | string (ID of other market) | | 366 | insurance pool fraction | no | decimal (default 0) | | 367 | successor auction | no | int64 (duration in seconds) | | 368 | is passed | no | boolean | not used | 369 | market type | no | string (perp for perpetual market) | | 370 | liquidation strategy | no | string (liquidation strategy name) | | 371 | price type | no | Price_Type | | 372 | decay weight | no | decimal (default 0) | | 373 | decay power | no | decimal (default 0) | | 374 | cash amount | no | uint (default 0) | | 375 | source weights | no | Source_Weights (default 0,0,0,0) | | 376 | source staleness tolerance | no | Staleness_Tolerance (default 1us,1us,1us,1us) | | 377 | oracle1 | no | string (composite price oracle name) | | 378 | oracle2 | no | string (composite price oracle name) | | 379 | oracle3 | no | string (composite price oracle name) | | 380 | oracle4 | no | string (composite price oracle name) | | 381 | oracle5 | no | string (composite price oracle name) | | 382 | tick size | no | uint (default 1) | | 383 | max price cap | no | uint | | 384 | binary | no | boolean (if true, max price cap is required) | | 385 | fully collateralised | no | boolean (if true, max price cap is required) | | 386 |----------------------------|----------|-----------------------------------------------|------------| 387 ``` 388 389 Details on the [`Price_Type` type](types.md#Price-type). 390 Details on the [`Source_Weights` type](types.md#Source-weights) 391 Details on the [`Staleness_Tolerance` type](types.md#Staleness-tolerance) 392 393 ## Optional market config components 394 395 As seen in the table above, there are certain optional parameters that haven't been covered yet. Most notably composite price oracles, oracles for perpetual markets, and assets. 396 397 ### Composite price oracles 398 399 There are no default composite price oracles provided, the only way to create one is to define one or more oracles using the following step: 400 401 ```cucumber 402 Given the composite price oracles from "0xCAFECAFE1": 403 | name | price property | price type | price decimals | 404 | composite-1 | price.USD.value | TYPE_INTEGER | 0 | 405 | composite-2 | price.USD.value.2 | TYPE_INTEGER | 0 | 406 ``` 407 408 Where the fields are defined as follows: 409 410 ``` 411 | name | required | string | 412 | price property | required | string | 413 | type | required | PropertyKey_Type | 414 | price decimals | optional | int | 415 ``` 416 417 Details on [`PropertyKey_Type` type](types.md#PropertyKey_Type). 418 419 ### Perpetual oracles 420 421 The pre-existing oracles have been covered as part of the data source config section. To create a custom perpetual oracle, a custom oracle can be created using the following step: 422 423 ```cucumber 424 Given the perpetual oracles from "0xCAFECAFE1": 425 | name | asset | settlement property | settlement type | schedule property | schedule type | margin funding factor | interest rate | clamp lower bound | clamp upper bound | quote name | settlement decimals | source weights | source staleness tolerance | price type | 426 | perp-oracle | ETH | perp.ETH.value | TYPE_INTEGER | perp.funding.cue | TYPE_TIMESTAMP | 0 | 0 | 0 | 0 | ETH | 18 | 1,0,0,0 | 100s,0s,0s,0s | weight | 427 ``` 428 429 Where the fields are defined as follows: 430 431 ``` 432 | field | required | type | 433 |-----------------------------|----------|-------------------------------------------------------| 434 | name | yes | string | 435 | asset | yes | string (asset ID) | 436 | settlement property | yes | string | 437 | settlement type | yes | PropertyKey_Type | 438 | schedule property | yes | string | 439 | schedule type | yes | PropertyKey_Type | 440 | settlement decimals | no | uint64 | 441 | margin fundgin factor | no | decimal (default 0) | 442 | interest rate | no | decimal (default 0) | 443 | clamp lower bound | no | decimal (default 0) | 444 | clamp upper bound | no | decimal (default 0) | 445 | quote name | no | string (asset ID) | 446 | funding rate scaling factor | no | decimal | 447 | funding rate lower bound | no | decimal | 448 | funding rate upper bound | no | decimal | 449 | decay weight | no | decimal (default 0) | 450 | decay power | no | decimal (default 0) | 451 | cash amount | no | decimal | 452 | source weights | no | Source_Weights | 453 | source staleness tolerance | no | Staleness_Tolerance (default 1000s,1000s,1000s,1000s) | 454 | price type | no | Price_Type | 455 ``` 456 457 Details on the [`Price_Type` type](types.md#Price-type). 458 Details on the [`Source_Weights` type](types.md#Source-weights) 459 Details on the [`Staleness_Tolerance` type](types.md#Staleness-tolerance) 460 461 ### Assets 462 463 It is not required to define an asset prior to using it in a market. If you create a market with an non-existing asset, the asset will be created ad-hoc, with the same number of decimal places as the market. As mentioned earlier, though, actual markets may have less decimal places than the asset they use. To make it possible to test whether or not the system handles these scenario's as expected, it's possible to configure an asset with a specific number of decimal places using the following step: 464 465 ```cucumber 466 Given the following assets are registered: 467 | id | decimal places | quantum | 468 | ETH | 18 | 10 | 469 | DAI | 18 | 1 | 470 | USDT | 10 | 2.3 | 471 ``` 472 473 Where the fields are defined as follows: 474 475 ``` 476 | id | string | required | 477 | decimal places | uint64 | required | 478 | quantum | decimal | optional | 479 ``` 480 481 ## Checking the market state 482 483 ### Market data 484 485 The most comprehensive way to check the market state is by checking the last `MarketData` event. This is done using the following step 486 487 ```cucumber 488 Then the market data for the market "ETH/MAR24" should be: 489 | mark price | trading mode | horizon | min bound | max bound | target stake | supplied stake | open interest | 490 | 1000 | TRADING_MODE_CONTINUOUS | 3600 | 973 | 1027 | 3556 | 100000 | 1 | 491 ``` 492 493 All fields are treated as optional, and are defined as follows: 494 495 ``` 496 | market | string | 497 | best bid price | Uint | 498 | best bid volume | uint64 | 499 | best offer price | Uint | 500 | best offer volume | uint64 | 501 | best static bid price | Uint | 502 | best static bid volume | uint64 | 503 | best static offer price | Uint | 504 | best static offer volume | uint64 | 505 | mid price | Uint | 506 | static mid price | Uint | 507 | mark price | Uint | 508 | last traded price | Uint | 509 | timestamp | int64 (timestamp) | 510 | open interest | uint64 | 511 | indicative price | Uint | 512 | indicative volume | uint64 | 513 | auction start | int64 (timestamp) | 514 | auction end | int64 (timestamp) | 515 | trading mode | Market_TradingMode | 516 | auction trigger | AuctionTrigger | 517 | extension trigger | AuctionTrigger | 518 | target stake | Uint | 519 | supplied stake | Uint | 520 | horizon | int64 (duration in seconds) | 521 | ref price | Uint (reference price) | 522 | min bound | Uint | 523 | max bound | Uint | 524 | market value proxy | Uint | 525 | average entry valuation | Uint | 526 | party | string | 527 | equity share | decimal | 528 ``` 529 530 Details on the [`Market_TradingMode` type](types.md#Trading-mode) 531 Details on the [`AuctionTrigger` type](types.md#Auction-trigger) 532 533 ### Market state 534 535 To check what the current `Market_state` of a given market is, the following step should be used: 536 537 ```cucumber 538 Then the market state should be "STATE_ACTIVE" for the market "ETH/DEC22" 539 ``` 540 541 Details on the [`Market_State` type](types.md#Market-state) 542 543 ### Last market state 544 545 Similarly to checking the market state for an active market, should a market have settled or succeeded, we can check the last market state event pertaining to that market using: 546 547 ```cucumber 548 Then the last market state should be "STATE_CANCELLED" for the market "ETH/JAN23" 549 ``` 550 551 Details on the [`Market_State` type](types.md#Market-state) 552 553 ### Mark price 554 555 To quickly check what the current mark price is: 556 557 ```cucumber 558 Then the mark price should be "1000" for the market "ETH/FEB23" 559 ```