Implement references in docs

apps/cic-eth/cic_eth/version.py

@@ -10,7 +10,7 @@ version = (
         0,
         11,
         0,
-        'beta.11',
+        'beta.12',
         )
 
 version_object = semver.VersionInfo(

apps/cic-eth/doc/texinfo/admin.texi

@@ -1,7 +1,5 @@
 @node cic-eth system maintenance
-@section System maintenance
-
-@subsection Admin API
+@appendix Admin API
 
 The admin API is still in an early stage of refinement. User friendliness can be considerably improved.
 
@@ -9,55 +7,54 @@ All of the API calls are celery task proxies, and return @code{Celery.AsyncResul
 
 In contrast to the client API module, this API does not currently implement a pluggable callback.
 
-@subsubsection registry
+@appendixsection registry
 
 Returns the @code{ContractRegistry} this instance of @code{cic-eth-tasker} is running on.
 
-@subsubsection proxy-do
+@appendixsection proxy-do
 
 Execute an arbitary JSON-RPC request using the @code{cic-eth-tasker} blockchain node RPC connection.
 
-@subsubsection default_token
+@appendixsection default_token
 
 Returns the default token symbol and address.
 
-@subsubsection lock
+@appendixsection lock
 
 Set lock bits, globally or per address
 
-@subsubsection unlock
+@appendixsection unlock
 
 Opposite of lock
 
-@subsubsection get_lock
+@appendixsection get_lock
 
 Get the current state of a lock
 
-@subsubsection tag_account
+@appendixsection tag_account
 
 Associate an identifier with an account address (@xref{cic-eth system accounts})
 
-@subsubsection have_account
+@appendixsection have_account
 
 Check whether a private key exists in the keystore able to sign on behalf of the given account (it actually performs a signature).
 
-@subsubsection resend
+@appendixsection resend
 
 Clone or resend a transaction
 
-@subsubsection check_nonce
+@appendixsection check_nonce
 
 Returns diagnostics for nonce sequences per account, e.g. detect nonce gaps that block execution of further transactions.
 
-@subsubsection fix_nonce
+@appendixsection fix_nonce
 
 Re-orders all nonces by shifting all transaction nonces after the given transaction down by one. This has the additional effect of obsoleting the given transaction. Can be used to close gaps in the nonce sequencing. Use with care!
 
-@subsubsection account
+@appendixsection account
 
 Return brief transaction info lists per account
 
-@subsubsection tx
+@appendixsection tx
 
 Return a complex transaction metadata object for a single transaction. The object assembles state from both the blockchain node and the custodial queue system.
-

apps/cic-eth/doc/texinfo/chains.texi

@@ -0,0 +1,4 @@
+@node cic-eth Appendix Task chains
+@appendix Task chains
+
+TBC - explain here how to generate these chain diagrams

apps/cic-eth/doc/texinfo/dependencies.texi

@@ -3,7 +3,7 @@
 
 This application is written in Python 3.8. It is tightly coupled with @code{python-celery}, which provides the task worker ecosystem. It also uses @code{SQLAlchemy} which provides useful abstractions for persistent storage though SQL, and @code{alembic} for database schema migrations.
 
-These is currently also a coupling with @code{Redis}, which is used as message broker for @code{python-celery}. This coupling may be relaxed in the future to allow other key-value pubsub solutions instead. @code{Redis} is also explicitly used by some CLI tools to retrieve results from command execution.
+There is currently also a somewhat explicit coupling with @code{Redis}, which is used as message broker for @code{python-celery}. @code{Redis} is also explicitly used by some CLI tools to retrieve results from command execution. This coupling may be relaxed in the future to allow other key-value pubsub solutions instead. 
 
 
 @subsection Generalized project dependencies
@@ -24,12 +24,12 @@ An keystore capable of signing for the EVM chain through a standard Ethereum JSO
 @anchor{cic-eth-dependencies-smart-contracts}
 @subsection Smart contract dependencies
 
-The Smart contracts needed by the network must be discoverable through a single entry point called the Contract Registry. Additionally, this contract registry must reference itself among its records. The authenticity of the contract registry must be guaranteed by external sources of trust.
+The Smart contracts needed by the network must be discoverable through a single entry point called the Contract Registry. The contract registry is expected to reference itself in its records. The authenticity of the contract registry must be guaranteed by external sources of trust.
 
-The contract registry maps contract addresses to well-known identifiers. These are as follows:
+The contract registry maps contract addresses to well-known identifiers. The contracts are as follows:
 
 @table @code
-@item ContractRegistry
+@item ContractRegistry (points to self)
 Resolves plaintext identifiers to contract addresses.
 @item AccountRegistry
 An append-only store of accounts hosted by the custodial system
@@ -43,4 +43,4 @@ Escrow contract for external spending on behalf of custodial users
 Called by newly created accounts to receive initial token balance
 @end table
 
-The closely related component @code{cic-eth-registry} facilitates lookups of resources on the blockchain network. In its current state it resolves tokens by symbol or address, and contracts by common-name identifiers.
+The dependency @code{cic-eth-registry} abstracts and facilitates lookups of resources on the blockchain network. In its current state it resolves tokens by symbol or address, and contracts by common-name identifiers. In the @code{cic-eth} code all lookups for EVM network resources will be performed through this dependency.

apps/cic-eth/doc/texinfo/index.texi

@@ -16,4 +16,5 @@ The current implementation is in its entirety based on the EVM network and with
 @include services.texi
 @include tools.texi
 @include admin.texi
-@include appendix.texi
+@include chains.texi
+@include transfertypes.texi

apps/cic-eth/doc/texinfo/interacting.texi

@@ -1,22 +1,22 @@
 @node cic-eth-interacting
 @section Interacting with the system
 
-The API to the @var{cic-eth} component is a proxy for executing @emph{chains of Celery tasks}. The tasks that compose individual chains are documented in appendix (?), which also describes a CLI tool that can generate graph representationso of them.
+The API to the @var{cic-eth} component is a proxy for executing @emph{chains of Celery tasks}. The tasks that compose individual chains are documented in @ref{cic-eth Appendix Task chains,the Task Chain appendix}, which also describes a CLI tool that can generate graph representationso of them.
 
-There are two API classes, @var{Api} and @var{AdminApi}. The former is described later in this section, the latter described in section (?).
+There are two API classes, @var{Api} and @var{AdminApi}. The former is described later in this section, the latter described in @ref{cic-eth system maintenance,the Admin API appendix}.
 
 
 @subsection Interface
 
 API calls are constructed by creating @emph{Celery task signatures} and linking them together, sequentially and/or in parallell. In turn, the tasks themselves may spawn other asynchronous tasks. This means that the code in @file{cic_eth.api.*} does not necessarily specify the full task graph that will be executed for any one command.
 
-The operational guarantee that tasks will be executed, not forgotten, and retried under certain circumstances is deferred to @var{Celery}. On top of this, the @var{chainqueue} component ensures that semantic state changes requested of it by the tasks are valid.
+The operational guarantee that tasks will be executed, not forgotten, and retried under certain circumstances is deferred to @var{Celery}. On top of this, the @var{chainqueue} component ensures that semantic state changes that the @code{Celery} tasks ask of it are valid.
 
 
 @anchor{cic-eth-locking}
 @subsection Locking
 
-All methods that make a change to the blockchain network are subject to the locking layer. Locks may be applied on a global or per-address basis. Lock states are defined by a combination of bit flags. The implemented lock bits are:
+All methods that make a change to the blockchain network must pass @emph{locking layer checks}. Locks may be applied on a global or per-address basis. Lock states are defined by a combination of bit flags. The implemented lock bits are:
 
 @table @var
 @item INIT
@@ -34,7 +34,7 @@ Until reset, no other part of the locking state can be reset
 
 @subsection Callback
 
-All API calls provide the option to attach a callback to the end of the task chain. This callback will be executed regardless of whether task chain execution successed or not.
+All API calls provide the option to attach a callback to the end of the task chain. This callback will be executed regardless of whether task chain execution succeeded or not.
 
 Refer to @file{cic-eth.callbacks.noop.noop} for the expected callback signature.
 
@@ -80,7 +80,7 @@ Retrieves a complex balance statement of a single account, including:
 @item Value increments due to by pending incoming transactions
 @end itemize
 
-Only the first of these balance items has guaranteed finality. The reduction by outgoing transaction can be reasonably be assumed to eventually become final. The same appied for the increment by incoming transaction, @emph{unless} the transfer is part of a multiple-transaction operation. For example, a @ref{cic-eth-convert-and-transfer,convert_and_transfer} operation may fail in the convert stage and/or may yield less tokens then expected after conversion.
+Only the first of these balance items has guaranteed finality. The reduction by outgoing transaction can be reasonably be assumed to eventually become final. The same applies for the increment by incoming transaction, @emph{unless} the transfer is part of a multiple-transaction operation. For example, a @ref{cic-eth-convert-and-transfer,convert_and_transfer} operation may fail in the convert stage and/or may yield less tokens then expected after conversion.
 
 
 @subsubsection list

apps/cic-eth/doc/texinfo/outgoing.texi

@@ -9,7 +9,7 @@ The term @var{state bit} refers to the bits definining the @code{chainqueue} sta
 
 Any task that changes blockchain state @strong{must} apply a @code{QUEUE} lock for the address it operates on. This is to ensure that transactions are sent to the network in order.@footnote{If too many transactions arrive out of order to the blockchain node, it may arbitrarily prune those that cannot directly be included in a block. This puts unnecessary strain (and reliance) on the transaction retry mechanism.}
 
-This lock will be released once the blockchain node confirms handover of the transaction.
+This lock will be released once the blockchain node confirms handover of the transaction.@footnote{This is the responsibility of the @var{dispatcher} service}
 
 
 @subsection Nonce

apps/cic-eth/doc/texinfo/services.texi

@@ -17,7 +17,7 @@ The other @var{cic-eth} daemons all interface with this component, along with an
 The tasker has a set of pre-requisites that must be fulfilled before it will start
 
 @itemize
-@item It must be given a valid @var{ContractRegistry} address, which must include valid references to all contracts specified in @strong{[point to section about contract deps]})
+@item It must be given a valid @var{ContractRegistry} address, which must include valid references to all contracts specified in @ref{cic-eth-dependencies-smart-contracts,Smart contract dependencies}
 @item The gas gifter balance must be above the minimum threshold (See "eth" section in configurations).
 @item There must be a valid alembic migration record in the storage database
 @item The redis backend must be reachable and writable
@@ -27,7 +27,7 @@ The tasker has a set of pre-requisites that must be fulfilled before it will sta
 
 @subsection tracker
 
-Implements the @var{chainsyncer}, and registers the filters described in @strong{[ref transaction monitoring]} to be executed for every transaction. It consumes the appropriate @var{TASKS_TRANSFER_CALLBACKS} configuration setting to add externally defined filters at without having to change the daemon code.
+Implements the @var{chainsyncer}, and registers the filters described in @ref{cic-eth-incoming,Incoming Transactions} to be executed for every transaction. It consumes the appropriate @var{TASKS_TRANSFER_CALLBACKS} configuration setting to add externally defined filters at without having to change the daemon code.
 
 The @var{tracker} has the same requisities for the @var{ContractRegistry} as the @var{tasker}.
 

apps/cic-eth/doc/texinfo/tools.texi

@@ -17,7 +17,7 @@ Returns information about a specific resource related to the tranasaction queue.
 
 @table @var
 @item lock
-If the argument is the literal string @kbd{lock}, it will list all active lock settings currently in effect. (see @strong{[reference locking section]})
+If the argument is the literal string @kbd{lock}, it will list all active lock settings currently in effect. (@xref{cic-eth-locking})
 @item <address>
 If the argument is a 0x-prefixed hex string of 42 characters, it returns all transactions where the specified address is a sender or recipient@footnote{If the address is the gas gifter or the accounts index writer, this may be a @emph{lot} of transactions. Use with care!}
 @item <tx_hash>
@@ -37,7 +37,7 @@ Execute a token transfer on behalf of a custodial account.
 
 @subsection tag (cic-eth-tag)
 
-Associate an account address with a string identifier. See @strong{[reference SYSTEM ACCOUNTS]}.
+Associate an account address with a string identifier. @xref{cic-eth system accounts}
 
 
 @anchor{cic-eth-tools-ctrl}

apps/cic-eth/doc/texinfo/transfertypes.texi

@@ -1,8 +1,3 @@
-@node cic-eth Appendix Task chains
-@appendix Task chains
-
-TBC - explain here how to generate these chain diagrams
-
 @node cic-eth Appendix Transaction types
 @appendix Transfer types