Augment "submit" command response

[mDuo13]

When you submit a transaction, there's a bunch of information you'd like to know so you can track your transaction's status accurately. You can look up some of that info separately, but you have to be careful about race conditions if you don't do everything in precisely the correct order. We can simplify a lot of the challenges by providing useful information directly in the response to the submit command.

Here are some suggestions (with credit to @ximinez for suggesting most of these):

• applied: boolean. Indicates whether the transaction was applied to the open ledger
• queued: boolean. Indicates whether the transaction was put into the transaction queue
• broadcast: boolean. Indicates whether the transaction was broadcast to the network
• kept (name pending): One or more fields to indicate that a transaction was kept by the server and may be retried later. (Aside from the queue, there are two "holding pens", localtxns and heldtxns, which are used in cases of a ledger jump or normal ledger advancement respectively. But I'm not sure distinguishing between the two is relevant to end-users.)
• available_sequence: number. (Also not sure about this name.) Regardless of the disposition of the transaction, returns the sequence number that the account that owns the just-submitted transaction should use on its next transaction to have the largest chance of success. In short, it'll look at the account sequence number and the transaction queue, and look for the first "available" sequence. If the Tickets amendment is enabled, this should adjust for that.
• account_sequence: number. The sequence number of transaction's sending account, as of the "current" ledger.
• open_ledger_reference_drops: number. (Not sure if this is a good idea or a good name.) Number of drops required for a reference transaction to get into the open ledger.
• validated_ledger_index: number. The ledger index of the latest validated ledger. The latest validated ledger at the time of submission. The earliest ledger index that the submitted transaction could appear in¹ is this value +1, so you can use this to easily bound your tx queries to find out the final status of this transaction. Returning the value at this point saves a separate request and avoids possible race conditions. (Example race condition: You request the latest ledger index with the "ledger" command, then you submit, but the submission returns first, then the ledger index advances some number of times, then your "ledger" command returns with a higher ledger index than the earliest one your transaction could conceivably be in. If the delays are big enough it's possible this could cause you to miss your transaction.) I specifically say validated ledger index because getting the latest current or closed ledger is not a guarantee—your transaction could (theoretically) make it into an earlier ledger index that also hasn't been validated yet.

¹Specifically, it's the earliest ledger index the submitted transaction can appear in as a result of this submission process. If the transaction had been previously been submitted to this or any other server, it could of course appear in an earlier ledger index.

[intelliot]

I don't know what I would individually use applied, queued, broadcast, or kept for, but I do want a boolean that indicates whether the transaction was "permanently rejected". Based on the descriptions above, I think it might be something like:

• rejected: boolean. Equal to !(applied || queued || broadcast || kept).

I guess the inverse might be called "accepted":

• accepted: boolean. Equal to applied || queued || broadcast || kept.

Here's my use case: If the transaction was permanently rejected, then I'll immediately inform the user that the transaction permanently failed and will not be applied to the ledger. (Of course, this only applies if the server and connection are trusted and secure, and my signed transaction was not exposed to anyone else.)

available_sequence, open_ledger_reference_drops (if the transaction was rejected for reason of fee), and validated_ledger_index are all very useful and I would certainly use them.