Block Explorer API - batch transaction errors

[edd]

Feature Overview

In order to usefully render the success or failure of a batch order
We will need improve on the simply returning the error field
So that individual transactions in the batch can be marked as successful or failed
and the success of the batch as a whole can be represented

Tasks

• Determine where exactly the errors should sit
  • implementor's choice: can be alongside the command or in an error structure, as long as the errors can be programmatically associated by position/index in the batch, order reference field, and order ID (or as many of those as are available for the given instruction in the batch that experienced an error)
• Put the errors along with the invidual commands or in individual error entries referencing the commands unambiguously by position/index in batch, order reference, and order ID, rather than all in one API field
• Ensure that different items of data about the error and it's associated command and order, e.g. index in batch, instruction type (submit/cancel/amend), order ID, market ID, error code, error text, etc. have individual fields and do not need to be e.g. parsed out of strings
• Decide how best to represent the success of the batch as a whole (is it if any passes it's all fine? Is a batch status even meaningful?)
• Ensure that whatever solution is decided makes it unambiguously possible to know a command succeeded, too. For example if there's no "success" status, just a lack of errors, then it needs to be gauranteed that no errors referencing the command means it succeeded.

Acceptance Criteria

• Every cancellation has an associated error message if it failed
• Every submission has an associated error message if it failed
• Every amendment has an associated error message if it failed
• Every cancellation, submission, and amendment can be definitively determined to have succeeded or failed
• A batch can be determined to be 'successful' or or 'partially successful', or 'unsuccessful'
• If there are any class of errors that can cause the whole batch to fail e.g. a validation error outside of the individual commands, or a key being spam banned, then it must be possible clear to a user attempting to interrogate the status of any given instruction that that instruction did not succeed, e.g. every instruction should be referenced so that if a user indexes the error data by one of the instruction/order identifiers or references they will not miss applicable errors.

Test Scenarios (non-exhaustive)

GIVEN a batch transaction with 2 cancellations
WHEN the first cancellation is for an order that does not exist
THEN the cancellation within the command object has an error field and that error field contains the error unable to find the order in the market

GIVEN a batch transaction with 2 amendments
WHEN the first amendment is for an order that is filled
THEN the amendment within the command object has an error field and that error field contains the error

GIVEN a batch transaction with 2 submissions
WHEN the first order is for a market that does not exist
THEN the order within the command object has an error field and that error field contains the error
Additional Details (optional)

tldr this is an API addition, not a TX change, with the goal of ensuring that bost algorthmic/API traders AND front end developers can ascertain the status of each component of a batch in order to update state, take further actions, and display information about the status to users.

It is important, particularly for API traders, that the data is structued and that there can be no "surprises".

See also #7246

[edd]

Dupe of #7843

[barnabee]

I tried to update the original ticket to include this, but adding my comment from Slack here for completenes:

This can be fulfilled by a new errors field outside of the "command" message, as long as any such field contains the metadata (index/location in batch, order reference, order ID) needed to associate the error with the instruction that caused it. We can accept “successful” being implied by nothing in the errors field referfencing a given instruction as long as it is guaranteed that the instruction succeeded in that case.