chaintool/chainqueue
4
0
Fork 0
Code Issues 1 Pull Requests Projects Releases Wiki Activity

Rename doc dir

Browse Source
This commit is contained in:
nolash
2021-08-29 11:32:13 +02:00
parent 28e7842f4d
commit dd3ce50ece
5 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
doc/texinfo/exec.texi Normal file
View File

@@ -0,0 +1,6 @@
@node chainqueue-executable
@section Executables
Chainqueue only provides a single executable. This executable lists items in queue based on given criteria. The available criteria more or less map to the arguments offered by @code{chainqueue.backend.Backend.get}.
When installing @code{chainqueue} as a python package, the list tool will be available in @code{PATH} as the command @file{chainqueue-list}.

8
doc/texinfo/index.texi Normal file
View File

@@ -0,0 +1,8 @@
@top chainqueue
@chapter Chainqueue
@include tx.texi
@include state.texi
@include stack.texi
@include exec.texi

58
doc/texinfo/stack.texi Normal file
View File

@@ -0,0 +1,58 @@
@node chainqueue-architecture
@section State storage
Chainqueue enables separate implementations of the state storage layer backend.
Included in the package are state storage for sql using the SQLAlchemy dependency, as well as state using native filesystem backend (without any additional dependencies).
The backend interface is defined in the @code{chainqueue.backend} module. It provides the following methods:
@itemize
@item Create a new queue item
@item Add cached data to queue item
@item Get a single queue item
@item Get multiple queue items based on given criteria
@item Dispatch a queue item to the network
@item Connect / disconnect to backend
@end itemize
@subsection SQL backend
This backend is Contained in the module @code{chainqueue.sql.backend.SQLBackend}. It translates high-level calls to invididual method calls in the query, state and tx submodules of @code{chainqueue.sql.backend}.
The @code{SQLBackend} object should provide all methods required to make practical use of the chainqueue package. However, all other modules in @code{chainqueue.sql} are also intended for public consumption.
The @code{chainqueue.sql.backend} in turn calls methods in the SQLAlchemy database model layer in @code{chainqueue.db.models}. The consumer is not intended to interface directly with @code{chainqueue.db.models}.
@subsection Filesystem backend
The filesystem state storage is provided by the @code{chainqueue.fs} module. is at the moment missing the @code{chainqueue.backend.Backend} implementation. Please refer to the code in @file{tests/tests_fs*.py} to learn how to use in its current state.
@section Adapters
The adapter layer enables chain specific code to be combined with an arbitrary storage backend. Typically, chain specific code is required to:
@itemize
@item Translate transaction wire format to generic transaction representation
@item Send transactions to the network
@end itemize
The adapter consumes a backend, and delegates calls to it as required.
Since adapters are chain specific, @code{chainqueue} only provides a base class that must be extended the chain implementer code. Specifically, the methods to extend are:
@table @code
@item Add
Add a transaction to the queue
@item Upcoming
Get queued transactions ready to be sent to network
@item Dispatch
Send a queued transaction to the network
@item Translate
Decode details of a transaction
@item Create_session, release_session
Session management to control queue state integrity
@end table

130
doc/texinfo/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.

30
doc/texinfo/tx.texi Normal file
View File

@@ -0,0 +1,30 @@
@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 queue state. @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 primary purpose of the @emph{cache} record is performance improvement. By keeping cached records of the expanded and interpreted properties of a transaction, fewer cycles need to be spent later on when needing to access these derived properties.
Keeping the cache also more easily enables conditional ordering and execution when querying data sets, 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{}}.