diff --git a/doc/texinfo/index.texi b/doc/texinfo/index.texi new file mode 100644 index 0000000..7f98838 --- /dev/null +++ b/doc/texinfo/index.texi @@ -0,0 +1,5 @@ +@top chainlib + +@chapter Chainlib + +@include interface.texi diff --git a/doc/texinfo/interface.texi b/doc/texinfo/interface.texi new file mode 100644 index 0000000..06fb7a5 --- /dev/null +++ b/doc/texinfo/interface.texi @@ -0,0 +1,59 @@ +@node chainlib-interface +@section The chainlib implementation + +Chainlib is an attempt at employing a universal interface to manipulate and access blockchains regardless of underlying architecture. + +It makes the following assumptions: + +@itemize +@item A block MUST have a interpretable serializable format, and contains zero of more transactions +@item A transaction MUST have a interpretable serializable format +@item A transaction MUST have a nonce associated with a sender address. This uniquely identifies the transaction on the network. +@item A transaction MUST have a fee bid to get the transaction executed on the network (a network that does not care about bids can still ignore this property). +@item A transaction signature MAY be locked to a particular chain identifier +@item The sender key of a transaction MAY be recovered by the signature of the transaction +@end itemize + + +@subsection Pluggable method interface + +The base chainlib blockchain interface is defined by the chainlib.interface.ChainInterface class. The sum of the unimplemented methods in this class summarizes the expected scope of abstraction necessary to interface with @emph{any} blockchain backend. + +Methods in this class will return objects that can be passed to an RPC connection that fits the block context. + +The implemented concepts are as follows, listed by method names: + +@table @code +@item block_latest +Retrieve the latest block from the network +@item block_by_hash +Retrieve the block corresponding to the given block hash +@item block_by_number +Retrieve the block corresponding to the given block number +@item block_from_src +Render a chainlib.block.Block derivative object from an architecture-dependent block representation source +@item block_to_src +Render an architecture dependent transaction representation from the given Block object +@item tx_by_hash +Retrieve the transaction corresponding to the given transaction hash +@item tx_by_block +Retrieve the transaction corresponding to the given block hash and transaction index +@item tx_receipt +Retrieve the details of a confirmed transaction +@item tx_raw +Generate an RPC query from raw transaction wire data +@item tx_pack +Generate raw transaction wire data from an architecture dependent transaction representation +@item tx_unpack +Generate architecture dependent transaction representation from raw transaction wire data +@item tx_from_src +Render a chainlib.tx.Tx derivative object from an architecture-dependent tx representation source +@item tx_to_src +Render an architecture dependent transaction representation from the given Tx object +@item address_safe +Generate a checksum-safe network address +@item address_normal +Generate an unambiguous network address +@item src_normalize +Generate an unambiguous dictionary from the given dictionary. For example, this can mean generating camel-case key equivalents for snake-case values. +@end table