adding cic-eth as sub dir

2021-02-01 09:12:51 -08:00
parent ed3991e997
commit a4587deac5
317 changed files with 819441 additions and 0 deletions
--- a/apps/cic-eth/doc/flowcharts/Makefile
+++ b/apps/cic-eth/doc/flowcharts/Makefile
@@ -0,0 +1,15 @@
+INPUTS = $(wildcard *.dot)
+OUTPUTS = $(patsubst %.dot, %.png, $(INPUTS))
+
+.SUFFIXES: .dot .png
+
+.dot.png:
+	dot -T png $(basename $@).dot > $@
+
+all: $(OUTPUTS)
+
+clean:
+	rm -vf *.png
+
+.PHONY: clean 
+
--- a/apps/cic-eth/doc/flowcharts/account_tasks.dot
+++ b/apps/cic-eth/doc/flowcharts/account_tasks.dot
@@ -0,0 +1,21 @@
+digraph {
+
+	create_account [
+		label="CIC-ETH API:\create account";
+		shape="ellipse";
+	];
+
+	callback [
+		label="callback";
+		shape="ellipse";
+		style="dashed";
+	];
+
+	create_account -> "eth.account.create";
+	create_account -> "eth.account.register" -> "eth.account.cache_account_data"; 
+	"eth.account.register" -> "queue.tx,create";
+	"eth.account.register" -> "eth.tx.check_gas";
+	"eth.tx.check_gas" -> "eth.tx.refill_gas" [ style="dashed" ];
+	"eth.tx.check_gas" -> callback [ style="dashed" ];
+	"eth.tx.refill_gas" -> callback [ style="dashed" ];
+}
--- a/apps/cic-eth/doc/flowcharts/balance_tasks.dot
+++ b/apps/cic-eth/doc/flowcharts/balance_tasks.dot
@@ -0,0 +1,16 @@
+digraph {
+	balance [
+		label="CIC-ETH API:\nbalance";
+		shape="ellipse";
+	];
+
+	callback [
+		label="callback";
+		shape="ellipse";
+		style="dashed";
+	];
+
+	balance -> "eth.token.resolve_tokens_by_symbol"
+	"eth.token.resolve_tokens_by_symbol" -> "eth.token.balance"
+	"eth.token.balance" -> callback [ style="dashed" ];
+}
--- a/apps/cic-eth/doc/flowcharts/callback_gift.dot
+++ b/apps/cic-eth/doc/flowcharts/callback_gift.dot
@@ -0,0 +1,10 @@
+digraph {
+
+	tx [
+		label="CIC-MANAGER\ncallbacks filter, tokengift";
+		shape="ellipse";
+	];
+
+	tx -> callback [ style="dashed" ];
+
+}
--- a/apps/cic-eth/doc/flowcharts/convert_tasks.dot
+++ b/apps/cic-eth/doc/flowcharts/convert_tasks.dot
@@ -0,0 +1,57 @@
+digraph {
+
+	convert_transfer [
+		label="CIC-ETH API:\nconvert_transfer";	
+		shape="ellipse";
+	];
+
+	callback [
+		label="callback";
+		shape="ellipse";
+		style="dashed";
+	];
+
+	convert_approve_zero [
+		label="eth.token.approve (zero)";
+		shape="ellipse";
+	];
+
+	convert_approve_amount [
+		label="eth.token.approve (amount)";
+		shape="ellipse";
+	];
+
+	cache_approve_zero [
+		label="eth.token.otx_cache_approve";
+		shape="ellipse";
+	];
+
+	cache_approve_amount [
+		label="eth.token.otx_cache_approve";
+		shape="ellipse";
+	];
+
+	queue_approve_zero [
+		label="queue.tx.create";
+		shape="ellipse";
+	];
+
+	queue_approve_amount [
+		label="queue.tx.create";
+		shape="ellipse";
+	];
+
+	convert_transfer -> "eth.token.resolve_tokens_by_symbol" -> "eth.bancor.convert_with_default_reserve";
+	"eth.bancor.convert_with_default_reserve" -> convert_approve_zero -> cache_approve_zero;
+	convert_approve_zero -> queue_approve_zero;
+	"eth.bancor.convert_with_default_reserve" -> convert_approve_amount -> cache_approve_amount;
+	convert_approve_amount -> queue_approve_amount;
+	"eth.bancor.convert_with_default_reserve" -> "eth.bancor.otx_cache_convert";
+	"eth.bancor.convert_with_default_reserve" -> "queue.tx.create";
+	"eth.bancor.convert_with_default_reserve" -> "eth.tx.check_gas";
+	"eth.bancor.convert_with_default_reserve" -> "eth.bancor.save_convert_recipient";
+	"eth.tx.check_gas" -> "eth.tx.refill_gas" [ style="dashed" ];
+	"eth.tx.check_gas" -> callback [ style="dashed" ];
+	"eth.tx.refill_gas" -> callback [ style="dashed" ];
+
+}
--- a/apps/cic-eth/doc/flowcharts/converttransfer_tasks.dot
+++ b/apps/cic-eth/doc/flowcharts/converttransfer_tasks.dot
@@ -0,0 +1,15 @@
+digraph {
+
+	tx [
+		label="CIC-MANAGER;\nconvert_filter";
+		shape="ellipse";
+	];
+
+	tx -> "eth.bancor.transfer_converted" -> "eth.token.otx_cache_transfer";
+	"eth.bancor.transfer_converted" -> "queue.tx.create";
+	"eth.bancor.transfer_converted" -> "eth.bancor.save_convert_transfer";
+	"eth.bancor.transfer_converted" -> "eth.tx.check_gas";
+	"eth.tx.check_gas" -> "eth.tx.refill_gas" [ style="dashed" ];
+	"eth.tx.check_gas" -> callback [ style="dashed" ];
+	"eth.tx.refill_gas" -> callback [ style="dashed" ];
+}
--- a/apps/cic-eth/doc/flowcharts/dispatch.dot
+++ b/apps/cic-eth/doc/flowcharts/dispatch.dot
@@ -0,0 +1,159 @@
+digraph G {
+
+	send [
+		label = "transfer";
+		shape = "ellipse";
+	];
+
+	params [
+		label = "get token, value, sender, recipient";
+		shape = "parallelogram";
+	];
+
+	token_lookup [
+		label = "token known?";
+		shape = "diamond";	
+	];
+
+	token_lookup_x [
+		xlabel = "UnknownTokenError";
+		shape = "point";
+	];
+
+	nonce [
+		label = "get sender nonce";
+		shape = "box";
+		style = "dashed";
+	];
+
+	sign_tx [
+		label = "sign tx";
+		shape = "box";
+	];
+
+	sign_tx_x [
+		xlabel = "SignerError";
+		shape = "point";
+	];
+
+	cache [
+		label = "queue signed tx";
+		shape = "cylinder";
+	];
+
+	gas [
+		label = "safe sender balance for gas?";
+		shape = "diamond";
+	];
+
+	gas_rq_exists [
+		label = "gas request already pending?"
+		shape = "diamond";
+	];
+
+	gas_rq [
+		label = "queue request for gas";
+		shape = "parallelogram";
+	];
+
+	gas_tx [
+		label = "enough gas for this tx?";
+		shape = "diamond";
+	];
+
+	cache_waitforgas [
+		label = "set status to WAITFORGAS";
+		shape = "parallelogram";
+	];
+
+	gas_tx_x [
+		xlabel = "OutOfGasError";
+		shape = "point";
+	];
+
+	tx_fail [
+		label = "temporary error?"
+		shape = "diamond"
+	];
+
+	tx_fail_known [
+		label = "known error?"
+		shape = "diamond"
+	];
+
+	cache_sent [
+		label = "set tx status to SENT";
+		shape = "cylinder";	
+	];
+
+	cache_unsent [
+		label = "set tx status to SENDFAIL";
+		shape = "cylinder";	
+	];
+
+	cache_revert [
+		label = "set tx status to REVERTED";
+		shape = "cylinder";	
+	];
+
+	cache_fubar [
+		label = "set tx status to FUBAR";
+		shape = "cylinder";	
+	];
+
+	send_tx_x_tmp [
+		xlabel = "TemporaryTxError";
+		shape = "point";
+	];
+
+	send_tx_x_final [
+		xlabel = "PermanentTxError";
+		shape = "point";
+	];
+
+	ok [
+		shape = "point";
+	];
+	
+
+	send -> params -> token_lookup;
+	
+	token_lookup -> token_lookup_x [ label = "no"; ];
+
+	token_lookup -> nonce [ label = "yes"; ];
+	nonce -> sign_tx;
+
+	sign_tx -> sign_tx_x [ label = "fail"; ];
+
+	sign_tx -> cache [ label = "ok"; ];
+	cache -> gas;
+
+	gas -> gas_rq_exists [ label = "no"; ];
+	gas_rq_exists -> gas_rq [ label = "no"; ];
+	gas_rq_exists -> gas_tx [ label = "yes"; ];
+	gas_rq -> gas_tx;
+
+	gas -> send_tx [ label = "yes"; ];	
+
+	gas_tx -> cache_waitforgas -> gas_tx_x [ label = "no"; ];
+
+	gas_tx -> send_tx [ label = "yes"; ];
+
+	send_tx -> tx_fail [ label = "fail"; ];
+
+	tx_fail -> cache_unsent [ label = "yes"; ];
+	cache_unsent -> send_tx_x_tmp;
+
+	tx_fail -> tx_fail_known [ label = "no"; ];
+
+	tx_fail_known -> cache_fubar [ label = "no"; ];
+
+	cache_fubar -> send_tx_x_final;
+
+	tx_fail_known -> cache_revert [ label = "yes"; ];
+	cache_revert -> send_tx_x_final;
+
+	send_tx -> cache_sent [ label = "ok"; ];
+	cache_sent -> ok;
+
+}
--- a/apps/cic-eth/doc/flowcharts/readme
+++ b/apps/cic-eth/doc/flowcharts/readme
@@ -0,0 +1,3 @@
+All *_tasks.dot files describe literal the literal tasks that get executed on the associated entry points. CIC-ETH API entrypoints refer to methods in "cic_eth/api/api_task.py"
+
+All *_semantic.dot files are flow charts decribing the processing of the associated entry points.
--- a/apps/cic-eth/doc/flowcharts/register_tasks.dot
+++ b/apps/cic-eth/doc/flowcharts/register_tasks.dot
@@ -0,0 +1,12 @@
+digraph {
+	
+	send [
+		label="CIC-MANAGER\nregistration filter";
+		shape="ellipse";
+	];
+
+	send -> "eth.account.gift" -> "eth.account.cache_gift_data";
+	"eth.account.gift" -> "queue.tx.create";
+	"eth.account.gift" -> "eth.tx.check_gas";
+	"eth.tx.check_gas" -> "eth.tx.refill_gas" [ style="dashed" ];
+}
--- a/apps/cic-eth/doc/flowcharts/send_tasks.dot
+++ b/apps/cic-eth/doc/flowcharts/send_tasks.dot
@@ -0,0 +1,17 @@
+digraph {
+
+	dispatcher [
+		label="CIC-ETH-DISPATCHER";
+		shape="ellipse";
+	];
+
+	send [
+		label="eth.tx.send";
+		shape="ellipse";
+	];
+
+	dispatcher -> send;
+	send -> "queue.tx.set_[sent|final|fubar]_status";
+	send -> "(send tx on blockchain)";
+	"queue.tx.set_[sent|final|fubar]_status" -> send [ style="dashed" ];
+}
--- a/apps/cic-eth/doc/flowcharts/transaction_semantic.dot
+++ b/apps/cic-eth/doc/flowcharts/transaction_semantic.dot
@@ -0,0 +1,104 @@
+digraph G {
+
+	send [
+		label = "transfer";
+		shape = "ellipse";
+	];
+
+	params [
+		label = "get token, value, sender, recipient";
+		shape = "parallelogram";
+	];
+
+	token_lookup [
+		label = "token known?";
+		shape = "diamond";	
+	];
+
+	token_lookup_x [
+		xlabel = "UnknownTokenError";
+		shape = "point";
+	];
+
+	nonce [
+		label = "get sender nonce";
+		shape = "box";
+		style = "dashed";
+	];
+
+	sign_tx [
+		label = "sign tx";
+		shape = "box";
+	];
+
+	sign_tx_x [
+		xlabel = "SignerError";
+		shape = "point";
+	];
+
+	cache [
+		label = "queue signed tx";
+		shape = "cylinder";
+	];
+
+	gas [
+		label = "safe sender balance for gas?";
+		shape = "diamond";
+	];
+
+	gas_rq_exists [
+		label = "gas request already pending?"
+		shape = "diamond";
+	];
+
+	gas_rq [
+		label = "queue request for gas";
+		shape = "parallelogram";
+	];
+
+	gas_tx [
+		label = "enough gas for this tx?";
+		shape = "diamond";
+	];
+
+	cache_waitforgas [
+		label = "set status to WAITFORGAS";
+		shape = "parallelogram";
+	];
+
+	gas_tx_x [
+		xlabel = "OutOfGasError";
+		shape = "point";
+	];
+
+	ok [
+		xlabel = "OK";
+		shape = "point";
+	];
+
+
+	send -> params -> token_lookup;
+	
+	token_lookup -> token_lookup_x [ label = "no"; ];
+
+	token_lookup -> nonce [ label = "yes"; ];
+	nonce -> sign_tx;
+
+	sign_tx -> sign_tx_x [ label = "fail"; ];
+
+	sign_tx -> cache [ label = "ok"; ];
+	cache -> gas;
+
+	gas -> gas_rq_exists [ label = "no"; ];
+	gas_rq_exists -> gas_rq [ label = "no"; ];
+	gas_rq_exists -> gas_tx [ label = "yes"; ];
+	gas_rq -> gas_tx;
+
+	gas -> ok [ label = "yes"; ];	
+
+	gas_tx -> cache_waitforgas -> gas_tx_x [ label = "no"; ];
+
+	gas_tx -> ok [ label = "yes"; ];
+
+
+}
--- a/apps/cic-eth/doc/flowcharts/transaction_tasks.dot
+++ b/apps/cic-eth/doc/flowcharts/transaction_tasks.dot
@@ -0,0 +1,22 @@
+digraph {
+
+	send [
+		label="CIC-ETH API:\ntransfer";
+		shape="ellipse";
+	];
+
+	callback [
+		label="callback";
+		shape="ellipse";
+		style="dashed";
+	];
+
+	send -> "eth.token.resolve_tokens_by_symbol"
+	"eth.token.resolve_tokens_by_symbol" -> "eth.token.transfer" -> "eth.queue.otx_cache_transfer";
+	"eth.token.transfer" -> "eth.queue.tx.create";
+	"eth.token.transfer" -> "eth.tx.check_gas";
+	"eth.tx.check_gas" -> "eth.tx.refill_gas" [ style="dashed" ];
+	"eth.tx.check_gas" -> callback [ style="dashed" ];
+	"eth.tx.refill_gas" -> callback [ style="dashed" ];
+
+}
--- a/apps/cic-eth/doc/flowcharts/transferauthorization_tasks.dot
+++ b/apps/cic-eth/doc/flowcharts/transferauthorization_tasks.dot
@@ -0,0 +1,65 @@
+digraph {
+
+	transferauthorization [
+		label="CIC-ETH API:\ntransfer authorization";
+		shape="ellipse";
+	];
+
+	callback [
+		label="callback";
+		shape="ellipse";
+		style="dashed";
+	];
+
+	resolve_transferauthorization [
+		label="eth.token.resolve_tokens_by_symbol";
+		shape="ellipse";
+	];
+
+	resolve_approve [
+		label="eth.token.resolve_tokens_by_symbol";
+		shape="ellipse";
+	];
+
+	checkgas_transferauthorization [
+		label="eth.tx.check_gas";
+		shape="ellipse";
+	];
+
+	checkgas_approve [
+		label="eth.tx.check_gas";
+		shape="ellipse";
+	];
+
+	refill_transferauthorization [
+		label="eth.tx.refill_gas";
+		shape="ellipse";
+	];
+
+	refill_approve [
+		label="eth.tx.refill_gas";
+		shape="ellipse";
+	];
+
+	queue_create_transferauthorization [
+		label="queue.tx.create";
+		shape="ellipse";
+	];
+
+	queue_create_approve [
+		label="queue.tx.create";
+		shape="ellipse";
+	];
+
+	transferauthorization ->  resolve_approve -> "eth.token.approve" -> "eth.token.otx_cache_approve";
+	"eth.token.approve" -> queue_create_approve;
+	"eth.token.approve" -> checkgas_approve;
+	checkgas_approve -> refill_approve [ style="dashed" ];
+
+	transferauthorization -> resolve_transferauthorization -> "eth.request.transfer_approve_request" -> "eth.token.otx_cache_transfer_approval_request";
+	"eth.request.transfer_approve_request" -> queue_create_transferauthorization;
+	"eth.request.transfer_approve_request" -> checkgas_transferauthorization;
+	checkgas_transferauthorization -> refill_transferauthorization [ style="dashed" ];
+	checkgas_approve -> callback [ style="dashed" ];
+	refill_approve -> callback [ style="dashed" ];
+}
--- a/apps/cic-eth/doc/flowcharts/tx_tasks.dot
+++ b/apps/cic-eth/doc/flowcharts/tx_tasks.dot
@@ -0,0 +1,9 @@
+digraph {
+
+	tx [
+		label="CIC-MANAGER;\ntx_filter";
+		shape="ellipse";
+	];
+
+	tx -> "queue.tx.set_final_status";
+}
--- a/apps/cic-eth/doc/sphinx/Makefile
+++ b/apps/cic-eth/doc/sphinx/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@PYTHONPATH=../.. $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@PYTHONPATH=../.. $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
--- a/apps/cic-eth/doc/sphinx/code.rst
+++ b/apps/cic-eth/doc/sphinx/code.rst
@@ -0,0 +1,56 @@
+Package cic_eth
+===============
+
+.. automodule:: cic_eth
+
+
+Module eth
+==========
+
+.. automodule:: cic_eth.eth
+   :members:
+
+.. automodule:: cic_eth.eth.factory
+   :members:
+
+.. automodule:: cic_eth.eth.tx
+   :members:
+
+.. automodule:: cic_eth.eth.account
+   :members:
+
+.. automodule:: cic_eth.eth.bancor
+   :members:
+
+.. automodule:: cic_eth.eth.token
+   :members:
+
+.. automodule:: cic_eth.eth.tasks
+   :members:
+
+
+Module queue
+============
+
+.. automodule:: cic_eth.queue.tx
+   :members:
+
+
+Module sync
+===========
+
+.. automodule:: cic_eth.sync.base
+   :members:
+
+.. automodule:: cic_eth.sync.mined
+   :members:
+
+.. automodule:: cic_eth.sync.mined
+   :members:
+
+.. automodule:: cic_eth.sync.head
+   :members:
+
+.. automodule:: cic_eth.sync.history
+   :members:
+
--- a/apps/cic-eth/doc/sphinx/conf.py
+++ b/apps/cic-eth/doc/sphinx/conf.py
@@ -0,0 +1,57 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'cic-eth'
+copyright = '2020, Louis Holbrook'
+author = 'Louis Holbrook'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+        'sphinx.ext.autodoc',
+        'celery.contrib.sphinx',
+        'sphinx.ext.todo',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+todo_include_todos = True
--- a/apps/cic-eth/doc/sphinx/index.rst
+++ b/apps/cic-eth/doc/sphinx/index.rst
@@ -0,0 +1,19 @@
+.. cic-indexer documentation master file, created by
+   sphinx-quickstart on Sun Sep 20 13:49:02 2020.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to cic-eth's documentation!
+===================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
--- a/apps/cic-eth/doc/texinfo/old.20210107/Makefile
+++ b/apps/cic-eth/doc/texinfo/old.20210107/Makefile
@@ -0,0 +1,5 @@
+all: html
+
+.PHONY: html
+html:
+	makeinfo --html --output html index.texi
--- a/apps/cic-eth/doc/texinfo/old.20210107/api.texi
+++ b/apps/cic-eth/doc/texinfo/old.20210107/api.texi
@@ -0,0 +1,34 @@
+@node Python API
+@chapter Python API
+
+@section Installation
+
+A @code{setuptools} file is provided to install @code{cic-eth} as a normal python package.
+
+The API will send tasks to the celery and immediately return task @code{uuid}. If an HTTP callback is provided, the result of the operation will be sent to it as a @code{POST} request with @code{application/json} content-type, with the following payload as pseudo-schema:
+
+@verbatim
+{
+	'root': <string: uuid of topmost task in the chain>,
+	'status': <integer: anything but 0 is error>,
+	'message': <contextual data payload>,
+	'result': <return value of last subtask if success, or uuid of last subtask on failure>
+}
+@end verbatim
+
+@subsection API calls
+
+Please refer to inline code docstrings in @file{cic_eth/api.py} for details on API function signatures and behaviors.
+
+@itemize 
+@item
+@code{create_account(...)} - Create a new account and add the private key to the keystore
+@item
+@code{balance(...)} - Query the token balance of an address
+@item
+@code{transfer(...)} - Transfer tokens between addresses
+@item
+@code{convert(...)} - Convert between tokens for same address
+@item
+@code{convert_transfer(...)} - Convert tokens and send destination token to a specified address
+@end itemize
--- a/apps/cic-eth/doc/texinfo/old.20210107/index.texi
+++ b/apps/cic-eth/doc/texinfo/old.20210107/index.texi
@@ -0,0 +1,28 @@
+\input texinfo
+@settitle Grassroots Economics CIC ETH 0.4.1
+
+@copying
+Released 2020 under GPL3
+@end copying
+
+@titlepage
+@title Community Inclusion Currency Network 
+@author Louis Holbrook
+
+@end titlepage
+
+@c
+@contents
+
+@ifnottex
+@node Top
+@top Grassroots Economics CIC ETH
+
+This document describes microservices that send transactions to and process events from an EVM blockchain.
+@end ifnottex
+
+
+@include overview.texi
+@include setup.texi
+@include run.texi
+@include api.texi
--- a/apps/cic-eth/doc/texinfo/old.20210107/overview.texi
+++ b/apps/cic-eth/doc/texinfo/old.20210107/overview.texi
@@ -0,0 +1,42 @@
+@node Overview
+@chapter Overview
+This is the core component for the CIC token network system. It provides a task worker infrastructure to interact with the Ethereum blockchain, aswell as daemons to monitor transactions.
+
+@section Reading this document
+
+Any paths in this document are relative to the root of the cic-eth git repository.
+
+@section Contents
+
+@itemize @bullet
+@item Python API that dispatches celery tasks for high-level actions
+@item Daemon for monitoring the state of and retrying outgoing transactions
+@item Daemon for monitoring new transactions of interest confirmed onchain
+@end itemize
+
+@section Dependencies
+
+Python dependencies can be acquired by running the usual python setup and/or using the provided requiremens.txt file.
+
+The application has the following non-python dependencies:
+
+@itemize @bullet
+@item
+@strong{PostgreSQL}: Database backend.
+@item
+@strong{Redis}: Broker and results for Celery workers.
+@item
+@strong{Bancor contracts}: A clone of the Bancor contact repository
+@item
+@strong{Ethereum node}: A synced ethereum node with keystore
+@end itemize
+
+@section Caveats
+
+The application @emph{must not} use private keys for which transactions may be generated from other sources.
+
+It application retrieves the transaction nonce for every transaction directly from the network. Any transaction submitted to it are passed on to the network with sequential nonces. The caller code needs to keep this in mind when considering whether to allow the account holder to submit additional transaction tasks before the current has been completed.
+
+@section Known issues
+
+The author has not yet figured out how to get @code{pytest-celery} to work with queues. Currently the functional tests hang when trying to run them.
--- a/apps/cic-eth/doc/texinfo/old.20210107/queue.texi
+++ b/apps/cic-eth/doc/texinfo/old.20210107/queue.texi
--- a/apps/cic-eth/doc/texinfo/old.20210107/run.texi
+++ b/apps/cic-eth/doc/texinfo/old.20210107/run.texi
@@ -0,0 +1,34 @@
+@node Running the application
+@chapter Running the application
+
+@section Celery worker
+
+The helper script @file{scripts/cic-eth-tasker.py} will connect to redis and the ethereum node and spawn a worker for all celery tasks.
+
+@section Transaction controller
+
+The celery task chains the process outgoing transactions only send the transactions to the network, after which their responsibility ends. And further processing is handled by @file{scripts/cic-eth-manager.py}.
+
+@subsection Monitor transaction state
+
+Records of transactions are added to the database, and the daemon looks for confirmations in block for these transaction, updating their state accordingly. The resulting state may @emph{only} by either @strong{SUCCESS} or @strong{REVERT}. A transaction is any of these states is finalized and won't be retried.
+
+@subsection Perform transfer after convert
+
+Handles the compound workflow where sender with token @code{A} wishes to send tokens to recipient with token @code{B}.
+
+The task worker only submits the convert transaction, because the actual amount of received tokens is not known before the convert takes place. The full amount of recevied tokens will be transferred after the successful convert.
+
+Convert-then-transfer tasks are recorded separately, and if the controller receive a confirmed convert transaction that has a local record, it submits a new transfer task to the task workers.
+
+@subsection Retry after timeout
+
+@strong{Not yet implemented!}.
+
+If a transaction lingers too long without being confirmed, the controller will attempt to re-submit the task and all its dependent tasks with a higher gas price.
+
+
+@section Transaction monitor
+
+@file{scripts/cic-eth-track.py} looks for token transfer or convert transaction for all known tokens on the network, and stores them in a local database cache.
+
--- a/apps/cic-eth/doc/texinfo/old.20210107/setup.texi
+++ b/apps/cic-eth/doc/texinfo/old.20210107/setup.texi
@@ -0,0 +1,98 @@
+@node Setup
+@chapter Setup
+
+@section Prerequisites
+
+@itemize
+@item A running ETH provider with:
+@itemize
+@item Deployed bancor contracts
+@item Sufficient balances for system accounts
+@end itemize
+@item A running ETH signer provider, that can handle the following 'web3' JSON-RPC calls:
+@itemize
+@item @command{personal_newAccount}
+@item @command{eth_signTransaction}
+@end itemize
+@end itemize
+
+@section Database migration
+
+Execute @code{alembic upgrade head} in @file{cic_eth/db/migrations} to generate the schema in the database.
+
+@section Configuration settings
+
+@file{cic-eth} uses configuration files in @code{'ini'} format. All names are translated to upper case letters, and all values are concatenated to sections with a @key{_}. Example:
+
+@verbatim
+[foo]
+bar_baz = 42
+@end verbatim
+
+The above entry becomes @code{FOO_BAR_BAZ} with value @code{42}
+
+@subsection Database
+@table @code
+@item DATABASE_NAME
+@item DATABASE_USER
+@item DATABASE_PASSWORD
+@item DATABASE_HOST
+@item DATABASE_PORT
+Postgres database settings
+@end table
+
+@subsection Redis
+
+@table @code
+@item REDIS_BROKER_URL
+Redis settings
+@end table
+
+@subsection SSL
+
+@table @code
+@item SSL_ENABLE_CLIENT
+Use SSL client certification for outgoing web requests (boolean)
+@item SSL_CERT_FILE
+Absolute path to client certificate file
+@item SSL_KEY_FILE
+Absolute path to client key file
+@item SSL_PASSWORD
+Password to unlock client key
+@item SSL_CA_FILE
+The client certificate's authority chain
+@end table
+
+@subsection Ethereum
+
+@table @code
+@item ETH_PROVIDER
+URL to JSON-RPC API provider
+@item ETH_GAS_PROVIDER_ADDRESS
+Address providing gas to fund transactions for accounts in keystore
+@end table
+
+@subsection Bancor
+
+@table @code
+@item BANCOR_REGISTRY_ADDRESS
+Contract address for the ContractRegistry contract
+@item BANCOR_DIR
+Absolute path to root of the Bancor Solidity contract GIT repository
+@end table
+
+@subsection Syncer
+
+@table @code
+@item SYNCER_LOOP_DELAY
+Delay in seconds to wait between polls when no data has been found
+@end table
+
+@subsection Signer
+
+@table @code
+@item SIGNER_SECRET (development only)
+Key used by keystore to encrypt secrets
+@item SIGNER_PASSWORD 
+Password for additional private key encryption on keystore
+@end table
--- a/apps/cic-eth/doc/texinfo/old.20210107/transactions.texi
+++ b/apps/cic-eth/doc/texinfo/old.20210107/transactions.texi
@@ -0,0 +1,26 @@
+@chapter Transactions
+
+@section States
+
+@subsection Send transaction to network
+
+@multitable @columnfractions .35 .15 .15 .35
+@headitem Item @tab Exception @tab Action
+
+@item Chain node unreachable
+@tab ChainUnavailableError
+@tab Retry: unlimited, backoff
+
+@item Cannot save tx state to database
+@tab DatabaseUnavailableError
+@tab Crash: Notify by email
+
+@item Signer unreachable
+@tab SignerUnavailableError
+@tab Retry: unlimited, backoff
+
+@item Unknown address
+@tab SignerAccountUnknownError
+@tab Fail
+
+
--- a/apps/cic-eth/doc/texinfo/overview.texi
+++ b/apps/cic-eth/doc/texinfo/overview.texi
@@ -0,0 +1,24 @@
+@node cic-eth
+@chapter cic-eth
+
+@section Overview
+
+@code{cic-eth} is the heart of the custodial account component. It is a combination of python-celery task queues and daemons that sign, dispatch and monitor blockchain transactions, aswell as triggering tasks contingent on other transactions.
+
+@subsection Dependencies
+
+The @code{cic-registry} module is used as a cache for contracts and tokens on the network.
+
+A web3 JSON-RPC service that transparently proxies a keystore and provides transaction and message signing. The current development version uses the python web3 middleware feature to route methodsi involving the keystore to the module @code{crypto-dev-signer}, which is hosted on @file{pypi.org}.
+
+@subsection What does it do
+
+
+
+@subsection Tasks
+
+Two main categories exist for tasks, @code{eth} and @code{queue}.
+
+The @code{eth} tasks provide means to construct and decode Ethereum transactions, as well as interfacing the underlying key store.
+
+Tasks in the @code{queue} module operate on the state of transactions queued for processing by @code{cic-eth}.