From bf1b02a59460304c049bb27af6db28e77a585049 Mon Sep 17 00:00:00 2001 From: Witold Date: Mon, 16 Sep 2024 12:11:02 +0200 Subject: [PATCH 1/3] refactor: add flag to determine behaviour on failure of a nested instruction --- protocol/0074-BTCH-batch-market-instructions.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/protocol/0074-BTCH-batch-market-instructions.md b/protocol/0074-BTCH-batch-market-instructions.md index a0c74eb03..a4594841b 100644 --- a/protocol/0074-BTCH-batch-market-instructions.md +++ b/protocol/0074-BTCH-batch-market-instructions.md @@ -26,6 +26,7 @@ Overall, building the ability to handle batches of market instructions in a sing - **Amendments**: this is a list (repeated field) of Amend Order instructions - **Submissions**: this is a list (repeated field) of Submit Order instructions - Additionally the batch may contain a single transaction to change the current margin mode. If this transaction fails, all later transactions within the batch (cancellations/amendments/submissions) for the market referred to in the update are Stopped for reason MARGIN_MODE_UPDATE_FAILED. +- Additionally the batch may contain a an optional `ON ERROR` parameter which determines the behaviour in case any instruction in the batch fails. The supported values should be either: `CONTINUE` or `STOP`. When `CONTINUE` is selected and an instruction within the batch fails the execution should move to the next instruction. When `STOP` is selected and an instruction within the batch fails the execution should stop an no other instructions should not be enacted. Default value should be `CONTINUE`. - The total number of instructions across all three lists (i.e. sum of the lengths of the lists) must be less than or equal to the current value of the network parameter `network.spam_protection.max.batch.size`. The margin mode update transaction is not included in this limit. ### Processing a batch @@ -33,7 +34,8 @@ Overall, building the ability to handle batches of market instructions in a sing - A batch is considered a single transaction, with a single transaction ID and a single timestamp applying to all instructions within it. Each instruction should be given a sub-identifier and index allowing it to be placed sequentially in the transaction (e.g. by consumers of the event stream). These identifiers must be sufficient for a user to determine which instruction within a batch any result (order updates, trades, errors, etc.) relates to. - The batches must be processed in the order **all cancellations, then all amendments, any margin mode update, then all submissions**. This is to prevent gaming the system, and to prevent any order being modified by more than one action in the batch. Updating the margin mode after cancellations and amendments allows the party to have control of which orders are outstanding when the margin mode changes. - When processing each list, the instructions within the list must be processed in the order they appear in the list (i.e. in the order prescribed by the submitter). (Notwithstanding that each list is processed in its entirety before moving onto the next list, in the order specified above). -- All instructions within each list must be validated as normal **at the time that the instruction is processed**. That is, instructions cannot be pre-validated as a batch. If a prior instruction, would create a state that would cause a later instruction to fail validation, the later instruction must fail validation (and vice verse). If validation fails, that instruction must be skipped and the subsequent instructions must still be processed. Any validation or other errors should be returned, as well as a reference to the instruction to which they relate, in the response. +- All instructions within each list must be validated as normal **at the time that the instruction is enacted**. That is, instructions cannot be pre-validated as a batch. If a prior instruction, would create a state that would cause a later instruction to fail validation, the later instruction must fail validation (and vice verse). +- If validation fails, the execution of other instructions depends on the value specified for the `ON ERROR` parameter. Any validation or other errors should be returned, as well as a reference to the instruction to which they relate, in the response. - Any errors encountered in processing an instruction after it passes validation must cause it to be skipped, and the errors, as well as the instruction to which they relate, must be available in the result of the transaction. - In addition to the usual validation and other errors that can occur in processing an instruction, the following also apply: - Any second or subsequent Amend Order instruction for the same order ID within a single Batch Instruction transaction is an error From 3c0b93450fbfd9d401fe2617f3e4edc3c88ec00b Mon Sep 17 00:00:00 2001 From: Witold Date: Wed, 18 Sep 2024 11:57:51 +0200 Subject: [PATCH 2/3] refactor: add ACs --- protocol/0074-BTCH-batch-market-instructions.md | 9 ++++++--- protocol/features.json | 5 ++++- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/protocol/0074-BTCH-batch-market-instructions.md b/protocol/0074-BTCH-batch-market-instructions.md index a4594841b..e2f3c82db 100644 --- a/protocol/0074-BTCH-batch-market-instructions.md +++ b/protocol/0074-BTCH-batch-market-instructions.md @@ -26,7 +26,7 @@ Overall, building the ability to handle batches of market instructions in a sing - **Amendments**: this is a list (repeated field) of Amend Order instructions - **Submissions**: this is a list (repeated field) of Submit Order instructions - Additionally the batch may contain a single transaction to change the current margin mode. If this transaction fails, all later transactions within the batch (cancellations/amendments/submissions) for the market referred to in the update are Stopped for reason MARGIN_MODE_UPDATE_FAILED. -- Additionally the batch may contain a an optional `ON ERROR` parameter which determines the behaviour in case any instruction in the batch fails. The supported values should be either: `CONTINUE` or `STOP`. When `CONTINUE` is selected and an instruction within the batch fails the execution should move to the next instruction. When `STOP` is selected and an instruction within the batch fails the execution should stop an no other instructions should not be enacted. Default value should be `CONTINUE`. +- Additionally the batch may contain a an optional `ON_ERROR` parameter which determines the behaviour in case any instruction in the batch fails. The supported values should be either: `CONTINUE` or `STOP`. When `CONTINUE` is selected and an instruction within the batch fails the execution should move to the next instruction. When `STOP` is selected and an instruction within the batch fails the execution should stop an no other instructions should not be enacted. Default value should be `CONTINUE`. - The total number of instructions across all three lists (i.e. sum of the lengths of the lists) must be less than or equal to the current value of the network parameter `network.spam_protection.max.batch.size`. The margin mode update transaction is not included in this limit. ### Processing a batch @@ -34,8 +34,8 @@ Overall, building the ability to handle batches of market instructions in a sing - A batch is considered a single transaction, with a single transaction ID and a single timestamp applying to all instructions within it. Each instruction should be given a sub-identifier and index allowing it to be placed sequentially in the transaction (e.g. by consumers of the event stream). These identifiers must be sufficient for a user to determine which instruction within a batch any result (order updates, trades, errors, etc.) relates to. - The batches must be processed in the order **all cancellations, then all amendments, any margin mode update, then all submissions**. This is to prevent gaming the system, and to prevent any order being modified by more than one action in the batch. Updating the margin mode after cancellations and amendments allows the party to have control of which orders are outstanding when the margin mode changes. - When processing each list, the instructions within the list must be processed in the order they appear in the list (i.e. in the order prescribed by the submitter). (Notwithstanding that each list is processed in its entirety before moving onto the next list, in the order specified above). -- All instructions within each list must be validated as normal **at the time that the instruction is enacted**. That is, instructions cannot be pre-validated as a batch. If a prior instruction, would create a state that would cause a later instruction to fail validation, the later instruction must fail validation (and vice verse). -- If validation fails, the execution of other instructions depends on the value specified for the `ON ERROR` parameter. Any validation or other errors should be returned, as well as a reference to the instruction to which they relate, in the response. +- All instructions within each list must be validated as normal **at the time that the instruction is enacted**. That is, instructions cannot be pre-validated as a batch. If a prior instruction, would create a state that would cause a later instruction to fail validation, the later instruction must fail validation (and vice verse). Any validation not dependent on other parameters or app state should be carried out as early as possible (e.g. check if type is numerical etc.). +- If validation fails, the execution of other instructions depends on the value specified for the `ON_ERROR` parameter. Any validation or other errors should be returned, as well as a reference to the instruction to which they relate, in the response. - Any errors encountered in processing an instruction after it passes validation must cause it to be skipped, and the errors, as well as the instruction to which they relate, must be available in the result of the transaction. - In addition to the usual validation and other errors that can occur in processing an instruction, the following also apply: - Any second or subsequent Amend Order instruction for the same order ID within a single Batch Instruction transaction is an error @@ -65,3 +65,6 @@ After entering or exiting an auction mid-batch, the full batch must be processed - Instructions within the same category within a batch should be executed in the order they are received. For example, if two Cancellations instructions are submitted in a batch: [C1, C2], then C1 should be executed before C2. (0074-BTCH-011) - If the margin mode update transaction fails all transactions in the batch referring to the same market are Stopped. (0074-BTCH-020). For product spot (0074-BTCH-022) - If the margin mode update transaction fails all transactions in the batch referring to a different market are attempted as usual. (0074-BTCH-021). For product spot (0074-BTCH-023) +- The current value of `network.validators.tendermint.number` is `n`, the batch contains a transaction to set `network.validators.multisig.numberOfSigners` to `n+1`. `ON_ERROR` parameter is not explicitly specified. The batch gets successfully submitted and voted in. When enacting `network.validators.multisig.numberOfSigners` change the parameter gets validated against the existing value of `network.validators.tendermint.number`, it doesn't pass the validation and the value doesn't get updated. An appropriate error gets recorded and the next transaction in the batch gets enacted at an appropriate time. (0074-BTCH-024). +- The current value of `network.validators.tendermint.number` is `n`, the batch contains a transaction to set `network.validators.multisig.numberOfSigners` to `n+1`. `ON_ERROR` parameter is set to `STOP`. The batch gets successfully submitted and voted in. When enacting `network.validators.multisig.numberOfSigners` change the parameter gets validated against the existing value of `network.validators.tendermint.number`, it doesn't pass the validation and the value doesn't get updated. An appropriate error gets recorded and no other transactions from the batch get enacted. (0074-BTCH-025). +- The current value of `network.validators.tendermint.number` is `n`, the batch contains a transaction to set `network.validators.tendermint.number` to `n+2` and `network.validators.multisig.numberOfSigners` to `n+1`. The batch gets successfully submitted and voted in. When enacting `network.validators.multisig.numberOfSigners` change the parameter gets validated against the new value of `network.validators.tendermint.number`, both parameters get set to their new values and the enactment of other transactions from the batch carries on. (0074-BTCH-026). diff --git a/protocol/features.json b/protocol/features.json index 2509f4c66..111a1f82d 100644 --- a/protocol/features.json +++ b/protocol/features.json @@ -769,7 +769,10 @@ "acs": [ "0016-PFUT-029", "0016-PFUT-030", - "0016-PFUT-031" + "0016-PFUT-031", + "0074-BTCH-024", + "0074-BTCH-025", + "0074-BTCH-026" ] }, "LP 3.0": { From 11b8f42995392b35df46043f611fa0732d05a2a5 Mon Sep 17 00:00:00 2001 From: Witold Date: Wed, 18 Sep 2024 12:09:21 +0200 Subject: [PATCH 3/3] refactor: Update protocol/0074-BTCH-batch-market-instructions.md Co-authored-by: David Siska <62546419+davidsiska-vega@users.noreply.github.com> --- protocol/0074-BTCH-batch-market-instructions.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/protocol/0074-BTCH-batch-market-instructions.md b/protocol/0074-BTCH-batch-market-instructions.md index e2f3c82db..20b94dc66 100644 --- a/protocol/0074-BTCH-batch-market-instructions.md +++ b/protocol/0074-BTCH-batch-market-instructions.md @@ -34,7 +34,8 @@ Overall, building the ability to handle batches of market instructions in a sing - A batch is considered a single transaction, with a single transaction ID and a single timestamp applying to all instructions within it. Each instruction should be given a sub-identifier and index allowing it to be placed sequentially in the transaction (e.g. by consumers of the event stream). These identifiers must be sufficient for a user to determine which instruction within a batch any result (order updates, trades, errors, etc.) relates to. - The batches must be processed in the order **all cancellations, then all amendments, any margin mode update, then all submissions**. This is to prevent gaming the system, and to prevent any order being modified by more than one action in the batch. Updating the margin mode after cancellations and amendments allows the party to have control of which orders are outstanding when the margin mode changes. - When processing each list, the instructions within the list must be processed in the order they appear in the list (i.e. in the order prescribed by the submitter). (Notwithstanding that each list is processed in its entirety before moving onto the next list, in the order specified above). -- All instructions within each list must be validated as normal **at the time that the instruction is enacted**. That is, instructions cannot be pre-validated as a batch. If a prior instruction, would create a state that would cause a later instruction to fail validation, the later instruction must fail validation (and vice verse). Any validation not dependent on other parameters or app state should be carried out as early as possible (e.g. check if type is numerical etc.). +- All instructions within each list must be validated as normal **at the time that the instruction is enacted**. That is, instructions cannot be pre-validated as a batch. If a prior instruction, would create a state that would cause a later instruction to fail validation, the later instruction must fail validation (and vice verse). +Any validation not dependent on other parameters or app state (i.e. static e.g. check if type is numerical etc.) should be carried on batch submission. - If validation fails, the execution of other instructions depends on the value specified for the `ON_ERROR` parameter. Any validation or other errors should be returned, as well as a reference to the instruction to which they relate, in the response. - Any errors encountered in processing an instruction after it passes validation must cause it to be skipped, and the errors, as well as the instruction to which they relate, must be available in the result of the transaction. - In addition to the usual validation and other errors that can occur in processing an instruction, the following also apply: