commit 7a621b82354bef65a2e6348368e7bd41e306776a
parent 20c3904e721490d115308a9c0569729bfa49844a
Author: lash <dev@holbrook.no>
Date: Sat, 3 Jun 2023 12:46:20 +0100
Update texinfo docs, generate readme from docs
Diffstat:
14 files changed, 622 insertions(+), 56 deletions(-)
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,3 +1,9 @@
+- 0.4.16
+ * Add long description to python package
+- 0.4.15
+ * Include rpc dialect in chain interface constructor
+- 0.4.14
+ * Add chainlib-gen man page in python package
- 0.4.13
* Expose string to bytes keccak hash
- 0.4.12
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1 +1 @@
-include *requirements.txt LICENSE WAIVER WAIVER.asc chainlib/data/config/* chainlib/data/env/* man/build/**
+include *requirements.txt LICENSE WAIVER WAIVER.asc chainlib/data/config/* chainlib/data/env/* man/build/** README*
diff --git a/Makefile b/Makefile
@@ -19,3 +19,13 @@ man:
#./scripts/chainlib-man.py -v -n chainlib-gen -d $(BUILD_DIR)/ man
cp -v man/chainlib-gen.groff man/build/chainlib-gen.1
+readme:
+ make -C doc/texinfo readme
+ pandoc -f docbook -t gfm doc/texinfo/build/docbook.xml > README.md
+
+python: build
+
+doc:
+ make -C doc/texinfo
+
+
diff --git a/README.md b/README.md
@@ -1,44 +1,428 @@
# chainlib
-Chainlib is a prototype attempt at writing a generalized code library structure in python3 for concepts that are valid across blockchains, either within the same chain technology or across them. If useful and/or successful, it should be considered ported to a more performant language (rust?).
+# Overview
-It is primarily aimed at (possibly threaded) console-environment development.
+Chainlib is an attempt at employing a universal interface to manipulate
+and access blockchains regardless of underlying architecture.
-It aims to give fine-grained control and transparency to all operations and transformations.
+It makes the following assumptions:
-It library code should be easy to understand and maintain.
+- A block MUST have a interpretable serializable format, and contains
+ zero of more transactions
-To achieve transparency and improve maintainability, it deliberately exposes the _user_ of this code to a certain degree of complexity.
+- A transaction MUST have a interpretable serializable format
-Ultimately, the chainlib library is for the developer who seeks to understand and contribute, rather than merely defer and consume.
+- A transaction MUST have a nonce associated with a sender address. This
+ uniquely identifies the transaction on the network.
+- A transaction MUST have a fee bid to get the transaction executed on
+ the network (a network that does not care about bids can just ignore
+ this property).
-## Requirements
+- A transaction signature MAY be locked to a particular chain identifier
-Chainlib seeks to keep its dependency graph and small as possible. Because of baggage from the initial phase of development, it depends on the `crypto-dev-signer` library to represent transaction structures. As this dependency also includes other routines not necessary for the code in the library, it will be replaced with a dedicated component. `crypto-dev-signer` will still be used as default for tests, and for the time being also for the CLI runnables.
+- The sender key of a transaction MAY be recovered by the signature of
+ the transaction
-To generate the bitcoin-style keccak256 hashes, `pysha3` is used. `pysha3` is a very fast python wrapper around the official keccak implementation from [XKCP](https://github.com/XKCP/XKCP).
+Chainlib is specifically designed for building command line interface
+tools. It provides templates for handling configuration, argument
+parsing and environment variable processing to build RPC connections to
+chain nodes for network queries and signing operations.
-The other requirements are very this code fragments that merely help to relieve a bit of tedium, and add no magic.
+# Command line interface provisions
-Chainlib is not compatible with python2, nor is there any reason to expect it will aim to be.
+The base CLI provisions of `chainlib` simplifies the generation of a
+some base object instances by command line arguments, environment
+variables and configuration schemas.
+To use CLI provisions, `chainlib.cli` should be imported. This
+automatically imports the following submodules:
-## Structure
+`arg`
+Define and/or select command-line arguments
-Any generalizable structures and code can be found in the base module directory `chainlib/`
+`config`
+Process configuration from command-line arguments and environment
+variables
-Currently the only operational code for available targets is for the `evm` and the `Ethereum` network protocol. This code can be found in the separate package `chainlib-eth`.
+`rpc`
+Create RPC connection from configuration
-Every module will have a subdirectory `runnable` which contains CLI convenience tooling for common operations. Any directory `example` will contain code snippets demonstrating usage.
+`wallet`
+Create wallet from configuration
+Any chain implementation building on `chainlib` should extend one or
+more of the classes in these modules as needed, for example order to add
+more configuration directives or command line argument flags.
-## How to use
+## Arguments
-There are no (exhaustive) tutorial planned for chainlib. All you need to know should be possible to easily understand from code in the `example` `tests` and `runnable` subfolders.
+`chainlib` defines a set of arguments that are common concepts for
+interfacing with blockchain RPCs. Which arguments to use for a specific
+instantiation can be defined using flags or symbols that define groups
+of flags.
+This functionality is provided by the `chainlib.cli.args.ArgumentParser`
+class. It is a thin wrapper around the standard library
+`argparser.ArgumentParser` class, only adding a method to add arguments
+to the instance based on the aforementioned flags.
-## See also
+Following is a description of all pre-defined arguments that are
+available with `chainlib`.
-* The [chainsyncer](https://git.defalsify.org/chainsyncer) project, which provides a simple chain syncer framework allowing for an arbitrary amount of pluggable code to be executed for each block transaction.
-* The [chainqueue](https://git.defalsify.org/chainqueue) project, which provides a transaction queueing daemon that handles conditional submisssion and resubmission of transactions to the network.
+### -c, –config
+
+Override configuration directives by reading ini-files in the given
+directory.
+
+Only configuration directives defined in the schema may be overridden.
+See [chainlib-config](#chainlib_002dconfig).
+
+### –env-prefix
+
+Prepend the given string to configuration directives when overriding by
+environment variables
+
+Normally, if a configuration directive `FOO_BAR` exists, the environment
+variable `FOO_BAR` will override its value. If `--env-prefix BAZ` is
+passed, the environment variable `BAZ_FOO_BAR` will be used instead to
+override the configuration directive `FOO_BAR`. The environment variable
+`FOO_BAR` will in this case *not* be used.
+
+### –height
+
+Query the chain RPC for results at a specific block height.
+
+Applies to *read* operations only.
+
+### -i, –chain-spec
+
+Chain specification string for the blockchain connection.
+
+This informs the implementing code about the architecture and deployment
+of the blockchain network. It can also be relevant when creating
+signatures for the network (e.g. the EIP155 signature scheme for EVM).
+
+### –fee-limit
+
+Use the exact given fee multiplier to calculate the final bid to get
+transaction executed on the network.
+
+How the fee semantics are employed depend on the chain implementation,
+but the final resulting bid *must always* be the product of
+`price * limit`.
+
+If *not* defined, the multiplier will be retrieved using the fees
+provider defined by the implementation.
+
+### –fee-price
+
+Use the exact given fee price as factor to calculate bid to get
+transaction executed on the network.
+
+How the fee semantics are employed depend on the chain implementation,
+but the final resulting bid *must always* be the product of
+`price * limit`.
+
+If *not* defined, the current recommended price will be retrieved from
+the fees provider defined by the implementation.
+
+### -n, –namespace
+
+Append the given namespace to implicit configuration override paths.
+
+For example, if linux xdg-basedir path is used, a namespace argument of
+`foo` in implementation domain `bar` will result in the configuration
+override path `$HOME/.config/bar/foo`.
+
+### –nonce
+
+Start at the exact given nonce for the query.
+
+If *not* defined, the next nonce will be retrieved from the nonce
+provider defined by the implementation.
+
+### -p, –provider
+
+URL of the chain RPC provider.
+
+### -s, –send
+
+CLI tools building on chainlib should *never* submit to the network by
+default. Instead, resulting transactions ready for network submission
+should be output to terminal.
+
+If the implementation wishes to allow the user to directly send to the
+network, the `-s` flag *must* be used for this purpose.
+
+### –seq
+
+By default, a random RPC id will be generated for every RPC call.
+
+However, some RPCs will only allow sequential serial numbers to be used
+as RPC ids, in which case this flag should be used.
+
+### –raw
+
+Generate output suitable for passing to another command (e.g. UNIX
+pipes).
+
+### –rpc-auth
+
+Tells the implementer which RPC authentication scheme to use (e.g.
+"basic" for http basic).
+
+### –rpc-credentials
+
+Tells the implemented wich RPC authentication credentials to use for
+selected rpc authentication scheme (e.g. "foo:bar" for user foo pass bar
+in scheme "basic" a.k.a. http basic).
+
+Credentials may for example also be a single value, like a private key,
+depending on the scheme and implementation.
+
+### –rpc-dialect
+
+Tells the implementer to optimize query, result and error reporting for
+the specific chain RPC backend dialect.
+
+### -u, –unsafe
+
+Allow arguments with blockchain addresses that are not checksum
+protected.
+
+### -v, -vv
+
+Defines logging verbosity.
+
+Specifically, `-v` will set loglevel to `INFO`, wheres `-vv` will set
+loglevel to `DEBUG`.
+
+Default loglevel is up to the implementer, but it is advisable to keep
+it at `WARNING`.
+
+### -w, -ww
+
+Toggles blocking in relation to chain RPC calls.
+
+If `-w` is set, the implementer should only block to obtain the result
+of the *last, and as few as possible preceding* RPC transactions.
+
+If `-ww` is set, the implementer should block to retrieve the results of
+*all* of the preceding RPC transactions.
+
+If the implementation consists of a single transaction, the effect of
+`-w` and `-ww` will always be the same. Nonetheless, the implementation
+will be forced to provide both arguments.
+
+If neither flag is set, the typical consequence is that the network
+transaction hash of the last transaction will be returned.
+
+### -y, –key-file
+
+Read private key from the given key file.
+
+# Rendering configurations
+
+Configurations in `chainlib` are processed, rendered and interfaced
+using the `confini` python package.
+
+In short, `confini` extends the functionality of Python’s standard
+library `configparser` package to allow merging of directives by parsing
+multiple ini-files from multiple directories.
+
+Furthermore, it employs this same multi-file approach when defining a
+configuration *schema*, aswell as defining source to *override* the
+values defined in the schema.
+
+See <https://gitlab.com/nolash/python-confini> for further details on
+`confini`.
+
+## Configuration schema in chainlib
+
+The chainlib configuration schema is, along with the provided command
+line arguments and environment variables, designed to cover the settings
+necessary for most normal chain RPC operations.
+
+### Configuration mapping
+
+Below follows a mapping of configuration directives to command line
+arguments and environment variables.
+
+Note that any configuration directives prefixed by `"_"` are not defined
+in the configuration schema, and are not overrideable by environment
+variables. These are values typically are only valid within the context
+of a single execution of the implemented tool.
+
+| arg | config | env |
+|-------------------------|-----------------------|-----------------------|
+| — | — | CONFINI_DIR [^1] |
+| -c. –config [^2] | — | — |
+| -i, –chain-spec | CHAIN_SPEC | CHAIN_SPEC |
+| –height | \_HEIGHT | — |
+| –fee-limit | \_FEE_LIMIT | — |
+| –fee-price | \_FEE_PRICE | — |
+| -n, –namespace | CONFIG_USER_NAMESPACE | CONFIG_USER_NAMESPACE |
+| –nonce | \_NONCE | — |
+| -p, –rpc-provider | RPC_HTTP_PROVIDER | RPC_HTTP_PROVIDER |
+| -a, -recipient | \_RECIPIENT | — |
+| -e, –executable-address | \_EXEC_ADDRESS | — |
+| –rpc-auth | RPC_AUTH | RPC_AUTH |
+| — | RPC_PROVIDER | RPC_PROVIDER [^3] |
+| — | RPC_SCHEME | RPC_SCHEME [^4] |
+| –rpc-credentials | RPC_CREDENTIALS | RPC_CREDENTIALS |
+| –rpc-dialect | RPC_DIALECT | RPC_DIALECT |
+| -s, –send | \_RPC_SEND | — |
+| –seq | \_SEQ | — |
+| -u, –unsafe | \_UNSAFE | — |
+| -w | \_WAIT | — |
+| -ww | \_WAIT_ALL | — |
+| -y, –key-file | WALLET_KEY_FILE | WALLET_KEY_FILE |
+| — [^5] | WALLET_PASSPHRASE | WALLET_PASSPHRASE |
+
+Currently `chainlib` only supports HTTP(S) when building RPC connections
+from command line arguments and configuration.
+
+# Base library contents
+
+## Pluggable method interface
+
+The base chainlib blockchain interface is defined by the
+`chainlib.interface.ChainInterface class`. All of the methods in this
+class are unimplemented. Together they make up the methods necessary to
+interface with *any* blockchain RPC.
+
+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.
+
+Most methods in this class will return objects that can be passed to an
+RPC connection that fits the block context.
+
+The available methods are:
+
+`block_latest`
+Retrieve the latest block from the network
+
+`block_by_hash`
+Retrieve the block corresponding to the given block hash
+
+`block_by_number`
+Retrieve the block corresponding to the given block number
+
+`block_from_src`
+Render a chainlib.block.Block derivative object from an
+architecture-dependent block representation source
+
+`block_to_src`
+Render an architecture dependent transaction representation from the
+given Block object
+
+`tx_by_hash`
+Retrieve the transaction corresponding to the given transaction hash
+
+`tx_by_block`
+Retrieve the transaction corresponding to the given block hash and
+transaction index
+
+`tx_receipt`
+Retrieve the details of a confirmed transaction
+
+`tx_raw`
+Generate an RPC query from raw transaction wire data
+
+`tx_pack`
+Generate raw transaction wire data from an architecture dependent
+transaction representation
+
+`tx_unpack`
+Generate architecture dependent transaction representation from raw
+transaction wire data
+
+`tx_from_src`
+Render a chainlib.tx.Tx derivative object from an architecture-dependent
+tx representation source
+
+`tx_to_src`
+Render an architecture dependent transaction representation from the
+given Tx object
+
+`address_safe`
+Generate a checksum-safe network address
+
+`address_normal`
+Generate an unambiguous network address
+
+`src_normalize`
+Generate an unambiguous dictionary from the given dictionary. For
+example, this can mean generating camel-case key equivalents for
+snake-case values.
+
+## The RPC interface
+
+`chainlib.connection` currently has support for HTTP(S) and UNIX socket
+RPC connections. Both rely on the Python *standard library* only
+(`urllib` and `socket`).
+
+It provides a thread-safe connection factory mechanism where connection
+constructor and location pairs are associated with string labels.
+
+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
+`chainlib.jsonrpc` module.
+
+## Blocks and transactions
+
+Common block and transaction concepts are represented by the
+`chainlib.block.Block` and `chainlib.tx.Tx` objects. These are very
+minimal base-classes that need to be extended for every blockchain
+implementation that is to be supported.
+
+When building transactions, implementations of the
+`chainlib.sign.Signer`, `chainlib.nonce.NonceOracle` and
+`chainlib.fee.FeeOracle` interfaces will provide the transaction factory
+object of the implementation with signatures, transaction nonces and
+transaction fee details respectively.
+
+## Other code features
+
+This section lists features that are considered outside the core of the
+`chainlib` package
+
+### RPC authenticator
+
+If you are relying on an RPC provider instead of running your own node
+(although, you know you *should* run your own node, right?), then RPC
+authentication may be relevant.
+
+`chainlib.auth` provides two authentication mechanisms for HTTP:
+
+`BasicAuth`
+The HTTP basic Authorization scheme
+
+`CustomHeaderTokenAuth`
+Define an arbitrary header name and value
+
+### Fee price aggregator
+
+The `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.
+
+[^1]: The `CONFINI_DIR` environment variable defines an explicit
+ configuration *schema* path.
+
+[^2]: The `-c` flag defines an explicit configuration *override* path.
+
+[^3]: RPC_PROVIDER will always be set to the same value as
+ RPC_HTTP_PROVIDER by default.
+
+[^4]: The RPC_SCHEME configuration directive is always set to ’http’ by
+ default.
+
+[^5]: This flag is not provided because it is simply not safe to define
+ passphrases as an argument on the command line.
diff --git a/doc/texinfo/Makefile b/doc/texinfo/Makefile
@@ -0,0 +1,5 @@
+all:
+ makeinfo --html -o build content.texi
+
+readme:
+ makeinfo --docbook --no-split -o build/docbook.xml content.texi
diff --git a/doc/texinfo/cli.texi b/doc/texinfo/cli.texi
@@ -1,4 +1,4 @@
-@section Command line interface provisions
+@chapter Command line interface provisions
The base CLI provisions of @code{chainlib} simplifies the generation of a some base object instances by command line arguments, environment variables and configuration schemas.
@@ -18,7 +18,7 @@ Create wallet from configuration
Any chain implementation building on @code{chainlib} should extend one or more of the classes in these modules as needed, for example order to add more configuration directives or command line argument flags.
-@subsection Arguments
+@section Arguments
@code{chainlib} defines a set of arguments that are common concepts for interfacing with blockchain RPCs. Which arguments to use for a specific instantiation can be defined using flags or symbols that define groups of flags.
@@ -27,34 +27,34 @@ This functionality is provided by the @code{chainlib.cli.args.ArgumentParser} cl
Following is a description of all pre-defined arguments that are available with @code{chainlib}.
-@subsubsection -c, --config
+@subsection -c, --config
Override configuration directives by reading ini-files in the given directory.
Only configuration directives defined in the schema may be overridden. @xref{chainlib-config}.
-@subsubsection --env-prefix
+@subsection --env-prefix
Prepend the given string to configuration directives when overriding by environment variables
Normally, if a configuration directive @code{FOO_BAR} exists, the environment variable @code{FOO_BAR} will override its value. If @code{--env-prefix BAZ} is passed, the environment variable @code{BAZ_FOO_BAR} will be used instead to override the configuration directive @code{FOO_BAR}. The environment variable @code{FOO_BAR} will in this case @emph{not} be used.
-@subsubsection --height
+@subsection --height
Query the chain RPC for results at a specific block height.
Applies to @emph{read} operations only.
-@subsubsection -i, --chain-spec
+@subsection -i, --chain-spec
Chain specification string for the blockchain connection.
This informs the implementing code about the architecture and deployment of the blockchain network. It can also be relevant when creating signatures for the network (e.g. the EIP155 signature scheme for EVM).
-@subsubsection --fee-limit
+@subsection --fee-limit
Use the exact given fee multiplier to calculate the final bid to get transaction executed on the network.
@@ -63,7 +63,7 @@ How the fee semantics are employed depend on the chain implementation, but the f
If @emph{not} defined, the multiplier will be retrieved using the fees provider defined by the implementation.
-@subsubsection --fee-price
+@subsection --fee-price
Use the exact given fee price as factor to calculate bid to get transaction executed on the network.
@@ -72,67 +72,67 @@ How the fee semantics are employed depend on the chain implementation, but the f
If @emph{not} defined, the current recommended price will be retrieved from the fees provider defined by the implementation.
-@subsubsection -n, --namespace
+@subsection -n, --namespace
Append the given namespace to implicit configuration override paths.
For example, if linux xdg-basedir path is used, a namespace argument of @code{foo} in implementation domain @code{bar} will result in the configuration override path @code{$HOME/.config/bar/foo}.
-@subsubsection --nonce
+@subsection --nonce
Start at the exact given nonce for the query.
If @emph{not} defined, the next nonce will be retrieved from the nonce provider defined by the implementation.
-@subsubsection -p, --provider
+@subsection -p, --provider
URL of the chain RPC provider.
-@subsubsection -s, --send
+@subsection -s, --send
CLI tools building on chainlib should @emph{never} submit to the network by default. Instead, resulting transactions ready for network submission should be output to terminal.
If the implementation wishes to allow the user to directly send to the network, the @code{-s} flag @emph{must} be used for this purpose.
-@subsubsection --seq
+@subsection --seq
By default, a random RPC id will be generated for every RPC call.
However, some RPCs will only allow sequential serial numbers to be used as RPC ids, in which case this flag should be used.
-@subsubsection --raw
+@subsection --raw
Generate output suitable for passing to another command (e.g. UNIX pipes).
-@subsubsection --rpc-auth
+@subsection --rpc-auth
Tells the implementer which RPC authentication scheme to use (e.g. "basic" for http basic).
-@subsubsection --rpc-credentials
+@subsection --rpc-credentials
Tells the implemented wich RPC authentication credentials to use for selected rpc authentication scheme (e.g. "foo:bar" for user foo pass bar in scheme "basic" a.k.a. http basic).
Credentials may for example also be a single value, like a private key, depending on the scheme and implementation.
-@subsubsection --rpc-dialect
+@subsection --rpc-dialect
Tells the implementer to optimize query, result and error reporting for the specific chain RPC backend dialect.
-@subsubsection -u, --unsafe
+@subsection -u, --unsafe
Allow arguments with blockchain addresses that are not checksum protected.
-@subsubsection -v, -vv
+@subsection -v, -vv
Defines logging verbosity.
@@ -141,7 +141,7 @@ Specifically, @code{-v} will set loglevel to @code{INFO}, wheres @code{-vv} will
Default loglevel is up to the implementer, but it is advisable to keep it at @code{WARNING}.
-@subsubsection -w, -ww
+@subsection -w, -ww
Toggles blocking in relation to chain RPC calls.
@@ -154,7 +154,7 @@ If the implementation consists of a single transaction, the effect of @code{-w}
If neither flag is set, the typical consequence is that the network transaction hash of the last transaction will be returned.
-@subsubsection -y, --key-file
+@subsection -y, --key-file
Read private key from the given key file.
diff --git a/doc/texinfo/code.texi b/doc/texinfo/code.texi
@@ -1,7 +1,7 @@
-@section Base library contents
+@chapter Base library contents
-@subsection Pluggable method interface
+@section Pluggable method interface
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.
@@ -47,7 +47,7 @@ Generate an unambiguous dictionary from the given dictionary. For example, this
@end table
-@subsection The RPC interface
+@section The RPC interface
@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}).
@@ -56,19 +56,19 @@ It provides a thread-safe connection factory mechanism where connection construc
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.
-@subsection Blocks and transactions
+@section Blocks and transactions
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.
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.
-@subsection Other code features
+@section Other code features
This section lists features that are considered outside the core of the @code{chainlib} package
-@subsubsection RPC authenticator
+@subsection RPC authenticator
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.
@@ -82,7 +82,7 @@ Define an arbitrary header name and value
@end table
-@subsubsection Fee price aggregator
+@subsection Fee price aggregator
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.
diff --git a/doc/texinfo/config.texi b/doc/texinfo/config.texi
@@ -1,5 +1,5 @@
@anchor{chainlib-config}
-@section Rendering configurations
+@chapter Rendering configurations
Configurations in @code{chainlib} are processed, rendered and interfaced using the @code{confini} python package.
@@ -10,12 +10,12 @@ Furthermore, it employs this same multi-file approach when defining a configurat
See @url{https://gitlab.com/nolash/python-confini} for further details on @code{confini}.
-@subsection Configuration schema in chainlib
+@section Configuration schema in chainlib
The chainlib configuration schema is, along with the provided command line arguments and environment variables, designed to cover the settings necessary for most normal chain RPC operations.
-@subsubsection Configuration mapping
+@subsection Configuration mapping
Below follows a mapping of configuration directives to command line arguments and environment variables.
diff --git a/doc/texinfo/content.texi b/doc/texinfo/content.texi
@@ -1,5 +1,4 @@
-@node chainlib
-@chapter Chainlib
+@top chainlib
@include intro.texi
@include cli.texi
diff --git a/doc/texinfo/intro.texi b/doc/texinfo/intro.texi
@@ -1,4 +1,4 @@
-@section Overview
+@chapter Overview
Chainlib is an attempt at employing a universal interface to manipulate and access blockchains regardless of underlying architecture.
diff --git a/man/build/chainlib-gen.1 b/man/build/chainlib-gen.1
@@ -0,0 +1,63 @@
+.TH chainlib-gen 1
+
+.SH NAME
+chainlib-gen \- Generate bytecode and arguments from modules implementing chainlib
+
+
+.SH SYNOPSIS
+
+.SY chainlib-gen
+-l
+.YS
+
+.SY chainlib-gen
+<module> <command> -k
+.YS
+
+.SY chainlib-gen
+<module> <command> [args...]
+.YS
+
+
+.SH DESCRIPTION
+.P
+chainlib-gen can be used to generate inputs necessary for publishing executable code for blockchain environments.
+.P
+A python module is considered to support chainlib-gen if the file \fI<package_dir>/data/.chainlib\fP exists.
+
+
+.SH Top-level options
+
+.TP
+.TQ
+.B -h
+.TQ
+.B --help
+Command help summary.
+
+.TP
+.B -v
+Verbose logging
+
+.TP
+.B -vv
+Very verbose logging
+
+
+.TP
+.B -l
+List supported module names
+
+
+.SH DISCOVERING MODULES
+.P
+Using the \fI-l\fP flag, chainlib-gen will list the names all supporing modules found in its search path.
+
+
+.SH Command options
+.P
+A supporting module will implement one or more commands, and will also define a default command that will be executed if no command is specified.
+
+.TP
+\fB-k\fP
+List required and optional arguments for <command> under <module>.
diff --git a/man/chainlib-gen.groff b/man/chainlib-gen.groff
@@ -0,0 +1,93 @@
+.TH chainlib-gen 1
+
+.SH NAME
+chainlib-gen \- Generate bytecode and arguments from modules implementing chainlib
+
+
+.SH SYNOPSIS
+
+.SY chainlib-gen
+-l
+.YS
+
+.SY chainlib-gen
+<module> <command> -k
+.YS
+
+.SY chainlib-gen
+<module> <command> [args...]
+.YS
+
+
+.SH DESCRIPTION
+.P
+chainlib-gen can be used to generate inputs necessary for publishing executable code for blockchain environments.
+.P
+A python module is considered to support chainlib-gen if the file \fI<package_dir>/data/.chainlib\fP exists.
+
+
+.SH Top-level options
+
+.TP
+.TQ
+.B -h
+.TQ
+.B --help
+Command help summary.
+
+.TP
+.B -v
+Verbose logging
+
+.TP
+.B -vv
+Very verbose logging
+
+
+.TP
+.B -l
+List supported module names
+
+
+.SH DISCOVERING MODULES
+.P
+Using the \fI-l\fP flag, chainlib-gen will list the names all supporing modules found in its search path.
+
+
+.SH Command options
+.P
+A supporting module will implement one or more commands.
+
+.TP
+\fB-k\fP
+List required and optional arguments for <command> under <module>.
+
+
+.SH KNOWN ISSUES
+.P
+Currently there is no way except reading module code to discover which module commands are available.
+
+
+.SH LICENSE
+
+This documentation and its source is licensed under the Creative Commons Attribution-Sharealike 4.0 International license.
+
+The source code of the tool this documentation describes is licensed under the Affero GNU General Public License 3.0.
+
+
+.SH COPYRIGHT AND CONTACT
+
+.MT dev@holbrook.no
+Louis Holbrook
+.ME
+
+.UR https://holbrook.no
+.UE https://holbrook.no
+
+.P
+PGP: 59A844A484AC11253D3A3E9DCDCBD24DD1D0E001
+
+
+.SH SOURCE CODE
+
+https://git.defalsify.org/chainlib
diff --git a/setup.cfg b/setup.cfg
@@ -3,7 +3,7 @@ name=chainlib
license=AGPLv3+
author_email=dev@holbrook.no
description=Generic blockchain access library and tooling
-version=0.4.15
+version=0.4.16
url=https://git.defalsify.org/chainlib
author=Louis Holbrook
diff --git a/setup.py b/setup.py
@@ -12,6 +12,10 @@ while True:
requirements.append(l.rstrip())
f.close()
+f = open('README.md', 'r')
+description = f.read()
+f.close()
+
setup(
install_requires=requirements,
extras_require={
@@ -29,4 +33,6 @@ setup(
'scripts/chainlib-man.py',
],
data_files=[("man/man1", ['man/build/chainlib-gen.1'],)],
+ long_description=description,
+ long_description_content_type='text/markdown',
)
