Implement references in docs
This commit is contained in:
nolash
parent
39f4191c52
commit
f2df5b596f
GPG Key ID:
21D2E7BB88C2A746
|
|
@ -10,7 +10,7 @@ version = (
|
|||
0,
|
||||
11,
|
||||
0,
|
||||
'beta.11',
|
||||
'beta.12',
|
||||
)
|
||||
|
||||
version_object = semver.VersionInfo(
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,4 @@
|
|||
@node cic-eth Appendix Task chains
|
||||
@appendix Task chains
|
||||
|
||||
TBC - explain here how to generate these chain diagrams
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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}.
|
||||
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
Loading…
Reference in New Issue