code.texi (4299B)
1 @chapter Base library contents 2 3 4 @section Pluggable method interface 5 6 The base chainlib blockchain interface is defined by the @code{chainlib.interface.ChainInterface class}. All of the methods in this class are unimplemented. Together they make up the methods necessary to interface with @emph{any} blockchain RPC. 7 8 It is up to the implemenenter to choose which of the methods that are needed in any particular context. The implementer would then connect the method symbols with actual code. 9 10 Most methods in this class will return objects that can be passed to an RPC connection that fits the block context. 11 12 The available methods are: 13 14 @table @code 15 @item block_latest 16 Retrieve the latest block from the network 17 @item block_by_hash 18 Retrieve the block corresponding to the given block hash 19 @item block_by_number 20 Retrieve the block corresponding to the given block number 21 @item block_from_src 22 Render a chainlib.block.Block derivative object from an architecture-dependent block representation source 23 @item block_to_src 24 Render an architecture dependent transaction representation from the given Block object 25 @item tx_by_hash 26 Retrieve the transaction corresponding to the given transaction hash 27 @item tx_by_block 28 Retrieve the transaction corresponding to the given block hash and transaction index 29 @item tx_receipt 30 Retrieve the details of a confirmed transaction 31 @item tx_raw 32 Generate an RPC query from raw transaction wire data 33 @item tx_pack 34 Generate raw transaction wire data from an architecture dependent transaction representation 35 @item tx_unpack 36 Generate architecture dependent transaction representation from raw transaction wire data 37 @item tx_from_src 38 Render a chainlib.tx.Tx derivative object from an architecture-dependent tx representation source 39 @item tx_to_src 40 Render an architecture dependent transaction representation from the given Tx object 41 @item address_safe 42 Generate a checksum-safe network address 43 @item address_normal 44 Generate an unambiguous network address 45 @item src_normalize 46 Generate an unambiguous dictionary from the given dictionary. For example, this can mean generating camel-case key equivalents for snake-case values. 47 @end table 48 49 50 @section The RPC interface 51 52 @code{chainlib.connection} currently has support for HTTP(S) and UNIX socket RPC connections. Both rely on the Python @emph{standard library} only (@code{urllib} and @code{socket}). 53 54 It provides a thread-safe connection factory mechanism where connection constructor and location pairs are associated with string labels. 55 56 There is also explicit builtin support for the JSONRPC RPC protocol, which allows for a pluggable error translater that can be customized to every RPC "dialect" that needs to be supported (examples are "geth" and "openethereum" dialects of the Ethereum node fauna). Classes to handle JSONRPC results, requests and errors are defined in the @code{chainlib.jsonrpc} module. 57 58 59 @section Blocks and transactions 60 61 Common block and transaction concepts are represented by the @code{chainlib.block.Block} and @code{chainlib.tx.Tx} objects. These are very minimal base-classes that need to be extended for every blockchain implementation that is to be supported. 62 63 When building transactions, implementations of the @code{chainlib.sign.Signer}, @code{chainlib.nonce.NonceOracle} and @code{chainlib.fee.FeeOracle} interfaces will provide the transaction factory object of the implementation with signatures, transaction nonces and transaction fee details respectively. 64 65 66 @section Other code features 67 68 This section lists features that are considered outside the core of the @code{chainlib} package 69 70 71 @subsection RPC authenticator 72 73 If you are relying on an RPC provider instead of running your own node (although, you know you @emph{should} run your own node, right?), then RPC authentication may be relevant. 74 75 @code{chainlib.auth} provides two authentication mechanisms for HTTP: 76 77 @table @code 78 @item BasicAuth 79 The HTTP basic Authorization scheme 80 @item CustomHeaderTokenAuth 81 Define an arbitrary header name and value 82 @end table 83 84 85 @subsection Fee price aggregator 86 87 The @code{chainlib.stat.ChainStat} class provides a simple implementation of a running average aggregator for network fee prices. This can be used to generate more precise fee price heuristics that in turn can be fed to a Fee Oracle. 88 89