From f33ddec7ab54015822b49d0375fda0ba8f385d05 Mon Sep 17 00:00:00 2001 From: Giulio rebuffo Date: Sun, 27 Sep 2020 21:40:48 +0200 Subject: [PATCH] first sphinx doc portion (#1144) * first sphinx doc portion * added .readthedocs.yml * fixed typos --- .gitignore | 3 +- .readthedocs.yml | 10 + docs/readthedocs/Makefile | 19 ++ docs/readthedocs/make.bat | 35 +++ docs/readthedocs/source/accounts.rst | 312 +++++++++++++++++++++++++++ docs/readthedocs/source/conf.py | 174 +++++++++++++++ docs/readthedocs/source/index.rst | 20 ++ 7 files changed, 572 insertions(+), 1 deletion(-) create mode 100644 .readthedocs.yml create mode 100644 docs/readthedocs/Makefile create mode 100644 docs/readthedocs/make.bat create mode 100644 docs/readthedocs/source/accounts.rst create mode 100644 docs/readthedocs/source/conf.py create mode 100644 docs/readthedocs/source/index.rst diff --git a/.gitignore b/.gitignore index 50a9dc8ea..bf380bdfc 100644 --- a/.gitignore +++ b/.gitignore @@ -15,6 +15,7 @@ */**/*dapps* build/_vendor/pkg /*.a +docs/readthedocs/build #* .#* @@ -53,4 +54,4 @@ right_*.txt root_*.txt __pycache__ -docker-compose.dev.yml \ No newline at end of file +docker-compose.dev.yml diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 000000000..3e9e272ce --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,10 @@ +# .readthedocs.yml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/readthedocs/source/conf.py \ No newline at end of file diff --git a/docs/readthedocs/Makefile b/docs/readthedocs/Makefile new file mode 100644 index 000000000..69fe55ecf --- /dev/null +++ b/docs/readthedocs/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(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 + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/readthedocs/make.bat b/docs/readthedocs/make.bat new file mode 100644 index 000000000..4d9eb83d9 --- /dev/null +++ b/docs/readthedocs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/docs/readthedocs/source/accounts.rst b/docs/readthedocs/source/accounts.rst new file mode 100644 index 000000000..be7838d9d --- /dev/null +++ b/docs/readthedocs/source/accounts.rst @@ -0,0 +1,312 @@ +======== +Accounts +======== +The accounts package implements integrates support for various kind of wallets into TurboGeth. +As of now, the following type of wallets are supported: + + * Keystore + * Smart Card wallet + * USB Wallets (E.g ledger) + * External Signers + +Keystore +======== + +The Keystore wallets refers to the wallets contained into the keystore/ directory, which can be generated with `personal.newAccount` in the console. + +The implementantion works with the following components: + * `watcher`, which listen to file system events in the keystore dir, so that it can tell `accountCache` when to scan. + * `fileCache`, track changes in keystore directory. + * `accountCache`, a live index of all accounts in the keystore (uses `watcher`). + * `Key`, it is an address-private_key pair, that is given by `Keystore` when there is an unlock. + * `keystoreWallet`, repressent a wallet + * `keyStorePlain`, it handles plain(unencrypted) keystore. + * `keyStorePassphrase`, it handles encrypted json keystore. + * `Keystore`, it repressent the keystore itself, it uses all the components cited above accordingly to context. + +Keystore: `watcher` +=================== +source: `(accounts/keystore/watch.go)` + +it contains a reference to an `accountCache`. + +listen to file system events in the keystore dir, so that it can tell `accountCache` when to scan. + +.. code-block:: go + + func (w *watcher) start(); + +`start()` starts the `loop()` goroutine. + +.. code-block:: go + + func (w *watcher) close(); + +`stop()` closes the `loop()` goroutine. + +.. code-block:: go + + func (w *watcher) loop(); + +`loop()` is to be used as a goroutine by `start`. It listen for file system events +into the keystore directory and when some are found it makes the `accountCache` scan +the keystore to find out what changed by invoking `scanAccounts()` from `accountCache` + +Keystore: `fileCache` +===================== +source: `(accounts/keystore/fileCache.go)` + +keeps track of changes in keystore directory. + +.. code-block:: go + + func (fc *fileCache) scan(keyDir string) (mapset.Set, mapset.Set, mapset.Set, error) + +Arguments: + * keyDir: directory of Keystore +Returns (if successful) : + * set of created files + * set of deleted files + * set of changed files + +`scan()` returns what file has been added, deleted anc changed after a file system event reported by +`watcher`, its purpose is to tell `accountCache` how to modify the list of accounts accordingly to the new changes. + +Keystore: `accountCache` +======================== +source: `(accounts/keystore/accountCache.go)` + +live index of accounts in keystore. make use of +fileCache and watcher. when watcher detects an event, +accountCache get from fileCache the changes and updates itself accordingly + +.. code-block:: go + + func (ac *accountCache) accounts() []accounts.Account; + +returns the accounts in keystore + +.. code-block:: go + + func (ac *accountCache) hasAddress(addr common.Address) bool; + +returns wheter there is a certain address in keystore + +.. code-block:: go + + func (ac *accountCache) add(newAccount accounts.Account); + +add a new account in live index, this is executed only if `fileCache` detects a file creation or +changes in an existing one. + +.. code-block:: go + + func (ac *accountCache) delete(removed accounts.Account); + +remove an Account in live index, this is executed only if `fileCache` detects a file deletion or +changes in an existing one. + +.. code-block:: go + + func (ac *accountCache) scanAccounts() error; + +it's executed by `watcher` when a file system event in the keystore directory is detected. +it first gets what changed, deleted and added through `fileCache`. +then for each added file, it `add()` them to account list, for file deleted it +`delete()` from the account list the deleted one and if it detects a change: it first +`delete()` the account and then `add()` it back again immediately after. + +Keystore: `Key` +=============== +source: `(accounts/keystore/key.go)` + +`Key` is a address-private_key pair. it is used in plain keystores as a json and in +other external components. + +.. code-block:: go + + type Key struct { + Id uuid.UUID + Address common.Address + PrivateKey *ecdsa.PrivateKey + } + +Keystore: `keystoreWallet` +========================== + +source: `(accounts/keystore/wallet.go)` + +it function as a wallet from the keystore. +it is an accounts.Wallet and its the type of wallet use in `(accounts/keystore/keystore.go)`. +it does **not** implement the following methods from wallet since it behaves like a plain wallet: + + * `open()` + * `close()` + * `SelfDerive()` + * `Derive()` + +.. code-block:: go + + func (w *keystoreWallet) Status() (string, error); + +it checks from the Keystore if the wallet is unlocked or not. the string is: + +.. code-block:: go + + "Unlocked" // unlocked wallet + "Locked" // locked wallet + +"Locked" is returned if the wallet is locked, and "Unlocked" if it is unlocked. + +.. code-block:: go + + func (w *keystoreWallet) Accounts() []accounts.Account; + +returns a list of 1 element which is the account repressented by the wallet. + +.. code-block:: go + + func (w *keystoreWallet) Contains(account accounts.Account) bool + +returns true if account is the same as wallet's. + +.. code-block:: go + + func (w *keystoreWallet) Contains(account accounts.Account) bool + +returns true if account is the same as wallet's. + +.. code-block:: go + + func (w *keystoreWallet) SignData(account accounts.Account, mimeType string, data []byte) ([]byte, error); + func (w *keystoreWallet) SignDataWithPassphrase(account accounts.Account, passphrase, mimeType string, data []byte) ([]byte, error); + func (w *keystoreWallet) SignText(account accounts.Account, text []byte) ([]byte, error); + func (w *keystoreWallet) SignTextWithPassphrase(account accounts.Account, passphrase string, text []byte) ([]byte, error); + func (w *keystoreWallet) SignTx(account accounts.Account, tx *types.Transaction, chainID *big.Int) (*types.Transaction, error); + func (w *keystoreWallet) SignTxWithPassphrase(account accounts.Account, passphrase string, tx *types.Transaction, chainID *big.Int) (*types.Transaction, error); + +the functions above are all used for signing related tasks by using the wallet's account. + +Keystore: `keystorePlain` and `keystorePassphrase` +================================================== + +source: `(accounts/keystore/plain.go)` + +source: `(accounts/keystore/passphrase.go)` + +they both implements these same methods: + +.. code-block:: go + + GetKey(addr common.Address, filename, auth string) (*Key, error) + StoreKey(dir, auth string, scryptN, scryptP int) (accounts.Account, error) + +which are used to store and retrieve the private key of an account into the keystore, the difference beetwen +keystorePlain and keystorePassphrase is that keyStorePlain does not require a password and +the private key is in plain text in the keystore dir, while keystorePassphrase is encrypted with a password. + +Keystore: `Keystore` +==================== + +source: `(accounts/keystore/keystore.go)` + +the Keystore object is a cluster in which all the above components are used accordingly, +it uses `fileCache`, `watcher` and `accountCache` to keep track of the keystore directory and have access to the wallets and +has the power to unlock and use each wallets inside the keystore directory. + +.. code-block:: go + + NewKeyStore(keydir string, scryptN, scryptP int) *KeyStore; + NewPlaintextKeyStore(keydir string) *KeyStore; + +the two function create a plainKeystore or a passphrase encrypted one. + +.. code-block:: go + + func (ks *KeyStore) Wallets() []accounts.Wallet; + +return every accounts in the keystore. + +.. code-block:: go + + func (ks *KeyStore) Subscribe(sink chan<- accounts.WalletEvent) event.Subscription + +creates an async subscription to receive notifications on the addition or removal of keystore wallets. + +.. code-block:: go + + func (ks *KeyStore) HasAddress(addr common.Address) bool; + +returns wheter given account is in keystore. + +.. code-block:: go + + func (ks *KeyStore) Accounts() []accounts.Account; + +returns all accounts in keystore. + +.. code-block:: go + + func (ks *KeyStore) Delete(a accounts.Account, passphrase string); + +delete an account from keystore. passphrase is needed. + +.. code-block:: go + + func (ks *KeyStore) SignData(account accounts.Account, mimeType string, data []byte) ([]byte, error); + func (ks *KeyStore) SignDataWithPassphrase(account accounts.Account, passphrase, mimeType string, data []byte) ([]byte, error); + func (ks *KeyStore) SignText(account accounts.Account, text []byte) ([]byte, error); + func (ks *KeyStore) SignTextWithPassphrase(account accounts.Account, passphrase string, text []byte) ([]byte, error); + func (ks *KeyStore) SignTx(account accounts.Account, tx *types.Transaction, chainID *big.Int) (*types.Transaction, error); + func (ks *KeyStore) SignTxWithPassphrase(account accounts.Account, passphrase string, tx *types.Transaction, chainID *big.Int) (*types.Transaction, error); + +the functions above are all used for signing related tasks by using the wallet's account. + +.. code-block:: go + + func (ks *KeyStore) Lock(addr common.Address) error + +lock a certain account in the keystore and remove the its private key from memory + +.. code-block:: go + + func (ks *KeyStore) TimedUnlock(a accounts.Account, passphrase string, timeout time.Duration) error; + +unlock an account for a given amount of time. + +.. code-block:: go + + func (ks *KeyStore) NewAccount(passphrase string) (accounts.Account, error) + +generates a new `Key` and store the related account in the keystore. + +.. code-block:: go + + func (ks *KeyStore) Export(a accounts.Account, passphrase, newPassphrase string) (keyJSON []byte, err error); + +export given account to json format encrypted with newPassphrase. + +.. code-block:: go + + func (ks *KeyStore) Import(a accounts.Account, passphrase, newPassphrase string) (accounts.Account, error); + +import given account and encrypt key with newPassphrase. + +.. code-block:: go + + func (ks *KeyStore) ImportECDSA(priv *ecdsa.PrivateKey, passphrase string) (accounts.Account, error); + +stores the given key into the key directory, encrypting it with the passphrase. + +.. code-block:: go + + func (ks *KeyStore) Update(a accounts.Account, passphrase, newPassphrase string) error; + +changes the passphrase of an existing account. + +.. code-block:: go + + func (ks *KeyStore) ImportPreSaleKey(keyJSON []byte, passphrase string) (accounts.Account, error); + +decrypts the given Ethereum presale wallet and stores +a key file in the key directory. The key file is encrypted with the same passphrase. \ No newline at end of file diff --git a/docs/readthedocs/source/conf.py b/docs/readthedocs/source/conf.py new file mode 100644 index 000000000..3b08a3835 --- /dev/null +++ b/docs/readthedocs/source/conf.py @@ -0,0 +1,174 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- 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 = u'Turbo Geth' +copyright = u'2020, Ledgerwatch' +author = u'Ledgerwatch' + +# The short X.Y version +version = u'' +# The full version, including alpha/beta/rc tags +release = u'' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# 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.autosectionlabel' +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['.templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# 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 = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# -- 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 = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# 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'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'TurboGethdoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'TurboGeth.tex', u'Turbo Geth Documentation', + u'Ledgerwatch', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'turbogeth', u'Turbo Geth Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'TurboGeth', u'Turbo Geth Documentation', + author, 'TurboGeth', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] diff --git a/docs/readthedocs/source/index.rst b/docs/readthedocs/source/index.rst new file mode 100644 index 000000000..5b8391998 --- /dev/null +++ b/docs/readthedocs/source/index.rst @@ -0,0 +1,20 @@ +.. Turbo Geth documentation master file, created by + sphinx-quickstart on Sat Sep 26 14:43:08 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Turbo Geth's documentation! +====================================== + +.. toctree:: + :maxdepth: 2 + + accounts + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` +* :ref: