Start of component documentation

This commit is contained in:
nolash 2021-06-07 07:00:19 +02:00
parent 99b901e2e3
commit d2da81e5cb
Signed by: lash
GPG Key ID: 21D2E7BB88C2A746
4 changed files with 166 additions and 1 deletions

View File

@ -51,7 +51,7 @@ class StatusEnum(enum.IntEnum):
SENDFAIL = StatusBits.DEFERRED | StatusBits.LOCAL_ERROR SENDFAIL = StatusBits.DEFERRED | StatusBits.LOCAL_ERROR
RETRY = StatusBits.QUEUED | StatusBits.DEFERRED RETRY = StatusBits.QUEUED | StatusBits.DEFERRED
READYSEND = StatusBits.QUEUED READYSEND = StatusBits.QUEUED
RESERVED = StatusBits.RESERVED RESERVED = StatusBits.QUEUED | StatusBits.RESERVED
OBSOLETED = StatusBits.OBSOLETE | StatusBits.IN_NETWORK OBSOLETED = StatusBits.OBSOLETE | StatusBits.IN_NETWORK

6
doc/infotex/index.texi Normal file
View File

@ -0,0 +1,6 @@
@top chainqueue
@chapter Chainqueue
@include tx.texi
@include state.texi

130
doc/infotex/state.texi Normal file
View File

@ -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.

29
doc/infotex/tx.texi Normal file
View File

@ -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{}}.