From d2da81e5cb718adf63af5615a1a7defbb6870a9e Mon Sep 17 00:00:00 2001 From: nolash Date: Mon, 7 Jun 2021 07:00:19 +0200 Subject: [PATCH] Start of component documentation --- chainqueue/enum.py | 2 +- doc/infotex/index.texi | 6 ++ doc/infotex/state.texi | 130 +++++++++++++++++++++++++++++++++++++++++ doc/infotex/tx.texi | 29 +++++++++ 4 files changed, 166 insertions(+), 1 deletion(-) create mode 100644 doc/infotex/index.texi create mode 100644 doc/infotex/state.texi create mode 100644 doc/infotex/tx.texi diff --git a/chainqueue/enum.py b/chainqueue/enum.py index d04e6b3..8146064 100644 --- a/chainqueue/enum.py +++ b/chainqueue/enum.py @@ -51,7 +51,7 @@ class StatusEnum(enum.IntEnum): SENDFAIL = StatusBits.DEFERRED | StatusBits.LOCAL_ERROR RETRY = StatusBits.QUEUED | StatusBits.DEFERRED READYSEND = StatusBits.QUEUED - RESERVED = StatusBits.RESERVED + RESERVED = StatusBits.QUEUED | StatusBits.RESERVED OBSOLETED = StatusBits.OBSOLETE | StatusBits.IN_NETWORK diff --git a/doc/infotex/index.texi b/doc/infotex/index.texi new file mode 100644 index 0000000..473573b --- /dev/null +++ b/doc/infotex/index.texi @@ -0,0 +1,6 @@ +@top chainqueue + +@chapter Chainqueue + +@include tx.texi +@include state.texi diff --git a/doc/infotex/state.texi b/doc/infotex/state.texi new file mode 100644 index 0000000..0b222dd --- /dev/null +++ b/doc/infotex/state.texi @@ -0,0 +1,130 @@ +@node chainqueue-states +@section State transitions + +Queued transactions are controlled using a combination of state bits, enumerated to human-readable labels. + +Some of these bits may only be set if certain bits have previously been set. + +Certain combinations of bits constitute @emph{semantic} states, intended for human consumption. + + +@subsection State bits + +@table @code +@item QUEUED +Transaction is ready to send to network. +@item RESERVED +Transaction is assigned to a process which will send it to the network. +@item IN_NETWORK +The transaction has been sent to the network. +@item DEFERRED +A transaction send could not be completed, and should be retired later. +@item GAS_ISSUES +The transaction sender does not have sufficient network token balance to send the transaction. +@item LOCAL_ERROR +The transaction request could not be sent, e.g. because the node was unavailable. +@item NODE_ERROR +The network gateway node rejected the transaction. (will always be a FINAL state). +@item NETWORK_ERROR +The network rejected the state change requested by the transaction (will always be a FINAL state). +@item UNKNOWN_ERROR +Any other error (will always be a FINAL state). +@item FINAL +The transaction request will not be processed further. +@item OBSOLETE +The transaction request has been superseded by a different transaction, e.g. an identical replacement transaction with a higher fee. +@item MANUAL +The state of the transaction request has been manipulated manually. +@end table + +@subsection State bit transitions + +When the @strong{FINAL} bit is set, no further state changes may be made. + +@multitable .25. 75 +@headitem bit +@tab precondition +@item QUEUED +@tab @emph{none} | DEFERRED | GAS_ISSUES +@item RESERVED +@tab QUEUED +@item IN_NETWORK +@tab RESERVED +@item GAS_ISSUES +@tab @emph{none} +@item DEFERRED +@tab RESERVED +@end multitable + + +@subsection State semantics + +@subsubsection Clean states + +@multitable .25 .50 .25 +@headitem state +@tab description +@tab bits set +@item PENDING +@tab The state of the transaction when it first enters the queue. +@tab (none) +@item READYSEND +@tab Transaction is ready to send to network +@tab QUEUED +@item RESERVED +@tab Transaction is assigned to a process which will send it to the network. +@tab QUEUED, RESERVED +@item SENT +@tab Transaction has been sent to the network +@tab IN_NETWORK +@item SUCCESS +@tab The transaction has successfully changed the network state. +@tab IN_NETWORK, FINAL +@item REVERTED +@tab The transaction was included by the network, but failed to change the network state. +@tab IN_NETWORK, NETWORK_ERROR, FINAL +@end multitable + + +@subsubsection Exception states + +@multitable .25 .50 .25 +@headitem state +@tab description +@tab bits set +@item GAS_ISSUES +@tab The transaction sender does not have sufficient network token balance to send the transaction. +@tab GAS_ISSUES +@item RETRY +@tab Transaction should be retried after a grace period +@tab QUEUED, DEFERRED +@item SENDFAIL +@tab The transaction request could not be sent, e.g. because the node was unavailable. +@tab DEFERRED, LOCAL_ERROR +@item REJECTED +@tab The transaction was rejected by the node. +@tab NODE_ERROR, FINAL +@end multitable + + +@subsubsection Replacement states + +@multitable .25 .50 .25 +@headitem state +@tab description +@tab bits set +@item OBSOLETED +@tab A attempt has been made to replace the transaction. +@tab OBSOLETE[, IN_NETWORK] +@item CANCELLED +@tab A different replacement transaction has been confirmed by the network. +@tab OBSOLETE, FINAL[, IN_NETWORK] +@item OVERRIDDEN +@tab The transaction has been cancelled by an explicit command. +@tab OBSOLETE, FINAL, MANUAL[, IN_NETWORK] +@end multitable + + +@subsection State log + +State transisitons can optionally be logged. This provides a list of date to state bitfield values for every change for every transaction. diff --git a/doc/infotex/tx.texi b/doc/infotex/tx.texi new file mode 100644 index 0000000..2588024 --- /dev/null +++ b/doc/infotex/tx.texi @@ -0,0 +1,29 @@ +@node chainqueue-tx +@section Transaction representation + +Transactions in chainqueue are chain-agnostic. Their representation should only presume a generalized concept of a chain transaction. Interpretation of what a transaction acutally contains or means is left to the client code of the queue to process. + +In storage each record is divided into two parts: A @emph{mandatory} part, and a @emph{cache} part. + + +@subsection Mandatory record + +This consists of the data required to order transactions, and to actually them to the network. Specifically, it contains: + +@itemize +@item @strong{hash} of the transaction +@item the serialized transaction @strong{payload} +@item the transaction @strong{nonce} +@item the @xref{chainqueue-states, queue state} +@item the @strong{block number} of a confirmed transaction +@end itemize + + +@subsection Cache record + +With exception of the @emph{nonce}, the @emph{cache} part of the record contains deserialized fields of the transaction, all of which can be reconstructed by the client code intepreting the transaction payload in the @emph{mandatory} part. + +The queue can still work without the cache record, but keeping one enables conditional ordering and execution, e.g. @emph{@guillemetleft{}the first unsent transaction nonce from sender S.@guillemetright{}} + +Additionally, the cache records curates some additional token semantics, defining in essence a transaction as @emph{@guillemetleft{}sender S sends X amount of token A as Y amount of token B to recipient R@guillemetright{}}. +