diff --git a/.gitignore b/.gitignore old mode 100644 new mode 100755 index 7dcf64d..567609b --- a/.gitignore +++ b/.gitignore @@ -1,8 +1 @@ -build - -# emacs Backup files -*~ - -# MacOS Development -.DS_Store - +build/ diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 9e22099..0000000 --- a/.travis.yml +++ /dev/null @@ -1,15 +0,0 @@ -sudo: false -cache: pypi -language: python -python: - - "2.7" -env: - matrix: - - TOX_ENV=rst_lint -install: - - 'travis_retry pip install setuptools --upgrade' - - 'travis_retry pip install tox' -script: - - tox -e $TOX_ENV -after_script: - - cat .tox/$TOX_ENV/log/*.log diff --git a/Makefile b/Makefile old mode 100644 new mode 100755 index c4c046f..5424faf --- a/Makefile +++ b/Makefile @@ -1,192 +1,18 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = build - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " applehelp to make an Apple Help Book" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " coverage to run coverage check of the documentation (if enabled)" - -clean: - rm -rf $(BUILDDIR)/* +all: + make html + make latex + make pdf html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/homesteadguide.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/homesteadguide.qhc" - -applehelp: - $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp - @echo - @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." - @echo "N.B. You won't be able to view it unless you put it in" \ - "~/Library/Documentation/Help or install it in your application" \ - "bundle." - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/homesteadguide" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/homesteadguide" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + mkdir -p build + sphinx-build -M html "." "build" latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -coverage: - $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage - @echo "Testing of coverage in the sources finished, look at the " \ - "results in $(BUILDDIR)/coverage/python.txt." - -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + mkdir -p build + sphinx-build -M latex "." "build" + +pdf: + mkdir -p build/pdf/latex + sphinx-build -M latexpdf "." "build/pdf" + mv build/pdf/latex/etc_tech_ref.pdf build/pdf/ + rm -rf build/pdf/latex diff --git a/README.rst b/README.rst deleted file mode 100644 index 109fe59..0000000 --- a/README.rst +++ /dev/null @@ -1,145 +0,0 @@ -.. image:: source/img/ethereum-classic-documentation-logo.png -.. :height: 500px -.. :width: 394 px - :scale: 50 % - :alt: ethereum-logo - :align: center - -***************************** -Classic-Guide -***************************** -|Gitter| |readthedoc| - -.. |Gitter| image:: https://badges.gitter.im/ethereumclassic/classic-guide.svg - :target: https://gitter.im/etherumclassic/classic-guide?utm_source=share-link&utm_medium=link&utm_campaign=share-link - - -.. |readthedoc| image:: https://readthedocs.org/projects/ethereum-classic-guide/badge/?version=latest - :target: http://ethereum-classic-guide.readthedocs.io/en/latest/?badge=latest - - -The Ethereum Classic Guide is the reference documentation accompanying the hard-fork of the Ethereum project. - -`Hosted on ReadTheDocs`_ - -HOW YOU CAN HELP -================================================================================ -**Classic Documentation Initiative** - -It doesn't matter if you are a beginner or an expert, there are many ways to help! - -Write Content to the Guide --------------------------------------------------------------------------------- -Help transfer and update content from the Ethereum Wiki, Ethereum Frontier Guide, the Ethereum Stack Exchange, Ethereum Homestead Guide or any other reputable source to relevant pages of the Classic guide. Alternatively, write your own content for the guide based on experience. - -Make sure the documentation you are porting over is still accurate and follows our guidelines for the Classic docs. (http://ethereum-classic-guide.readthedocs.io/en/latest/about.html) - -Review What Has Been Written --------------------------------------------------------------------------------- -Have a look at our guide and give us feedback by visiting our Gitter Chatroom (https://gitter.im/ethereumclassic/classic-guide) or submit a pull request or issue to this repo. Too EZ. - -What's In It For Me? --------------------------------------------------------------------------------- -Your name will forever be immortalized, both in my heart and on the Contributors page in the guide. -As a side effect, you may also get those good feels that you get when you help improve documentation :-) - -GETTING STARTED -====================== - -This project uses Sphinx (http://www.sphinx-doc.org/en/stable/index.html) to build html that is published to Read the Docs. To run this documentation on your computer, you should do the following: - -Prerequisites --------------------------------------------------------------------------------- -* Python 2.6 or later -* git - -Install Sphinx, etc --------------------------------------------------------------------------------- -For OSX/Linux users (based on instructions here: https://read-the-docs.readthedocs.org/en/latest/getting_started.html) - -* From command line: ``sudo pip install sphinx`` - -For Windows users: - -* http://www.sphinx-doc.org/en/stable/install.html#windows-install-python-and-sphinx - -Get source code --------------------------------------------------------------------------------- -* git clone: https://github.com/ethereumclassic/classic-guide.git - -Build and view html --------------------------------------------------------------------------------- -* In a terminal window, go to your classic-guide directory. -* ``make html`` -* ``cd build/html`` -* ``open index.html`` (open in web browser) -* Tip: each time you run ``make html``, just reload your browser to view changes - - -RESOURCES -================================================================================ - -**Classic** - -* Classic Guide online: http://ethereum-classic-guide.readthedocs.io/en/latest/index.html -* Github: https://github.com/ethereumclassic/classic-guide -* Gitter: https://gitter.im/ethereumclassic/classic-guide - -**Homestead and legacy docs** - -* Homestead Guide online: https://ethereum-homestead.readthedocs.org/en/latest/index.html -* Github: https://github.com/ethereum/homestead-guide -* Gitter: https://gitter.im/ethereum/homestead-guide -* Google doc: https://docs.google.com/document/d/1rVjrNgaDRAQdPp4rGqWrEk5fPgiHff0xsYGCyf06oM8/edit -* Ethereum Wiki: https://github.com/ethereum/wiki/wiki -* Frontier Guide: https://ethereum.gitbooks.io/frontier-guide/content/ (see below for converted files) -* Souptacular's Giant List of Ethereum Resources: https://souptacular.gitbooks.io/ethereum-tutorials-and-tips-by-hudson/content/giant_ethereum_resource_list.html - -**Read the Docs and Sphinx** - -- Read the Docs: https://read-the-docs.readthedocs.org/en/latest/getting_started.html -- Sphinx docs: http://www.sphinx-doc.org/en/stable/contents.html -- reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html -- RST cheat sheet: https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst - -Directory structure -========================= - -.. code-block:: - - homestead-guide - build - workdir, not commited to repo - source - actual content in rst - conf.py - sphinx configuration - old-docs-for-reference (Frontier era stuff) - wiki - the legacy wiki - gitbook - the legacy gitbook resources (converted to rst) - make.bat - windows command to build docs - Makefile - platforms with make to build docs - - -Roadmap for Classic Guide -================================================================================ - -* fork homestead guide from ethereum -* compile/deploy on readthedocs -* include cheatsheat, rst/sphinx/readthedocs resources -* reach out to community reddit - classic documentation initiative -* allocate chapters to people (ideally author and reviewer) -* migrate old wiki under frontier/wiki (all md files converted to rst) -* migrate old frontier-guide content under frontier/gitbook (all md content converted to rst) -* script to annotate entire wiki with legacy warning - -Strategy for migrating old Homestead-guide content (Old) -======================================================== - -* temporaritly include resources about the documentation project within the book itself - * rst cheatsheet - * rst/sphinx/readthedocs resources - * compilation/deployment instructions - * link to issues and process - * style guide, conventions -* include the rst conversion of the wiki -* include the rst conversion of the gitbook - -.. _Hosted on ReadTheDocs: https://ethereum-classic-guide.readthedocs.io/en/latest/ diff --git a/make.bat b/make.bat deleted file mode 100644 index 134997c..0000000 --- a/make.bat +++ /dev/null @@ -1,263 +0,0 @@ -@ECHO OFF - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set BUILDDIR=build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source -set I18NSPHINXOPTS=%SPHINXOPTS% source -if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% - set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% -) - -if "%1" == "" goto help - -if "%1" == "help" ( - :help - echo.Please use `make ^` where ^ is one of - echo. html to make standalone HTML files - echo. dirhtml to make HTML files named index.html in directories - echo. singlehtml to make a single large HTML file - echo. pickle to make pickle files - echo. json to make JSON files - echo. htmlhelp to make HTML files and a HTML help project - echo. qthelp to make HTML files and a qthelp project - echo. devhelp to make HTML files and a Devhelp project - echo. epub to make an epub - echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - echo. text to make text files - echo. man to make manual pages - echo. texinfo to make Texinfo files - echo. gettext to make PO message catalogs - echo. changes to make an overview over all changed/added/deprecated items - echo. xml to make Docutils-native XML files - echo. pseudoxml to make pseudoxml-XML files for display purposes - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled - echo. coverage to run coverage check of the documentation if enabled - goto end -) - -if "%1" == "clean" ( - for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* - goto end -) - - -REM Check if sphinx-build is available and fallback to Python version if any -%SPHINXBUILD% 1>NUL 2>NUL -if errorlevel 9009 goto sphinx_python -goto sphinx_ok - -:sphinx_python - -set SPHINXBUILD=python -m sphinx.__init__ -%SPHINXBUILD% 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 -) - -:sphinx_ok - - -if "%1" == "html" ( - %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/html. - goto end -) - -if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. - goto end -) - -if "%1" == "singlehtml" ( - %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. - goto end -) - -if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the pickle files. - goto end -) - -if "%1" == "json" ( - %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the JSON files. - goto end -) - -if "%1" == "htmlhelp" ( - %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run HTML Help Workshop with the ^ -.hhp project file in %BUILDDIR%/htmlhelp. - goto end -) - -if "%1" == "qthelp" ( - %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run "qcollectiongenerator" with the ^ -.qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\homesteadguide.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\homesteadguide.ghc - goto end -) - -if "%1" == "devhelp" ( - %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. - goto end -) - -if "%1" == "epub" ( - %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The epub file is in %BUILDDIR%/epub. - goto end -) - -if "%1" == "latex" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "latexpdf" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - cd %BUILDDIR%/latex - make all-pdf - cd %~dp0 - echo. - echo.Build finished; the PDF files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "latexpdfja" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - cd %BUILDDIR%/latex - make all-pdf-ja - cd %~dp0 - echo. - echo.Build finished; the PDF files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "text" ( - %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The text files are in %BUILDDIR%/text. - goto end -) - -if "%1" == "man" ( - %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The manual pages are in %BUILDDIR%/man. - goto end -) - -if "%1" == "texinfo" ( - %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. - goto end -) - -if "%1" == "gettext" ( - %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The message catalogs are in %BUILDDIR%/locale. - goto end -) - -if "%1" == "changes" ( - %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - if errorlevel 1 exit /b 1 - echo. - echo.The overview file is in %BUILDDIR%/changes. - goto end -) - -if "%1" == "linkcheck" ( - %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - if errorlevel 1 exit /b 1 - echo. - echo.Link check complete; look for any errors in the above output ^ -or in %BUILDDIR%/linkcheck/output.txt. - goto end -) - -if "%1" == "doctest" ( - %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - if errorlevel 1 exit /b 1 - echo. - echo.Testing of doctests in the sources finished, look at the ^ -results in %BUILDDIR%/doctest/output.txt. - goto end -) - -if "%1" == "coverage" ( - %SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage - if errorlevel 1 exit /b 1 - echo. - echo.Testing of coverage in the sources finished, look at the ^ -results in %BUILDDIR%/coverage/python.txt. - goto end -) - -if "%1" == "xml" ( - %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The XML files are in %BUILDDIR%/xml. - goto end -) - -if "%1" == "pseudoxml" ( - %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. - goto end -) - -:end diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/ABI-dream-API.rst b/old-docs-for-reference/go-ethereum-wiki.rst/ABI-dream-API.rst deleted file mode 100644 index bde14a0..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/ABI-dream-API.rst +++ /dev/null @@ -1,90 +0,0 @@ -.. code:: go - - package main - - import "fmt" - - type Type byte - - const ( - AddressTy Type = iota - Int32Ty - Int64Ty - Int256Ty - // .... - ) - - func main() { - // ABI. - abi := ABI{ - Methods: []Method{ - Method{ - Name: "balance", - Const: true, - }, - - Method{ - Name: "send", - Const: false, - Arguments: []Argument{ - Argument{ - Name: "to", - Type: AddressTy, - }, - Argument{ - Name: "amount", - Type: Int256Ty, - }, - }, - }, - }, - } - // The above should be returned by = ParseABI(json) - - account := state.GetAccount(address) - account.SetABI(abi) - - // Hot wallet (to supply transactor) - hot := state.GetAccount(hotAddress) - // "idea" to specify the transactor - state.SetTransactor(hot) - // OR specify it through call - account.Call(hot /* .... see params below */) - - // This will do a local call (const = true) - balance, err := account.Call("balance") - if err != nil { - exit(err) - } - fmt.Println("balance =", balance) - - // This will do an actual transaction (const = false) - ret, err := account.Call("send", Address([]byte("my_address")), Int256("111111111111111111")) - if err != nil { - exit(err) - } - fmt.Println("ret =", ret) - - // "low" level transaction method w/ private key - to := state.GetAccount(toAddress) - tx, err := state.Transact(hot, to, Int256("123"), Int256("123"), Int256("123"), []byte("data")) - if err != nil { - exit(err) - } - fmt.Println("tx =", tx) - - // This should return an error (no private key) - tx, err = state.Transact(to, hot, Int256("123"), Int256("123"), Int256("123"), []byte("data")) - if err != nil { - exit(err) - } - fmt.Println("tx =", tx) - } - - // JSON - /* - [ - { "name" : "balance", "const" : true }, - { "name" : "send", "const" : false, "input" : [ { "name" : "to", "type" : "int256" } ] }, - ] - */ diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Accounts---key-storage-specification.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Accounts---key-storage-specification.rst deleted file mode 100644 index 4c33915..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Accounts---key-storage-specification.rst +++ /dev/null @@ -1,98 +0,0 @@ -**THIS PAGE IS PARTLY OUTDATED! TODO: REFACTOR OR DELETE** - -Accounts / key storage specification -==================================== - -This is an attempt to compile a single, written specification from the -multiple sources which have so far been used for accounts / key storage -specs: - -- Skype calls -- Skype chats -- Email conversations -- Github issues -- Github pull request comments -- Github commits -- Lively in-person discussions in the Amsterdam office. -- Several past instances of the Amsterdam office whiteboard contents. - -Background -========== - -Up until Ethereum PoC 8, the Go client has used a single, default key in -plaintext on disk for use as wallet and for signing all txs. We want to -extend this to have a more generic key storage supporting multiple keys. -We also want an "accounts" abstraction over these keys where an account -corresponds to a key, and a user can have multiple accounts and be able -to send / receive to any of them. - -The goal of this is to support better wallet / account functionality -both in Mist as well as in dapps. - -Specification -============= - -Key Storage ------------ - -The key storage must support: - -1. Generation of new keys -2. Deletion of keys. -3. Multiple, uniquely identifiable keys. -4. Password protection of keys. -5. Persistence of keys (e.g. on disk) -6. Export & Import of keys. -7. Import of pre-sale keys (generated by - https://github.com/ethereum/pyethsaletool) NOTE: this is a different - import functionality than general import (6) -8. Proper use of secure cryptography for key generation, password - protection, key persistence and export format of keys. -9. Mechanism for Backing the keys up – maybe automatically - -Account Manager ---------------- - -0. Account == address of an Ethereum account == address of EC public key - of EC private key the user controls. - -The account manager must support: - -1. Account creation & deletion -2. Multiple, unique accounts. -3. Persistence of accounts (e.g. on disk) -4. An account is mapped to a single key. -5. The account is identifiable by some public, non-sensitive data. E.g. - the Ethereum address of a EC keypair can be used as account - identifier / address. - -Mist ----- - -The Mist UI must support: - -1. Creation of a new account. -2. Display a list of all available accounts (addresses) -3. Copy-paste of account addresses to easily use when receiving funds. -4. Choosing one of the available accounts when sending a tx. -5. Typing password when accessing one of the hot wallet keys -6. Showing the possible ways to temporarily input wallet keys when - needed - -RPC API -------- - -The RPC API must support: - -1. The list of accounts is exposed through the eth\_accounts API: - https://github.com/ethereum/wiki/wiki/JSON-RPC#eth\_accounts -2. Using any of the available accounts as from/sender with the - eth\_transact API: - https://github.com/ethereum/wiki/wiki/JSON-RPC#eth\_transact (NOTE: - the current API definition on that wiki page does not include a - from/sender field!) - -Wallet dapp ------------ - -TODO: diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Assembler.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Assembler.rst deleted file mode 100644 index a291b37..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Assembler.rst +++ /dev/null @@ -1,141 +0,0 @@ -This is the assembler code emitted by the Mutan compiler and which can -be used directly in the ``asm`` expression followed by the asm opcodes. - -Comments can be made using ";" - -.. code:: d - - asm { - push1 10 ; Push 10 to stack - push1 20 ; Push 20 to stack - add ; Add 10 and 20 together - } - -Arithmetic operations -^^^^^^^^^^^^^^^^^^^^^ - -:: - - stop - add - mul - sub - div - sdiv - mod - smod - exp - neg - lt - gt - eq - not - -Bit operations -^^^^^^^^^^^^^^ - -:: - - and - or - xor - byte - -Crypto operations -^^^^^^^^^^^^^^^^^ - -:: - - sha3 - -Context operations -^^^^^^^^^^^^^^^^^^ - -:: - - address - balance - origin - caller - callvalue - calldataload - calldatasize - gasprice - -Block operations -^^^^^^^^^^^^^^^^ - -:: - - prevhash - coinbase - timestamp - number - difficulty - gaslimit - -Storage and execution operations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - pop - dup - swap - mload - mstore - mstore8 - sload - sstore - jump - jumpi - pc - msize - -Call / Create operations -^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - create - call - return - suicide - -Push operations -^^^^^^^^^^^^^^^ - -:: - - push1 - push2 - push3 - push4 - push5 - push6 - push7 - push8 - push9 - push10 - push11 - push12 - push13 - push14 - push15 - push16 - push17 - push18 - push19 - push20 - push21 - push22 - push23 - push24 - push25 - push26 - push27 - push28 - push29 - push30 - push31 - push32 diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Backup-&-restore.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Backup-&-restore.rst deleted file mode 100644 index d7b55fe..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Backup-&-restore.rst +++ /dev/null @@ -1,85 +0,0 @@ -**DO NOT FORGET YOUR PASSWORD** and **BACKUP YOUR KEYSTORE** - -Backup & restore -================ - -Data directory --------------- - -Everything ``geth`` persists gets written inside its data directory -(except for the PoW Ethash DAG, see note below). The default data -directory locations are platform specific: - -- Mac: ``~/Library/Ethereum`` -- Linux: ``~/.ethereum`` -- Windows: ``%APPDATA%/Ethereum`` - -Accounts are stored in the ``keystore`` subdirectory. The contents of -this directories should be transportable between nodes, platforms, -implementations (C++, Go, Python). - -To configure the location of the data directory, the ``--datadir`` -parameter can be specified. See `CLI -Options `__ -for more details. - -***Note:** The `Ethash -DAG `__ -is stored at ``~/.ethash`` (Mac/Linux) or ``~/AppData/Ethash`` (Windows) -so that it can be reused by all clients. You can store this in a -different location by using a symbolic link.* - -Upgrades --------- - -Sometimes the internal database formats need updating (for example, when -upgrade from before 0.9.20). This can be run with the following command -(geth should not be otherwise running): - -:: - - geth upgradedb - -Cleanup -------- - -Geth's blockchain and state databases can be removed with: - -:: - - geth removedb - -This is useful for deleting an old chain and sync'ing to a new one. It -only affects data directories that can be re-created on synchronisation -and does not touch the keystore. - -Blockchain import/export ------------------------- - -Export the blockchain in binary format with: - -:: - - geth export - -Or if you want to back up portions of the chain over time, a first and -last block can be specified. For example, to back up the first epoch: - -:: - - geth export 0 29999 - -Note that when backing up a partial chain, the file will be appended -rather than truncated. - -Import binary-format blockchain exports with: - -:: - - geth import - -*See https://github.com/ethereum/wiki/wiki/Blockchain-import-export for -more info* - -And finally: **DO NOT FORGET YOUR PASSWORD** and **BACKUP YOUR -KEYSTORE** \ No newline at end of file diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Blockpool.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Blockpool.rst deleted file mode 100644 index d1dc86d..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Blockpool.rst +++ /dev/null @@ -1,360 +0,0 @@ -technical notes to the go-ethereum blockchain synchronisation module - -Intro ------ - -An Ethereum node needs to acquire the set of blocks from which the -current consensus can be proved. This includes scenarios where the node -starts up from scratch (i.e., with an empty database) in which case the -block pool acts as a *download manager* as well as normal operation -where the node needs to synchronize recent blocks by finding the best -candidate new blocks. Since network latency and disruption can cause any -amount of blocks to be missed the two scenarios can be considered the -same task: finding the best chain to give to the blockchain manager. - -**Goal**: The Blockpool needs to find the best chain to be inserted in -the blockchain. - -In order the achieve this, the blockpool can only rely on p2p -communication using the `Ethereum wire -protocol `__. - -Terminology ------------ - -The blockchain database is a tree structure with exactly one root, the -*genesis block* and contains at least one leaf node. The consensus -protocol specifies that the block with the highest *total difficulty* is -the consensus state. The total difficulty of a block is always strictly -higher than that of its parent, so a consensus state is always a leaf -node. The current known best block is also called the *head block* of -the node. When the node is starting up the first time with an empty -database, the head block is the genesis block itself. - -A *chain* is any sequence of blocks connecting a root with a leaf node. -The leaf node with the highest total difficulty is the head of the block -chain which specifies the consensus state of the network. The chain -connecting the genesis block with the head is the *canonical chain*. - -A sequence of blocks or block hashes that form a contiguous subsequence -of a chain is called a *section*. The youngest section of blocks headed -by the peer's current head is called the peer's *head section*. - -If there are two different blocks with the same parent, the chain has a -*fork*. Those blocks which do not end up on the canonical chain are -called *stale* blocks, a sequence of such blocks is a *stale section*. - -The Blockpool stores a pool of blocks which have not been processed yet, -thus it acts as a queue or processing buffer for the blockchain manager. -Therefore the notions of chain, fork, section, etc. carry over to -sequences of blocks and blockhashes in the blockpool. - -Interface with network protocol and peers ------------------------------------------ - -As a proper decentralised consensus system, Ethereum relies only on -other peers to synchronise. The `eth wire -protocol `__ -defines the messages that the blockpool can use to communicate. For a -naive new node, the only entry point to the blockchain is the head block -advertised by a peer as part of their status message (``StatusMsg``, -i.e., protocol handshake) or when a ``NewBlockMsg`` is received from a -miner. A sequence of block hashes can be requested and received with -``getBlockHashesMsg``/``BlockHashesMsg`` message pair. A set of blocks -can be requested and received with ``getBlocksMsg``/``BlocksMsg`` -message pair. - -Although the exact way synchronisation is done is not specified by -either the wire protocol or the block chain consensus protocol, the -messages provided restrict the synchronisation process: - -**Synchronisation**: proceeds from head to known block by requesting and -fetching block hashes iteratively from young to old (head to root). -Based on block hashes, blocks can be requested. Based on the parenthash -of a block, independent sections can be linked and a chain established. -By checking if a block is found in the block chain the root of the -blockpool can be established and the chain can be inserted in the -blockchain. - -We will elaborate on how exactly this is done below. - -Our implementation currently provide 4 entry points to the blockpool for -the ``eth`` protocol instances running on each peer. These get called -when a message relevant to blockchain synchronisation is received from -the peer. - -Adding and removing a peer -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -```AddPeer`` `__ -is `called by the ``eth`` -protocol `__ -right after receiving the `*status message* <>`__ (or protocol -handshake) from a peer. The blockpool registers the peer with -information about its total difficulty and current head block. It also -registers *peer callbacks* so that the blockpool can send requests -directly to a peer (``requestBlockHashes`` and ``requestBlocks``) and -report a peer error (``peerError``). - -Once a peer is removed (disconnect or eviction), the `protocol calls -back `__ -to the BlockPool to unregister the peer with -```RemovePeer`` `__. - -The blockpool synchronisation relies on choosing the *best peer* out of -the connected peers. The best peer is defined as the peer with the -highest advertised total difficulty that is ahead of us. The blockpool -works by following and replicating the best peer's canonical chain. - -**Strategy**: follow the best peer and replicate its canonical chain. - -In our architecture the Blockpool controls peer selection only -indirectly. If a peer violates a blockpool policy, the blockpool reports -it as a peer error. If the error is fatal, the peer is disconnected and -suspended for ``PeerSuspensionInterval``. Synchronisation therefore -crucially relies on a healthy network (i.e., connectivity as well as -efficient message relaying). - -Choosing the best peer -^^^^^^^^^^^^^^^^^^^^^^ - -Every time a peer is registered, its total difficulty is checked against -the best peer. If it is higher, the peer is *promoted as best peer*. -Every time the best peer disconnects, a new "second best" peer is -promoted. Surely this is limited to peers that are ahead of us, i.e., -ones with advertised total difficulty strictly greater than ours. - -Since our own total difficulty can change when mining, the blockpool -needs to receive updates of the last total difficulty. This is achieved -by subscribing to ``ChainHeadEvent`` posted in the blockchain manager. A -blockpool update routine is listening to these total difficulty updates -and if it finds that our own total difficulty goes above that of the -best peer, the peer is demoted (our own node becomes the best peer as it -were). Note that because of forks it is not sufficient to check if we -already have the head block of a peer. - -Adding and updating peer info -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The total difficulty determining best peer status is communicated in one -of the following 4 ways: - -- when a peer is connected, the ``eth`` protocol receives its status - message that contains the total difficulty of the peer as well as its - current block hash. If this total difficulty is higher than that of - self and other peers, a peer switch happens: the new peer is promoted - best peer, the current best peer (if there was one) is demoted. -- when `a new block message - arrives `__, - it contains the new total difficulty, as well as the head block - (including its header hash). To allow for the update of peers head - info and a potential peer switch, the `protocol calls - ``AddPeer`` `__. - In the special case when a new block message arrives from the best - peer, its head information is updated and a new process is launched - to obtain the peer's new head section. -- when a peer sends a block, it can optionally include the total - difficulty *td*. The head information on the peer `gets updated <>`__ - in this case as well. Since we requested this block, it cannot be the - head of the pool. However if the current best peer as well as all - others with difficulty above *td* get disconnected, this peer can be - choosen as best peer. - -Add block hashes -~~~~~~~~~~~~~~~~ - -The third entry poing, -```AddBlockHashes`` `__ -is `called by the ``eth`` -protocol `__ -when a ``blockHashesMsg`` (blockhashes message) arrives. Since the -blockpool needs to follow the canonical chain of the best peer at all -times, only the best peer can add block hashes. If this is not the case, -``AddBlockHashes`` returns without effect. - -Add blocks -~~~~~~~~~~ - -```AddBlocks`` `__ -is `called by the ``eth`` -protocol `__ -when a ``blocksMsg`` (blocks message) arrives. The various blocks are -requested from multiple peers therefore they are accepted from any peer. -The peer is recorded on the pool node as the source of the block, this -makes it possible to assign an error to the peer in case the block is -invalid. - -Synchronisation ---------------- - -Once a peer is promoted as best peer (total difficulty, and current -chain head block registered) a *head section process* is started, which -first requests from the peer the head block itself. Once the head block -is received, blockhashes starting from the peer's head block are -requested from the best peer. - -Once a response is received (and the protocol calls ``AddBlockHashes``), -the sequence of block hashes in the response from the best peer are used -to build up a sequence nodes replicating the head section of the peer's -canonical chain. If the peer fails to respond to requests, after a -period of -```blockTimeout`` `__, -an ``ErrInsufficientChainInfo`` error is raised. As a consequence, the -peer is disconnected and suspended for ``PeerSuspensionInterval`` during -which it is not allowed to reconnect. - -Once the head section nodes are set up, the blockpool starts requesting -blocks for that section. The requests are distributed among multiple -peers so that fetching is optimised. - -If the root block of a section is received, then we can connect a -section to its parent section (the root block's parent is the parent -section's head block). We can repeat requesting blockhashes for the -parent section since now we have a way to tell if they arrived. - -Once a batch of hashes is received, the node skeleton for the new -section is built, and a process similar to the head section process is -repeated in a somewhat simplified form. To recap, each section runs its -own parallel process with 2 main objective: - get hashes for its parent -section, and - obtain the blocks in the section. This is achieved by - -requesting hashes starting from the root (bottom) node of the section - -requesting blocks based on the hashes in the section - -Block requests are distributed among connected peers to optimise -bandwidth utilisation. - -With this recursive strategy, a chain is getting built from young to old -blocks section by section. This process is repeated until a known block -is reached. If the known block is found in the blockchain, the -descendent blocks in the chain can be inserted to the blockchain. If the -block is known to the blockpool, i.e., it is found in a known section, -then the peer is registered with the section's process. This means that -the section is requesting and receiving blocks because the section is -part of the best peer's canonical chain. If block insertion reveals an -invalid block, its source (may not be online any more) is given a -``ErrInvalidBlock`` error resulting in disconnect and suspension. - -If a block process does not complete within a set period of time -```blockTimeout`` `__, -the chain is killed and the synchronisation is reattempted with -(potentially) new peers. Note that these timeouts are needed to protect -against attacks where a rogue peer is sending random blockhashes -indefinitely. - -Interface to Ethereum core --------------------------- - -The interface of the Blockpool with the core is defined with the help of -4 entry points. These are specified as parameters to the `blockpool -constructor <>`__. - -Block verification -~~~~~~~~~~~~~~~~~~ - -Initial block validation that does not require the block to have a known -(already processed and valid) parent block. `Soft proof of work -validation `__ -is such a step. - -This is used as a first line of defence: when received, blocks are -verified, which by putting a cost to make a peer accept your block, -protects against simple spamming. If PoW verification fails the sender -peer receives an ``ErrInvalidPoW`` error. As a consequence, it is -disconnected and not allowed to reconnect for -```PeerSuspensionInterval`` `__ - -Inserting a block into blockchain -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Add one or more blocks on top of a known block. See -```ChainManager.InsertChain`` `__ -The chain manager runs the vm and does proper block validation as well -as establishes which block has the highest total difficulty defining the -head of the node. If the chain manager finds a block invalid, the peer -that supplied the block receives an ``ErrInvalidBlock`` error and as a -consequence, gets disconnected and suspended for -``PeerSuspensionInterval``. After successfully inserting blocks, if the -block is or was the head block of a peer, the blockpool also checks if -the block's actual total difficulty is identical to one advertised by -the peer. If it is not, the peer received an ``ErrIncorrectTD`` and as a -consequence gets disconnected and suspended for -``PeerSuspensionInterval``. This protects against rogue peers -advertising a high total difficulty and forcing us to follow their -(potentially non-canonical) chain. - -Query if block is known -~~~~~~~~~~~~~~~~~~~~~~~ - -When receiving block hashes and blocks, we need to check whether the -block is already in the blockchain. See -```ChainManager.HasBlock`` `__. - -Current Total Difficulty -~~~~~~~~~~~~~~~~~~~~~~~~ - -`Subscription to new block event <>`__, to help set and reset current -total difficulty of our head block. This is needed to filter out -candidate best peers that are behind and therefore useless. - -Further features and optimisations ----------------------------------- - -- maximise bandwidth utilisation by running parallel section processes - fetching blocks -- peer switch: section processes that are part of a stale fork (not on - the canonical chain of the new best peer) are put to *idle mode*, - i.e., parent section hash requests and block requests are not sent, - missing blocks are not checked. Only the absolute deadline timer is - active on this process. -- resilience to quick peers switches when several competing miners are - connected -- section process caching: if a registered active peer is promoted best - peer not for the first time during its connection, all non-contiguous - series of sections are activated (they may or may not have been part - of the canonical chain of the previous best peer) -- In order to help optimise mining, blocks are inserted into the - blockchain the earliest possible time (not waiting for the entire - section to be processed for instance). - -Known limitations ------------------ - -The parameters are not currently optimised or even tried against other -settings. This includes batch size, section length, timeouts, and block -request distribution strategy. - -When distributing block requests, we could in principle be smarter and -do not request blocks from peers with a known lower difficulty. It is -unclear how certain we can be of peers state, since they could have -caught up synchronising since we received any information about their -head. - -In case of a network outage, the timeouts are still ticking, if the -connection is intermittent, this could cause a lot of repeated work -rebuilding the same sections over and over. - -Errors ------- - -The Blockpool uses these -`errors `__ -that are meant to be 'assigned' to peers. - -- ``ErrInvalidBlock`` : Invalid block. Block insertion fails. (Fatal) -- ``ErrInvalidPoW``: Invalid PoW. Light block verification fails. - (Fatal) -- ``ErrUnrequestedBlock``: Unrequested block. Error when there is an - attempt to add a block to the pool, but there is no skeleton node for - the blockhash. -- ``ErrInsufficientChainInfo``: Insufficient chain info. This error is - raised if the best peer fails to provide the block for their - advertised current block hash or fail to provide a sequence of - ancestor hashes of which the *head section* is build up. (Fatal) -- ``ErrIdleTooLong``: Idle too long. This error is raised if the best - peer does not send a new block message after an idle period. (Fatal) -- ``ErrIncorrectTD``: Incorrect ID. Raised when the peer is found to - advertise incorrect TD for their head block. (Fatal) - -Fatal errors lead to the peer getting disconnected and suspended for a -period of ``PeerSuspensionInterval`` for the duration of which they are -not allowed to reconnect. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Building-Edge.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Building-Edge.rst deleted file mode 100644 index 070d841..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Building-Edge.rst +++ /dev/null @@ -1,45 +0,0 @@ -We assume you have a GOPATH set up appropriately. If not, you can read -about setting it up here: http://golang.org/doc/code.html#GOPATH. - -In order to 'build edge', we need to switch 3 repos to their 'develop' -branch - -- Begin by getting the newest version of the go client source and their - dependencies: - - :: - - go get -u -d github.com/obscuren/serpent-go - go get -u -d github.com/ethereum/go-ethereum/ethereum - go get -u -d github.com/ethereum/go-ethereum/mist - -- Init the serpent submodule - - :: - - cd $GOPATH/src/github.com/obscuren/serpent-go - git submodule init - git submodule update - -- Switch to the ``develop`` branch the necessary repos: - - :: - - cd $GOPATH/src/github.com/ethereum/go-ethereum - git checkout develop - - cd $GOPATH/src/github.com/ethereum/eth-go - git checkout develop - - cd $GOPATH/src/github.com/obscuren/mutan - git checkout develop - -- Go forth and build away: - - :: - - cd $GOPATH/src/github.com/ethereum/go-ethereum/ethereum - go install -v - - cd $GOPATH/src/github.com/ethereum/go-ethereum/mist - go install -v diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Building-Ethereum.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Building-Ethereum.rst deleted file mode 100644 index ee9b96c..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Building-Ethereum.rst +++ /dev/null @@ -1,35 +0,0 @@ -Installation Instructions -------------------------- - -Follow the appropriate link below to find installation instructions for -your platform. - -- `Installation Instructions for Mac OS - X `__ -- `Installation Instructions for - Windows `__ -- Installation Instructions for Linux/Unix -- `Ubuntu `__ -- `Arch `__ -- `FreeBSD `__ -- `Setup for Raspberry - Pi `__ -- `ARM `__ -- `Usage instructions for - Docker `__ - -You can also use a one-line script install Geth. Open a command line or -terminal tool (if you are unsure how to do this, consider waiting for a -more user friendly release) and paste the command below: - -:: - - bash <(curl -L https://install-geth.ethereum.org) - -This script will detect your OS and will attempt to install the Ethereum -CLI. For more options including package managers, check the OS-specific -subsections. - -Further links \* `Compiled binaries on launchpad.net buildbot -listings `__ \* `Ethereum -buildbot `__ diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Building-Qt.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Building-Qt.rst deleted file mode 100644 index 5157139..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Building-Qt.rst +++ /dev/null @@ -1,34 +0,0 @@ -Ethereum(Go) Requires QML 5.4+ - -Mac OS X --------- - -Please see `build instruction for -OSX `__ - -Linux ------ - -Ubuntu 14.04 -~~~~~~~~~~~~ - -:: - - sudo apt-get install pkg-config - sudo add-apt-repository ppa:ethereum/ethereum-qt - sudo apt-get update - sudo apt-get install -y qtbase5-dev qtbase5-private-dev libqt5opengl5-dev qtdeclarative5-dev qml-module-qtquick-controls qml-module-qtquick-dialogs libqt5webengine5-dev - -Now it's time to build Qt: - -:: - - go get -u github.com/obscuren/qml - cd $GOPATH/src/github.com/obscuren/qml && git checkout v1 - go build - -If you receive an error about not being able to find Qt\* items, check -that PKG\_CONFIG\_PATH and LD\_LIBRARY\_PATH have been set -(``echo $PKG_CONFIG_PATH`` and ``echo $LD_LIBRARY_PATH``) and if not, -running ``source /opt/qt54/bin/qt54-env.sh`` will set the variables for -the current session. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Command-Line-Options.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Command-Line-Options.rst deleted file mode 100644 index ab17e07..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Command-Line-Options.rst +++ /dev/null @@ -1,242 +0,0 @@ -Command line options -==================== - -:: - - NAME: - geth - the go-ethereum command line interface - - USAGE: - geth [options] command [command options] [arguments...] - - VERSION: - 1.3.1 - - COMMANDS: - recover Attempts to recover a corrupted database by setting a new block by number or hash - blocktest loads a block test file - import import a blockchain file - export export blockchain into file - upgradedb upgrade chainblock database - removedb Remove blockchain and state databases - dump dump a specific block from storage - monitor Geth Monitor: node metrics monitoring and visualization - makedag generate ethash dag (for testing) - gpuinfo gpuinfo - gpubench benchmark GPU - version print Ethereum version numbers - wallet Ethereum presale wallet - account manage accounts - console Geth Console: interactive JavaScript environment - attach Geth Console: interactive JavaScript environment (connect to node) - js executes the given JavaScript files in the Geth JavaScript VM - help, h Shows a list of commands or help for one command - - ETHEREUM OPTIONS: - --datadir "/home/youruser/.ethereum" Data directory for the databases and keystore - --networkid "1" Network identifier (integer, 0=Olympic, 1=Frontier, 2=Morden) - --olympic Olympic network: pre-configured pre-release test network - --testnet Morden network: pre-configured test network with modified starting nonces (replay protection) - --dev Developer mode: pre-configured private network with several debugging flags - --genesis Insert/overwrite the genesis block (JSON format) - --identity Custom node name - --fast Enables fast syncing through state downloads - --cache "0" Megabytes of memory allocated to internal caching (min 16MB / database forced) - --blockchainversion "3" Blockchain version (integer) - - ACCOUNT OPTIONS: - --unlock Unlock an account (may be creation index) until this program exits (prompts for password) - --password Password file to use with options/subcommands needing a pass phrase - - API AND CONSOLE OPTIONS: - --rpc Enable the HTTP-RPC server - --rpcaddr "127.0.0.1" HTTP-RPC server listening interface - --rpcport "8545" HTTP-RPC server listening port - --rpcapi "db,eth,net,web3" API's offered over the HTTP-RPC interface - --ipcdisable Disable the IPC-RPC server - --ipcapi "admin,db,eth,debug,miner,net,shh,txpool,personal,web3" API's offered over the IPC-RPC interface - --ipcpath "/home/youruser/.ethereum/geth.ipc" Filename for IPC socket/pipe - --rpccorsdomain Domains from which to accept cross origin requests (browser enforced) - --jspath "." JavaSript root path for `loadScript` and document root for `admin.httpGet` - --exec Execute JavaScript statement (only in combination with console/attach) - - NETWORKING OPTIONS: - --bootnodes Space-separated enode URLs for P2P discovery bootstrap - --port "30303" Network listening port - --maxpeers "25" Maximum number of network peers (network disabled if set to 0) - --maxpendpeers "0" Maximum number of pending connection attempts (defaults used if set to 0) - --nat "any" NAT port mapping mechanism (any|none|upnp|pmp|extip:) - --nodiscover Disables the peer discovery mechanism (manual peer addition) - --nodekey P2P node key file - --nodekeyhex P2P node key as hex (for testing) - - MINER OPTIONS: - --mine Enable mining - --minerthreads "8" Number of CPU threads to use for mining - --minergpus List of GPUs to use for mining (e.g. '0,1' will use the first two GPUs found) - --autodag Enable automatic DAG pregeneration - --etherbase "0" Public address for block mining rewards (default = first account created) - --gasprice "50000000000" Minimal gas price to accept for mining a transactions - --extradata Block extra data set by the miner (default = client version) - - GAS PRICE ORACLE OPTIONS: - --gpomin "50000000000" Minimum suggested gas price - --gpomax "500000000000" Maximum suggested gas price - --gpofull "80" Full block threshold for gas price calculation (%) - --gpobasedown "10" Suggested gas price base step down ratio (1/1000) - --gpobaseup "100" Suggested gas price base step up ratio (1/1000) - --gpobasecf "110" Suggested gas price base correction factor (%) - - VIRTUAL MACHINE OPTIONS: - --vmdebug Virtual Machine debug output - --jitvm Enable the JIT VM - --forcejit Force the JIT VM to take precedence - --jitcache "64" Amount of cached JIT VM programs - - LOGGING AND DEBUGGING OPTIONS: - --verbosity "3" Logging verbosity: 0-6 (0=silent, 1=error, 2=warn, 3=info, 4=core, 5=debug, 6=debug detail) - --vmodule "" Per-module verbosity: comma-separated list of =, where is file literal or a glog pattern - --backtrace ":0" Request a stack trace at a specific logging statement (e.g. "block.go:271") - --logfile Log output file within the data dir (default = no log file generated) - --pprof Enable the profiling server on localhost - --pprofport "6060" Profile server listening port - --metrics Enable metrics collection and reporting - - EXPERIMENTAL OPTIONS: - --shh Enable Whisper - --natspec Enable NatSpec confirmation notice - - MISCELLANEOUS OPTIONS: - --solc "solc" Solidity compiler command to be used - --help, -h show help - -Note that the default for datadir is platform-specific. See `backup & -restore `__ -for more information. - -Examples --------- - -Accounts -~~~~~~~~ - -See `Account -management `__ - -Import ether presale wallet into your node (prompts for password): - -:: - - geth wallet import /path/to/my/etherwallet.json - -Import an EC privatekey into an ethereum account (prompts for password): - -:: - - geth account import /path/to/key.prv - -Geth JavaScript Runtime Environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -See `Geth javascript -console `__ - -Bring up the geth javascript console: - -:: - - geth --verbosity 5 --jspath /mydapp/js console 2>> /path/to/logfile - -Execute ``test.js`` javascript using js API and log Debug-level messages -to ``/path/to/logfile``: - -:: - - geth --verbosity 6 js test.js 2>> /path/to/logfile - -Import/export chains and dump blocks -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Import a blockchain from file: - -:: - - geth import blockchain.bin - -Upgrade chainblock database -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When the consensus algorithm is changed blocks in the blockchain must be -reimported with the new algorithm. Geth will inform the user with -instructions when and how to do this when it's necessary. - -:: - - geth upgradedb - -Mining and networking -~~~~~~~~~~~~~~~~~~~~~ - -Start two mining nodes using different data directories listening on -ports 30303 and 30304, respectively: - -:: - - geth --mine --minerthreads 4 --datadir /usr/local/share/ethereum/30303 --port 30303 - geth --mine --minerthreads 4 --datadir /usr/local/share/ethereum/30304 --port 30304 - -Start an rpc client on port 8000: - -:: - - geth --rpc=true --rpcport 8000 --rpccorsdomain '"*"' - -Launch the client without network: - -:: - - geth --maxpeers 0 --nodiscover --networdid 3301 js justwannarunthis.js - -Resetting the blockchain -^^^^^^^^^^^^^^^^^^^^^^^^ - -In the datadir, delete the blockchain directory. For an example above: - -:: - - rm -rf /usr/local/share/ethereum/30303/blockchain - -Sample usage in testing environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The lines below are meant only for test network and safe environments -for non-interactive scripted use. - -:: - - geth --datadir /tmp/eth/42 --password <(echo -n notsosecret) account new 2>> /tmp/eth/42.log - geth --datadir /tmp/eth/42 --port 30342 js <(echo 'console.log(admin.nodeInfo().NodeUrl)') > enode 2>> /tmp/eth/42.log - geth --datadir /tmp/eth/42 --port 30342 --password <(echo -n notsosecret) --unlock primary --minerthreads 4 --mine 2>> /tmp/eth/42.log - -Attach -~~~~~~ - -Attach a console to a running geth instance. By default this happens -over IPC over the default IPC endpoint but when necessary a custom -endpoint could be specified: - -:: - - geth attach ipc:/some/path - geth attach rpc:http://host:8545 - -Alternative ways to set flags ------------------------------ - -**WARNING:** This is not available for the latest frontier. - -The same flags can be set via config file (by default -``/conf.ini``) as well as environment variables. - -**Precedence**: default < config file < environment variables < command -line diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Connecting-to-the-network.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Connecting-to-the-network.rst deleted file mode 100644 index e81b762..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Connecting-to-the-network.rst +++ /dev/null @@ -1,171 +0,0 @@ -Connecting to the network -========================= - -How Peers Are Found -------------------- - -Geth continuously attempts to connect to other nodes on the network -until it has peers. If you have UPnP enabled on your router or run -Ethereum on an Internet-facing server, it will also accept connections -from other nodes. - -Geth finds peers through something called the discovery protocol. In the -discovery protocol, nodes are gossipping with each other to find out -about other nodes on the network. In order to get going initially, geth -uses a set of bootstrap nodes whose endpoints are recorded in the source -code. - -To change the bootnodes on startup, use the ``--bootnodes`` option and -separate the nodes by spaces. For example: - -:: - - geth --bootnodes "enode://pubkey1@ip1:port1 enode://pubkey2@ip2:port2 enode://pubkey3@ip3:port3" - -Common Problems With Connectivity ---------------------------------- - -Sometimes you just can't get connected. The most common reasons are as -follows: - -- Your local time might be incorrect. An accurate clock is required to - participate in the Ethereum network. Check your OS for how to resync - your clock (example sudo ntpdate -s time.nist.gov) because even 12 - seconds too fast can lead to 0 peers. -- Some firewall configurations can prevent UDP traffic from flowing. - You can use the static nodes feature or ``admin.addPeer()`` on the - console to configure connections by hand. - -To start geth without the discovery protocol, you can use the -``--nodiscover`` parameter. You only want this is you are running a test -node or an experimental test network with fixed nodes. - -Checking Connectivity ---------------------- - -To check how many peers the client is connected to in the interactive -console, the ``net`` module has two attributes give you info about the -number of peers and whether you are a listening node. - -.. code:: js - - > net.listening - true - > net.peerCount - 4 - -To get more information about the connected peers, such as IP address -and port number, supported protocols, use the ``peers()`` function of -the ``admin`` object. ``admin.peers()`` returns the list of currently -connected peers. - -:: - - > admin.peers - [{ - ID: 'a4de274d3a159e10c2c9a68c326511236381b84c9ec52e72ad732eb0b2b1a2277938f78593cdbe734e6002bf23114d434a085d260514ab336d4acdc312db671b', - Name: 'Geth/v0.9.14/linux/go1.4.2', - Caps: 'eth/60', - RemoteAddress: '5.9.150.40:30301', - LocalAddress: '192.168.0.28:39219' - }, { - ID: 'a979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c', - Name: 'Geth/v0.9.15/linux/go1.4.2', - Caps: 'eth/60', - RemoteAddress: '52.16.188.185:30303', - LocalAddress: '192.168.0.28:50995' - }, { - ID: 'f6ba1f1d9241d48138136ccf5baa6c2c8b008435a1c2bd009ca52fb8edbbc991eba36376beaee9d45f16d5dcbf2ed0bc23006c505d57ffcf70921bd94aa7a172', - Name: 'pyethapp_dd52/v0.9.13/linux2/py2.7.9', - Caps: 'eth/60, p2p/3', - RemoteAddress: '144.76.62.101:30303', - LocalAddress: '192.168.0.28:40454' - }, { - ID: 'f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0', - Name: '++eth/Zeppelin/Rascal/v0.9.14/Release/Darwin/clang/int', - Caps: 'eth/60, shh/2', - RemoteAddress: '129.16.191.64:30303', - LocalAddress: '192.168.0.28:39705' - } ] - -To check the ports used by geth and also find your enode URI run: - -:: - - > admin.nodeInfo - { - Name: 'Geth/v0.9.14/darwin/go1.4.2', - NodeUrl: 'enode://3414c01c19aa75a34f2dbd2f8d0898dc79d6b219ad77f8155abf1a287ce2ba60f14998a3a98c0cf14915eabfdacf914a92b27a01769de18fa2d049dbf4c17694@[::]:30303', - NodeID: '3414c01c19aa75a34f2dbd2f8d0898dc79d6b219ad77f8155abf1a287ce2ba60f14998a3a98c0cf14915eabfdacf914a92b27a01769de18fa2d049dbf4c17694', - IP: '::', - DiscPort: 30303, - TCPPort: 30303, - Td: '2044952618444', - ListenAddr: '[::]:30303' - } - -Custom Networks ---------------- - -Sometimes you might not need to connect to the live public network, you -can instead choose to create your own private testnet. This is very -useful if you don't need to test external contracts and want just to -test the technology, because you won't have to compete with other miners -and will easily generate a lot of test ether to play around (replace -12345 with any non-negative number): - -:: - - geth -—networkid="12345" console - -It is also possible to run geth with a custom genesis block from a JSON -file by supplying the ``--genesis`` flag. The genesis JSON file should -have the following format: - -.. code:: js - - { - "alloc": { - "dbdbdb2cbd23b783741e8d7fcf51e459b497e4a6": { - "balance": "1606938044258990275541962092341162602522202993782792835301376" - }, - "e6716f9544a56c530d868e4bfbacb172315bdead": { - "balance": "1606938044258990275541962092341162602522202993782792835301376" - }, - ... - }, - "nonce": "0x000000000000002a", - "difficulty": "0x020000", - "mixhash": "0x0000000000000000000000000000000000000000000000000000000000000000", - "coinbase": "0x0000000000000000000000000000000000000000", - "timestamp": "0x00", - "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000", - "extraData": "0x", - "gasLimit": "0x2fefd8" - } - -Static nodes ------------- - -Geth also supports a feature called static nodes if you have certain -peers you always want to connect to. Static nodes are re-connected on -disconnects. You can configure permanent static nodes by putting -something like the following into ``/static-nodes.json``: - -.. code:: js - - [ - "enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303", - "enode://pubkey@ip:port" - ] - -You can also add static nodes at runtime via the js console using -```admin.addPeer()`` `__: - -.. code:: js - - admin.addPeer("enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303") - -Caveat: Currently the console is lacking support for removing a peer, -increasing peercount or adding a non-static peer but not to keep try -reconnecting. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Contract-Tutorial.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Contract-Tutorial.rst deleted file mode 100644 index 9c5c95c..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Contract-Tutorial.rst +++ /dev/null @@ -1,1460 +0,0 @@ -Introduction ------------- - -Now that you mastered the basics on how to get started and how to send -ether, it's time to get your hands dirty in what really makes Ethereum -stand out of the crowd: smart contracts. Smart contracts are pieces of -code that live on the blockchain and execute commands exactly how they -were told to. They can read other contracts, make decisions, send ether -and execute other contracts. Contracts will exist and run as long as the -whole network exists, and will only stop if they run out of gas or if -they were programmed to self destruct. - -What can you do with contracts? You can do almost anything really, but -for this guide let's do some simple things: You will get funds through a -crowdfunding that, if successful, will supply a radically transparent -and democratic organization that will only obey its own citizens, will -never swerve away from its constitution and cannot be censored or shut -down. And all that in less than 300 lines of code. - -So let's start now. - -Your first citizen: the greeter -------------------------------- - -Now that you’ve mastered the basics of Ethereum, let’s move into your -first serious contract. The Frontier is a big open territory and -sometimes you might feel lonely, so our first order of business will be -to create a little automatic companion to greet you whenever you feel -lonely. We’ll call him the “Greeter”. - -The Greeter is an intelligent digital entity that lives on the -blockchain and is able to have conversations with anyone who interacts -with it, based on its input. It might not be a talker, but it’s a great -listener. Here is its code: - -.. code:: js - - contract mortal { - /* Define variable owner of the type address*/ - address owner; - - /* this function is executed at initialization and sets the owner of the contract */ - function mortal() { owner = msg.sender; } - - /* Function to recover the funds on the contract */ - function kill() { if (msg.sender == owner) suicide(owner); } - } - - contract greeter is mortal { - /* define variable greeting of the type string */ - string greeting; - - /* this runs when the contract is executed */ - function greeter(string _greeting) public { - greeting = _greeting; - } - - /* main function */ - function greet() constant returns (string) { - return greeting; - } - } - -You'll notice that there are two different contracts in this code: -*"mortal"* and *"greeter"*. This is because Solidity (the high level -contract language we are using) has *inheritance*, meaning that one -contract can inherit characteristics of another. This is very useful to -simplify coding as common traits of contracts don't need to be rewritten -every time, and all contracts can be written in smaller, more readable -chunks. So by just declaring that *greeter is mortal* you inherited all -characteristics from the "mortal" contract and kept the greeter code -simple and easy to read. - -The inherited characteristic *"mortal"* simply means that the greeter -contract can be killed by its owner, to clean up the blockchain and -recover funds locked into it when the contract is no longer needed. -Contracts in Ethereum are, by default, immortal and have no owner, -meaning that once deployed the author has no special privileges anymore. -Consider this before deploying. - -Installing a compiler -~~~~~~~~~~~~~~~~~~~~~ - -Before you are able to Deploy it though, you'll need two things: the -compiled code, and the Application Binary Interface, which is a sort of -reference template that defines how to interact with the contract. - -The first you can get by using a compiler. You should have a solidity -compiler built in on your geth console. To test it, use this command: - -:: - - eth.getCompilers() - -If you have it installed, it should output something like this: - -:: - - ['Solidity' ] - -If instead the command returns an error, then you need to install it. - -Using an online compiler -^^^^^^^^^^^^^^^^^^^^^^^^ - -If you don't have solC installed, we have a `online solidity -compiler `__ available. But be -aware that **if the compiler is compromised, your contract is not -safe**. For this reason, if you want to use the online compiler we -encourage you to `host your -own `__. - -Install SolC on Ubuntu -^^^^^^^^^^^^^^^^^^^^^^ - -Press control+c to exit the console (or type *exit*) and go back to the -command line. Open the terminal and execute these commands: - -:: - - sudo add-apt-repository ppa:ethereum/ethereum - sudo apt-get update - sudo apt-get install solc - which solc - -Take note of the path given by the last line, you'll need it soon. - -Install SolC on Mac OSX -^^^^^^^^^^^^^^^^^^^^^^^ - -You need `brew `__ in order to install on your mac - -:: - - brew install cpp-ethereum - brew linkapps cpp-ethereum - which solc - -Take note of the path given by the last line, you'll need it soon. - -Install SolC on Windows -^^^^^^^^^^^^^^^^^^^^^^^ - -You need `chocolatey `__ in order to install -solc. - -:: - - cinst -pre solC-stable - -Windows is more complicated than that, you'll need to wait a bit more. - -If you have the SolC Solidity Compiler installed, you need now reformat -by removing spaces so it fits into a string variable `(there are some -online tools that will do -this) `__: - -Compile from source -^^^^^^^^^^^^^^^^^^^ - -:: - - git clone https://github.com/ethereum/cpp-ethereum.git - mkdir cpp-ethereum/build - cd cpp-ethereum/build - cmake -DJSONRPC=OFF -DMINER=OFF -DETHKEY=OFF -DSERPENT=OFF -DGUI=OFF -DTESTS=OFF -DJSCONSOLE=OFF .. - make -j4 - make install - which solc - -Linking your compiler in Geth -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Now `go back to the console <../geth>`__ and type this command to -install solC, replacing *path/to/solc* to the path that you got on the -last command you did: - -:: - - admin.setSolc("path/to/solc") - -Now type again: - -:: - - eth.getCompilers() - -If you now have solC installed, then congratulations, you can keep -reading. If you don't, then go to our -`forums `__ or -`subreddit `__ and berate us on -failing to make the process easier. - -Compiling your contract -~~~~~~~~~~~~~~~~~~~~~~~ - -If you have the compiler installed, you need now reformat your contract -by removing line-breaks so it fits into a string variable `(there are -some online tools that will do -this) `__: - -:: - - var greeterSource = 'contract mortal { address owner; function mortal() { owner = msg.sender; } function kill() { if (msg.sender == owner) suicide(owner); } } contract greeter is mortal { string greeting; function greeter(string _greeting) public { greeting = _greeting; } function greet() constant returns (string) { return greeting; } }' - - var greeterCompiled = web3.eth.compile.solidity(greeterSource) - -You have now compiled your code. Now you need to get it ready for -deployment, this includes setting some variables up, like what is your -greeting. Edit the first line below to something more interesting than -'Hello World!" and execute these commands: - -:: - - var _greeting = "Hello World!" - var greeterContract = web3.eth.contract(greeterCompiled.greeter.info.abiDefinition); - - var greeter = greeterContract.new(_greeting,{from:web3.eth.accounts[0], data: greeterCompiled.greeter.code, gas: 1000000}, function(e, contract){ - if(!e) { - - if(!contract.address) { - console.log("Contract transaction send: TransactionHash: " + contract.transactionHash + " waiting to be mined..."); - - } else { - console.log("Contract mined! Address: " + contract.address); - console.log(contract); - } - - } - }) - -Using the online compiler -^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you don't have solC installed, you can simply use the online -compiler. Copy the source code above to the `online solidity -compiler `__ and then your -compiled code should appear on the left pane. Copy the code on the box -labeled **Geth deploy** to a text file. Now change the first line to -your greeting: - -:: - - var _greeting = "Hello World!" - -Now you can paste the resulting text on your geth window. Wait up to -thirty seconds and you'll see a message like this: - -:: - - Contract mined! address: 0xdaa24d02bad7e9d6a80106db164bad9399a0423e - -You will probably be asked for the password you picked in the beginning, -because you need to pay for the gas costs to deploying your contract. -This contract is estimated to need 172 thousand gas to deploy (according -to the `online solidity -compiler `__), at the time of -writing, gas on the test net is priced at 1 to 10 microethers per unit -of gas (nicknamed "szabo" = 1 followed by 12 zeroes in wei). To know the -latest price in ether all you can see the `latest gas prices at the -network stats page `__ and multiply both -terms. - -**Notice that the cost is not paid to the `ethereum -developers <../foundation>`__, instead it goes to the *Miners*, people -who are running computers who keep the network running. Gas price is set -by the market of the current supply and demand of computation. If the -gas prices are too high, you can be a miner and lower your asking -price.** - -After less than a minute, you should have a log with the contract -address, this means you've sucessfully deployed your contract. You can -verify the deployed code (compiled) by using this command: - -:: - - eth.getCode(greeter.address) - -If it returns anything other than "0x" then congratulations! Your little -Greeter is live! If the contract is created again (by performing another -eth.sendTransaction), it will be published to a new address. - -Run the Greeter -~~~~~~~~~~~~~~~ - -In order to call your bot, just type the following command in your -terminal: - -:: - - greeter.greet(); - -Since this call changes nothing on the blockchain, it returns instantly -and without any gas cost. You should see it return your greeting: - -:: - - 'Hello World!' - -Getting other people to interact with your code -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In order to other people to run your contract they need two things: the -address where the contract is located and the ABI (Application Binary -Interface) which is a sort of user manual, describing the name of its -functions and how to call them. In order to get each of them run these -commands: - -:: - - greeterCompiled.greeter.info.abiDefinition; - greeter.address; - -Then you can instantiate a javascript object which can be used to call -the contract on any machine connected to the network. Replace 'ABI' and -'address' to create a contract object in javascript: - -:: - - var greeter = eth.contract(ABI).at(Address); - -This particular example can be instantiated by anyone by simply calling: - -:: - - var greeter2 = eth.contract([{constant:false,inputs:[],name:'kill',outputs:[],type:'function'},{constant:true,inputs:[],name:'greet',outputs:[{name:'',type:'string'}],type:'function'},{inputs:[{name:'_greeting',type:'string'}],type:'constructor'}]).at('greeterAddress'); - -Replace *greeterAddress* with your contract's address. - -**Tip: if the solidity compiler isn't properly installed in your -machine, you can get the ABI from the online compiler. To do so, use the -code below carefully replacing -*greeterCompiled.greeter.info.abiDefinition* with the abi from your -compiler.** - -Cleaning up after yourself: -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You must be very excited to have your first contract live, but this -excitement wears off sometimes, when the owners go on to write further -contracts, leading to the unpleasant sight of abandoned contracts on the -blockchain. In the future, blockchain rent might be implemented in order -to increase the scalability of the blockchain but for now, be a good -citizen and humanely put down your abandoned bots. - -Unlike last time we will not be making a call as we wish to change -something on the blockchain. This requires a transaction be sent to the -network and a fee to be paid for the changes made. The suicide is -subsidized by the network so it will cost much less than a usual -transaction. - -:: - - greeter.kill.sendTransaction({from:eth.accounts[0]}) - -You can verify that the deed is done simply seeing if this returns 0: - -:: - - eth.getCode(greeter.contractAddress) - -Notice that every contract has to implement its own kill clause. In this -particular case only the account that created the contract can kill it. - -If you don't add any kill clause it could potentially live forever (or -at least until the frontier contracts are all wiped) independently of -you and any earthly borders, so before you put it live check what your -local laws say about it, including any possible limitation on technology -export, restrictions on speech and maybe any legislation on the civil -rights of sentient digital beings. Treat your bots humanely. - -The Coin --------- - -What is a coin? Coins are much more interesting and useful than they -seem, they are in essence just a tradeable token, but can become much -more, depending on how you use them. Its value depends on what you do -with it: a token can be used to control access (**an entrance ticket**), -can be used for voting rights in an organization (**a share**), can be -placeholders for an asset held by a third party (**a certificate of -ownership**) or even be simply used as an exchange of value within a -community (**a currency**). - -You could do all those things by creating a centralized server, but -using an Ethereum token contract comes with some free functionalities: -for one, it's a decentralized service and tokens can be still exchanged -even if the original service goes down for any reason. The code can -guarantee that no tokens will ever be created other than the ones set in -the original code. Finally, by having each user hold their own token, -this eliminates the scenarios where one single server break-in can -result in the loss of funds from thousands of clients. - -You could create your own token on a different blockchain, but creating -on Ethereum is easier — so you can focus your energy on the innovation -that will make your coin stand out - and it's more secure, as your -security is provided by all the miners who are supporting the Ethereum -network. Finally, by creating your token in Ethereum, your coin will be -compatible with any other contract running on Ethereum. - -The Code -~~~~~~~~ - -This is the code for the contract we're building: - -:: - - contract token { - mapping (address => uint) public coinBalanceOf; - event CoinTransfer(address sender, address receiver, uint amount); - - /* Initializes contract with initial supply tokens to the creator of the contract */ - function token(uint supply) { - coinBalanceOf[msg.sender] = supply; - } - - /* Very simple trade function */ - function sendCoin(address receiver, uint amount) returns(bool sufficient) { - if (coinBalanceOf[msg.sender] < amount) return false; - coinBalanceOf[msg.sender] -= amount; - coinBalanceOf[receiver] += amount; - CoinTransfer(msg.sender, receiver, amount); - return true; - } - } - -If you have ever programmed, you won't find it hard to understand what -it does: it is a contract that generates 10 thousand tokens to the -creator of the contract, and then allows anyone with enough balance to -send it to others. These tokens are the minimum tradeable unit and -cannot be subdivided, but for the final users could be presented as a -100 units subdividable by 100 subunits, so owning a single token would -represent having 0.01% of the total. If your application needs more fine -grained atomic divisibility, then just increase the initial issuance -amount. - -In this example we declared the variable "coinBalanceOf" to be public, -this will automatically create a function that checks any account's -balance. - -Compile and Deploy -~~~~~~~~~~~~~~~~~~ - -**So let's run it!** - -:: - - var tokenSource = ' contract token { mapping (address => uint) public coinBalanceOf; event CoinTransfer(address sender, address receiver, uint amount); /* Initializes contract with initial supply tokens to the creator of the contract */ function token(uint supply) { coinBalanceOf[msg.sender] = supply; } /* Very simple trade function */ function sendCoin(address receiver, uint amount) returns(bool sufficient) { if (coinBalanceOf[msg.sender] < amount) return false; coinBalanceOf[msg.sender] -= amount; coinBalanceOf[receiver] += amount; CoinTransfer(msg.sender, receiver, amount); return true; } }' - - var tokenCompiled = eth.compile.solidity(tokenSource) - -Now let’s set up the contract, just like we did in the previous section. -Change the "initial Supply" to the amount of non divisible tokens you -want to create. If you want to have divisible units, you should do that -on the user frontend but keep them represented in the minimun unit of -account. - -:: - - var supply = 10000; - var tokenContract = web3.eth.contract(tokenCompiled.token.info.abiDefinition); - var token = tokenContract.new( - supply, - { - from:web3.eth.accounts[0], - data:tokenCompiled.token.code, - gas: 1000000 - }, function(e, contract){ - if(!e) { - - if(!contract.address) { - console.log("Contract transaction send: TransactionHash: " + contract.transactionHash " waiting to be mined..."); - - } else { - console.log("Contract mined! Address: " + contract.address); - console.log(contract); - } - - } - }) - -Online Compiler -^^^^^^^^^^^^^^^ - -**If you don't have solC installed, you can simply use the online -compiler.** Copy the contract code to the `online solidity -compiler `__, if there are no -errors on the contract you should see a text box labeled **Geth -Deploy**. Copy the content to a text file so you can change the first -line to set the initial supply, like this: - -:: - - var supply = 10000; - -Now you can paste the resulting text on your geth window. Wait up to -thirty seconds and you'll see a message like this: - -:: - - Contract mined! address: 0xdaa24d02bad7e9d6a80106db164bad9399a0423e - -Check balance watching coin transfers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If everything worked correctly, you should be able to check your own -balance with: - -:: - - token.coinBalanceOf(eth.accounts[0]) + " tokens" - -It should have all the 10 000 tokens that were created once the contract -was published. Since there is not any other defined way for new coins to -be issued, these are all that will ever exist. - -You can set up a **Watcher** to react whenever anyone sends a coin using -your contract. Here's how you do it: - -:: - - var event = token.CoinTransfer({}, '', function(error, result){ - if (!error) - console.log("Coin transfer: " + result.args.amount + " tokens were sent. Balances now are as following: \n Sender:\t" + result.args.sender + " \t" + token.coinBalanceOf.call(result.args.sender) + " tokens \n Receiver:\t" + result.args.receiver + " \t" + token.coinBalanceOf.call(result.args.receiver) + " tokens" ) - }); - -Sending coins -~~~~~~~~~~~~~ - -Now of course those tokens aren't very useful if you hoard them all, so -in order to send them to someone else, use this command: - -:: - - token.sendCoin.sendTransaction(eth.accounts[1], 1000, {from: eth.accounts[0]}) - -If a friend has registered a name on the registrar you can send it -without knowing their address, doing this: - -:: - - token.sendCoin.sendTransaction(registrar.addr("Alice"), 2000, {from: eth.accounts[0]}) - -Note that our first function **coinBalanceOf** was simply called -directly on the contract instance and returned a value. This was -possible since this was a simple read operation that incurs no state -change and which executes locally and synchronously. Our second function -**sendCoin** needs a **.sendTransaction()** call. Since this function is -meant to change the state (write operation), it is sent as a transaction -to the network to be picked up by miners and included in the canonical -blockchain. As a result the consensus state of all participant nodes -will adequately reflect the state changes resulting from executing the -transaction. Sender address needs to be sent as part of the transaction -to fund the fuel needed to run the transaction. Now, wait a minute and -check both accounts balances: - -:: - - token.coinBalanceOf.call(eth.accounts[0])/100 + "% of all tokens" - token.coinBalanceOf.call(eth.accounts[1])/100 + "% of all tokens" - token.coinBalanceOf.call(registrar.addr("Alice"))/100 + "% of all tokens" - -Improvement suggestions -~~~~~~~~~~~~~~~~~~~~~~~ - -Right now this cryptocurrency is quite limited as there will only ever -be 10,000 coins and all are controlled by the coin creator, but you can -change that. You could for example reward ethereum miners, by creating a -transaction that will reward who found the current block: - -:: - - mapping (uint => address) miningReward; - function claimMiningReward() { - if (miningReward[block.number] == 0) { - coinBalanceOf[block.coinbase] += 1; - miningReward[block.number] = block.coinbase; - } - } - -You could modify this to anything else: maybe reward someone who finds a -solution for a new puzzle, wins a game of chess, install a solar -panel—as long as that can be somehow translated to a contract. Or maybe -you want to create a central bank for your personal country, so you can -keep track of hours worked, favours owed or control of property. In that -case you might want to add a function to allow the bank to remotely -freeze funds and destroy tokens if needed. - -Register a name for your coin -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The commands mentioned only work because you have token javascript -object instantiated on your local machine. If you send tokens to someone -they won't be able to move them forward because they don't have the same -object and wont know where to look for your contract or call its -functions. In fact if you restart your console these objects will be -deleted and the contracts you've been working on will be lost forever. -So how do you instantiate the contract on a clean machine? - -There are two ways. Let's start with the quick and dirty, providing your -friends with a reference to your contract’s ABI: - -:: - - token = eth.contract([{constant:false,inputs:[{name:'receiver',type:'address'},{name:'amount',type:'uint256'}],name:'sendCoin',outputs:[{name:'sufficient',type:'bool'}],type:'function'},{constant:true,inputs:[{name:'',type:'address'}],name:'coinBalanceOf',outputs:[{name:'',type:'uint256'}],type:'function'},{inputs:[{name:'supply',type:'uint256'}],type:'constructor'},{anonymous:false,inputs:[{indexed:false,name:'sender',type:'address'},{indexed:false,name:'receiver',type:'address'},{indexed:false,name:'amount',type:'uint256'}],name:'CoinTransfer',type:'event'}]).at('0x4a4ce7844735c4b6fc66392b200ab6fe007cfca8') - -Just replace the address at the end for your own token address, then -anyone that uses this snippet will immediately be able to use your -contract. Of course this will work only for this specific contract so -let's analyze step by step and see how to improve this code so you'll be -able to use it anywhere. - -All accounts are referenced in the network by their public address. But -addresses are long, difficult to write down, hard to memorize and -immutable. The last one is specially important if you want to be able to -generate fresh accounts in your name, or upgrade the code of your -contract. In order to solve this, there is a default name registrar -contract which is used to associate the long addresses with short, -human-friendly names. - -Names have to use only alphanumeric characters and, cannot contain blank -spaces. In future releases the name registrar will likely implement a -bidding process to prevent name squatting but for now, it works on a -first come first served basis: as long as no one else registered the -name, you can claim it. - -First, if you register a name, then you won't need the hardcoded address -in the end. Select a nice coin name and try to reserve it for yourself. -First, select your name: - -:: - - var tokenName = "MyFirstCoin" - -Then, check the availability of your name: - -:: - - registrar.addr(tokenName) - -If that function returns "0x00..", you can claim it to yourself: - -:: - - registrar.reserve.sendTransaction(tokenName, {from: eth.accounts[0]}); - -Wait for the previous transaction to be picked up. Wait up to thirty -seconds and then try: - -:: - - registrar.owner(myName) - -If it returns your address, it means you own that name and are able to -set your chosen name to any address you want: - -:: - - registrar.setAddress.sendTransaction(tokenName, token.address, true,{from: eth.accounts[0]}); - -*You can replace **token.address** for **eth.accounts[0]** if you want -to use it as a personal nickname.* - -Wait a little bit for that transaction to be picked up too and test it: - -:: - - registrar.addr("MyFirstCoin") - -You can send a transaction to anyone or any contract by name instead of -account simply by typing - -:: - - eth.sendTransaction({from: eth.accounts[0], to: registrar.addr("MyFirstCoin"), value: web3.toWei(1, "ether")}) - -**Tip: don't mix registrar.addr for registrar.owner. The first is to -which address that name is pointed at: anyone can point a name to -anywhere else, just like anyone can forward a link to google.com, but -only the owner of the name can change and update the link. You can set -both to be the same address.** - -This should now return your token address, meaning that now the previous -code to instantiate could use a name instead of an address. - -:: - - token = eth.contract([{constant:false,inputs:[{name:'receiver',type:'address'},{name:'amount',type:'uint256'}],name:'sendCoin',outputs:[{name:'sufficient',type:'bool'}],type:'function'},{constant:true,inputs:[{name:'',type:'address'}],name:'coinBalanceOf',outputs:[{name:'',type:'uint256'}],type:'function'},{inputs:[{name:'supply',type:'uint256'}],type:'constructor'},{anonymous:false,inputs:[{indexed:false,name:'sender',type:'address'},{indexed:false,name:'receiver',type:'address'},{indexed:false,name:'amount',type:'uint256'}],name:'CoinTransfer',type:'event'}]).at(registrar.addr("MyFirstCoin")) - -This also means that the owner of the coin can update the coin by -pointing the registrar to the new contract. This would, of course, -require the coin holders trust the owner set at -registrar.owner("MyFirstCoin") - -Of course this is a rather unpleasant big chunk of code just to allow -others to interact with a contract. There are some avenues being -investigated to upload the contract ABI to the network, so that all the -user will need is the contract name. You can `read about these -approaches `__ -but they are very experimental and will certainly change in the future. - -Learn More -~~~~~~~~~~ - -- `Meta coin - standard `__ - is a proposed standardization of function names for coin and token - contracts, to allow them to be automatically added to other Ethereum - contract that utilizes trading, like exchanges or escrow. - -- `Formal - proofing `__ - is a way where the contract developer will be able to assert some - invariant qualities of the contract, like the total cap of the coin. - *Not yet implemented*. - -Crowdfund your idea -=================== - -Sometimes a good idea takes a lot of funds and collective effort. You -could ask for donations, but donors prefer to give to projects they are -more certain that will get traction and proper funding. This is an -example where a crowdfunding would be ideal: you set up a goal and a -deadline for reaching it. If you miss your goal, the donations are -returned, therefore reducing the risk for donors. Since the code is open -and auditable, there is no need for a centralized trusted platform and -therefore the only fees everyone will pay are just the gas fees. - -In a crowdfunding prizes are usually given. This would require you to -get everyone's contact information and keep track of who owns what. But -since you just created your own token, why not use that to keep track of -the prizes? This allows donors to immediately own something after they -donated. They can store it safely, but they can also sell or trade it if -they realize they don't want the prize anymore. If your idea is -something physical, all you have to do after the project is completed is -to give the product to everyone who sends you back a token. If the -project is digital the token itself can immediately be used for users to -participate or get entry on your project. - -The code -~~~~~~~~ - -The way this particular crowdsale contract works is that you set an -exchange rate for your token and then the donors will immediately get a -proportional amount of tokens in exchange of their ether. You will also -choose a funding goal and a deadline: once that deadline is over you can -ping the contract and if the goal was reached it will send the ether -raised to you, otherwise it goes back to the donors. Donors keep their -tokens even if the project doesn't reach its goal, as a proof that they -helped. - -:: - - contract token { mapping (address => uint) public coinBalanceOf; function token() {} function sendCoin(address receiver, uint amount) returns(bool sufficient) { } } - - contract Crowdsale { - - address public beneficiary; - uint public fundingGoal; uint public amountRaised; uint public deadline; uint public price; - token public tokenReward; - Funder[] public funders; - event FundTransfer(address backer, uint amount, bool isContribution); - - /* data structure to hold information about campaign contributors */ - struct Funder { - address addr; - uint amount; - } - - /* at initialization, setup the owner */ - function Crowdsale(address _beneficiary, uint _fundingGoal, uint _duration, uint _price, token _reward) { - beneficiary = _beneficiary; - fundingGoal = _fundingGoal; - deadline = now + _duration * 1 minutes; - price = _price; - tokenReward = token(_reward); - } - - /* The function without name is the default function that is called whenever anyone sends funds to a contract */ - function () { - uint amount = msg.value; - funders[funders.length++] = Funder({addr: msg.sender, amount: amount}); - amountRaised += amount; - tokenReward.sendCoin(msg.sender, amount / price); - FundTransfer(msg.sender, amount, true); - } - - modifier afterDeadline() { if (now >= deadline) _ } - - /* checks if the goal or time limit has been reached and ends the campaign */ - function checkGoalReached() afterDeadline { - if (amountRaised >= fundingGoal){ - beneficiary.send(amountRaised); - FundTransfer(beneficiary, amountRaised, false); - } else { - FundTransfer(0, 11, false); - for (uint i = 0; i < funders.length; ++i) { - funders[i].addr.send(funders[i].amount); - FundTransfer(funders[i].addr, funders[i].amount, false); - } - } - suicide(beneficiary); - } - } - -Set the parameters -~~~~~~~~~~~~~~~~~~ - -Before we go further, let's start by setting the parameters of the -crowdsale: - -:: - - var _beneficiary = eth.accounts[1]; // create an account for this - var _fundingGoal = web3.toWei(100, "ether"); // raises 100 ether - var _duration = 30; // number of minutes the campaign will last - var _price = web3.toWei(0.02, "ether"); // the price of the tokens, in ether - var _reward = token.address; // the token contract address. - -On Beneficiary put the new address that will receive the raised funds. -The funding goal is the amount of ether to be raised. Deadline is -measured in blocktimes which average 12 seconds, so the default is about -4 weeks. The price is tricky: but just change the number 2 for the -amount of tokens the contributors will receive for each ether donated. -Finally reward should be the address of the token contract you created -in the last section. - -In this example you are selling on the crowdsale half of all the tokens -that ever existed, in exchange for 100 ether. Decide those parameters -very carefully as they will play a very important role in the next part -of our guide. - -Deploy -~~~~~~ - -You know the drill: if you are using the solC compiler,\ `remove line -breaks `__ and -copy the following commands on the terminal: - -:: - - var crowdsaleCompiled = eth.compile.solidity(' contract token { mapping (address => uint) public coinBalanceOf; function token() {} function sendCoin(address receiver, uint amount) returns(bool sufficient) { } } contract Crowdsale { address public beneficiary; uint public fundingGoal; uint public amountRaised; uint public deadline; uint public price; token public tokenReward; Funder[] public funders; event FundTransfer(address backer, uint amount, bool isContribution); /* data structure to hold information about campaign contributors */ struct Funder { address addr; uint amount; } /* at initialization, setup the owner */ function Crowdsale(address _beneficiary, uint _fundingGoal, uint _duration, uint _price, token _reward) { beneficiary = _beneficiary; fundingGoal = _fundingGoal; deadline = now + _duration * 1 minutes; price = _price; tokenReward = token(_reward); } /* The function without name is the default function that is called whenever anyone sends funds to a contract */ function () { Funder f = funders[++funders.length]; f.addr = msg.sender; f.amount = msg.value; amountRaised += f.amount; tokenReward.sendCoin(msg.sender, f.amount/price); FundTransfer(f.addr, f.amount, true); } modifier afterDeadline() { if (now >= deadline) _ } /* checks if the goal or time limit has been reached and ends the campaign */ function checkGoalReached() afterDeadline { if (amountRaised >= fundingGoal){ beneficiary.send(amountRaised); FundTransfer(beneficiary, amountRaised, false); } else { FundTransfer(0, 11, false); for (uint i = 0; i < funders.length; ++i) { funders[i].addr.send(funders[i].amount); FundTransfer(funders[i].addr, funders[i].amount, false); } } suicide(beneficiary); } }'); - - var crowdsaleContract = web3.eth.contract(crowdsaleCompiled.Crowdsale.info.abiDefinition); - var crowdsale = crowdsaleContract.new( - _beneficiary, - _fundingGoal, - _duration, - _price, - _reward, - { - from:web3.eth.accounts[0], - data:crowdsaleCompiled.Crowdsale.code, - gas: 1000000 - }, function(e, contract){ - if(!e) { - - if(!contract.address) { - console.log("Contract transaction send: TransactionHash: " + contract.transactionHash " waiting to be mined..."); - - } else { - console.log("Contract mined! Address: " + contract.address); - console.log(contract); - } - - } }) - -**If you are using the *online compiler* Copy the contract code to the -`online solidity compiler `__, -and then grab the content of the box labeled **\ Geth Deploy\ **. Since -you have already set the parameters, you don't need to change anything -to that text, simply paste the resulting text on your geth window.** - -Wait up to thirty seconds and you'll see a message like this: - -:: - - Contract mined! address: 0xdaa24d02bad7e9d6a80106db164bad9399a0423e - -If you received that alert then your code should be online. You can -always double check by doing this: - -:: - - eth.getCode(crowdsale.address) - -Now fund your newly created contract with the necessary tokens so it can -automatically distribute rewards to the contributors! - -:: - - token.sendCoin.sendTransaction(crowdsale.address, 5000,{from: eth.accounts[0]}) - -After the transaction is picked, you can check the amount of tokens the -crowdsale address has, and all other variables this way: - -:: - - "Current crowdsale must raise " + web3.fromWei(crowdsale.fundingGoal.call(), "ether") + " ether in order to send it to " + crowdsale.beneficiary.call() + "." - -Put some watchers on -~~~~~~~~~~~~~~~~~~~~ - -You want to be alerted whenever your crowdsale receives new funds, so -paste this code: - -:: - - var event = crowdsale.FundTransfer({}, '', function(error, result){ - if (!error) - - if (result.args.isContribution) { - console.log("\n New backer! Received " + web3.fromWei(result.args.amount, "ether") + " ether from " + result.args.backer ) - - console.log( "\n The current funding at " +( 100 * crowdsale.amountRaised.call() / crowdsale.fundingGoal.call()) + "% of its goals. Funders have contributed a total of " + web3.fromWei(crowdsale.amountRaised.call(), "ether") + " ether."); - - var timeleft = Math.floor(Date.now() / 1000)-crowdsale.deadline(); - if (timeleft>3600) { console.log("Deadline has passed, " + Math.floor(timeleft/3600) + " hours ago") - } else if (timeleft>0) { console.log("Deadline has passed, " + Math.floor(timeleft/60) + " minutes ago") - } else if (timeleft>-3600) { console.log(Math.floor(-1*timeleft/60) + " minutes until deadline") - } else { console.log(Math.floor(-1*timeleft/3600) + " hours until deadline") - } - - } else { - console.log("Funds transferred from crowdsale account: " + web3.fromWei(result.args.amount, "ether") + " ether to " + result.args.backer ) - } - - }); - -Register the contract -~~~~~~~~~~~~~~~~~~~~~ - -You are now set. Anyone can now contribute by simply sending ether to -the crowdsale address, but to make it even simpler, let's register a -name for your sale. First, pick a name for your crowdsale: - -:: - - var name = "mycrowdsale" - -Check if that's available and register: - -:: - - registrar.addr(name) - registrar.reserve.sendTransaction(name, {from: eth.accounts[0]}); - -Wait for the previous transaction to be picked up and then: - -:: - - registrar.setAddress.sendTransaction(name, crowdsale.address, true,{from: eth.accounts[0]}); - -Contribute to the crowdsale -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Contributing to the crowdsale is very simple, it doesn't even require -instantiating the contract. This is because the crowdsale responds to -simple ether deposits, so anyone that sends ether to the crowdsale will -automatically receive a reward. Anyone can contribute to it by simply -executing this command: - -:: - - var amount = web3.toWei(5, "ether") // decide how much to contribute - - eth.sendTransaction({from: eth.accounts[0], to: crowdsale.address, value: amount, gas: 1000000}) - -Alternatively, if you want someone else to send it, they can even use -the name registrar to contribute: - -:: - - eth.sendTransaction({from: eth.accounts[0], to: registrar.addr("mycrowdsale"), value: amount, gas: 500000}) - -Now wait a minute for the blocks to pickup and you can check if the -contract received the ether by doing any of these commands: - -:: - - web3.fromWei(crowdsale.amountRaised.call(), "ether") + " ether" - token.coinBalanceOf.call(eth.accounts[0]) + " tokens" - token.coinBalanceOf.call(crowdsale.address) + " tokens" - -Recover funds -~~~~~~~~~~~~~ - -Once the deadline is passed someone has to wake up the contract to have -the funds sent to either the beneficiary or back to the funders (if it -failed). This happens because there is no such thing as an active loop -or timer on Ethereum so any future transactions must be pinged by -someone. - -:: - - crowdsale.checkGoalReached.sendTransaction({from:eth.accounts[0], gas: 2000000}) - -You can check your accounts with these lines of code: - -:: - - web3.fromWei(eth.getBalance(eth.accounts[0]), "ether") + " ether" - web3.fromWei(eth.getBalance(eth.accounts[1]), "ether") + " ether" - token.coinBalanceOf.call(eth.accounts[0]) + " tokens" - token.coinBalanceOf.call(eth.accounts[1]) + " tokens" - -The crowdsale instance is setup to self destruct once it has done its -job, so if the deadline is over and everyone got their prizes the -contract is no more, as you can see by running this: - -:: - - eth.getCode(crowdsale.address) - -So you raised a 100 ethers and successfully distributed your original -coin among the crowdsale donors. What could you do next with those -things? - -Democracy DAO -============= - -So far you have created a tradeable token and you successfully -distributed it among all those who were willing to help fundraise a 100 -ethers. That's all very interesting but what exactly are those tokens -for? Why would anyone want to own or trade it for anything else -valuable? If you can convince your new token is the next big money maybe -others will want it, but so far your token offers no value per se. We -are going to change that, by creating your first decentralized -autonomous organization, or DAO. - -Think of the DAO as the constitution of a country, the executive branch -of a government or maybe like a robotic manager for an organization. The -DAO receives the money that your organization raises, keeps it safe and -uses it to fund whatever its members want. The robot is incorruptible, -will never defraud the bank, never create secret plans, never use the -money for anything other than what its constituents voted on. The DAO -will never disappear, never run away and cannot be controlled by anyone -other than its own citizens. - -The token we distributed using the crowdsale is the only citizen -document needed. Anyone who holds any token is able to create and vote -on proposals. Similar to being a shareholder in a company, the token can -be traded on the open market and the vote is proportional to amounts of -tokens the voter holds. - -Take a moment to dream about the revolutionary possibilities this would -allow, and now you can do it yourself, in under a 100 lines of code: - -The Code -~~~~~~~~ - -:: - - contract token { mapping (address => uint) public coinBalanceOf; function token() { } function sendCoin(address receiver, uint amount) returns(bool sufficient) { } } - - - contract Democracy { - - uint public minimumQuorum; - uint public debatingPeriod; - token public voterShare; - address public founder; - Proposal[] public proposals; - uint public numProposals; - - event ProposalAdded(uint proposalID, address recipient, uint amount, bytes32 data, string description); - event Voted(uint proposalID, int position, address voter); - event ProposalTallied(uint proposalID, int result, uint quorum, bool active); - - struct Proposal { - address recipient; - uint amount; - bytes32 data; - string description; - uint creationDate; - bool active; - Vote[] votes; - mapping (address => bool) voted; - } - - struct Vote { - int position; - address voter; - } - - function Democracy(token _voterShareAddress, uint _minimumQuorum, uint _debatingPeriod) { - founder = msg.sender; - voterShare = token(_voterShareAddress); - minimumQuorum = _minimumQuorum || 10; - debatingPeriod = _debatingPeriod * 1 minutes || 30 days; - } - - - function newProposal(address _recipient, uint _amount, bytes32 _data, string _description) returns (uint proposalID) { - if (voterShare.coinBalanceOf(msg.sender)>0) { - proposalID = proposals.length++; - Proposal p = proposals[proposalID]; - p.recipient = _recipient; - p.amount = _amount; - p.data = _data; - p.description = _description; - p.creationDate = now; - p.active = true; - ProposalAdded(proposalID, _recipient, _amount, _data, _description); - numProposals = proposalID+1; - } - } - - function vote(uint _proposalID, int _position) returns (uint voteID){ - if (voterShare.coinBalanceOf(msg.sender)>0 && (_position >= -1 || _position <= 1 )) { - Proposal p = proposals[_proposalID]; - if (p.voted[msg.sender] == true) return; - voteID = p.votes.length++; - p.votes[voteID] = Vote({position: _position, voter: msg.sender}); - p.voted[msg.sender] = true; - Voted(_proposalID, _position, msg.sender); - } - } - - function executeProposal(uint _proposalID) returns (int result) { - Proposal p = proposals[_proposalID]; - /* Check if debating period is over */ - if (now > (p.creationDate + debatingPeriod) && p.active){ - uint quorum = 0; - /* tally the votes */ - for (uint i = 0; i < p.votes.length; ++i) { - Vote v = p.votes[i]; - uint voteWeight = voterShare.coinBalanceOf(v.voter); - quorum += voteWeight; - result += int(voteWeight) * v.position; - } - /* execute result */ - if (quorum > minimumQuorum && result > 0 ) { - p.recipient.call.value(p.amount)(p.data); - p.active = false; - } else if (quorum > minimumQuorum && result < 0) { - p.active = false; - } - ProposalTallied(_proposalID, result, quorum, p.active); - } - } - } - -There's a lot of going on but it's simpler than it looks. The rules of -your organization are very simple: anyone with at least one token can -create proposals to send funds from the country's account. After a week -of debate and votes, if it has received votes worth a total of 100 -tokens or more and has more approvals than rejections, the funds will be -sent. If the quorum hasn't been met or it ends on a tie, then voting is -kept until it's resolved. Otherwise, the proposal is locked and kept for -historical purposes. - -So let's recap what this means: in the last two sections you created -10,000 tokens, sent 1,000 of those to another account you control, 2,000 -to a friend named Alice and distributed 5,000 of them via a crowdsale. -This means that you no longer control over 50% of the votes in the DAO, -and if Alice and the community bands together, they can outvote any -spending decision on the 100 ethers raised so far. This is exactly how a -democracy should work. If you don't want to be a part of your country -anymore the only thing you can do is sell your own tokens on a -decentralized exchange and opt out, but you cannot prevent the others -from doing so. - -Set Up your Organization -~~~~~~~~~~~~~~~~~~~~~~~~ - -So open your console and let's get ready to finally put your country -online. First, let's set the right parameters, pick them with care: - -:: - - var _voterShareAddress = token.address; - var _minimumQuorum = 10; // Minimun amount of voter tokens the proposal needs to pass - var _debatingPeriod = 60; // debating period, in minutes; - -With these default parameters anyone with any tokens can make a proposal -on how to spend the organization's money. The proposal has 1 hour to be -debated and it will pass if it has at least votes from at least 0.1% of -the total tokens and has more support than rejections. Pick those -parameters with care, as you won't be able to change them in the future. - -:: - - var daoCompiled = eth.compile.solidity('contract token { mapping (address => uint) public coinBalanceOf; function token() { } function sendCoin(address receiver, uint amount) returns(bool sufficient) { } } contract Democracy { uint public minimumQuorum; uint public debatingPeriod; token public voterShare; address public founder; Proposal[] public proposals; uint public numProposals; event ProposalAdded(uint proposalID, address recipient, uint amount, bytes32 data, string description); event Voted(uint proposalID, int position, address voter); event ProposalTallied(uint proposalID, int result, uint quorum, bool active); struct Proposal { address recipient; uint amount; bytes32 data; string description; uint creationDate; bool active; Vote[] votes; mapping (address => bool) voted; } struct Vote { int position; address voter; } function Democracy(token _voterShareAddress, uint _minimumQuorum, uint _debatingPeriod) { founder = msg.sender; voterShare = token(_voterShareAddress); minimumQuorum = _minimumQuorum || 10; debatingPeriod = _debatingPeriod * 1 minutes || 30 days; } function newProposal(address _recipient, uint _amount, bytes32 _data, string _description) returns (uint proposalID) { if (voterShare.coinBalanceOf(msg.sender)>0) { proposalID = proposals.length++; Proposal p = proposals[proposalID]; p.recipient = _recipient; p.amount = _amount; p.data = _data; p.description = _description; p.creationDate = now; p.active = true; ProposalAdded(proposalID, _recipient, _amount, _data, _description); numProposals = proposalID+1; } else { return 0; } } function vote(uint _proposalID, int _position) returns (uint voteID){ if (voterShare.coinBalanceOf(msg.sender)>0 && (_position >= -1 || _position <= 1 )) { Proposal p = proposals[_proposalID]; if (p.voted[msg.sender] == true) return; voteID = p.votes.length++; Vote v = p.votes[voteID]; v.position = _position; v.voter = msg.sender; p.voted[msg.sender] = true; Voted(_proposalID, _position, msg.sender); } else { return 0; } } function executeProposal(uint _proposalID) returns (int result) { Proposal p = proposals[_proposalID]; /* Check if debating period is over */ if (now > (p.creationDate + debatingPeriod) && p.active){ uint quorum = 0; /* tally the votes */ for (uint i = 0; i < p.votes.length; ++i) { Vote v = p.votes[i]; uint voteWeight = voterShare.coinBalanceOf(v.voter); quorum += voteWeight; result += int(voteWeight) * v.position; } /* execute result */ if (quorum > minimumQuorum && result > 0 ) { p.recipient.call.value(p.amount)(p.data); p.active = false; } else if (quorum > minimumQuorum && result < 0) { p.active = false; } } ProposalTallied(_proposalID, result, quorum, p.active); } }'); - - var democracyContract = web3.eth.contract(daoCompiled.Democracy.info.abiDefinition); - - var democracy = democracyContract.new( - _voterShareAddress, - _minimumQuorum, - _debatingPeriod, - { - from:web3.eth.accounts[0], - data:daoCompiled.Democracy.code, - gas: 3000000 - }, function(e, contract){ - if(!e) { - - if(!contract.address) { - console.log("Contract transaction send: TransactionHash: " + contract.transactionHash " waiting to be mined..."); - - } else { - console.log("Contract mined! Address: " + contract.address); - console.log(contract); - } - - } - }) - -**If you are using the *online compiler* Copy the contract code to the -`online solidity compiler `__, -and then grab the content of the box labeled **\ Geth Deploy\ **. Since -you have already set the parameters, you don't need to change anything -to that text, simply paste the resulting text on your geth window.** - -Wait a minute until the miners pick it up. It will cost you about 850k -Gas. Once that is picked up, it's time to instantiate it and set it up, -by pointing it to the correct address of the token contract you created -previously. - -If everything worked out, you can take a look at the whole organization -by executing this string: - -:: - - "This organization has " + democracy.numProposals() + " proposals and uses the token at the address " + democracy.voterShare() ; - -If everything is setup then your DAO should return a proposal count of 0 -and an address marked as the "founder". While there are still no -proposals, the founder of the DAO can change the address of the token to -anything it wants. - -Register your organization name -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Let's also register a name for your contract so it's easily accessible -(don't forget to check your name availability with -registrar.addr("nameYouWant") before reserving!) - -:: - - var name = "MyPersonalDemocracy" - registrar.reserve.sendTransaction(name, {from: eth.accounts[0]}) - var democracy = eth.contract(daoCompiled.Democracy.info.abiDefinition).at(democracy.address); - democracy.setup.sendTransaction(registrar.addr("MyFirstCoin"),{from:eth.accounts[0]}) - -Wait for the previous transactions to be picked up and then: - -:: - - registrar.setAddress.sendTransaction(name, democracy.address, true,{from: eth.accounts[0]}); - -The Democracy Watchbots -~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - var event = democracy.ProposalAdded({}, '', function(error, result){ - if (!error) - console.log("New Proposal #"+ result.args.proposalID +"!\n Send " + web3.fromWei(result.args.amount, "ether") + " ether to " + result.args.recipient.substring(2,8) + "... for " + result.args.description ) - }); - var eventVote = democracy.Voted({}, '', function(error, result){ - if (!error) - var opinion = ""; - if (result.args.position > 0) { - opinion = "in favor" - } else if (result.args.position < 0) { - opinion = "against" - } else { - opinion = "abstaining" - } - - console.log("Vote on Proposal #"+ result.args.proposalID +"!\n " + result.args.voter + " is " + opinion ) - }); - var eventTally = democracy.ProposalTallied({}, '', function(error, result){ - if (!error) - var totalCount = ""; - if (result.args.result > 1) { - totalCount = "passed" - } else if (result.args.result < 1) { - totalCount = "rejected" - } else { - totalCount = "a tie" - } - console.log("Votes counted on Proposal #"+ result.args.proposalID +"!\n With a total of " + Math.abs(result.args.result) + " out of " + result.args.quorum + ", proposal is " + totalCount + ". Proposal is " + (result.args.active? " still on the floor" : "archived") ) - }); - -Interacting with the DAO -~~~~~~~~~~~~~~~~~~~~~~~~ - -After you are satisfied with what you want, it's time to get all that -ether you got from the crowdfunding into your new organization: - -:: - - eth.sendTransaction({from: eth.accounts[1], to: democracy.address, value: web3.toWei(100, "ether")}) - -This should take only a minute and your country is ready for business! -Now, as a first priority, your organisation needs a nice logo, but -unless you are a designer, you have no idea how to do that. For the sake -of argument let's say you find that your friend Bob is a great designer -who's willing to do it for only 10 ethers, so you want to propose to -hire him. - -:: - - recipient = registrar.addr("bob"); - amount = web3.toWei(10, "ether"); - shortNote = "Logo Design"; - - democracy.newProposal.sendTransaction( recipient, amount, '', shortNote, {from: eth.accounts[0], gas:1000000}) - -After a minute, anyone can check the proposal recipient and amount by -executing these commands: - -:: - - "This organization has " + (Number(democracy.numProposals())+1) + " pending proposals"; - -Keep an eye on the organization -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Unlike most governments, your country's government is completely -transparent and easily programmable. As a small demonstration here's a -snippet of code that goes through all the current proposals and prints -what they are and for whom: - -:: - - function checkAllProposals() { - console.log("Country Balance: " + web3.fromWei( eth.getBalance(democracy.address), "ether") ); - for (i = 0; i< (Number(democracy.numProposals())); i++ ) { - var p = democracy.proposals(i); - var timeleft = Math.floor(((Math.floor(Date.now() / 1000)) - Number(p[4]) - Number(democracy.debatingPeriod()))/60); - console.log("Proposal #" + i + " Send " + web3.fromWei( p[1], "ether") + " ether to address " + p[0].substring(2,6) + " for "+ p[3] + ".\t Deadline:"+ Math.abs(Math.floor(timeleft)) + (timeleft>0?" minutes ago ":" minutes left ") + (p[5]? " Active":" Archived") ); - } - } - - checkAllProposals(); - -A concerned citizen could easily write a bot that periodically pings the -blockchain and then publicizes any new proposals that were put forth, -guaranteeing total transparency. - -Now of course you want other people to be able to vote on your -proposals. You can check the crowdsale tutorial on the best way to -register your contract app so that all the user needs is a name, but for -now let's use the easier version. Anyone should be able to instantiate a -local copy of your country in their computer by using this giant -command: - -:: - - democracy = eth.contract( [{ constant: true, inputs: [{ name: '', type: 'uint256' } ], name: 'proposals', outputs: [{ name: 'recipient', type: 'address' }, { name: 'amount', type: 'uint256' }, { name: 'data', type: 'bytes32' }, { name: 'descriptionHash', type: 'bytes32' }, { name: 'creationDate', type: 'uint256' }, { name: 'numVotes', type: 'uint256' }, { name: 'quorum', type: 'uint256' }, { name: 'active', type: 'bool' } ], type: 'function' }, { constant: false, inputs: [{ name: '_proposalID', type: 'uint256' } ], name: 'executeProposal', outputs: [{ name: 'result', type: 'uint256' } ], type: 'function' }, { constant: true, inputs: [ ], name: 'debatingPeriod', outputs: [{ name: '', type: 'uint256' } ], type: 'function' }, { constant: true, inputs: [ ], name: 'numProposals', outputs: [{ name: '', type: 'uint256' } ], type: 'function' }, { constant: true, inputs: [ ], name: 'founder', outputs: [{ name: '', type: 'address' } ], type: 'function' }, { constant: false, inputs: [{ name: '_proposalID', type: 'uint256' }, { name: '_position', type: 'int256' } ], name: 'vote', outputs: [{ name: 'voteID', type: 'uint256' } ], type: 'function' }, { constant: false, inputs: [{ name: '_voterShareAddress', type: 'address' } ], name: 'setup', outputs: [ ], type: 'function' }, { constant: false, inputs: [{ name: '_recipient', type: 'address' }, { name: '_amount', type: 'uint256' }, { name: '_data', type: 'bytes32' }, { name: '_descriptionHash', type: 'bytes32' } ], name: 'newProposal', outputs: [{ name: 'proposalID', type: 'uint256' } ], type: 'function' }, { constant: true, inputs: [ ], name: 'minimumQuorum', outputs: [{ name: '', type: 'uint256' } ], type: 'function' }, { inputs: [ ], type: 'constructor' } ] ).at(registrar.addr('MyPersonalCountry')) - -Then anyone who owns any of your tokens can vote on the proposals by -doing this: - -:: - - var proposalID = 0; - var position = -1; // +1 for voting yea, -1 for voting nay, 0 abstains but counts as quorum - democracy.vote.sendTransaction(proposalID, position, {from: eth.accounts[0], gas: 1000000}); - - var proposalID = 1; - var position = 1; // +1 for voting yea, -1 for voting nay, 0 abstains but counts as quorum - democracy.vote.sendTransaction(proposalID, position, {from: eth.accounts[0], gas: 1000000}); - -Unless you changed the basic parameters in the code, any proposal will -have to be debated for at least a week until it can be executed. After -that anyone—even a non-citizen—can demand the votes to be counted and -the proposal to be executed. The votes are tallied and weighted at that -moment and if the proposal is accepted then the ether is sent -immediately and the proposal is archived. If the votes end in a tie or -the minimum quorum hasn’t been reached, the voting is kept open until -the stalemate is resolved. If it loses, then it's archived and cannot be -voted again. - -:: - - var proposalID = 1; - democracy.executeProposal.sendTransaction(proposalID, {from: eth.accounts[0], gas: 1000000}); - -If the proposal passed then you should be able to see Bob's ethers -arriving on his address: - -:: - - web3.fromWei(eth.getBalance(democracy.address), "ether") + " ether"; - web3.fromWei(eth.getBalance(registrar.addr("bob")), "ether") + " ether"; - -**Try for yourself:** This is a very simple democracy contract, which -could be vastly improved: currently, all proposals have the same -debating time and are won by direct vote and simple majority. Can you -change that so it will have some situations, depending on the amount -proposed, that the debate might be longer or that it would require a -larger majority? Also think about some way where citizens didn't need to -vote on every issue and could temporarily delegate their votes to a -special representative. You might have also noticed that we added a tiny -description for each proposal. This could be used as a title for the -proposal or could be a hash of a larger document describing it in -detail. - -Let's go exploring! -~~~~~~~~~~~~~~~~~~~ - -You have reached the end of this tutorial, but it's just the beginning -of a great adventure. Look back and see how much you accomplished: you -created a living, talking robot, your own cryptocurrency, raised funds -through a trustless crowdfunding and used it to kickstart your own -personal democratic organization. - -For the sake of simplicity, we only used the democratic organization you -created to send ether around, the native currency of Ethereum. While -that might be good enough for some, this is only scratching the surface -of what can be done. In the Ethereum network contracts have all the same -rights as any normal user, meaning that your organization could do any -of the transactions that you executed coming from your own accounts. - -What could happen next? -~~~~~~~~~~~~~~~~~~~~~~~ - -- The greeter contract you created at the beginning could be improved - to charge ether for its services and could funnel those funds into - the DAO. - -- The tokens you still control could be sold on a decentralized - exchange or traded for goods and services to fund further develop the - first contract and grow the organization. - -- Your DAO could own its own name on the name registrar, and then - change where it's redirecting in order to update itself if the token - holders approved. - -- The organization could hold not only ethers, but any kind of other - coin created on Ethereum, including assets whose value are tied to - the bitcoin or dollar. - -- The DAO could be programmed to allow a proposal with multiple - transactions, some scheduled to the future. It could also own shares - of other DAO's, meaning it could vote on larger organization or be a - part of a federation of DAO's. - -- The Token Contract could be reprogrammed to hold ether or to hold - other tokens and distribute it to the token holders. This would link - the value of the token to the value of other assets, so paying - dividends could be accomplished by simply moving funds to the token - address. - -This all means that this tiny society you created could grow, get -funding from third parties, pay recurrent salaries, own any kind of -crypto-assets and even use crowdsales to fund its activities. All with -full transparency, complete accountability and complete immunity from -any human interference. While the network lives the contracts will -execute exactly the code they were created to execute, without any -exception, forever. - -So what will your contract be? Will it be a country, a company, a -non-profit group? What will your code do? - -That's up to you. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Contracts-and-Transactions.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Contracts-and-Transactions.rst deleted file mode 100644 index ba62165..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Contracts-and-Transactions.rst +++ /dev/null @@ -1,986 +0,0 @@ -Account types and transactions -============================== - -There are two types of accounts in Ethereum state: \* Normal or -externally controlled accounts and \* contracts, i.e., snippets of code, -think a class. - -Both types of accounts have an ether balance. - -Transactions can be fired from both types of accounts, though contracts -only fire transactions in response to other transactions that they have -received. Therefore, all action on the Ethereum block chain is set in -motion by transactions fired from externally-controlled accounts. - -The simplest transactions are ether transfer transactions. But before we -go into that you should read up on -`accounts `__ -and perhaps on -`mining `__. - -Ether transfer -============== - -Assuming the account you are using as sender has sufficient funds, -sending ether couldn't be easier. Which is also why you should probably -be careful with this! You have been warned. - -.. code:: js - - eth.sendTransaction({from: '0x036a03fc47084741f83938296a1c8ef67f6e34fa', to: '0xa8ade7feab1ece71446bed25fa0cf6745c19c3d5', value: web3.toWei(1, "ether")}) - -Note the unit conversion in the ``value`` field. Transaction values are -expressed in weis, the most granular units of value. If you want to use -some other unit (like ``ether`` in the example above), use the function -``web3.toWei`` for conversion. - -Also, be advised that the amount debited from the source account will be -slightly larger than that credited to the target account, which is what -has been specified. The difference is a small transaction fee, discussed -in more detail later. - -Contracts can receive transfers just like externally controlled -accounts, but they can also receive more complicated transactions that -actually run (parts of) their code and update their state. In order to -understand those transactions, a rudimentary understanding of contracts -is required. - -Writing a contract -================== - -Contracts live on the blockchain in an Ethereum-specific binary format -(Ethereum Virtual Machine (=EVM) bytecode). However, contracts are -typically written in some high level language such as -`solidity `__ -and then compiled into byte code to be uploaded on the blockchain. - -Note that other languages also exist, notably -`serpent `__ and -`LLL `__. Legacy -Mutan (an early c-like language) is no longer officially maintained. - -Language Resources ------------------- - -Solidity -~~~~~~~~ - -Docs and tutorials -^^^^^^^^^^^^^^^^^^ - -- `Ethereum wiki - tutorial `__ -- `Solidity FAQ - Ethereum - forum `__ -- `The Solidity Programming Language · - ethereum/wiki `__ -- `Ethereum ÐΞVcon-0: Solidity, Vision and Roadmap - YouTube - Video `__ -- `Dapps for beginners `__ -- `Tutorial - 1 `__ -- `Tutorial - 2 `__ -- `Tutorial 3 (JavaScript API for - Ethereum) `__ - (Outdated) -- `Solidity tutorial 1 by Eris - Industries `__ -- `dapp tutorials by Andreas Olofsson (Eris - Industries) `__ -- `Eris Solidity - resources `__ - -Examples -^^^^^^^^ - -- `A dapp - listing `__ -- `Solidity Contracts on Ethereum - - Ether.Fund `__ -- `Ethereum dapp bin `__ -- `Solidity Standard - Library `__ -- `Whisper chat - dapp `__ - written in meteor -- `order statistic - tree `__ by - Conrad Bars - -Compilers -^^^^^^^^^ - -- `Solidity realtime - compiler `__ - -Serpent -~~~~~~~ - -- `source on github `__ -- `serpent language - spec `__ - -Contract/dapp development environments and frameworks ------------------------------------------------------ - -- `Mix standalone - IDE `__ by - ETHDEV -- in-browser `Cosmo `__ that - connects to ``geth`` via RPC. By Nick Dodson -- `embark - framework `__ by - Iuri Mathias -- `truffle `__ by Tim Coulter - -Compiling a contract -==================== - -Contracts live on the blockchain in an Ethereum-specific binary format -(Ethereum Virtual Machine (=EVM) bytecode). However, contracts are -typically written in some high level language such as -`solidity `__ -and then compiled into byte code to be uploaded on the blockchain. - -For the frontier release, ``geth`` supports solidity compilation through -system call to ``solc``, the command line `solidity -compiler `__ -by Christian R. and Lefteris K. You can try `Solidity realtime -compiler `__ (by Christian R) -or `Cosmo `__ or -`Mix `__. - -If you start up your ``geth`` node, you can check if the solidity -compiler is available. This is what happens, if it is not: - -.. code:: js - - > eth.compile.solidity("") - eth_compileSolidity method not available: solc (solidity compiler) not found - at InvalidResponse (:-57465:-25) - at send (:-115373:-25) - at solidity (:-104109:-25) - at :1:1 - -After you found a way to install ``solc``, you make sure it's in the -path. If -```eth.getCompilers()`` `__ -still does not find it (returns an empty array), you can set a custom -path to the ``solc`` executable on the command line using th ``solc`` -flag. - -:: - - geth --datadir ~/frontier/00 --solc /usr/local/bin/solc --natspec - -You can also set this option at runtime via the console: - -.. code:: js - - > admin.setSolc("/usr/local/bin/solc") - solc v0.9.32 - Solidity Compiler: /usr/local/bin/solc - Christian and Lefteris (c) 2014-2015 - true - -Let us take this simple contract source: - -.. code:: js - - > source = "contract test { function multiply(uint a) returns(uint d) { return a * 7; } }" - -This contract offers a unary method: called with a positive integer -``a``, it returns ``a * 7``. - -You are ready to compile solidity code in the ``geth`` JS console using -```eth.compile.solidity`` `__: - -.. code:: js - - > contract = eth.compile.solidity(source).test - { - code: '605280600c6000396000f3006000357c010000000000000000000000000000000000000000000000000000000090048063c6888fa114602e57005b60376004356041565b8060005260206000f35b6000600782029050604d565b91905056', - info: { - language: 'Solidity', - languageVersion: '0', - compilerVersion: '0.9.13', - abiDefinition: [{ - constant: false, - inputs: [{ - name: 'a', - type: 'uint256' - } ], - name: 'multiply', - outputs: [{ - name: 'd', - type: 'uint256' - } ], - type: 'function' - } ], - userDoc: { - methods: { - } - }, - developerDoc: { - methods: { - } - }, - source: 'contract test { function multiply(uint a) returns(uint d) { return a * 7; } }' - } - } - -The compiler is also available via -`RPC `__ and therefore -via -`web3.js `__ -to any in-browser Ðapp connecting to ``geth`` via RPC/IPC. - -The following example shows how you interface ``geth`` via JSON-RPC to -use the compiler. - -:: - - ./geth --datadir ~/eth/ --loglevel 6 --logtostderr=true --rpc --rpcport 8100 --rpccorsdomain '*' --mine console 2>> ~/eth/eth.log - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_compileSolidity","params":["contract test { function multiply(uint a) returns(uint d) { return a * 7; } }"],"id":1}' http://127.0.0.1:8100 - -The compiler output for one source will give you contract objects each -representing a single contract. The actual return value of -``eth.compile.solidity`` is a map of contract name -- contract object -pairs. Since our contract's name is ``test``, -``eth.compile.solidity(source).test`` will give you the contract object -for the test contract containing the following fields: - -- ``code``: the compiled EVM code -- ``info``: the rest of the metainfo the compiler outputs -- ``source``: the source code -- ``language``: contract language (Solidity, Serpent, LLL) -- ``languageVersion``: contract language version -- ``compilerVersion``: compiler version -- ``abiDefinition``: `Application Binary Interface - Definition `__ -- ``userDoc``: `NatSpec user - Doc `__ -- ``developerDoc``: `NatSpec developer - Doc `__ - -The immediate structuring of the compiler output (into ``code`` and -``info``) reflects the two very different **paths of deployment**. The -compiled EVM code is sent off to the blockchain with a contract creation -transaction while the rest (info) will ideally live on the decentralised -cloud as publicly verifiable metadata complementing the code on the -blockchain. - -If your source contains multiple contracts, the output will contain an -entry for each contact, the corresponding contract info object can be -retrieved with the name of the contract as attribute name. You can try -this by inspecting the most current GlobalRegistrar code: - -.. code:: js - - contracts = eth.compile.solidity(globalRegistrarSrc) - -Creating and deploying a contract -================================= - -Now that you got both an unlocked account as well as some funds, you can -create a contract on the blockchain by `sending a -transaction `__ -to the empty address with the evm code as data. Simple, eh? - -.. code:: js - - primaryAddress = eth.accounts[0] - MyContract = eth.contract(abi); - contact = MyContract.new(arg1, arg2, ...,{from: primaryAddress, data: evmCode}) - -All binary data is serialised in hexadecimal form. Hex strings always -have a hex prefix ``0x``. - -Note that ``arg1, arg2, ...`` are the arguments for the contract -constructor, in case it accepts any. - -Also note that this step requires you to pay for execution. Your balance -on the account (that you put as sender in the ``from`` field) will be -reduced according to the gas rules of the VM once your transaction makes -it into a block. More on that later. After some time, your transaction -should appear included in a block confirming that the state it brought -about is a consensus. Your contract now lives on the blockchain. - -The asynchronous way of doing the same looks like this: - -.. code:: js - - MyContract.new([arg1, arg2, ...,]{from: primaryAccount, data: evmCode}, function(err, contract) { - if (!err && contract.address) - console.log(contract.address); - }); - -Gas and transaction costs -========================= - -So how did you pay for all this? Under the hood, the transaction -specified a gas limit and a gasprice, both of which could have been -specified directly in the transaction object. - -Gas limit is there to protect you from buggy code running until your -funds are depleted. The product of ``gasPrice`` and ``gas`` represents -the maximum amount of Wei that you are willing to pay for executing the -transaction. What you specify as ``gasPrice`` is used by miners to rank -transactions for inclusion in the blockchain. It is the price in Wei of -one unit of gas, in which VM operations are priced. - -The gas expenditure incurred by running your contract will be bought by -the ether you have in your account at a price you specified in the -transaction with ``gasPrice``. If you do not have the ether to cover all -the gas requirements to complete running your code, the processing -aborts and all intermediate state changes roll back to the -pre-transaction snapshot. The gas used up to the point where execution -stopped were used after all, so the ether balance of your account will -be reduced. These parameters can be adjusted on the transaction object -fields ``gas`` and ``gasPrice``. The ``value`` field is used the same as -in ether transfer transactions between normal accounts. In other words -transferring funds is available between any two accounts, either normal -(i.e. externally controlled) or contract. If your contract runs out of -funds, you should see an insufficient funds error. - -For testing and playing with contracts you can use the test network or -`set up a private node (or -cluster) `__ -potentially isolated from all the other nodes. If you then mine, you can -make sure that your transaction will be included in the next block. You -can see the pending transactions with: - -.. code:: js - - eth.getBlock("pending", true).transactions - -You can retrieve blocks by number (height) or by their hash: - -.. code:: js - - genesis = eth.getBlock(0) - eth.getBlock(genesis.hash).hash == genesis.hash - true - -Use ``eth.blockNumber`` to get the current blockchain height and the -"latest" magic parameter to access the current head (newest block). - -.. code:: js - - currentHeight = eth.blockNumber() - eth.getBlock("latest").hash == eth.getBlock(eth.blockNumber).hash - true - -Contract info (metadata) -======================== - -In the previous sections we explained how you create a contract on the -blockchain. Now we deal with the rest of the compiler output, the -**contract metadata** or contract info. The idea is that - -- contract info is uploaded somewhere identifiable by a ``url`` which - is publicly accessible -- anyone can find out what the ``url`` is only knowing the contracts - address - -These requirements are achieved very simply by using a 2 step blockchain -registry. The first step registers the contract code (hash) with a -content hash in a contract called ``HashReg``. The second step registers -a url with the content hash in the ``UrlHint`` contract. These `simple -registry -contracts `__ -will be part of the frontier proposition. - -By using this scheme, it is sufficient to know a contract's address to -look up the url and fetch the actual contract metadata info bundle. Read -on to learn why this is good. - -So if you are a conscientious contract creator, the steps are the -following: - -1. Deploy the contract itself to the blockchain -2. Get the contract info json file. -3. Deploy contract info json file to any url of your choice -4. Register codehash ->content hash -> url - -The JS API makes this process very easy by providing helpers. Call -```admin.register`` <>`__ to extract info from the contract, write out -its json serialisation in the given file, calculates the content hash of -the file and finally registers this content hash to the contract's code -hash. Once you deployed that file to any url, you can use -```admin.registerUrl`` <>`__ to register the url with your content hash -on the blockchain as well. (Note that in case a fixed content addressed -model is used as document store, the url-hint is no longer necessary.) - -.. code:: js - - source = "contract test { function multiply(uint a) returns(uint d) { return a * 7; } }" - // compile with solc - contract = eth.compile.solidity(source).test - // create contract object - var MyContract = eth.contract(contract.info.abiDefinition) - // extracts info from contract, save the json serialisation in the given file, - contenthash = admin.saveInfo(contract.info, "~/dapps/shared/contracts/test/info.json") - // send off the contract to the blockchain - MyContract.new({from: primaryAccount, data: contract.code}, function(error, contract){ - if(!error && contract.address) { - // calculates the content hash and registers it with the code hash in `HashReg` - // it uses address to send the transaction. - // returns the content hash that we use to register a url - admin.register(primaryAccount, contract.address, contenthash) - // here you deploy ~/dapps/shared/contracts/test/info.json to a url - admin.registerUrl(primaryAccount, hash, url) - } - }); - -Interacting with contracts -========================== - -```eth.contract`` `__ -can be used to define a contract *class* that will comply with the -contract interface as described in its `ABI -definition `__. - -.. code:: js - - var Multiply7 = eth.contract(contract.info.abiDefinition); - var myMultiply7 = Multiply7.at(address); - -Now all the function calls specified in the abi are made available on -the contract instance. You can just call those methods on the contract -instance and chain ``sendTransaction(3, {from: address})`` or -``call(3)`` to it. The difference between the two is that ``call`` -performs a "dry run" locally, on your computer, while -``sendTransaction`` would actually submit your transaction for inclusion -in the block chain and the results of its execution will eventually -become part of the global consensus. In other words, use ``call``, if -you are interested only in the return value and use ``sendTransaction`` -if you only care about "side effects" on the state of the contract. - -In the example above, there are no side effects, therefore -``sendTransaction`` only burns gas and increases the entropy of the -universe. All "useful" functionality is exposed by ``call``: - -.. code:: js - - myMultiply7.multiply.call(6) - 42 - -Now suppose this contract is not yours, and you would like documentation -or look at the source code. This is made possible by making available -the contract info bundle and register it in the blockchain. The -``admin`` API provides convenience methods to fetch this bundle for any -contract that chose to register. To see how it works, read about -`Contract -Metadata `__ or -read the contract info deployment section of this document. - -.. code:: js - - // get the contract info for contract address to do manual verification - var info = admin.getContractInfo(address) // lookup, fetch, decode - var source = info.source; - var abiDef = info.abiDefinition - -NatSpec -======= - -This section will further elaborate what you can do with contracts and -transactions building on a protocol NatSpec. Solidity implements smart -comments doxigen style which then can be used to generate various -facades meta documents of the code. One such use case is to generate -custom messages for transaction confirmation that clients can prompt -users with. - -So we now extend the ``multiply7`` contract with a smart comment -specifying a custom confirmation message (notice). - -.. code:: js - - contract test { - /// @notice Will multiply `a` by 7. - function multiply(uint a) returns(uint d) { - return a * 7; - } - } - -The comment has expressions in between backticks which are to be -evaluated at the time the transaction confirmation message is presented -to the user. The variables that refer to parameters of method calls then -are instantiated in accordance with the actual transaction data sent by -the user (or the user's dapp). NatSpec support for confirmation notices -is fully implemented in ``geth``. NatSpec relies on both the abi -definition as well as the userDoc component to generate the proper -confirmations. Therefore in order to access that, the contract needs to -have registered its contract info as described above. - -Let us see a full example. As a very conscientious smart contract dev, -you first create your contract and deploy according to the recommended -steps above: - -.. code:: js - - source = "contract test { - /// @notice Will multiply `a` by 7. - function multiply(uint a) returns(uint d) { - return a * 7; - } - }" - contract = eth.compile.solidity(source).test - MyContract = eth.contract(contract.info.abiDefinition) - contenthash = admin.saveInfo(contract.info, "~/dapps/shared/contracts/test/info.json") - MyContract.new({from: primary, data: contract.code}, function(error, contract){ - if(!error && contract.address) { - admin.register(primary, contract.address, contenthash) - // put it up on your favourite oldworld site: - admin.registerUrl(contentHash, "http://dapphub.com/test/info.json") - } - }); - -Note that if we use content addressed storage system like swarm the -second step is unnecessary, since the contenthash is (deterministically -translates to) the unique address of the content itself. - -For the purposes of a painless example just simply use the file url -scheme (not exactly the cloud, but will show you how it works) without -needing to deploy. - -.. code:: js - - admin.registerUrl(contentHash, "file:///home/nirname/dapps/shared/contracts/test/info.json") - -Now you are done as a dev, so swap seats as it were and pretend that you -are a user who is sending a transaction to the infamous ``multiply7`` -contract. - -You need to start the client with the ``--natspec`` flag to enable smart -confirmations and contractInfo fetching. You can also set it on the -console with ``admin.startNatSpec()`` and ``admin.stopNatSpec()``. - -:: - - geth --natspec --unlock primary console 2>> /tmp/eth.log - -Now at the console type: - -.. code:: js - - // obtain the abi definition for your contract - var info = admin.getContractInfo(address) - var abiDef = info.abiDefinition - // instantiate a contract for transactions - var Multiply7 = eth.contract(abiDef); - var myMultiply7 = Multiply7.at(address); - -And now try to send an actual transaction: - -.. code:: js - - > myMultiply7.multiply.sendTransaction(6, {from: eth.accounts[0]}) - NatSpec: Will multiply 6 by 7. - Confirm? [y/n] y - > - -When this transaction gets included in a block, somewhere on a lucky -miner's computer, 6 will get multiplied by 7, with the result ignored. -Mission accomplished. - -If the transaction is not picked up, we can see it with: - -.. code:: js - - eth.pendingTransactions - -This accumulates all the transactions sent, even the ones that were -rejected and are not included in the current mined block (trans state). -These latter can be shown by: - -.. code:: js - - eth.getBlock("pending", true).transactions() - -if you identify the index of your rejected transaction, you can resend -it with modified gas limit and gas price (both optional parameters): - -.. code:: js - - tx = eth.pendingTransactions[1] - eth.resend(tx, newGasPrice, newGasLimit) - -Testing contracts and transactions -================================== - -Often you need to resort to a low level strategy of testing and -debugging contracts and transactions. This section introduces some debug -tools and practices you can use. In order to test contracts and -transactions without real-word consequences, you best test it on a -private blockchain. This can be achieved with configuring an alternative -network id (select a unique integer) and/or disable peers. It is -recommended practice that for testing you use an alternative data -directory and ports so that you never even accidentally clash with your -live running node (assuming that runs using the defaults. Starting your -``geth`` with in VM debug mode with profiling and highest logging -verbosity level is recommended: - -.. code:: js - - geth --datadir ~/dapps/testing/00/ --port 30310 --rpcport 8110 --networkid 4567890 --nodiscover --maxpeers 0 --vmdebug --verbosity 6 --pprof --pprofport 6110 console 2>> ~/dapp/testint/00/00.log - -Before you can submit any transactions, you need mine some ether on your -private chain and for that you need an account. See the sections on -`Mining `__ and -`Accounts `__ - -.. code:: js - - // create account. will prompt for password - personal.newAccount("mypassword"); - // name your primary account, will often use it - primary = eth.accounts[0]; - // check your balance (denominated in ether) - balance = web3.fromWei(eth.getBalance(primary), "ether"); - -.. code:: js - - // assume an existing unlocked primary account - primary = eth.accounts[0]; - - // mine 10 blocks to generate ether - - // starting miner - miner.start(8); - // sleep for 10 blocks. - admin.sleepBlocks(10); - // then stop mining (just not to burn heat in vain) - miner.stop() ; - balance = web3.fromWei(eth.getBalance(primary), "ether"); - -After you create transactions, you can force process them with the -following lines: - -:: - - miner.start(1); - admin.sleepBlocks(1); - miner.stop() ; - -you can check your pending transactions with - -.. code:: js - - // shows transaction pool - txpool.status - // number of pending txs - eth.getBlockTransactionCount("pending"); - // print all pending txs - eth.getBlock("pending", true).transactions - -If you submitted contract creation transaction, you can check if the -desired code actually got inserted in the current blockchain: - -.. code:: js - - txhash = eth.sendTansaction({from:primary, data: code}) - //... mining - contractaddress = eth.getTransactionReceipt(txhash); - eth.getCode(contractaddress) - -Registrar services -================== - -The frontier chain comes with some very basic baselayer services, most -of all the registrar. The registrar is composed of 3 components. - -- GlobalRegistrar to associate names (strings) to accounts (addresses). -- HashReg to associate hashes to hashes (map any object to a 'content' - hash. -- UrlHint to associate content hashes to a hint for the location of the - content. This is needed only if content storage is not content - addressed, otherwise content hash is already the content address. If - it is used, content fetched from the url should hash to content hash. - In order to check authenticity of content one can check if this - verifies. - -Create and deploy GlobalRegistrar, HashReg and UrlHint ------------------------------------------------------- - -If the registrar contracts are not hardcoded in the blockchain (they are -not at the time of writing), the registrars need to be deployed at least -once on every chain. - -If you are on *the main live chain*, the address of the main global -registrar is hardcoded in the latest clients and therefore *you do not -need to do anything*. If you want to change this or you are on a private -chain you need to deploy these contracts at least once: - -.. code:: js - - primary = eth.accounts[0]; - - globalRegistrarAddr = admin.setGlobalRegistrar("", primary); - hashRegAddr = admin.setHashReg("", primary); - urlHintAddr = admin.setUrlHint("", primary); - -You need to mine or wait till the txs are all picked up. Initialise the -registrar on the new address and check if the other registrars' names -resolve to the correct addresses: - -.. code:: js - - registrar = GlobalRegistrar.at(globalRegistrarAddr); - primary == registrar.owner("HashReg"); - primary == registrar.owner("UrlHint"); - hashRegAddr == registrar.addr("HashReg"); - urlHintAddr registrar.addr("UrlHint"); - -and the following ones return correct code: - -.. code:: js - - eth.getCode(registrar.address); - eth.getCode(registrar.addr("HashReg")); - eth.getCode(registrar.addr("UrlHint")); - -From the second time onwards on the same chain as well as on other -nodes, you simply seed with the GlobalRegistrars address, the rest is -handled through it. - -.. code:: js - - primary = eth.accounts[0]; - globalRegistrarAddr = "0x225178b4829bbe7c9f8a6d2e3d9d87b66ed57d4f" - - // set the global registrar address - admin.setGlobalRegistrar(globalRegistrarAddr) - // set HashReg address via globalRegistrar - hashRegAddr = admin.setHashReg() - // set UrlHint address via globalRegistrar - urlHintAddr = admin.setUrlHint() - - // (re)sets the registrar variable to a GlobalRegistrar contract instance - registrar = GlobalRegistrar.at(globalRegistrarAddr); - -If this is successful, you should be able to check with the following -commands if the registrar returns addresses: - -.. code:: js - - registrar.owner("HashReg"); - registrar.owner("UrlHint"); - registrar.addr("HashReg"); - registrar.addr("UrlHint"); - -and the following ones return correct code: - -.. code:: js - - eth.getCode(registrar.address); - eth.getCode(registrar.addr("HashReg")); - eth.getCode(registrar.addr("UrlHint")); - -Using the registrar services ----------------------------- - -Can provide useful interfaces between contracts and dapps. - -Global registrar -~~~~~~~~~~~~~~~~ - -To reserve a name register an account address with it, you need the -following: - -:: - - registrar.reserve.sendTransaction(name, {from:primary}) - registrar.setAddress.sendTransaction (name, address, true, {from: primary}) - -You need to wait for the transactions to be picked up (or force mine -them if you are on a private chain). To check you query the registrar: - -.. code:: js - - registrar.owner(name) - registrar.addr(name) - -HashReg and UrlHint -~~~~~~~~~~~~~~~~~~~ - -HashReg and UrlHint can be used with the following abis: - -.. code:: js - - hashRegAbi = '[{"constant":false,"inputs":[],"name":"setowner","outputs":[],"type":"function"},{"constant":false,"inputs":[{"name":"_key","type":"uint256"},{"name":"_content","type":"uint256"}],"name":"register","outputs":[],"type":"function"}]' - urlHintAbi = '[{"constant":false,"inputs":[{"name":"_hash","type":"uint256"},{"name":"idx","type":"uint8"},{"name":"_url","type":"uint256"}],"name":"register","outputs":[],"type":"function"}]' - -setting up the contract instances: - -.. code:: js - - hashReg = eth.contract(hashRegAbi).at(registrar.addr("HashReg"))); - urlHint = eth.contract(UrlHintAbi).at(registrar.addr("UrlHint"))); - -Associate a content hash to a key hash: - -.. code:: js - - hashReg.register.sendTransaction(keyhash, contenthash, {from:primary}) - -Associate a url to a content hash: - -.. code:: js - - urlHint.register.sendTransaction(contenthash, url, {from:primary}) - -To check resolution: - -.. code:: js - - contenthash = hashReg._hash(keyhash); - url = urlHint._url(contenthash); - -Example script -============== - -The example script below demonstrates most features discussed in this -tutorial. You can run it with the -`JSRE `__ -as ``geth js script.js 2>>geth.log`` . If you want to run this test on a -local private chain, then start geth with: - -:: - - geth --maxpeers 0 --networkid 123456 --nodiscover --unlock primary js script.js 2>> geth.log - -Note that ``networkid`` can be any arbitrary non-negative integer, 0 is -always the live net. - -:: - - personal.newAccount("") - - primary = eth.accounts[0]; - balance = web3.fromWei(eth.getBalance(primary), "ether"); - personal.unlockAccount(primary, "00"); - // miner.setEtherbase(primary) - - miner.start(8); admin.sleepBlocks(10); miner.stop() ; - - // 0xc6d9d2cd449a754c494264e1809c50e34d64562b - primary = eth.accounts[0]; - balance = web3.fromWei(eth.getBalance(primary), "ether"); - - globalRegistrarTxHash = admin.setGlobalRegistrar("0x0"); - //'0x0' - globalRegistrarTxHash = admin.setGlobalRegistrar("", primary); - //'0xa69690d2b1a1dcda78bc7645732bb6eefcd6b188eaa37abc47a0ab0bd87a02e8' - miner.start(1); admin.sleepBlocks(1); miner.stop(); - //true - globalRegistrarAddr = eth.getTransactionReceipt(globalRegistrarTxHash).contractAddress; - //'0x3d255836f5f8c9976ec861b1065f953b96908b07' - eth.getCode(globalRegistrarAddr); - //... - admin.setGlobalRegistrar(globalRegistrarAddr); - registrar = GlobalRegistrar.at(globalRegistrarAddr); - - hashRegTxHash = admin.setHashReg("0x0"); - hashRegTxHash = admin.setHashReg("", primary); - txpool.status - miner.start(1); admin.sleepBlocks(1); miner.stop(); - hashRegAddr = eth.getTransactionReceipt(hashRegTxHash).contractAddress; - eth.getCode(hashRegAddr); - - registrar.reserve.sendTransaction("HashReg", {from:primary}); - registrar.setAddress.sendTransaction("HashReg",hashRegAddr,true, {from:primary}); - miner.start(1); admin.sleepBlocks(1); miner.stop(); - registrar.owner("HashReg"); - registrar.addr("HashReg"); - - urlHintTxHash = admin.setUrlHint("", primary); - miner.start(1); admin.sleepBlocks(1); miner.stop(); - urlHintAddr = eth.getTransactionReceipt(urlHintTxHash).contractAddress; - eth.getCode(urlHintAddr); - - registrar.reserve.sendTransaction("UrlHint", {from:primary}); - registrar.setAddress.sendTransaction("UrlHint",urlHintAddr,true, {from:primary}); - miner.start(1); admin.sleepBlocks(1); miner.stop(); - registrar.owner("UrlHint"); - registrar.addr("UrlHint"); - - globalRegistrarAddr = "0xfd719187089030b33a1463609b7dfea0e5de25f0" - admin.setGlobalRegistrar(globalRegistrarAddr); - registrar = GlobalRegistrar.at(globalRegistrarAddr); - admin.setHashReg(""); - admin.setUrlHint(""); - - ///// /////////////////////////////// - - admin.stopNatSpec(); - primary = eth.accounts[0]; - personal.unlockAccount(primary, "00") - - globalRegistrarAddr = "0xfd719187089030b33a1463609b7dfea0e5de25f0"; - admin.setGlobalRegistrar(globalRegistrarAddr); - registrar = GlobalRegistrar.at(globalRegistrarAddr); - admin.setHashReg("0x0"); - admin.setHashReg(""); - admin.setUrlHint("0x0"); - admin.setUrlHint(""); - - - registrar.owner("HashReg"); - registrar.owner("UrlHint"); - registrar.addr("HashReg") - registrar.addr("UrlHint"); - - - ///////////////////////////////////// - eth.getBlockTransactionCount("pending"); - miner.start(1); admin.sleepBlocks(1); miner.stop(); - - source = "contract test {\n" + - " /// @notice will multiply `a` by 7.\n" + - " function multiply(uint a) returns(uint d) {\n" + - " return a * 7;\n" + - " }\n" + - "} "; - contract = eth.compile.solidity(source).test; - txhash = eth.sendTransaction({from: primary, data: contract.code}); - - eth.getBlock("pending", true).transactions; - - miner.start(1); admin.sleepBlocks(1); miner.stop(); - contractaddress = eth.getTransactionReceipt(txhash).contractAddress; - eth.getCode(contractaddress); - - multiply7 = eth.contract(contract.info.abiDefinition).at(contractaddress); - fortytwo = multiply7.multiply.call(6); - - ///////////////////////////////// - - // register a name for the contract - registrar.reserve.sendTransaction(primary, {from: primary}); - registrar.setAddress.sendTransaction("multiply7", contractaddress, true, {from: primary}); - //////////////////////// - - admin.stopNatSpec(); - filename = "/info.json"; - contenthash = admin.saveInfo(contract.info, "/tmp" + filename); - admin.register(primary, contractaddress, contenthash); - eth.getBlock("pending", true).transactions; - miner.start(1); admin.sleepBlocks(1); miner.stop(); - - admin.registerUrl(primary, contenthash, "file://" + filename); - eth.getBlock("pending", true).transactions; - miner.start(1); admin.sleepBlocks(1); miner.stop(); - - //////////////////// - - // retrieve contract address using global registrar entry with 'multply7' - contractaddress = registrar.addr("multiply7); - // retrieve the info using the url - info = admin.getContractInfo(contractaddress); - multiply7 = eth.contract(info.abiDefinition).at(contractaddress); - // try Natspec - admin.startNatSpec(); - fortytwo = multiply7.multiply.sendTransaction(6, { from: primary }); diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Creating-your-own-Ethereum-apps-using-Eth-go.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Creating-your-own-Ethereum-apps-using-Eth-go.rst deleted file mode 100644 index de5c41f..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Creating-your-own-Ethereum-apps-using-Eth-go.rst +++ /dev/null @@ -1,139 +0,0 @@ -The modular nature of Go and the Ethereum Go implementation, -`eth-go `__, make it very easy to -build your own Ethereum native applications. - -This post will cover the minimal steps required to build an native -Ethereum application. - -Ethereum comes with a global config found in the -`ethutil `__ -package. The global config requires you to set a base path to store it's -files (database, settings, etc). - -.. code:: go - - func main() { - // Read config - ethutil.ReadConfig(".test", ethutil.LogStd, nil, "MyEthApp") - } - -ReadConfig takes four arguments. The data folder to use, a log flag, a -globalConf instance and an id string to identify your app to other nodes -in the network. - -Once you've configured the global config you can set up and create your -Ethereum node. The Ethereum Object, or Node, will handle all trafic from -and to the Ethereum network as well as handle all incoming block and -transactions. A new node can be created through the ``new`` method found -in `eth-go `__. - -.. code:: go - - func main() { - // Read config - ethutil.ReadConfig(".test", ethutil.LogStd, nil, "MyEthApp") - - // Create a new Ethereum node - ethereum, err := eth.New(eth.CapDefault, false) - if err != nil { - panic(fmt.Sprintf("Could not start node: %s\n", err)) - } - // Set the port (default 30303) - ethereum.Port = "10101" - // Once we reach max, bounce them off. - ethereum.MaxPeers = 10 - } - -New requires two arguments; the capabilities of the node and whether or -not to use UPNP for port-forwarding. If you don't want to fallback to -client-only features set an Ethereum port and the max amount of peers -this node can connect to. - -In order to identify the node to the network you'll be required to -create a private key. The easiest way to create a new keypair is by -using the ``KeyRing`` found in the ``ethutil`` package. - -.. code:: go - - func main() { - // Read config - ethutil.ReadConfig(".test", ethutil.LogStd, nil, "MyEthApp") - - // Create a new Ethereum node - ethereum, err := eth.New(eth.CapDefault, false) - if err != nil { - panic(fmt.Sprintf("Could not start node: %s\n", err)) - } - // Set the port (default 30303) - ethereum.Port = "10101" - // Once we reach max, bounce them off. - ethereum.MaxPeers = 10 - - keyRing := ethutil.GetKeyRing() - // Create a new key if non exist - if keyRing.Len() == 0 { - // Create a new keypair - keyPair, err := ethutil.GenerateNewKeyPair() - if err != nil { - panic(err) - } - - // Add the keypair to the key ring - keyRing.Add(keyPair) - } - } - -Once the base Ethereum stack has been set up it's time to fire up its -engines and connect to the main network. - -.. code:: go - - package main - - import ( - "github.com/ethereum/eth-go" - "github.com/ethereum/eth-go/ethutil" - ) - - func main() { - // Read config - ethutil.ReadConfig(".test", ethutil.LogStd, nil, "MyEthApp") - - // Create a new Ethereum node - ethereum, err := eth.New(eth.CapDefault, false) - if err != nil { - panic(fmt.Sprintf("Could not start node: %s\n", err)) - } - // Set the port (default 30303) - ethereum.Port = "10101" - // Once we reach max, bounce them off. - ethereum.MaxPeers = 10 - - keyRing := ethutil.GetKeyRing() - // Create a new key if non exist - if keyRing.Len() == 0 { - // Create a new keypair - keyPair, err := ethutil.GenerateNewKeyPair() - if err != nil { - panic(err) - } - - // Add the keypair to the key ring - keyRing.Add(keyPair) - } - - ethereum.Start(true) - ethereum.WaitForShutdown() - } - -``ethereum.Start()`` takes one argument, whether or not we want to -connect to one of the known seed nodes. If you want your own little -testnet-in-a-box you can disable it else set it to true. - -Your node should now be catching up with the blockchain. From here on -out you are on your own. You could create a reactor to listen to -specific events or just dive into the chain state directly. If you want -to look at some example code you can check `DNSEth -here. `__ - -Have fun! diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Cross-compiling-Ethereum.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Cross-compiling-Ethereum.rst deleted file mode 100644 index 03e4bb5..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Cross-compiling-Ethereum.rst +++ /dev/null @@ -1,195 +0,0 @@ -Developers usually have a preferred platform that they feel most -comfortable working in, with all the necessary tools, libraries and -environments set up for an optimal workflow. However, there's often need -to build for either a different CPU architecture, or an entirely -different operating system; but maintaining a development environment -for each and switching between the them quickly becomes unwieldy. - -Here we present a very simple way to cross compile Ethereum to various -operating systems and architectures using a minimal set of prerequisites -and a completely containerized approach, guaranteeing that your -development environment remains clean even after the complex -requirements and mechanisms of a cross compilation. - -The currently supported target platforms are: - -- ARMv7 Android and iOS -- 32 bit, 64 bit and ARMv5 Linux -- 32 bit and 64 bit Mac OSX -- 32 bit and 64 bit Windows - -Please note, that cross compilation does not replace a release build. -Although resulting binaries can usually run perfectly on the desired -platform, compiling on a native system with the specialized tools -provided by the official vendor can often result in more a finely -optimized code. - -Cross compilation environment ------------------------------ - -Although the ``go-ethereum`` project is written in Go, it does include a -bit of C code shared between all implementations to ensure that all -perform equally well, including a dependency to the GNU Multiple -Precision Arithmetic Library. Because of these, Go cannot by itself -compile to a different platform than the host. To overcome this -limitation, we will use ```xgo`` `__, a -Go cross compiler package based on Docker containers that has been -architected specifically to allow both embedded C snippets as well as -simpler external C dependencies during compilation. - -The ``xgo`` project has two simple dependencies: Docker (to ensure that -the build environment is completely contained) and Go. On most platforms -these should be available from the official package repositories. For -manually installing them, please consult their install guides at -`Docker `__ and -`Go `__ respectively. This guide assumes -that these two dependencies are met. - -To install and/or update xgo, simply type: - -:: - - $ go get -u github.com/karalabe/xgo - -You can test whether ``xgo`` is functioning correctly by requesting it -to cross compile itself and verifying that all cross compilations -succeeded or not. - -:: - - $ xgo github.com/karalabe/xgo - ... - - $ ls -al - -rwxr-xr-x 1 root root 2792436 Sep 14 16:45 xgo-android-21-arm - -rwxr-xr-x 1 root root 2353212 Sep 14 16:45 xgo-darwin-386 - -rwxr-xr-x 1 root root 2906128 Sep 14 16:45 xgo-darwin-amd64 - -rwxr-xr-x 1 root root 2388288 Sep 14 16:45 xgo-linux-386 - -rwxr-xr-x 1 root root 2960560 Sep 14 16:45 xgo-linux-amd64 - -rwxr-xr-x 1 root root 2437864 Sep 14 16:45 xgo-linux-arm - -rwxr-xr-x 1 root root 2551808 Sep 14 16:45 xgo-windows-386.exe - -rwxr-xr-x 1 root root 3130368 Sep 14 16:45 xgo-windows-amd64.exe - -Building Ethereum ------------------ - -Cross compiling Ethereum is analogous to the above example, but an -additional flags is required to satisfy the dependencies: - -- ``--deps`` is used to inject arbitrary C dependency packages and - pre-build them - -Injecting the GNU Arithmetic Library dependency and selecting ``geth`` -would be: - -:: - - $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \ - github.com/ethereum/go-ethereum/cmd/geth - ... - - $ ls -al - -rwxr-xr-x 1 root root 23213372 Sep 14 17:59 geth-android-21-arm - -rwxr-xr-x 1 root root 14373980 Sep 14 17:59 geth-darwin-386 - -rwxr-xr-x 1 root root 17373676 Sep 14 17:59 geth-darwin-amd64 - -rwxr-xr-x 1 root root 21098910 Sep 14 17:59 geth-linux-386 - -rwxr-xr-x 1 root root 25049693 Sep 14 17:59 geth-linux-amd64 - -rwxr-xr-x 1 root root 20578535 Sep 14 17:59 geth-linux-arm - -rwxr-xr-x 1 root root 16351260 Sep 14 17:59 geth-windows-386.exe - -rwxr-xr-x 1 root root 19418071 Sep 14 17:59 geth-windows-amd64.exe - -As the cross compiler needs to build all the dependencies as well as the -main project itself for each platform, it may take a while for the build -to complete (approximately 3-4 minutes on a Core i7 3770K machine). - -Fine tuning the build -~~~~~~~~~~~~~~~~~~~~~ - -By default Go, and inherently ``xgo``, checks out and tries to build the -master branch of a source repository. However, more often than not, -you'll probably want to build a different branch from possibly an -entirely different remote repository. These can be controlled via the -``--remote`` and ``--branch`` flags. - -To build the ``develop`` branch of the official ``go-ethereum`` -repository instead of the default ``master`` branch, you just need to -specify it as an additional command line flag (``--branch``): - -:: - - $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \ - --branch=develop \ - github.com/ethereum/go-ethereum/cmd/geth - -Additionally, during development you will most probably want to not only -build a custom branch, but also one originating from your own fork of -the repository instead of the upstream one. This can be done via the -``--remote`` flag: - -:: - - $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \ - --remote=https://github.com/karalabe/go-ethereum \ - --branch=rpi-staging \ - github.com/ethereum/go-ethereum/cmd/geth - -By default ``xgo`` builds binaries for all supported platforms and -architectures, with Android binaries defaulting to the highest released -Android NDK platform. To limit the build targets or compile to a -different Android platform, use the ``--targets`` CLI parameter. - -:: - - $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \ - --targets=android-16/arm,windows/* \ - github.com/ethereum/go-ethereum/cmd/geth - -Building locally -~~~~~~~~~~~~~~~~ - -If you would like to cross compile your local development version, -simply specify a local path (starting with ``.`` or ``/``), and ``xgo`` -will use all local code from ``GOPATH``, only downloading missing -dependencies. In such a case of course, the ``--branch``, ``--remote`` -and ``--pkg`` arguments are no-op: - -:: - - $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \ - ./cmd/geth - -Using the Makefile ------------------- - -Having understood the gist of ``xgo`` based cross compilation, you do -not need to actually memorize and maintain these commands, as they have -been incorporated into the official -`Makefile `__ -and can be invoked with a trivial ``make`` request: - -- ``make geth-cross``: Cross compiles to every supported OS and - architecture -- ``make geth-``: Cross compiles supported architectures of a - particular OS (e.g. ``linux``) -- ``make geth--``: Cross compiles to a specific - OS/architecture (e.g. ``linux``, ``arm``) - -We advise using the ``make`` based commands opposed to manually invoking -``xgo`` as we do maintain the Makefile actively whereas we cannot -guarantee that this document will be always readily updated to latest -advancements. - -Tuning the cross builds -~~~~~~~~~~~~~~~~~~~~~~~ - -A few of the ``xgo`` build options have also been surfaced directly into -the Makefile to allow fine tuning builds to work around either upstream -Go issues, or to enable some fancier mechanics. - -- ``make ... GO=``: Use a specific Go runtime (e.g. ``1.5.1``, - ``1.5-develop``, ``develop``) -- ``make ... MODE=``: Build a specific target type (e.g. ``exe``, - ``c-archive``). - -Please note that these are not yet fully finalized, so they may or may -not change in the future as our code and the Go runtime features change. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Database.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Database.rst deleted file mode 100644 index b01ce97..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Database.rst +++ /dev/null @@ -1,8 +0,0 @@ -Go Ethereum database - -:: - - "PV" : Number // The protocol version this database is compatible with. - "LTD" : Number // The highest known total difficulty - -**Please note, all entries are arbitrary length byte arrays.** diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Developers'-Guide.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Developers'-Guide.rst deleted file mode 100644 index 641d06a..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Developers'-Guide.rst +++ /dev/null @@ -1,234 +0,0 @@ -**NOTE: These instructions are for people who want to contribute Go -source code changes. If you just want to run ethereum, use the normal -`Installation -Instructions `__** - -Developers' guide -================= - -This document is the entry point for developers of the etherum go -implementation. Developers here refer to the hands-on: who are -interested in build, develop, debug, submit a bug report or pull request -or contribute to ``go-ethereum`` with code. - -Build and Test --------------- - -Go environment -~~~~~~~~~~~~~~ - -We assume that you have ```go`` v1.4 -installed `__, -and ``GOPATH`` is set. - -**Note**:You must have your working copy under -``$GOPATH/src/github.com/ethereum/go-ethereum``. You also usually want -to checkout the ``develop`` branch (instead of master). - -Since ``go`` does not use relative path for import, working in any other -directory will have no effect, since the import paths will be appended -to ``$GOPATH/src``, and if the lib does not exist, the version at master -HEAD will be downloaded. - -Most likely you will be working from your fork of ``go-ethereum``, let's -say from ``github.com/nirname/go-ethereum``. Clone or move your fork -into the right place: - -:: - - git clone git@github.com:nirname/go-ethereum.git $GOPATH/src/github.com/ethereum/go-ethereum - -Godep for dependency management -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -go-ethereum uses `Godep `__ to manage -dependencies. - -Install godep: - -:: - - go get github.com/tools/godep - -Make sure that go binaries are on your executable path: - -:: - - PATH=$GOPATH/bin:$PATH - -``godep`` should be prepended to all go calls ``build``, ``install`` and -``test``. - -Alternatively, you can prepend the go-ethereum Godeps directory to your -current ``GOPATH``: - -:: - - GOPATH=`godep path`:$GOPATH - -Building executables -~~~~~~~~~~~~~~~~~~~~ - -Switch to the go-ethereum repository root directory (Godep expects a -local `Godeps -folder `__ -). - -Each wrapper/executable found in `the ``cmd`` -directory `__ -can be built individually. - -Building Geth (CLI) -~~~~~~~~~~~~~~~~~~~ - -**Note**: Geth (the ethereum command line client) is the focus of the -`Frontier -release `__. - -To build the CLI: - -:: - - godep go install -v ./cmd/geth - -See the `documentation on how to use -Geth `__ - -Read about cross compilation of go-ethereum -`here `__. - -Git flow -~~~~~~~~ - -To make life easier try `git -flow `__ it -sets this all up and streamlines your work flow. - -Testing -~~~~~~~ - -Testing one library: - -:: - - godep go test -v -cpu 4 ./eth - -Using options ``-cpu`` (number of cores allowed) and ``-v`` (logging -even if no error) is recommended. - -Testing only some methods: - -:: - - godep go test -v -cpu 4 ./eth -run TestMethod - -**Note**: here all tests with prefix *TestMethod* will be run, so if you -got TestMethod, TestMethod1, then both! - -Running benchmarks, eg.: - -:: - - cd bzz - godep go test -v -cpu 4 -bench . -run BenchmarkJoin - -for more see `go test -flags `__ - -See integration testing information on the `Testing wiki -page `__ - -Metrics and monitoring -~~~~~~~~~~~~~~~~~~~~~~ - -``geth`` can do node behaviour monitoring, aggregation and show -performance metric charts. Read about `metrics and -monitoring `__ - -Add and update dependencies -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To update a dependency version (for example, to include a new upstream -fix), run - -:: - - go get -u - godep update - -To track a new dependency, add it to the project as normal than run - -:: - - godep save ./... - -Changes to the `Godeps -folder `__ -should be manually verified then committed. - -To make life easier try `git -flow `__ it -sets this all up and streamlines your work flow. - -Contributing ------------- - -Only github is used to track issues. (Please include the commit and -branch when reporting an issue.) - -Pull requests should by default commit on the ``develop`` branch. The -``master`` branch is only used for finished stable major releases. - -Stacktrace ----------- - -The code uses ``pprof`` on localhost port 6060 by default if ``geth`` is -started with the ``--pprof`` option. So bring up -http://localhost:6060/debug/pprof to see the heap, running routines etc. -By clicking full goroutine stack dump (clicking -http://localhost:6060/debug/pprof/goroutine?debug=2) you can generate -trace that is useful for debugging. - -Note that if you run multiple instances of ``geth``, this port will only -work for the first instance that was launched. If you want to generate -stacktraces for these other instances, you need to start them up -choosing an alternative pprof port. Make sure you are redirecting stderr -to a logfile. - -:: - - geth -port=30300 -loglevel 5 --pprof --pprofport 6060 2>> /tmp/00.glog - geth -port=30301 -loglevel 5 --pprof --pprofport 6061 2>> /tmp/01.glog - geth -port=30302 -loglevel 5 --pprof --pprofport 6062 2>> /tmp/02.glog - -Alternatively if you want to kill the clients (in case they hang or -stalled synching, etc) but have the stacktrace too, you can use the -``-QUIT`` signal with ``kill``: - -:: - - killall -QUIT geth - -This will dump stracktraces for each instance to their respective log -file. - -Code formatting ---------------- - -Sources are formatted according to the `Go Formatting -Style `__. - -Dev Tutorials -------------- - -- `Private networks, local clusters and - monitoring `__ - -- `P2P - 101 `__: a - tutorial about setting up and creating a p2p server and p2p sub - protocol. - -- `How to - Whisper `__: - an introduction to whisper. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Disclaimer.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Disclaimer.rst deleted file mode 100644 index 5d24143..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Disclaimer.rst +++ /dev/null @@ -1,248 +0,0 @@ -Disclaimer -========== - -Safety caveats - -Security warnings ------------------ - -- **You are responsible for your own computer security.** If your - machine is compromised you **will** lose your ether, access to any - contracts and maybe more. - -- **You are responsible for your own actions.** If you mess something - up or break any laws while using this software, it's your fault, and - your fault only. - -- **You are responsible for your own karma.** Don't be a jerk and - respect others. - -- This software is open source under a `GNU Lesser General Public - License `__ license. - -Legal warning: Disclaimer of Liabilites and Warranties ------------------------------------------------------- - -Short version -~~~~~~~~~~~~~ - -- **The user expressly knows and agrees that the user is using the - Ethereum platform at the user’s sole risk.** -- **The user represents that the user has an adequate understanding of - the risks, usage and intricacies of cryptographic tokens and - blockchain-based open source software, eth platform and eth.** -- **The user acknowledges and agrees that, to the fullest extent - permitted by any applicable law, the disclaimers of liability - contained herein apply to any and all damages or injury whatsoever - caused by or related to risks of, use of, or inability to use, eth or - the Ethereum platform under any cause or action whatsoever of any - kind in any jurisdiction, including, without limitation, actions for - breach of warranty, breach of contract or tort (including negligence) - and that neither stiftung Ethereum nor the Ethereum team shall be - liable for any indirect, incidental, special, exemplary or - consequential damages, including for loss of profits, goodwill or - data.** -- **Some jurisdictions do not allow the exclusion of certain warranties - or the limitation or exclusion of liability for certain types of - damages. therefore, some of the above limitations in this section may - not apply to a user. In particular, nothing in these terms shall - affect the statutory rights of any user or exclude injury arising - from any willful misconduct or fraud of stiftung Ethereum.** - -Long Version: Terms and Conditions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The following Terms and Conditions (“Terms”) govern the use of the -Ethereum open source software platform (“Ethereum Platform”). Prior to -any use of the Ethereum Platform, the User confirms to understand and -expressly agrees to all of the Terms. All capitalized terms in this -agreement will be given the same effect and meaning as in the Terms. The -group of developers and other personnel that is now, or will be, -employed by, or contracted with, Stiftung Ethereum (“Stiftung Ethereum”) -is termed the “Ethereum Team.” The Platform will be developed by persons -and entities who support Ethereum, including both volunteers and -developers who are paid by nonprofit entities interested in supporting -the Ethereum Platform. - -The user acknowledges the following serious risks to any use the -Ethereum Platform and ETH and expressly agrees not to hold liable -Ethereum Stiftung or Ethereum Team should any of these risks occur: - -Risk of Regulatory Actions in One or More Jurisdictions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The Ethereum Platform and ETH could be impacted by one or more -regulatory inquiries or regulatory action, which could impede or limit -the ability of Stiftung Ethereum to continue to develop the Ethereum -Platform, or which could impeded or limit the ability of User to use -Ethereum Platform or ETH. - -Risk of Alternative, Unofficial Ethereum Networks -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -It is possible that alternative Ethereum-based networks could be -established, which utilize the same open source source code and open -source protocol underlying the Ethereum Platform. The Ethereum network -may compete with these alternative Ethereum-based networks, which could -potentially negatively impact the Ethereum Platform and ETH. - -Risk of Insufficient Interest in the Ethereum Platform or Distributed Applications -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -It is possible that the Ethereum Platform will not be used by a large -number of external businesses, individuals, and other organizations and -that there will be limited public interest in the creation and -development of distributed applications. Such a lack of interest could -impact the development of the Ethereum Platform and potential uses of -ETH. It cannot predict the success of its own development efforts or the -efforts of other third parties. - -Risk that the Ethereum Platform, As Developed, Will Not Meet the Expectations of User -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The User recognizes that the Ethereum Platform is under development and -may undergo significant changes before release. User acknowledges that -any expectations regarding the form and functionality of the Ethereum -Platform held by the User may not be met upon release of the Ethereum -Platform, for any number of reasons including a change in the design and -implementation plans and execution of the implementation of the Ethereum -Platform. - -Risk of Security Weaknesses in the Ethereum Platform Core Infrastructure Software -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The Ethereum Platform rests on open-source software, and there is a risk -that the Ethereum Stiftung or the Ethereum Team, or other third parties -not directly affiliated with the Stiftung Ethereum, may introduce -weaknesses or bugs into the core infrastructural elements of the -Ethereum Platform causing the system to lose ETH stored in one or more -User accounts or other accounts or lose sums of other valued tokens -issued on the Ethereum Platform. - -Risk of Weaknesses or Exploitable Breakthroughs in the Field of Cryptography -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Cryptography is an art, not a science. And the state of the art can -advance over time Advances in code cracking, or technical advances such -as the development of quantum computers, could present risks to -cryptocurrencies and the Ethereum Platform, which could result in the -theft or loss of ETH. To the extent possible, Stiftung Ethereum intends -to update the protocol underlying the Ethereum Platform to account for -any advances in cryptography and to incorporate additional security -measures, but cannot it cannot predict the future of cryptography or the -success of any future security updates. - -Risk of Ether Mining Attacks -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -As with other cryptocurrencies, the blockchain used for the Ethereum -Platform is susceptible to mining attacks, including but not limited to -double-spend attacks, majority mining power attacks, “selfish-mining” -attacks, and race condition attacks. Any successful attacks present a -risk to the Ethereum Platform, expected proper execution and sequencing -of ETH transactions, and expected proper execution and sequencing of -contract computations. Despite the efforts of the Ethereum Stiftung and -Team, known or novel mining attacks may be successful. - -Risk of Rapid Adoption and Increased Demand -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If the Ethereum Platform is rapidly adopted, the demand for ETH could -rise dramatically and at a pace that exceeds the rate with which ETH -miners can create new ETH tokens. Under such a scenario, the entire -Ethereum Platform could become destabilized, due to the increased cost -of running distributed applications. In turn, this could dampen interest -in the Ethereum Platform and ETH. Instability in the demand of for ETH -may lead to a negative change of the economical parameters of an -Ethereum based business which could result in the business being unable -to continue to operate economically or to cease operation. - -Risk of Rapid Adoption and Insufficiency of Computational Application Processing Power on the Ethereum Platform -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If the Ethereum Platform is rapidly adopted, the demand for transaction -processing and distributed application computations could rise -dramatically and at a pace that exceeds the rate with which ETH miners -can bring online additional mining power. Under such a scenario, the -entire Ethereum Platform could become destabilized, due to the increased -cost of running distributed applications. In turn, this could dampen -interest in the Ethereum Platform and ETH. Insufficiency of -computational resources and an associated rise in the price of ETH could -result in businesses being unable to acquire scarce computational -resources to run their distributed applications. This would represent -revenue losses to businesses or worst case, cause businesses to cease -operations because such operations have become uneconomical due to -distortions in the crypto-economy. - -Acknowledgment, Acceptance of all Risks and Disclaimer of Warranties and -Liabilities **THE USER EXPRESSLY KNOWS AND AGREES THAT THE USER IS USING -THE ETHEREUM PLATFORM AT THE USER’S SOLE RISK. THE USER REPRESENTS THAT -THE USER HAS AN ADEQUATE UNDERSTANDING OF THE RISKS, USAGE AND -INTRICACIES OF CRYPTOGRAPHIC TOKENS AND BLOCKCHAIN-BASED OPEN SOURCE -SOFTWARE, ETH PLATFORM AND ETH. THE USER ACKNOWLEDGES AND AGREES THAT, -TO THE FULLEST EXTENT PERMITTED BY ANY APPLICABLE LAW, THE DISCLAIMERS -OF LIABILITY CONTAINED HEREIN APPLY TO ANY AND ALL DAMAGES OR INJURY -WHATSOEVER CAUSED BY OR RELATED TO RISKS OF, USE OF, OR INABILITY TO -USE, ETH OR THE ETHEREUM PLATFORM UNDER ANY CAUSE OR ACTION WHATSOEVER -OF ANY KIND IN ANY JURISDICTION, INCLUDING, WITHOUT LIMITATION, ACTIONS -FOR BREACH OF WARRANTY, BREACH OF CONTRACT OR TORT (INCLUDING -NEGLIGENCE) AND THAT NEITHER STIFTUNG ETHEREUM NOR ETHERUM TEAM SHALL BE -LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL -DAMAGES, INCLUDING FOR LOSS OF PROFITS, GOODWILL OR DATA. SOME -JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF CERTAIN WARRANTIES OR THE -LIMITATION OR EXCLUSION OF LIABILITY FOR CERTAIN TYPES OF DAMAGES. -THEREFORE, SOME OF THE ABOVE LIMITATIONS IN THIS SECTION MAY NOT APPLY -TO A USER. IN PARTICULAR, NOTHING IN THESE TERMS SHALL AFFECT THE -STATUTORY RIGHTS OF ANY USER OR EXCLUDE INJURY ARISING FROM ANY WILLFUL -MISCONDUCT OR FRAUD OF STIFTUNG ETHEREUM**. - -Dispute Resolution -^^^^^^^^^^^^^^^^^^ - -All disputes or claims arising out of, relating to, or in connection -with the Terms, the breach thereof, or use of the Ethereum Platform -shall be finally settled under the Rules of Arbitration of the -International Chamber of Commerce by one or more arbitrators appointed -in accordance with said Rules. All claims between the parties relating -to these Terms that are capable of being resolved by arbitration, -whether sounding in contract, tort, or otherwise, shall be submitted to -ICC arbitration. Prior to commencing arbitration, the parties have a -duty to negotiate in good faith and attempt to resolve their dispute in -a manner other than by submission to ICC arbitration. The arbitration -panel shall consist of one arbitrator only, unless the ICC Court of -Arbitration determines that the dispute is such as to warrant three -arbitrators. If the Court determines that one arbitrator is sufficient, -then such arbitrator shall be Swiss resident. If the Court determines -that three arbitrators are necessary, then each party shall have 30 days -to nominate an arbitrator of its choice -- in the case of the Claimant, -measured from receipt of notification of the ICC Court’s decision to -have three arbitrators; in the case of Respondent, measured from receipt -of notification of Claimant’s nomination. All nominations must be Swiss -resident. If a party fails to nominate an arbitrator, the Court will do -so. The Court shall also appoint the chairman. All arbitrators shall be -and remain “independent” of the parties involved in the arbitration. The -place of arbitration shall be Zug, Switzerland. The language of the -arbitration shall be English. In deciding the merits of the dispute, the -tribunal shall apply the laws of Switzerland and any discovery shall be -limited and shall not involve any depositions or any other examinations -outside of a formal hearing. The tribunal shall not assume the powers of -amiable compositeur or decide the case ex aequo et bono. In the final -award, the tribunal shall fix the costs of the arbitration and decide -which of the parties shall bear such costs in what proportion. Every -award shall be binding on the parties. The parties undertake to carry -out the award without delay and waive their right to any form of -recourse against the award in so far as such waiver can validly be made. - -Force Majeure -^^^^^^^^^^^^^ - -**STIFTUNG ETHEREUM** is finally not liable for: - -- unavoidable casualty, -- delays in delivery of materials, -- embargoes, -- government orders, -- acts of civil or military authorities, -- lack of energy, or -- any similar unforeseen event that renders performance commercially - implausible. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Ethereum-Specification.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Ethereum-Specification.rst deleted file mode 100644 index f690f5c..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Ethereum-Specification.rst +++ /dev/null @@ -1,44 +0,0 @@ -Specifications of all Ethereum technologies, languages, protocols, etc. - -Whitepapers and design rationale -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- `Ethereum - Whitepaper `__ -- `Design - Rationale `__ -- `Ethereum Yellow Paper `__ -- `ÐΞVp2p - Whitepaper `__ - (WiP) -- `Ethash `__ - -Specs -~~~~~ - -- `JavaScript - API `__ -- `Generic JSON RPC `__ -- [JSRE admin - API](https://github.com/ethereum/go-ethereum/wiki/JavaScript-Console#console-api -- `RLP `__ -- `ÐΞVp2p Wire - Protocol `__ -- `Web3 Secret - Storage `__ -- `Patricia - Tree `__ -- `Wire - protocol `__ -- `Light client - protocol `__ -- `Solidity, Docs & - ABI `__ -- `NatSpec `__ -- `Contract - ABI `__ -- `Ethash `__ -- `Ethash C API `__ -- `Ethash DAG `__ -- `ICAP: Inter-exchange Client Address - Protocol `__ diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Ethereum-on-Android.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Ethereum-on-Android.rst deleted file mode 100644 index bd80aff..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Ethereum-on-Android.rst +++ /dev/null @@ -1,107 +0,0 @@ -Building Geth for Android is a non trivial task, as it requires cross -compiling external C dependencies (`GNU Arithmetic -Library `__); internal C dependencies -(`ethash `__); as well as the entire -CGO enabled Go code-base to Android. This is further complicated by the -Position Independent Executables (PIE) security feature introduced since -Android 4.1 Jelly Bean, requiring different compiler and linker options -based on the target Android platform version. - -To cope with all the build issues, the -```xgo`` `__ CGO enabled Go cross -compiler is used, which assembles an entire multi-platform cross -compiler suite into a single mega docker container. Details about using -``xgo`` can be found in the project's -`README `__, with -Ethereum specifics on the go-ethereum cross compilation `wiki -page `__. - -TL;DR - -:: - - $ go get -u github.com/karalabe/xgo - $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \ - --branch=develop \ - --targets=android-16/arm \ - github.com/ethereum/go-ethereum/cmd/geth - - $ ls -al - -rwxr-xr-x 1 root root 23213348 Sep 14 19:35 geth-android-16-arm - -Deploying a binary ------------------- - -Currently ``xgo`` will compile a native Android binary that can be -copied onto a device and executed from a terminal emulator. As Ethereum -Android support at the moment is mostly a developer feature, there have -been no attempts at making it even remotely user friendly (installers, -APKs, etc). - -To push a native binary onto an Android device, you'll need an Android -SDK installed. The most lightweight solution is the standalone `SDK -Tools Only `__ -package. Download and extract for your local machine's platform. Since -building the binary is already done, we only need the `Android Debug -Bridge `__ to push it -to our device, which can be installed using the SDK's ``android`` tool -``$YOUR_SDK_PATH/tools/android`` -> ``Android SDK Platform Tools`` -(deselect everything else). We'll assume -``$YOUR_SDK_PATH/platform-tools/adb`` is in the PATH environmental -variable from now on. - -You can list the available devices via: - -:: - - $ adb devices - List of devices attached - 0149CBF30201400E device - -Deploying the binary to an Android device can be done in two steps. -First copy the binary into the non-executable ``sdcard`` filesystem on -the device. You may be asked the first time by the device to grant -developer permission (also developer mode should be enabled on the -devices prior). - -:: - - $ adb push $PATH_TO_BINARY/geth-android-16-arm /sdcard/ - 1984 KB/s (23213348 bytes in 11.421s) - -Then the binary needs to be moved to a file system with executable -permissions, and said permissions need to be granted. On an unrooted -phone the following path should be accessible with USB developer -options. - -:: - - $ adb shell - $ cp /sdcard/geth-android-16-arm /data/local/tmp/geth - $ cd /data/local/tmp - $ chmod 751 geth - -Running the deployed binary ---------------------------- - -After pushing the binary to the device and setting the appropriate -permissions, you may execute Geth straight from the Android Debug Bridge -shell: - -:: - - $ ./geth - I0911 11:09:05.329120 1427 cmd.go:125] Starting Geth/v1.1.0/android/go1.5.1 - I0911 11:09:05.466782 1427 server.go:311] Starting Server - I0911 11:09:05.823965 1427 udp.go:207] Listening, enode://824e1a16bd6cb9931bec1ab6268cd76571936d5674505d53c7409b2b860cd9e396a66c7fe4c3ad4e60c43fe42408920e33aaf3e7bbdb6123f8094dbc423c2bb1@[::]:30303 - I0911 11:09:05.832037 1427 backend.go:560] Server started - I0911 11:09:05.848936 1427 server.go:552] Listening on [::]:30303 - -A fancier way would be to start a terminal emulator on the Android -device itself and run the binary expressly from it (remember, deployed -at ``/data/local/tmp/geth``): - -.. figure:: http://i.imgur.com/wylOsBL.jpg - :alt: Geth on Android - - Geth on Android diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/FAQ.rst b/old-docs-for-reference/go-ethereum-wiki.rst/FAQ.rst deleted file mode 100644 index 6a78704..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/FAQ.rst +++ /dev/null @@ -1,19 +0,0 @@ --------------- - -**Q.** I noticed my peercount slowly decrease, and now it is at 0. -Restarting doesn't get any peers. - -**A.** Check and sync your clock with ntp. -`Example `__ -``sudo ntpdate -s time.nist.gov`` - --------------- - -**Q.** I would like to run multiple geth instances but got the error -"Fatal: blockchain db err: resource temporarily unavailable". - -**A.** Geth uses a datadir to store the blockchain, accounts and some -additional information. This directory cannot be shared between running -instances. If you would like to run multiple instances follow -`these `__ -instructions. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Frontier.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Frontier.rst deleted file mode 100644 index b8b1c4b..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Frontier.rst +++ /dev/null @@ -1,211 +0,0 @@ -**FRONTIER IS COMING** - -- `Frontier launch final - steps `__ -- `Etherchain API `__ look out for - block #1028201 -- `Olympic network stats `__ - -Ethereum Frontier Release -========================= - -Introduction ------------- - -Frontier is the first in a series of releases that punctuate the roadmap -for the development of Ethereum. Frontier will be followed by -‘Homestead’, ‘Metropolis’ and ‘Serenity’ throughout the coming year, -each adding new features and improving the user friendliness and -security of the platform. - -Ethereum is special and different from other software projects in that -its release also involves launching a live network. After a year and a -half of development the Proof of Concept series completed 9 cycles. The -10th iteration resulted in the Olympic testnet, which gradually led to -the Release Candidate client for Frontier. - -The Ethereum network goes live when the clients consent on the **genesis -block** and start mining transactions on it. The genesis block will -reference an initial system state where all the accounts set up by the -presale exist with the correct amount of pre-issued ether allocated. -Initially, the network will be in a "thawing" state allowing only blocks -to be mined, but not transactions to be processed. This allows for users -to have a break-in period to connect to the network while also building -up its security. - -In conjunction with the Frontier launch several exchanges will likely -start enabling trade of Ether, which will provide necessary liquidity to -the marketplace, allowing users and miners to transfer their holdings to -other users requiring more or less Ether. As opposed to an earlier -strategy, there is no plan to remove any contracts from the blockchain -or otherwise alter the network to carry balances over to Homestead. In -other words, the state in Homestead will be a direct and unmodified -continuation of the state in Frontier. - -Mining reward is the full amount of 5 ether per block (as opposed to our -earlier proposal of a reduced amount). Mining rewards are discussed in -detail -`here `__ - -Safety warnings ---------------- - -- **You are responsible for your own computer security.** If your - machine is compromised you **will** lose your ether, access to any - contracts and maybe more. -- **You are responsible for your own actions.** If you mess something - up or break any laws while using this software, it's your fault, and - your fault only. -- **You are responsible for your own karma.** Don't be a jerk and - respect others. - -**WARNING:** Before you interact with the Ethereum Frontier network, -make sure you read the documentation and understand the caveats and -risks. Please read the `legal -disclaimer `__ - -Components released -------------------- - -The focus of Frontier is the Go implementation of an Ethereum full node, -with a command line interface codenamed "Geth". - -By `installing and running -``geth`` `__, you can -take part in the Ethereum live network, mine ether on the blockchain, -transfer funds between addresses, create contracts and send -transactions. - -**WARNING**: before you use ``geth`` or interact with the Ethereum -Frontier live network, make sure you read the documentation and fully -understand the `caveats and -risks `__. - -Apart from ``geth``, the Go CLI, the Frontier release contains the -following components: - -- ``web3.js`` library implementing the `JavaScript - API `__ for - dapps to conveniently interact with an Ethereum node -- ``solc`` a standalone solidity compiler. You only need this if you - want to use your dapp or `console to compile solidity - code `__. -- ``ethminer`` a standalone miner for openCL `GPU - mining `__ -- ``netstat`` a `network monitoring - GUI `__ allows - you to add your node to the http://stats.ethdev.com page - -The actual launch process -------------------------- - -Ethereum is not something that’s centrally ‘launched’, but instead -emerges from consensus. Users will have to voluntarily download and run -a specific version of the software, then manually generate and load the -Genesis block to join the official project’s network. - -Once Frontier has been installed on their machines, users will need to -generate the Genesis block themselves, then load it into their Frontier -clients. A script and instructions on how to do this will be provided as -part of the new Ethereum website, as well as our various wikis. - -We’re often asked how existing users will switch from the test network -to the live network: it will be done through a switch at the Geth -console (--networkId). By default the new build will aim to connect to -the live network, to switch back to the test network you’ll simply -indicate a network id of ‘0’. - -Bugs, Issues and Complications ------------------------------- - -The work on the Frontier software is far from over. Expect weekly -updates which will give you access to better, more stable clients. Many -of the planned Frontier gotchas (which included a chain reset at -Homestead, limiting mining rewards to 10%, and centralized -checkpointing) were deemed unnecessary. However, there are still big -differences between Frontier and Homestead. In Frontier, we’re going to -have issues, we’re going to have updates, and there will be bugs – users -are taking their chances when using the software. There will be big -(BIG) warning messages before developers are able to even install it. In -Frontier, documentation is limited, and the tools provided require -advanced technical skills. - -The Canary Contracts --------------------- - -The Canary contracts are simple switches holding a value equal to 0 or -1. Each contract is controlled by a different member of the Eth/Dev team -and will be updated to ‘1’ if the internal Frontier Disaster Recovery -Team flags up a consensus issue, such as a fork. - -Within each Frontier client, a check is made after each block against 4 -contracts. If two out of four of these contracts have a value switched -from 0 to 1, mining stops and a message urging the user to update their -client is displayed. This is to prevent “fire and forget” miners from -preventing a chain upgrade. - -This process is centralized and will only run for the duration of -Frontier. It helps preventing the risk of a prolonged period (24h+) of -outage. - -Stats, Status and Badblock websites ------------------------------------ - -You probably are already familiar with our network stats monitor, -https://stats.ethdev.com/. It gives a quick overview of the health of -the network, block resolution time and Gas statistics. Remember that -participation in the stats page is voluntary, and nodes have to add -themselves before they appear on the panel. See details on `network -monitoring `__ - -In addition to the stats page, we will have a status page at -https://status.ethereum.org/ (no link as the site is not live yet) which -will gives a concise overview of any issue that might be affecting -Frontier. Use it as your first port of call if you think something might -not be right. - -Finally, if any of the clients receive an invalid block, they will -refuse to process it send it to the bad block website (AKA ‘Sentinel’). -This could mean a bug, or something more serious, such as a fork. Either -way, this process will alert our developers to potential issues on the -network. The website itself is public and available at -https://badblocks.ethdev.com (currently operating on the testnet). - -A Clean Testnet ---------------- - -During the last couple of months, the Ethereum test network was pushed -to its limits in order to test scalability and block propagation times. -As part of this test we encouraged users to spam the network with -transactions, contract creation code and call to contracts, at times -reaching over 25 transactions per second. This has led the test network -chain to grow to a rather unwieldy size, making it difficult for new -users to catch up. For this reason, and shortly after the Frontier -release, there will be a new test network following the same rules as -Frontier. - -Olympic rewards distribution ----------------------------- - -During the Olympic phase there were a number of rewards for various -achievements including mining prowess. These rewards will not be part of -the Frontier Genesis block, but instead will be handed out by a -Foundation bot during the weeks following the release. - -Resources: - `Frontier launch final -steps `__ - `Frontier -is -coming `__ -blogpost by Stephan Tual announcing the launch. - `The frontier -website `__ - `Original announcement of -the release -scheme `__ -by Vinay Gupta - `Follow-up -blogpost `__ -- `Least Authority audit -blogpost `__ -with links to the audit report, - `Deja Vu audit -blogpost `__ -- `Olympic. Frontier -prerelease `__, -Vitalik's blogpost detailing olympic rewards. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Gas-Price-Oracle.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Gas-Price-Oracle.rst deleted file mode 100644 index 8eaf6a9..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Gas-Price-Oracle.rst +++ /dev/null @@ -1,46 +0,0 @@ -The gas price oracle is a helper function of the Geth client that tries -to find an appropriate default gas price when sending transactions. It -can be parametrized with the following command line options: - -- gpomin: lower limit of suggested gas price. This should be set at - least as high as the "gasprice" setting usually used by miners so - that your transactions will not be rejected automatically because of - a too low price. - -- gpomax: higher limit of suggested gas price. During load peaks when - there is a competition between transactions to get into the blocks, - the price needs to be limited, otherwise the oracle would eventually - try to overbid everyone else at any price. - -- gpofull: a block is considered "full" when a certain percentage of - the block gas limit (specified in percents) is used up by - transactions. If a block is not "full", that means that a transaction - could have been accepted even with a minimal price offered. - -- gpobasedown: an exponential ratio (specified in 1/1000ths) by which - the base price decreases when the lowest acceptable price of the last - block is below the last base price. - -- gpobaseup: an exponential ratio (specified in 1/1000ths) by which the - base price increases when the lowest acceptable price of the last - block is over the last base price. - -- gpobasecf: a correction factor (specified in percents) of the base - price. The suggested price is the corrected base price, limited by - gpomin and gpomax. - -The lowest acceptable price is defined as a price that could have been -enough to insert a transaction into a certain block. Although this value -varies slightly with the gas used by the particular transaction, it is -aproximated as follows: if the block is full, it is the lowest -transaction gas price found in that block. If the block is not full, it -equals to gpomin. - -The base price is a moving value that is adjusted from block to block, -up if if was lower than the lowest acceptable price, down otherwise. -Note that there is a slight amount of randomness added to the correction -factors so that your client will not behave absolutely predictable on -the market. - -If you want to specify a constant for the default gas price and not use -the oracle, set both gpomin and gpomax to the same value. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Geth.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Geth.rst deleted file mode 100644 index 1e7751f..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Geth.rst +++ /dev/null @@ -1,164 +0,0 @@ -Geth -==== - -``geth`` is the the command line interface for running a full Ethereum -node implemented in Go. It is the main deliverable of the `Frontier -Release `__ - -Capabilities ------------- - -By installing and running ``geth``, you can take part in the Ethereum -frontier live network and \* mine real ether \* transfer funds between -addresses \* create contracts and send transactions \* explore block -history \* and much much more - -Install -------- - -Supported Platforms are Linux, Mac Os and Windows. - -We support two types of installation: binary or scripted install for -users. See `Install -instructions `__ -for binary and scripted installs. - -Developers and community enthusiast are advised to read the `Developers' -Guide `__, -which contains detailed instructions for manual build from source (on -any platform) as well as detailed tips on testing, monitoring, -contributing, debugging and submitting pull requests on github. - -Interfaces ----------- - -- Javascript Console: ``geth`` can be launched with an interactive - console, that provides a javascript runtime environment exposing a - javascript API to interact with your node. `Javascript Console - API `__ - includes the ``web3`` javascript Ðapp API as well as an additional - admin API. -- JSON-RPC server: ``geth`` can be launched with a json-rpc server that - exposes the `JSON-RPC - API `__ -- `Command line - options `__ - documents command line parameters as well as subcommands. - -Basic Use Case Documentation ----------------------------- - -- `Managing - accounts `__ -- `Mining `__ -- `Contracts and - Transactions `__ - -**Note** buying and selling ether through exchanges is not discussed -here. - -License -------- - -The Ethereum Core Protocol licensed under the `GNU Lesser General Public -License `__. All frontend client -software (under -`cmd `__) is -licensed under the `GNU General Public -License `__. - -Troubleshooting ---------------- - -If something went wrong first read our -`Troubleshooting `__ -checklist as well as the -`FAQ `__. -If you still didn't find your answer please open an issue on GitHub or -contact our help desk on helpdesk@ethereum.org. - -Reporting ---------- - -Security issues are best sent to security@ethereum.org or shared in PM -with devs on one of the channels (see Community and Suppport). - -Non-sensitive bug reports are welcome on github. Please always state the -version (on master) or commit of your build (if on develop), give as -much detail as possible about the situation and the anomaly that -occurred. Provide logs or stacktrace if you can. - -Contributors ------------- - -Ethereum is joint work of ETHDEV and the community. - -Name or blame = list of contributors: \* -`go-ethereum `__ -\* -`cpp-ethereum `__ -\* `web3.js `__ -\* `ethash `__ -\* -`netstats `__, -`netintelligence-api `__ - -Community and support ---------------------- - -Ethereum on social media -~~~~~~~~~~~~~~~~~~~~~~~~ - -- Main site: https://www.ethereum.org -- ETHDEV: https://ethdev.com -- Forum: https://forum.ethereum.org -- Github: https://github.com/ethereum -- Blog: https://blog.ethereum.org -- Wiki: http://wiki.ethereum.org -- Twitter: http://twitter.com/ethereumproject -- Reddit: http://reddit.com/r/ethereum -- Meetups: http://ethereum.meetup.com -- Facebook: https://www.facebook.com/ethereumproject -- Youtube: http://www.youtube.com/ethereumproject -- Google+: http://google.com/+EthereumOrgOfficial - -IRC -~~~ - -IRC Freenode channels: \* ``#ethereum``: for general discussion \* -``#ethereum-dev``: for development specific questions and discussions \* -``##ethereum``: for offtopic and banter \* ``#ethereumjs``: for -questions related to web3.js and node-ethereum \* ``#ethereum-markets``: -Trading \* ``#ethereum-mining`` Mining \* ``#dappdevs``: Dapp developers -channel \* ``#ethdev``: buildserver etc - -`IRC Logs by ZeroGox `__ - -Gitter -~~~~~~ - -- `go-ethereum Gitter `__ -- `cpp-ethereum Gitter `__ -- `web3.js Gitter `__ -- `Ethereum documentation project - Gitter `__ - -Forum -~~~~~ - -- `Forum `__ - -The ZeroGox Bot -~~~~~~~~~~~~~~~ - -`ZeroGox Bot `__ - -Dapp developers' mailing list -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -https://dapplist.net/ - -Helpdesk -~~~~~~~~ - -On gitter, irc, skype or mail to helpdesk@ethereum.org diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Getting-Geth.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Getting-Geth.rst deleted file mode 100644 index 5425bca..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Getting-Geth.rst +++ /dev/null @@ -1,62 +0,0 @@ -Getting Geth -============ - -The Frontier tool is called Geth (the old english third person singular -conjugation of "to go". Quite appropriate given geth is written in -`Go `__. Geth is a multipurpose command line tool -that runs a full Ethereum node implemented in Go. It offers three -interfaces: the `command line subcommands and -options <./Command-Line-Options>`__, a Json-rpc server and an -interactive console. - -In order to install Geth, open a command line or terminal tool (if you -are unsure how to do this, consider waiting for a more user friendly -release) and paste the command below: - -:: - - bash <(curl https://install-geth.ethereum.org) - -This script will detect your OS and will attempt to install the Ethereum -CLI. For more options including package managers, check the OS-specific -subsections. - -First run ---------- - -For the purposes of this guide, we will focus on the interactive -console, a JavaScript environment. The history of the console is -persisted between sessions, providing for a powerful and flexible way of -using the client. You can navigate your command history by using the up -and down arrow keys, like a standard command line. To get started Type -the code below on your terminal - -:: - - geth console - -Once geth is fully started, you should see a ``>`` prompt, letting you -know the console is ready. To exit, type ``exit`` at the prompt and hit -``[enter]``. - -Using stderr -~~~~~~~~~~~~ - -Output from the console can be logged or redirected: - -``geth console 2>>geth.log`` - -Using standard tools, the log can be monitored in a separate window: - -``tail -f geth.log`` - -Alternatively, you can also run one terminal with the interactive -console and a second one with the logging output directly. - -1. Open two terminals -2. In the **second** terminal type ``tty``. The output will be something - like ``/dev/pts/13`` -3. In your main terminal, type: ``geth console 2>> /dev/pts/13`` - -This will allow you to monitor your node without cluttering the -interactive console. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Go-ethereum-management-API's.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Go-ethereum-management-API's.rst deleted file mode 100644 index 44dcb42..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Go-ethereum-management-API's.rst +++ /dev/null @@ -1,734 +0,0 @@ -Overview -======== - -Beside the official `Dapp -API `__ interface the go -Ethereum node has support for additional management API's. These API's -are offered using `JSON-RPC `__ -and follow the same conventions as used in the Dapp API. The go Ethereum -package comes with a console client which has support for all additional -API's. - -How to -====== - -It is possible to specify the set of API's which are offered over an -interface with the ``--${interface}api`` command line argument for the -go ethereum daemon. Where ``${interface}`` can be ``rpc`` for the -``http`` interface or ``ipc`` for an unix socket on unix or named pipe -on Windows. - -For example, ``geth --ipcapi "admin,eth,miner" --rpcapi "eth,web3"`` -will \* enable the admin, official dapp and miner API over the IPC -interface \* enable the eth and web3 API over the RPC interface - -Please note that offering an API over the ``rpc`` interface will give -everyone access to the API who can access this interface (e.g. dapp's). -So be careful which API's you enable. By default geth enables all API's -over the ``ipc`` interface and only the db,eth,net and web3 API's over -the ``rpc`` interface. - -To determine which API's an interface provides the ``modules`` -transaction can be used, e.g. over an ``ipc`` interface on unix systems: - -:: - - echo '{"jsonrpc":"2.0","method":"modules","params":[],"id":1}' | nc -U $datadir/geth.ipc - -will give all enabled modules including the version number: - -:: - - { - "id":1, - "jsonrpc":"2.0", - "result":{ - "admin":"1.0", - "db":"1.0", - "debug":"1.0", - "eth":"1.0", - "miner":"1.0", - "net":"1.0", - "personal":"1.0", - "shh":"1.0", - "txpool":"1.0", - "web3":"1.0" - } - } - -Integration ------------ - -These additional API's follow the same conventions as the official dapp -API. Web3 can be -`extended `__ and used to -consume these additional API's. - -The different functions are split into multiple smaller logically -grouped API's. Examples are given for the `Javascript -console `__ -but can easily be converted to a rpc request. - -**2 examples:** - -- Console: ``miner.start()`` - -- IPC: - ``echo '{"jsonrpc":"2.0","method":"miner_start","params":[],"id":1}' | nc -U $datadir/geth.ipc`` - -- RPC: - ``curl -X POST --data '{"jsonrpc":"2.0","method":"miner_start","params":[],"id":74}' localhost:8545`` - -With the number of THREADS as an arguments: - -- Console: ``miner.start(4)`` - -- IPC: - ``echo '{"jsonrpc":"2.0","method":"miner_start","params":[4],"id":1}' | nc -U $datadir/geth.ipc`` - -- RPC: - ``curl -X POST --data '{"jsonrpc":"2.0","method":"miner_start","params":[4],"id":74}' localhost:8545`` - -Admin ------ - -Provides various functions for managing a geth node \* -`addPeer <#admin_addPeer>`__ \* [peers] (#admin\_peers) \* -`importChain <#admin_importChain>`__ \* -`exportChain <#admin_exportChain>`__ \* `verbosity <#admin_verbosity>`__ -\* `setSolc <#admin_setColc>`__ \* `startRPC <#admin_startRPC>`__ \* -`stopRPC <#admin_stopRPC>`__ - -Db --- - -This is the official Dapp API. See for more information `this -page `__. - -Debug ------ - -- `dumpBlock <#debug_dumpBlock>`__ -- [getBlockRlp] (#debug\_getBlockRlp) -- `printBlock <#debug_printBlock>`__ -- `processBlock <#debug_processBlock>`__ -- `seedHash <#debug_seedHash>`__ -- `setHead <#debug_setHead>`__ - -Eth ---- - -This is the official Dapp API. See for more information `this -page `__. - -Miner ------ - -Allows full control over the miner and -`DAG `__. \* -`start <#miner_start>`__ \* `stop <#miner_stop>`__ \* -`hashrate <#miner_hashrate>`__ \* `setExtra <#miner_setExtra>`__ \* -`setGasPrice <#miner_setGasPrice>`__ \* -`startAutoDAG <#miner_startAutoDAG>`__ \* -`stopAutoDAG <#miner_stopAutoDAG>`__ \* `makeDAG <#miner_makeDAG>`__ - -Net ---- - -Network related functions \* `peerCount <#net_peerCount>`__ \* -`listening <#net_listening>`__ - -Personal --------- - -Support for account management. \* -`listAccounts <#personal_listAccounts>`__ \* -`newAccount <#personal_newAccount>`__ \* -`unlockAccount <#personal_unlockAccount>`__ - -Txpool ------- - -Gives insight in the transaction pool \* `status <#txpool_status>`__ - -Web3 ----- - -This is the official Dapp API. See for more information `this -page `__. - -admin\_addPeer -~~~~~~~~~~~~~~ - -Add peer to node - -Parameters -^^^^^^^^^^ - -- ``Url``, peer enode url - -Return -^^^^^^ - -``boolean`` indicating if the peer was added - -Example -^^^^^^^ - -``admin.addPeer("enode://4d19a2d...167fa41@XXX.XXX.XXX.XXX:30303")`` -\*\*\* - -admin\_peers -~~~~~~~~~~~~ - -This property will show all connected peers. - -Example -^^^^^^^ - -``admin.peers`` \*\*\* - -admin\_importChain -~~~~~~~~~~~~~~~~~~ - -Import an exported chain from file into node. This only works if no -chain already exists: it does not delete any existing data. - -Parameters -^^^^^^^^^^ - -- ``Filename``, the fully qualified path to the file containing the - chain to be imported - -Return -^^^^^^ - -``boolean`` indicating if chain was imported - -Example -^^^^^^^ - -``admin.importChain("/tmp/chain.txt")`` \*\*\* - -admin\_exportChain -~~~~~~~~~~~~~~~~~~ - -Export the blockchain to a file - -Parameters -^^^^^^^^^^ - -- ``Filename``, the fully qualified path to the file where the - blockchain must be exported - -Return -^^^^^^ - -``boolean`` indicating if chain was exported - -Example -^^^^^^^ - -``admin.exportChain("/tmp/chain.txt")`` \*\*\* - -admin\_verbosity -~~~~~~~~~~~~~~~~ - -Set loglevel - -Parameters -^^^^^^^^^^ - -- ``Level``, the verbosity level with 0 the least and 6 the most - verbose - -Return -^^^^^^ - -``boolean`` indicating if chain was exported - -Example -^^^^^^^ - -``admin.verbosity(5)`` \*\*\* - -admin\_setSolc -~~~~~~~~~~~~~~ - -Set the path to the solidity compiler for ``eth.compileSolidity``. - -Parameters -^^^^^^^^^^ - -- ``Path``, full path to solidity compiler - -Return -^^^^^^ - -``string`` in case the path was valid a brief description about the -solidity compiler - -Example -^^^^^^^ - -``admin.setSolc("/tmp/solc")`` \*\*\* - -admin\_startRPC -~~~~~~~~~~~~~~~ - -Start the HTTP RPC interface - -Parameters -^^^^^^^^^^ - -- ``ListenAddress``, open listener on this host -- ``ListenPort``, open listener on this port -- ``CorsDomain``, the cross origin resource shared header -- ``Apis``, comma separated list with the API modules which are offered - over this interface - -Return -^^^^^^ - -``boolean`` indication if the interface was started - -Example -^^^^^^^ - -``admin.startRPC("127.0.0.1", 8545, "*", "eth,net,web3")`` \*\*\* - -admin\_stopRPC -~~~~~~~~~~~~~~ - -Stop the HTTP RPC interface - -Return -^^^^^^ - -``boolean`` indication if the interface was stopped - -Example -^^^^^^^ - -``admin.stopRPC()`` - --------------- - -debug\_dumpBlock -~~~~~~~~~~~~~~~~ - -Dump block - -Parameters -^^^^^^^^^^ - -``integer``, block number - -Return -^^^^^^ - -``string`` dumped block - -Example -^^^^^^^ - -``debug.dumpBlock(0)`` \*\*\* - -debug\_getBlockRlp -~~~~~~~~~~~~~~~~~~ - -Get RLP encoded block - -Parameters -^^^^^^^^^^ - -``integer``, block number - -Return -^^^^^^ - -``string`` RLP encoded block - -Example -^^^^^^^ - -``debug.getBlockRlp(0)`` \*\*\* - -debug\_printBlock -~~~~~~~~~~~~~~~~~ - -Pretty print block - -Parameters -^^^^^^^^^^ - -``integer``, block number - -Return -^^^^^^ - -``string`` formatted block - -Example -^^^^^^^ - -``debug.printBlock(0)`` \*\*\* - -debug\_processBlock -~~~~~~~~~~~~~~~~~~~ - -Reprocess a block - -Parameters -^^^^^^^^^^ - -``integer``, block number - -Return -^^^^^^ - -``boolean`` indication if the block was successful processed - -Example -^^^^^^^ - -``debug.processBlock(0)`` - --------------- - -debug\_seedHash -~~~~~~~~~~~~~~~ - -Block seed hash - -Parameters -^^^^^^^^^^ - -``NONE`` - -Return -^^^^^^ - -``string`` block seed hash - -Example -^^^^^^^ - -``debug.seedHash(eth.blockNumber)`` - --------------- - -debug\_setHead -~~~~~~~~~~~~~~ - -Rewind the chain to a specific block - -Parameters -^^^^^^^^^^ - -``integer``, block number - -Return -^^^^^^ - -``boolean`` indication if the new head was successful set - -Example -^^^^^^^ - -``debug.setHead(eth.blockNumber-5000)`` - --------------- - -miner\_start -~~~~~~~~~~~~ - -This will generates the DAG if necessary and starts the miner - -Parameters -^^^^^^^^^^ - -``integer``, an optional integer which specifies the number of threads, -if not specified the number of CPU's is used - -Return -^^^^^^ - -``boolean`` indicating if the miner was started - -Example -^^^^^^^ - -``miner.start()`` \*\*\* - -miner\_stop -~~~~~~~~~~~ - -This will stop the miner - -Parameters -^^^^^^^^^^ - -none - -Return -^^^^^^ - -``boolean`` indicating if the miner was stopped - -Example -^^^^^^^ - -``miner.stop()`` - --------------- - -miner\_hashrate -~~~~~~~~~~~~~~~ - -Miner hashrate - -Parameters -^^^^^^^^^^ - -none - -Return -^^^^^^ - -``integer`` hashes p/s - -Example -^^^^^^^ - -``miner.hashrate`` - --------------- - -miner\_setExtra -~~~~~~~~~~~~~~~ - -Store additional data in a mined block - -Parameters -^^^^^^^^^^ - -``string`` string with extra data (max 1024 bytes) - -Return -^^^^^^ - -``boolean`` indication if the DATA was set - --------------- - -miner\_setGasPrice -~~~~~~~~~~~~~~~~~~ - -Set the gas price. - -Parameters -^^^^^^^^^^ - -``string`` gas price, this can be a base8 (start with 0b), base10 (no -prefix) or base16 representation (start with 0x) - -Return -^^^^^^ - -``boolean`` indication if the new price was set - --------------- - -miner\_startAutoDAG -~~~~~~~~~~~~~~~~~~~ - -Pregenerate the DAG, this will allow for a seamless transition between -the different epochs. If not enabled the miner will need to generate the -DAG when a new epoch begins (each 30k blocks). This takes some time and -will stop the miner until the DAG is generated. - -Parameters -^^^^^^^^^^ - -none - -Return -^^^^^^ - -``boolean`` indication if the command was successful - --------------- - -miner\_stopAutoDAG -~~~~~~~~~~~~~~~~~~ - -Stop DAG pregeneration. - -Parameters -^^^^^^^^^^ - -none - -Return -^^^^^^ - -``boolean`` indication if the command was successful - --------------- - -miner\_makeDAG -~~~~~~~~~~~~~~ - -Start the DAG creator process. - -Parameters -^^^^^^^^^^ - -none - -Return -^^^^^^ - -``boolean`` indication if the command was successful - --------------- - -net\_peerCount -~~~~~~~~~~~~~~ - -The number of connected peers - -Parameters -^^^^^^^^^^ - -none - -Return -^^^^^^ - -``integer`` number of peers - -Example -^^^^^^^ - -``net.peerCount`` - --------------- - -net\_listening -~~~~~~~~~~~~~~ - -Indication if this node is currently listening for new peers - -Parameters -^^^^^^^^^^ - -none - -Return -^^^^^^ - -``boolean`` indication if this node accepts new peers - -Example -^^^^^^^ - -``net.listening`` - --------------- - -personal\_listAccounts -~~~~~~~~~~~~~~~~~~~~~~ - -List all accounts - -Parameters -^^^^^^^^^^ - -none - -Return -^^^^^^ - -``array`` collection with accounts - -Example -^^^^^^^ - -``personal.listAccounts`` - --------------- - -personal\_newAccount -~~~~~~~~~~~~~~~~~~~~ - -Create a new account - -Parameters -^^^^^^^^^^ - -``string``, passphrase to protect the account - -Return -^^^^^^ - -``string`` address of the new account - -Example -^^^^^^^ - -``personal.newAccount("mypasswd")`` - --------------- - -personal\_unlockAccount -~~~~~~~~~~~~~~~~~~~~~~~ - -Unlock an account - -Parameters -^^^^^^^^^^ - -``string``, address of the account to delete - -``string``, passphrase of the account to delete (optional in console, -user will be prompted) - -``integer``, unlock account for duration seconds (optional) - -Return -^^^^^^ - -``boolean`` indication if the account was unlocked - -Example -^^^^^^^ - -``personal.unlockAccount(eth.coinbase, "mypasswd", 300)`` - --------------- - -txpool\_status -~~~~~~~~~~~~~~ - -Number of pending/queued transactions - -Parameters -^^^^^^^^^^ - -``NONE`` - -Return -^^^^^^ - -``pending`` all processable transactions - -``queued`` all non-processable transactions - -Example -^^^^^^^ - -``txpool.status`` - --------------- diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Home.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Home.rst deleted file mode 100644 index e027988..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Home.rst +++ /dev/null @@ -1,33 +0,0 @@ -- User documentation can be found at our `Ethereum User Guide and - reference - manual `__. -- For the API reference and developer documentation head over to the - auto generated - `GoDoc `__ - documentation. - -This is the Wiki for the official Ethereum golang implementation. For -generic Ethereum-related information (whitepaper, yellow paper, protocol -and interface specs, APIs, dapp development guides, etc) see the -`Ethereum main wiki `__. - -Main entry points: - -- `Bitchin' - Tricks `__ -- `Ethereum Frontier - Release `__ -- `Installation - Instructions `__ -- `Managing - Accounts `__ -- `Command Line - Options `__ -- `JavaScript - Console `__ -- `Setting up private network or local - cluster `__ -- `Developers' - Guide `__ - -Sidebar lists all pages. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/How-to-Whisper.rst b/old-docs-for-reference/go-ethereum-wiki.rst/How-to-Whisper.rst deleted file mode 100644 index 9da8f42..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/How-to-Whisper.rst +++ /dev/null @@ -1,133 +0,0 @@ -Whisper is a pure identity-based messaging system. Whisper provides a -low-level (non-application-specific) but easily-accessible API without -being based upon or prejudiced by the low-level hardware attributes and -characteristics, particularly the notion of singular endpoints. - -This tutorial assumes you've read `p2p -101 `__. If -you haven't read it I suggest you read it. This tutorial will guide you -to setting up a full p2p server with whisper capabilities. - -Let's quickly cover some of whisper's basic functionality and discuss it -in greater detail later. - -.. code:: go - - whisper.Send(myEnvelope) - -The notion of envelopes and messages in whisper is somewhat blurred. An -application shouldn't ever need to know the difference between the two -and should only care about the information it's interested in. Therefor -whisper comes with a subscribing mechanism which allows you watch/listen -for specific whisper messages (e.g., to you, with a specific topic, -etc). - -.. code:: go - - whisper.Watch(Filter{ - From: myFriendsPubKey, - Fn: func(msg *whisper.Message) { /* ... */ }, - }) - -Envelopes & Messages --------------------- - -Whenever you want to send message over the whisper network you need to -prove to network you've done some significant work for sealing the -message (such is the cost for sending messages) and thus the more work -you put in to sealing the message the higher the priority the message -will have when propagating it over the network. - -Whisper's *P*\ roof *o*\ f *W*\ ork consists of a simple SHA3 algorithm -in which we try to find the smallest number within a given time frame. -Giving the algorithm more time will result in a smaller number which -means the message has a higher priority in the network. - -Messages are also sealed with a *T*\ ime *T*\ o *L*\ ive. Whisper peers -will automatically flush out messages which have exceeded their time to -live (with a maximum up to 2 days). - -Additionally messages may also contain a recipient (public key) and a -set of topics. Topics will allow us to specify messages their subject -(e.g., "shoes", "laptop", "marketplace", "chat"). Topics are -automatically hashed and only the first 4 bytes are used during -transmission and as such, topics are not 100% reliable, they should be -treated as a probabilistic message filter. - -Sending a whisper message requires you to: - -1. create a new ``whisper.Message`` -2. ``Seal`` it (optionally encrypt, sign and supply with topics) -3. ``Send`` it to your peers - -.. code:: go - - topics := TopicsFromString("my", "message") - msg := whisper.NewMessage([]byte("hello world")) // 1 - envelope := msg.Seal(whisper.Opts{ // 2 - From: myPrivateKey, // Sign it - Topics: topics, - }) - whisper.Send(envelope) // 3 - -Whenever a message needs to be encrypted for a specific recipient supply -the ``Opts`` struct with an additional ``To`` parameter which accepts -the recipients public key (``ecdsa.PublicKey``). - -Watching & Listening --------------------- - -Watching for specific messages on the whisper network can be done using -the ``Watch`` method. You have the option to watch for messages from a -specific recipient, with specific topics or messages directly directed -to you. - -.. code:: go - - topics := TopicsFromString("my", "message") - whisper.Watch(Filter{ - Topics: topics - Fn: func(msg *Message) { - fmt.Println(msg) - }, - }) - -Connecting it all together --------------------------- - -Now if we tie it all together and supply whisper as a sub-protocol to -the DEV's P2P service we have whisper including peer handling and -message propagation. - -.. code:: go - - package main - - import ( - "fmt" - "log" - "os" - - "github.com/ethereum/go-ethereum/p2p" - "github.com/ethereum/go-ethereum/whisper" - "github.com/obscuren/secp256k1-go" - ) - - func main() { - pub, _ := secp256k1.GenerateKeyPair() - - whisper := whisper.New() - - srv := p2p.Server{ - MaxPeers: 10, - Identity: p2p.NewSimpleClientIdentity("my-whisper-app", "1.0", "", string(pub)), - ListenAddr: ":8000", - Protocols: []p2p.Protocol{whisper.Protocol()}, - } - if err := srv.Start(); err != nil { - fmt.Println("could not start server:", err) - os.Exit(1) - } - - select {} - } diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Installation-Instructions-for-ARM.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Installation-Instructions-for-ARM.rst deleted file mode 100644 index 559facd..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Installation-Instructions-for-ARM.rst +++ /dev/null @@ -1,17 +0,0 @@ -Installation Instructions for ARM -================================= - -Geth is built for ARM using cross-compilation. See `Cross compiling -Ethereum `__ -for more details. - -RasPi 2 -------- - -1. Download the `precompiled binary from master - branch `__ -2. Copy it to a location in $PATH (i.e. /usr/bin/local) -3. Run ``geth`` - -Further details: -https://github.com/ethereum/wiki/wiki/Raspberry-Pi-instructions diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Installation-Instructions-for-Arch.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Installation-Instructions-for-Arch.rst deleted file mode 100644 index 3d98d28..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Installation-Instructions-for-Arch.rst +++ /dev/null @@ -1,16 +0,0 @@ -Installing from source ----------------------- - -Install dependencies - -.. code:: shell - - pacman -S git go gcc gmp - -Download and build geth - -.. code:: shell - - git clone https://github.com/ethereum/go-ethereum - cd go-ethereum - make geth diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Installation-Instructions-for-FreeBSD.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Installation-Instructions-for-FreeBSD.rst deleted file mode 100644 index 307e3e5..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Installation-Instructions-for-FreeBSD.rst +++ /dev/null @@ -1,38 +0,0 @@ -Building from source --------------------- - -Building Geth (command line client) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Clone the repository to a directory of your choosing: - -.. code:: shell - - git clone https://github.com/ethereum/go-ethereum - -Building ``geth`` requires some external libraries to be installed: - -- `GMP `__ -- `Go `__ - -.. code:: shell - - pkg install gmp go - -If your golang version is >= 1.5, build the ``geth`` program using the -following command. - -.. code:: shell - - cd go-ethereum - make geth - -If your golang version is < 1.5 (quarterly packages, for example), use -the following command instead. - -.. code:: shell - - cd go-ethereum - CC=clang make geth - -You can now run ``build/bin/geth`` to start your node. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Installation-Instructions-for-Mac.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Installation-Instructions-for-Mac.rst deleted file mode 100644 index efefedc..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Installation-Instructions-for-Mac.rst +++ /dev/null @@ -1,59 +0,0 @@ -Installing with Homebrew ------------------------- - -By far the easiest way to install go-ethereum is to use our Homebrew -tap. If you don't have Homebrew, `install it first `__. - -Then run the following commands to add the tap and install ``geth``: - -.. code:: shell - - brew tap ethereum/ethereum - brew install ethereum - -You can install the develop branch by running ``--devel``: - -.. code:: shell - - brew install ethereum --devel - -After installing, run ``geth account new`` to create an account on your -node. - -You should now be able to run ``geth`` and connect to the network. - -Make sure to check the different options and commands with -``geth --help`` - -For options and patches, see: -https://github.com/ethereum/homebrew-ethereum - -Building from source --------------------- - -Building Geth (command line client) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Clone the repository to a directory of your choosing: - -.. code:: shell - - git clone https://github.com/ethereum/go-ethereum - -Building ``geth`` requires some external libraries to be installed: - -- `GMP `__ -- `Go `__ - -.. code:: shell - - brew install gmp go - -Finally, build the ``geth`` program using the following command. - -.. code:: shell - - cd go-ethereum - make geth - -You can now run ``build/bin/geth`` to start your node. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Installation-Instructions-for-Ubuntu.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Installation-Instructions-for-Ubuntu.rst deleted file mode 100644 index ef17da2..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Installation-Instructions-for-Ubuntu.rst +++ /dev/null @@ -1,58 +0,0 @@ -Installing from PPA -------------------- - -For the latest development snapshot, both ``ppa:ethereum/ethereum`` and -``ppa:ethereum/ethereum-dev`` are needed. If you want the stable version -from the last PoC release, add only the first one. - -.. code:: shell - - sudo apt-get install software-properties-common - sudo add-apt-repository -y ppa:ethereum/ethereum - sudo add-apt-repository -y ppa:ethereum/ethereum-dev - sudo apt-get update - sudo apt-get install ethereum - -After installing, run ``geth account new`` to create an account on your -node. - -You should now be able to run ``geth`` and connect to the network. - -Make sure to check the different options and commands with -``geth --help`` - -You can alternatively install only the ``geth`` CLI with -``apt-get install geth`` if you don't want to install the other -utilities (``bootnode``, ``evm``, ``disasm``, ``rlpdump``, ``ethtest``). - -Building from source --------------------- - -Building Geth (command line client) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Clone the repository to a directory of your choosing: - -.. code:: shell - - git clone https://github.com/ethereum/go-ethereum - -Install latest distribution of Go (v1.4) if you don't have it already: - -`See -instructions `__ - -Building ``geth`` requires some external libraries to be installed: - -.. code:: shell - - sudo apt-get install -y build-essential libgmp3-dev golang - -Finally, build the ``geth`` program using the following command. - -.. code:: shell - - cd go-ethereum - make geth - -You can now run ``build/bin/geth`` to start your node. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Installation-instructions-for-Windows.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Installation-instructions-for-Windows.rst deleted file mode 100644 index bc136dd..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Installation-instructions-for-Windows.rst +++ /dev/null @@ -1,77 +0,0 @@ -Binaries -======== - -Download stable binaries ------------------------- - -All versions of Geth are built and available for download at -https://build.ethereum.org/builds/Windows%20Go%20master%20branch/. The -latest version is always available as -`Geth-Win64-latest.zip `__ - -1. Download zip file -2. Extract geth.exe from zip -3. Open a command terminal -4. chdir -5. open geth.exe - -[STRIKEOUT:Installing from Chocolatey] --------------------------------------- - -***Note: Chocolatey is stuck at 1.2.2 and deprecated. Consider using -another method*** - -For master branch: - -:: - - choco install geth-stable - -*For more information see https://chocolatey.org/packages/geth-stable* - -For develop branch: - -:: - - choco install geth-latest - -*For more information see https://chocolatey.org/packages/geth-latest* - -Source -====== - -Powershell script for building with Cygwin -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -geth < 1.4.0 (MSYS2/GMP dependency): -https://gist.github.com/tgerring/b93057e06960d906574c - -geth >= 1.4.0 (Cygwin/MingW): -https://gist.github.com/tgerring/79f018954aadfb3f406e - -Building from source with winbuilds ------------------------------------ - -1. Install Git from http://git-scm.com/downloads -2. Install Golang from - https://storage.googleapis.com/golang/go1.4.2.windows-amd64.msi -3. Install winbuilds from - http://win-builds.org/1.5.0/win-builds-1.5.0.exe to ``c:\winbuilds`` -4. Run win builds here. It's safe to remove big dependencies like QT - and GTK which aren't needed. *An exact list of dependencies should - be determined* -5. Setup environment paths -6. Add ``GOROOT`` pointed to ``c:\go`` and ``GOPATH`` to ``c:\godev`` - (you are free to pick these paths). -7. Set ``PATH`` to - ``%PATH%;%GOROOT%\bin;%GOPATH%\bin;c:\winbuilds\bin`` -8. Open a terminal and install godep first: - ``go get -u github.com/tools/godep`` -9. Open a terminal and download go-ethereum - ``go get -d -u github.com/ethereum/go-ethereum`` -10. Try building ethereum with go dep, navigate to - ``c:\godev\src\github.com\ethereum\go-ethereum\cmd\geth`` and run - ``git checkout develop && godep go install`` - -If you want to build from an other branch bypass ``godep go install`` -for ``go install`` and checkout the dependencies manually. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Installing-Go.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Installing-Go.rst deleted file mode 100644 index f7929c1..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Installing-Go.rst +++ /dev/null @@ -1,52 +0,0 @@ -Windows -~~~~~~~ - -Download and run the installer found at http://golang.org/doc/install - -OS X -~~~~ - -Download an install the darwin binary from https://golang.org/dl/ - -Linux -~~~~~ - -Ubuntu 14.04 -^^^^^^^^^^^^ - -The apt-get repositories for 14.04 contain golang 1.2.1. Version 1.4.2 -is required, so you can download directly (as above). Alternatively, you -can `add the ethereum apt -repository `__, -which hosts golang 1.4.2. Then you can use -``sudo apt-get install golang`` to install. You will still have to set -the $GOPATH and $PATH variables as specified below. - -If you are getting 'error 2' when building Geth or 'expected target' -errors, it's because you compiled geth while using Go 1.3.x. Run 'make -clean' in the go-ethereum folder then run 'make geth' again to solve the -issue. - -Other distros -^^^^^^^^^^^^^ - -Download the latest distribution - -``curl -O https://storage.googleapis.com/golang/go1.4.2.linux-amd64.tar.gz`` - -Unpack it to the ``/usr/local`` (might require sudo) - -``tar -C /usr/local -xzf go1.4.2.linux-amd64.tar.gz`` - -Set GOPATH and PATH -^^^^^^^^^^^^^^^^^^^ - -For Go to work properly, you need to set the following two environment -variables: - -- Setup a go folder - ``mkdir -p ~/go; echo "export GOPATH=$HOME/go" >> ~/.bashrc`` -- Update your path - ``echo "export PATH=$PATH:$HOME/go/bin:/usr/local/go/bin" >> ~/.bashrc`` -- Read the environment variables into current session: - ``source ~/.bashrc`` diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/JavaScript-Console.rst b/old-docs-for-reference/go-ethereum-wiki.rst/JavaScript-Console.rst deleted file mode 100644 index f38ee3a..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/JavaScript-Console.rst +++ /dev/null @@ -1,1376 +0,0 @@ -JavaScript Runtime Environment -============================== - -Ethereum implements a **javascript runtime environment** (JSRE) that can -be used in either interactive (console) or non-interactive (script) -mode. - -Ethereum's Javascript console exposes the full `web3 JavaScript dapp -API `__ and the -`admin -API `__. - -Interactive use: the JSRE REPL Console --------------------------------------- - -The ``ethereum CLI`` executable ``geth`` has a JavaScript console (a -**Read, Evaluate & Print Loop** = REPL exposing the JSRE), which can be -started with the ``console`` or ``attach`` subcommand. The ``console`` -subcommands starts the geth node and then opens the console. The -``attach`` subcommand will not start the geth node but instead tries to -open the console on a running geth instance. - -:: - - $ geth console - $ geth attach - -The attach node accepts an endpoint in case the geth node is running -with a non default ipc endpoint or you would like to connect over the -rpc interface. - -:: - - $ geth attach ipc:/some/custom/path - $ geth attach rpc:http://191.168.1.1:8545 - -Note that by default the geth node doesn't start the rpc service and not -all functionality is provided over this interface due to security -reasons. These defaults can be overridden when the ``--rpcapi`` argument -when the geth node is started, or with -`admin.startRPC `__. - -If you need log information, start with: - -:: - - $ geth --verbosity 5 console 2>> /tmp/eth.log - -Otherwise mute your logs, so that it does not pollute your console: - -:: - - $ geth console 2>> /dev/null - -or - -:: - - $ geth --verbosity 0 console - -Note: Since the database can only be accessed by one process, this means -you cannot run ``geth console`` if you have an instance of geth already -running. - -Non-interactive use: JSRE script mode -------------------------------------- - -It's also possible to execute files to the JavaScript intepreter. The -``console`` and ``attach`` subcommand accept the ``--exec`` argument -which is a javascript statement. - -:: - - $ geth --exec "eth.blockNumber" attach - -This prints the current block number of a running geth instance. - -Or execute a script with more complex statements with: - -:: - - $ geth --exec 'loadScript("/tmp/checkbalances.js")' attach - $ geth --jspath "/tmp" --exec 'loadScript("checkbalances.js")' attach - -Find an example script -`here `__ - -Use the ``--jspath `` to set a libdir for your js -scripts. Parameters to ``loadScript()`` with no absolute path will be -understood relative to this directory. - -You can exit the console cleanly by typing ``exit`` or simply with -``CTRL-C``. - -Caveat ------- - -The go-ethereum JSRE uses the `Otto JS -VM `__ which has some limitations: - -- "use strict" will parse, but does nothing. -- The regular expression engine (re2/regexp) is not fully compatible - with the ECMA5 specification. - -Note that the other known limitation of Otto (namely the lack of timers) -is taken care of. Ethereum JSRE implements both ``setTimeout`` and -``setInterval``. In addition to this, the console provides -``admin.sleep(seconds)`` as well as a "blocktime sleep" method -``admin.sleepBlocks(number)``. - -Since ``ethereum.js`` uses the -```bignumer.js`` `__ library -(MIT Expat Licence), it is also autoloded. - -Timers ------- - -In addition to the full functionality of JS (as per ECMA5), the Ethereum -JSRE is augmented with various timers. It implements ``setInterval``, -``clearInterval``, ``setTimeout``, ``clearTimeout`` you may be used to -using in browser windows. It also provides implementation for -``admin.sleep(seconds)`` and a block based timer, -``admin.sleepBlocks(n)`` which sleeps till the number of new blocks -added is equal to or greater than ``n``, think "wait for n -confirmations". - -Management APIs -=============== - -Beside the official `Dapp -API `__ interface the go -Ethereum node has support for additional management API's. These API's -are offered using `JSON-RPC `__ -and follow the same conventions as used in the Dapp API. The go Ethereum -package comes with a console client which has support for all additional -API's. - -How to -====== - -It is possible to specify the set of API's which are offered over an -interface with the ``--${interface}api`` command line argument for the -go ethereum daemon. Where ``${interface}`` can be ``rpc`` for the -``http`` interface or ``ipc`` for an unix socket on unix or named pipe -on Windows. - -For example, ``geth --ipcapi "admin,eth,miner" --rpcapi "eth,web3"`` -will \* enable the admin, official dapp and miner API over the IPC -interface \* enable the eth and web3 API over the RPC interface - -Please note that offering an API over the ``rpc`` interface will give -everyone access to the API who can access this interface (e.g. dapp's). -So be careful which API's you enable. By default geth enables all API's -over the ``ipc`` interface and only the db,eth,net and web3 API's over -the ``rpc`` interface. - -To determine which API's an interface provides the ``modules`` -transaction can be used, e.g. over an ``ipc`` interface on unix systems: - -:: - - echo '{"jsonrpc":"2.0","method":"modules","params":[],"id":1}' | nc -U $datadir/geth.ipc - -will give all enabled modules including the version number: - -:: - - { - "id":1, - "jsonrpc":"2.0", - "result":{ - "admin":"1.0", - "db":"1.0", - "debug":"1.0", - "eth":"1.0", - "miner":"1.0", - "net":"1.0", - "personal":"1.0", - "shh":"1.0", - "txpool":"1.0", - "web3":"1.0" - } - } - -Integration ------------ - -These additional API's follow the same conventions as the official Dapp -API. Web3 can be -`extended `__ and used to -consume these additional API's. - -The different functions are split into multiple smaller logically -grouped API's. Examples are given for the `Javascript -console `__ -but can easily be converted to a rpc request. - -**2 examples:** - -- Console: ``miner.start()`` - -- IPC: - ``echo '{"jsonrpc":"2.0","method":"miner_start","params":[],"id":1}' | nc -U $datadir/geth.ipc`` - -- RPC: - ``curl -X POST --data '{"jsonrpc":"2.0","method":"miner_start","params":[],"id":74}' localhost:8545`` - -With the number of THREADS as an arguments: - -- Console: ``miner.start(4)`` - -- IPC: - ``echo '{"jsonrpc":"2.0","method":"miner_start","params":[4],"id":1}' | nc -U $datadir/geth.ipc`` - -- RPC: - ``curl -X POST --data '{"jsonrpc":"2.0","method":"miner_start","params":[4],"id":74}' localhost:8545`` - -Management API Reference ------------------------- - -- `eth <#eth>`__ -- `sign <#ethsign>`__ -- `pendingTransactions <#ethpendingtransactions>`__ -- `resend <#ethresend>`__ -- `admin <#admin>`__ -- `addPeer <#adminaddpeer>`__ -- `peers <#adminpeers>`__ -- `nodeInfo <#adminnodeinfo>`__ -- `datadir <#admindatadir>`__ -- `importChain <#adminimportchain>`__ -- `exportChain <#adminexportchain>`__ -- `chainSyncStatus <#adminchainsyncstatus>`__ -- `startRPC <#adminstartrpc>`__ -- `stopRPC <#adminstoprpc>`__ -- `verbosity <#adminverbosity>`__ -- `setSolc <#adminsetsolc>`__ -- `sleepBlocks <#adminsleepblocks>`__ -- `startNatSpec <#adminstartnatspec>`__ -- `stopNatSpec <#adminstopnatspec>`__ -- `getContractInfo <#admingetcontractinfo>`__ -- `register <#adminregister>`__ -- `registerUrl <#adminregisterurl>`__ -- `miner <#miner>`__ -- `start <#minerstart>`__ -- `stop <#minerstop>`__ -- `startAutoDAG <#minerstartautodag>`__ -- `stopAutoDAG <#minerstopautodag>`__ -- `makeDAG <#minermakedag>`__ -- `hashrate <#minerhashrate>`__ -- `setExtra <#minersetextra>`__ -- [setGasPrice] (#minersetgasprice) -- [setEtherbase] (#minersetetherbase) -- `personal <#personal>`__ -- `newAccount <#personalnewaccount>`__ -- `listAccounts <#personallistaccounts>`__ -- `deleteAccount <#personaldeleteaccount>`__ -- `unlockAccount <#personalunlockaccount>`__ -- `txpool <#txpool>`__ -- `status <#txpoolstatus>`__ -- `debug <#debug>`__ -- `setHead <#debugsethead>`__ -- `seedHash <#debugseedhash>`__ -- `processBlock <#debugprocessblock>`__ -- `getBlockRlp <#debuggetblockrlp>`__ -- `printBlock <#debugprintblock>`__ -- `dumpBlock <#debugdumpblock>`__ -- `metrics <#debugmetrics>`__ -- `loadScript <#loadscript>`__ -- `sleep <#sleep>`__ -- `setInterval <#setInterval>`__ -- `clearInterval <#clearInterval>`__ -- `setTimeout <#setTimeout>`__ -- `clearTimeout <#clearTimeout>`__ -- `web3 <#web3>`__ -- `net <#net>`__ -- `eth <#eth>`__ -- `shh <#shh>`__ -- `db <#db>`__ -- `inspect <#inspect>`__ - --------------- - -Personal -^^^^^^^^ - -The ``personal`` api exposes method for personal the methods to manage, -control or monitor your node. It allows for limited file system access. - --------------- - -personal.listAccounts -^^^^^^^^^^^^^^^^^^^^^ - -:: - - personal.listAccounts - -List all accounts - -Return -^^^^^^ - -collection with accounts - -Example -^^^^^^^ - -``personal.listAccounts`` - --------------- - -personal.newAccount -^^^^^^^^^^^^^^^^^^^ - -:: - - personal.newAccount(passwd) - -Create a new password protected account - -Return -^^^^^^ - -``string`` address of the new account - -Example -^^^^^^^ - -``personal.newAccount("mypasswd")`` - --------------- - -personal.deleteAccount -^^^^^^^^^^^^^^^^^^^^^^ - -:: - - personal.deleteAccount(addr, passwd) - -Delete the account with the given address and password - -Return -^^^^^^ - -indication if the account was deleted - -Example -^^^^^^^ - -``personal.deleteAccount(eth.coinbase, "mypasswd")`` - --------------- - -personal.unlockAccount -^^^^^^^^^^^^^^^^^^^^^^ - -:: - - personal.unlockAccount(addr, passwd, duration) - -Unlock the account with the given address, password and an optional -duration (in seconds) - -Return -^^^^^^ - -``boolean`` indication if the account was unlocked - -Example -^^^^^^^ - -``personal.unlockAccount(eth.coinbase, "mypasswd", 300)`` - --------------- - -TxPool -~~~~~~ - -txpool.status -^^^^^^^^^^^^^ - -:: - - txpool.status - -Number of pending/queued transactions - -Return -^^^^^^ - -``pending`` all processable transactions - -``queued`` all non-processable transactions - -Example -^^^^^^^ - -``txpool.status`` - --------------- - -admin -^^^^^ - -The ``admin`` exposes the methods to manage, control or monitor your -node. It allows for limited file system access. - --------------- - -admin.chainSyncStatus -^^^^^^^^^^^^^^^^^^^^^ - -:: - - admin.chainSyncStatus - -Prints info on blockchain synching. - -return -~~~~~~ - -``blocksAvailable``, blocks which have not been downloaded - -``blocksWaitingForImport``, downloaded blocks waiting before import - -``estimate``, a (very rough) estimate before the node has imported all -blocks - -``importing``, blocks currently importing - --------------- - -admin.verbosity -^^^^^^^^^^^^^^^ - -:: - - admin.verbosity(level) - -**Sets** logger verbosity level to *level*. 1-6: silent, error, warn, -info, debug, detail - -Example -''''''' - -:: - - > admin.verbosity(6) - --------------- - -admin.nodeInfo -^^^^^^^^^^^^^^ - -:: - - admin.nodeInfo - -Returns -''''''' - -information on the node. - -Example -''''''' - -:: - - > admin.nodeInfo - { - Name: 'Ethereum(G)/v0.9.36/darwin/go1.4.1', - NodeUrl: 'enode://c32e13952965e5f7ebc85b02a2eb54b09d55f553161c6729695ea34482af933d0a4b035efb5600fc5c3ea9306724a8cbd83845bb8caaabe0b599fc444e36db7e@89.42.0.12:30303', - NodeID: '0xc32e13952965e5f7ebc85b02a2eb54b09d55f553161c6729695ea34482af933d0a4b035efb5600fc5c3ea9306724a8cbd83845bb8caaabe0b599fc444e36db7e', - IP: '89.42.0.12', - DiscPort: 30303, - TCPPort: 30303, - Td: '0', - ListenAddr: '[::]:30303' - } - -To connect to a node, use the -`enode-format `__ -nodeUrl as an argument to `addPeer <#adminaddpeer>`__ or with CLI param -``bootnodes``. - --------------- - -admin.addPeer -^^^^^^^^^^^^^ - -:: - - admin.addPeer(nodeURL) - -Pass a ``nodeURL`` to connect a to a peer on the network. The -``nodeURL`` needs to be in `enode URL -format `__. geth -will maintain the connection until it shuts down and attempt to -reconnect if the connection drops intermittently. - -You can find out your own node URL by using -`nodeInfo <#adminnodeinfo>`__ or looking at the logs when the node boots -up e.g.: - -:: - - [P2P Discovery] Listening, enode://6f8a80d14311c39f35f516fa664deaaaa13e85b2f7493f37f6144d86991ec012937307647bd3b9a82abe2974e1407241d54947bbb39763a4cac9f77166ad92a0@54.169.166.226:30303 - -Returns -''''''' - -``true`` on success. - -Example -''''''' - -.. code:: javascript - - > admin.addPeer('enode://6f8a80d14311c39f35f516fa664deaaaa13e85b2f7493f37f6144d86991ec012937307647bd3b9a82abe2974e1407241d54947bbb39763a4cac9f77166ad92a0@54.169.166.226:30303') - --------------- - -admin.peers -^^^^^^^^^^^ - -:: - - admin.peers - -Returns -''''''' - -an array of objects with information about connected peers. - -Example -''''''' - -:: - - > admin.peers - [ { ID: '0x6cdd090303f394a1cac34ecc9f7cda18127eafa2a3a06de39f6d920b0e583e062a7362097c7c65ee490a758b442acd5c80c6fce4b148c6a391e946b45131365b', Name: 'Ethereum(G)/v0.9.0/linux/go1.4.1', Caps: 'eth/56, shh/2', RemoteAddress: '54.169.166.226:30303', LocalAddress: '10.1.4.216:58888' } { ID: '0x4f06e802d994aaea9b9623308729cf7e4da61090ffb3615bc7124c5abbf46694c4334e304be4314392fafcee46779e506c6e00f2d31371498db35d28adf85f35', Name: 'Mist/v0.9.0/linux/go1.4.2', Caps: 'eth/58, shh/2', RemoteAddress: '37.142.103.9:30303', LocalAddress: '10.1.4.216:62393' } ] - --------------- - -admin.importChain -^^^^^^^^^^^^^^^^^ - -:: - - admin.importChain(file) - -Imports the blockchain from a marshalled binary format. **Note** that -the blockchain is reset (to genesis) before the imported blocks are -inserted to the chain. - -Returns -''''''' - -``true`` on success, otherwise ``false``. - -Example -''''''' - -.. code:: javascript - - admin.importChain('path/to/file') - // true - --------------- - -admin.exportChain -^^^^^^^^^^^^^^^^^ - -:: - - admin.exportChain(file) - -Exports the blockchain to the given file in binary format. - -Returns -''''''' - -``true`` on success, otherwise ``false``. - -Example -''''''' - -.. code:: javascript - - admin.exportChain('path/to/file') - --------------- - -admin.startRPC -^^^^^^^^^^^^^^ - -:: - - admin.startRPC(host, portNumber, corsheader, modules) - -Starts the HTTP server for the -`JSON-RPC `__. - -Returns -''''''' - -``true`` on success, otherwise ``false``. - -Example -''''''' - -.. code:: javascript - - admin.startRPC("127.0.0.1", 8545, "*", "web3,db,net,eth") - // true - --------------- - -admin.stopRPC -^^^^^^^^^^^^^ - -:: - - admin.stopRPC() - -Stops the HTTP server for the -`JSON-RPC `__. - -Returns -''''''' - -``true`` on success, otherwise ``false``. - -Example -''''''' - -.. code:: javascript - - admin.stopRPC() - // true - --------------- - -admin.sleepBlocks -^^^^^^^^^^^^^^^^^ - -:: - - admin.sleepBlocks(n) - -Sleeps for n blocks. - --------------- - -admin.datadir -^^^^^^^^^^^^^ - -:: - - admin.datadir - -the directory this nodes stores its data - -Returns -''''''' - -directory on success - -Example -''''''' - -.. code:: javascript - - admin.datadir - '/Users/username/Library/Ethereum' - --------------- - -admin.setSolc -^^^^^^^^^^^^^ - -:: - - admin.setSolc(path2solc) - -Set the solidity compiler - -Returns -''''''' - -a string describing the compiler version when path was valid, otherwise -an error - -Example -''''''' - -.. code:: javascript - - admin.setSolc('/some/path/solc') - 'solc v0.9.29 - Solidity Compiler: /some/path/solc - ' - --------------- - -admin.startNatSpec -^^^^^^^^^^^^^^^^^^ - -:: - - admin.startNatSpec() - -activate NatSpec: when sending a transaction to a contract, Registry -lookup and url fetching is used to retrieve authentic contract Info for -it. It allows for prompting a user with authentic contract-specific -confirmation messages. - --------------- - -admin.stopNatSpec -^^^^^^^^^^^^^^^^^ - -:: - - admin.stopNatSpec() - -deactivate NatSpec: when sending a transaction, the user will be -prompted with a generic confirmation message, no contract info is -fetched - --------------- - -admin.getContractInfo -^^^^^^^^^^^^^^^^^^^^^ - -:: - - admin.getContractInfo(address) - -this will retrieve the `contract info -json `__ -for a contract on the address - -Returns -''''''' - -returns the contract info object - -Examples -'''''''' - -.. code:: js - - > info = admin.getContractInfo(contractaddress) - > source = info.source - > abi = info.abiDefinition - --------------- - -admin.saveInfo -^^^^^^^^^^^^^^ - -:: - - admin.saveInfo(contract.info, filename); - -will write `contract info -json `__ -into the target file, calculates its content hash. This content hash -then can used to associate a public url with where the contract info is -publicly available and verifiable. If you register the codehash (hash of -the code of the contract on contractaddress). - -Returns -''''''' - -``contenthash`` on success, otherwise ``undefined``. - -Examples -'''''''' - -.. code:: js - - source = "contract test {\n" + - " /// @notice will multiply `a` by 7.\n" + - " function multiply(uint a) returns(uint d) {\n" + - " return a * 7;\n" + - " }\n" + - "} "; - contract = eth.compile.solidity(source).test; - txhash = eth.sendTransaction({from: primary, data: contract.code }); - // after it is uncluded - contractaddress = eth.getTransactionReceipt(txhash); - filename = "/tmp/info.json"; - contenthash = admin.saveInfo(contract.info, filename); - --------------- - -admin.register -^^^^^^^^^^^^^^ - -:: - - admin.register(address, contractaddress, contenthash); - -will register content hash to the codehash (hash of the code of the -contract on contractaddress). The register transaction is sent from the -address in the first parameter. The transaction needs to be processed -and confirmed on the canonical chain for the registration to take -effect. - -Returns -''''''' - -``true`` on success, otherwise ``false``. - -Examples -'''''''' - -.. code:: js - - source = "contract test {\n" + - " /// @notice will multiply `a` by 7.\n" + - " function multiply(uint a) returns(uint d) {\n" + - " return a * 7;\n" + - " }\n" + - "} "; - contract = eth.compile.solidity(source).test; - txhash = eth.sendTransaction({from: primary, data: contract.code }); - // after it is uncluded - contractaddress = eth.getTransactionReceipt(txhash); - filename = "/tmp/info.json"; - contenthash = admin.saveInfo(contract.info, filename); - admin.register(primary, contractaddress, contenthash); - --------------- - -admin.registerUrl -^^^^^^^^^^^^^^^^^ - -:: - - admin.registerUrl(address, codehash, contenthash); - -this will register a contant hash to the contract' codehash. This will -be used to locate `contract info -json `__ -files. Address in the first parameter will be used to send the -transaction. - -Returns -''''''' - -``true`` on success, otherwise ``false``. - -Examples -'''''''' - -.. code:: js - - source = "contract test {\n" + - " /// @notice will multiply `a` by 7.\n" + - " function multiply(uint a) returns(uint d) {\n" + - " return a * 7;\n" + - " }\n" + - "} "; - contract = eth.compile.solidity(source).test; - txhash = eth.sendTransaction({from: primary, data: contract.code }); - // after it is uncluded - contractaddress = eth.getTransactionReceipt(txhash); - filename = "/tmp/info.json"; - contenthash = admin.saveInfo(contract.info, filename); - admin.register(primary, contractaddress, contenthash); - admin.registerUrl(primary, contenthash, "file://"+filename); - --------------- - -Miner -~~~~~ - -miner.start -^^^^^^^^^^^ - -:: - - miner.start(threadCount) - -Starts -`mining `__ -on with the given ``threadNumber`` of parallel threads. This is an -optional argument. - -Returns -''''''' - -``true`` on success, otherwise ``false``. - -Example -''''''' - -.. code:: javascript - - miner.start() - // true - --------------- - -miner.stop -^^^^^^^^^^ - -:: - - miner.stop(threadCount) - -Stops ``threadCount`` miners. This is an optional argument. - -Returns -''''''' - -``true`` on success, otherwise ``false``. - -Example -''''''' - -.. code:: javascript - - miner.stop() - // true - --------------- - -miner.startAutoDAG -^^^^^^^^^^^^^^^^^^ - -:: - - miner.startAutoDAG() - -Starts automatic pregeneration of the `ethash -DAG `__. This process -make sure that the DAG for the subsequent epoch is available allowing -mining right after the new epoch starts. If this is used by most network -nodes, then blocktimes are expected to be normal at epoch transition. -Auto DAG is switched on automatically when mining is started and -switched off when the miner stops. - -Returns -''''''' - -``true`` on success, otherwise ``false``. - --------------- - -miner.stopAutoDAG -^^^^^^^^^^^^^^^^^ - -:: - - miner.stopAutoDAG() - -Stops automatic pregeneration of the `ethash -DAG `__. Auto DAG is -switched off automatically when mining is stops. - -Returns -''''''' - -``true`` on success, otherwise ``false``. - --------------- - -miner.makeDAG -^^^^^^^^^^^^^ - -:: - - miner.makeDAG(blockNumber, dir) - -Generates the DAG for epoch ``blockNumber/epochLength``. dir specifies a -target directory, If ``dir`` is the empty string, then ethash will use -the default directories ``~/.ethash`` on Linux and MacOS, and -``~\AppData\Ethash`` on Windows. The DAG file's name is -``full-R-`` - -Returns -''''''' - -``true`` on success, otherwise ``false``. - --------------- - -miner.hashrate -^^^^^^^^^^^^^^ - -:: - - miner.hashrate - -Returns -''''''' - -Returns the current hash rate in H/s. - --------------- - -miner.setExtra -^^^^^^^^^^^^^^ - -:: - - miner.setExtra("extra data") - -**Sets** the extra data for the block when finding a block. Limited to -32 bytes. - --------------- - -miner.setGasPrice -^^^^^^^^^^^^^^^^^ - -:: - - miner.setGasPrice(gasPrice) - -**Sets** the the gasprice for the miner - --------------- - -miner.setEtherbase -^^^^^^^^^^^^^^^^^^ - -:: - - miner.setEtherbase(account) - -**Sets** the the ether base, the address that will receive mining -rewards. - --------------- - -Debug -~~~~~ - -debug.setHead -^^^^^^^^^^^^^ - -:: - - debug.setHead(blockNumber) - -**Sets** the current head of the blockchain to the block referred to by -*blockNumber*. See -`web3.eth.getBlock `__ -for more details on block fields and lookup by number or hash. - -Returns -''''''' - -``true`` on success, otherwise ``false``. - -Example -''''''' - -:: - - debug.setHead(eth.blockNumber-1000) - --------------- - -debug.seedHash -^^^^^^^^^^^^^^ - -:: - - debug.seedHash(blockNumber) - -Returns the hash for the epoch the given block is in. - -Returns -''''''' - -hash in hex format - -Example -''''''' - -:: - - > debug.seedHash(eth.blockNumber) - '0xf2e59013a0a379837166b59f871b20a8a0d101d1c355ea85d35329360e69c000' - --------------- - -debug.processBlock -^^^^^^^^^^^^^^^^^^ - -:: - - debug.processBlock(blockNumber) - -Processes the given block referred to by *blockNumber* with the VM in -debug mode. See -`web3.eth.getBlock `__ -for more details on block fields and lookup by number or hash. In -combination with ``setHead``, this can be used to replay processing of a -block to debug VM execution. - -Returns -''''''' - -``true`` on success, otherwise ``false``. - -Example -''''''' - -:: - - debug.processBlock(140101) - --------------- - -debug.getBlockRlp -^^^^^^^^^^^^^^^^^ - -:: - - debug.getBlockRlp(blockNumber) - -Returns the hexadecimal representation of the RLP encoding of the block. -See -`web3.eth.getBlock `__ -for more details on block fields and lookup by number or hash. - -Returns -''''''' - -The hex representation of the RLP encoding of the block. - -Example -''''''' - -:: - - > debug.getBlockRlp(131805) 'f90210f9020ba0ea4dcb53fe575e23742aa30266722a15429b7ba3d33ba8c87012881d7a77e81ea01dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d4934794a4d8e9cae4d04b093aac82e6cd355b6b963fb7ffa01f892bfd6f8fb2ec69f30c8799e371c24ebc5a9d55558640de1fb7ca8787d26da056e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421a056e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421b901000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000083bb9266830202dd832fefd880845534406d91ce9e5448ce9ed0af535048ce9ed0afce9ea04cf6d2c4022dfab72af44e9a58d7ac9f7238ffce31d4da72ed6ec9eda60e1850883f9e9ce6a261381cc0c0' - --------------- - -debug.printBlock -^^^^^^^^^^^^^^^^ - -:: - - debug.printBlock(blockNumber) - -Prints information about the block such as size, total difficulty, as -well as header fields properly formatted. - -See -`web3.eth.getBlock `__ -for more details on block fields and lookup by number or hash. - -Returns -''''''' - -formatted string representation of the block - -Example -''''''' - -:: - - > debug.printBlock(131805) - BLOCK(be465b020fdbedc4063756f0912b5a89bbb4735bd1d1df84363e05ade0195cb1): Size: 531.00 B TD: 643485290485 { - NoNonce: ee48752c3a0bfe3d85339451a5f3f411c21c8170353e450985e1faab0a9ac4cc - Header: - [ - - ParentHash: ea4dcb53fe575e23742aa30266722a15429b7ba3d33ba8c87012881d7a77e81e - UncleHash: 1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347 - Coinbase: a4d8e9cae4d04b093aac82e6cd355b6b963fb7ff - Root: 1f892bfd6f8fb2ec69f30c8799e371c24ebc5a9d55558640de1fb7ca8787d26d - TxSha 56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421 - ReceiptSha: 56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421 - Bloom: 00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 - Difficulty: 12292710 - Number: 131805 - GasLimit: 3141592 - GasUsed: 0 - Time: 1429487725 - Extra: ΞTHΞЯSPHΞЯΞ - MixDigest: 4cf6d2c4022dfab72af44e9a58d7ac9f7238ffce31d4da72ed6ec9eda60e1850 - Nonce: 3f9e9ce6a261381c - ] - Transactions: - [] - Uncles: - [] - } - --------------- - -debug.dumpBlock -^^^^^^^^^^^^^^^ - -:: - - debug.dumpBlock(blockNumber) - -Returns -''''''' - -the raw dump of a block referred to by block number or block hash or -undefined if the block is not found. see -`web3.eth.getBlock `__ -for more details on block fields and lookup by number or hash. - -Example -''''''' - -.. code:: js - - > debug.dumpBlock(eth.blockNumber) - --------------- - -debug.metrics -^^^^^^^^^^^^^ - -:: - - debug.metrics(raw) - -Returns -''''''' - -Collection of metrics, see for more information -`this `__ -wiki page. - -Example -''''''' - -.. code:: js - - > metrics(true) - --------------- - -loadScript -^^^^^^^^^^ - -:: - - loadScript('/path/to/myfile.js'); - -Loads a JavaScript file and executes it. Relative paths are interpreted -as relative to ``jspath`` which is specified as a command line flag, see -`Command Line -Options `__. - -sleep -^^^^^ - -:: - - sleep(s) - -Sleeps for s seconds. - -setInterval -^^^^^^^^^^^ - -:: - - setInterval(s, func() {}) - -clearInterval -^^^^^^^^^^^^^ - -setTimeout -^^^^^^^^^^ - -clearTimeout -^^^^^^^^^^^^ - --------------- - -web3 -^^^^ - -The ``web3`` exposes all methods of the `JavaScript -API `__. - --------------- - -net -^^^ - -The ``net`` is a shortcut for -`web3.net `__. - --------------- - -eth -^^^ - -The ``eth`` is a shortcut for -`web3.eth `__. -In addition to the ``web3`` and ``eth`` interfaces exposed by -`web3.js `__ a few additional calls -are exposed. - --------------- - -eth.sign -^^^^^^^^ - -:: - - eth.sign(signer, data) - -eth.pendingTransactions -^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - eth.pendingTransactions - -Returns pending transactions that belong to one of the users -``eth.accounts``. - --------------- - -eth.resend -^^^^^^^^^^ - -:: - - eth.resend(tx, , ) - -Resends the given transaction returned by ``pendingTransactions()`` and -allows you to overwrite the gas price and gas limit of the transaction. - -Example -''''''' - -.. code:: javascript - - eth.sendTransaction({from: eth.accounts[0], to: "...", gasPrice: "1000"}) - var tx = eth.pendingTransactions()[0] - eth.resend(tx, web3.toWei(10, "szabo")) - --------------- - -shh -^^^ - -The ``shh`` is a shortcut for -`web3.shh `__. - --------------- - -db -^^ - -The ``db`` is a shortcut for -`web3.db `__. - --------------- - -inspect -^^^^^^^ - -The ``inspect`` method pretty prints the given value (supports colours) - --------------- diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Legacy.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Legacy.rst deleted file mode 100644 index 88f7c5b..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Legacy.rst +++ /dev/null @@ -1,24 +0,0 @@ -Legacy ------- - -- `iceCREAM `__ - -- `eth-go `__: - An introduction which will help you bootstrap your own, native, Go - Ethereum application. - -Mutan -~~~~~ - -`Mutan 0.5 -Examples `__ - -`Mutan 0.4 -Examples `__ - -`Mutan 0.4 `__ - -`Mutan 0.2 `__ - -`Mutan 0.2 -Example `__ diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Managing-your-accounts.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Managing-your-accounts.rst deleted file mode 100644 index 87304d3..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Managing-your-accounts.rst +++ /dev/null @@ -1,401 +0,0 @@ -Managing accounts -================= - -**WARNING** Remember your password. - -If you lose the password you use to encrypt your account, you will not -be able to access that account. Repeat: It is NOT possible to access -your account without a password and there is no *forgot my password* -option here. Do not forget it. - -**Note**: the key file name naming convention changed as of ``0.9.36``. -This document is meant to reflect accurate information on accounts as -used by the frontier release. - -The Ethereum CLI ``geth`` provides account management via the -``account`` subcommand: - -:: - - account command [arguments...] - -Manage accounts lets you create new accounts, list all existing -accounts, import a private key into a new account, migrate to newest key -format and change your password. - -It supports interactive mode, when you are prompted for password as well -as non-interactive mode where passwords are supplied via a given -password file. Non-interactive mode is only meant for scripted use on -test networks or known safe environments. - -Make sure you remember the password you gave when creating a new account -(with new, update or import). Without it you are not able to unlock your -account. - -Note that exporting your key in unencrypted format is NOT supported. - -Keys are stored under ``/keystore``. Make sure you backup your -keys regularly! See `DATADIR backup & -restore `__ -for more information. The newest format of the keyfiles is: -``UTC---
``. The order of accounts -when listing, is lexicographic, but as a consequence of the timestamp -format, it is actually order of creation - -It is safe to transfer the entire directory or the individual keys -therein between Ethereum nodes. Note that in case you are adding keys to -your node from a different node, the order of accounts may change. So -make sure you do not rely or change the index in your scripts or code -snippets. - -And finally. **DO NOT FORGET YOUR PASSWORD** - -:: - - SUBCOMMANDS: - - list print account addresses - new create a new account - update update an existing account - import import a private key into a new account - - -You can get info about further subcommands by -``geth account help `` - -Accounts can also be managed via the `Javascript -Console `__ - -Examples --------- - -Interactive use -~~~~~~~~~~~~~~~ - -creating an account -^^^^^^^^^^^^^^^^^^^ - -:: - - $ geth account new - Your new account is locked with a password. Please give a password. Do not forget this password. - Passphrase: - Repeat Passphrase: - Address: {168bc315a2ee09042d83d7c5811b533620531f67} - -Listing accounts -^^^^^^^^^^^^^^^^ - -:: - - $ geth account list - Account #0: {a94f5374fce5edbc8e2a8697c15331677e6ebf0b} - Account #1: {c385233b188811c9f355d4caec14df86d6248235} - Account #2: {7f444580bfef4b9bc7e14eb7fb2a029336b07c9d} - -Import private key -^^^^^^^^^^^^^^^^^^ - -:: - - $ geth --datadir /someOtherEthDataDir account import ./key.prv - The new account will be encrypted with a passphrase. - Please enter a passphrase now. - Passphrase: - Repeat Passphrase: - Address: {7f444580bfef4b9bc7e14eb7fb2a029336b07c9d} - -Account update -^^^^^^^^^^^^^^ - -:: - - $ geth account update a94f5374fce5edbc8e2a8697c15331677e6ebf0b - Unlocking account a94f5374fce5edbc8e2a8697c15331677e6ebf0b | Attempt 1/3 - Passphrase: - 0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b - Account 'a94f5374fce5edbc8e2a8697c15331677e6ebf0b' unlocked. - Please give a new password. Do not forget this password. - Passphrase: - Repeat Passphrase: - 0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b - -Non-interactive use -~~~~~~~~~~~~~~~~~~~ - -You supply a plaintext password file as argument to the ``--password`` -flag. The data in the file consists of the raw characters of the -password, followed by a single newline. - -**Note**: Supplying the password directly as part of the command line is -not recommended, but you can always use shell trickery to get round this -restriction. - -:: - - $ geth --password /path/to/password account new - - $ geth --password /path/to/password account update b0047c606f3af7392e073ed13253f8f4710b08b6 - - $ geth account list - - $ geth --datadir /someOtherEthDataDir --password /path/to/anotherpassword account import ./key.prv - -Creating accounts -================= - -Creating a new account ----------------------- - -:: - - geth account new - -Creates a new account and prints the address. - -On the console, use: - -:: - - > personal.newAccount("passphrase") - -The account is saved in encrypted format. You **must** remember this -passphrase to unlock your account in the future. - -For non-interactive use the passphrase can be specified with the -``--password`` flag: - -:: - - geth --password account new - -Note, this is meant to be used for testing only, it is a bad idea to -save your password to file or expose in any other way. - -Creating an account by importing a private key ----------------------------------------------- - -:: - - geth account import - -Imports an unencrypted private key from ```` and creates a new -account and prints the address. - -The keyfile is assumed to contain an unencrypted private key as -canonical EC raw bytes encoded into hex. - -The account is saved in encrypted format, you are prompted for a -passphrase. - -You must remember this passphrase to unlock your account in the future. - -For non-interactive use the passphrase can be specified with the -``--password`` flag: - -:: - - geth --password account import - -**Note**: Since you can directly copy your encrypted accounts to another -Ethereum instance, this import/export mechanism is not needed when you -transfer an account between nodes. - -**Warning:** when you copy keys into an existing node's keystore, the -order of accounts you are used to may change. Therefore you make sure -you either do not rely on the account order or doublecheck and update -the indexes used in your scripts. - -**Warning:** If you use the password flag with a password file, best to -make sure the file is not readable or even listable for anyone but you. -You achieve this with: - -:: - - touch /path/to/password - chmod 700 /path/to/password - cat > /path/to/password - >I type my pass here^D - -Updating an existing account ----------------------------- - -You can update an existing account on the command line with the -``update`` subcommand with the account address or index as parameter. - -:: - - geth account update b0047c606f3af7392e073ed13253f8f4710b08b6 - geth account update 2 - -The account is saved in the newest version in encrypted format, you are -prompted for a passphrase to unlock the account and another to save the -updated file. - -This same command can therefore be used to migrate an account of a -deprecated format to the newest format or change the password for an -account. - -For non-interactive use the passphrase can be specified with the -``--password`` flag: - -:: - - geth --password account new - -Since only one password can be given, only format update can be -performed, changing your password is only possible interactively. - -**Note**: Account update has the a side effect that the order of your -accounts changes. - -After a successful update, all previous formats/versions of that same -key will be removed! - -Importing your presale wallet -============================= - -Importing your presale wallet is very easy. If you remember your -password that is: - -:: - - geth wallet import /path/to/my/presale.wallet - -will prompt for your password and imports your ether presale account. It -can be used non-interactively with the --password option taking a -passwordfile as argument containing the wallet password in cleartext. - -Listing accounts and checking balances -====================================== - -Listing your current accounts -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -From the command line, call the CLI with: - -:: - - $ geth account list - Account #0: {d1ade25ccd3d550a7eb532ac759cac7be09c2719} - Account #1: {da65665fc30803cb1fb7e6d86691e20b1826dee0} - Account #2: {e470b1a7d2c9c5c6f03bbaa8fa20db6d404a0c32} - Account #3: {f4dd5c3794f1fd0cdc0327a83aa472609c806e99} - -to list your accounts in order of creation. - -**Note**: This order can change if you copy keyfiles from other nodes, -so make sure you either do not rely on indexes or make sure if you copy -keys you check and update your account indexes in your scripts. - -When using the console: - -:: - - > eth.accounts - ['0x407d73d8a49eeb85d32cf465507dd71d507100c1'] - -or via RPC: - -:: - - # Request - $ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":1} http://127.0.0.1:8545' - - # Result - { - "id":1, - "jsonrpc": "2.0", - "result": ["0x407d73d8a49eeb85d32cf465507dd71d507100c1"] - } - -If you want to use an account non-interactively, you need to unlock it. -You can do this on the command line with the ``--unlock`` option which -takes a whitespace separated list of accounts (in hex or index) as -argument so you can unlock the accounts programmatically for one -session. This is useful if you want to use your account from dapps via -RPC. ``--unlock`` will unlock the first account. This is useful when you -created your account programmatically, you do not need to know the -actual account to unlock it. - -Unlocking one account: - -:: - - geth --password <(echo this is not secret!) account new - geth --password <(echo this is not secret!) --unlock primary --rpccorsdomain localhost --verbosity 6 2>> geth.log - -Instead of the account address, you can use integer indexes which refers -to the address position in the account listing (and corresponds to order -of creation) - -The command line allows you to unlock multiple accounts. In this case -the argument to unlock is a whitespace delimited list of accounts -addresses or indexes. - -:: - - geth --unlock "0x407d73d8a49eeb85d32cf465507dd71d507100c1 0 5 e470b1a7d2c9c5c6f03bbaa8fa20db6d404a0c32" - -If this construction is used non-interactively, your password file will -need to contain the respective passwords for the accounts in question, -one per line. - -On the console you can also unlock accounts (one at a time). - -:: - - personal.unlockAccount(address, "password") - -Note that we do NOT recommend using the password argument here, since -the console history is logged, so you may compromise your account. You -have been warned. - -Checking account balances -~~~~~~~~~~~~~~~~~~~~~~~~~ - -To check your the etherbase account balance: - -:: - - > web3.fromWei(eth.getBalance(eth.coinbase), "ether") - 6.5 - -Print all balances with a JavaScript function: - -:: - - function checkAllBalances() { - var i =0; - eth.accounts.forEach( function(e){ - console.log(" eth.accounts["+i+"]: " + e + " \tbalance: " + web3.fromWei(eth.getBalance(e), "ether") + " ether"); - i++; - }) - }; - -That can then be executed with: - -:: - - > checkAllBalances(); - eth.accounts[0]: 0xd1ade25ccd3d550a7eb532ac759cac7be09c2719 balance: 63.11848 ether - eth.accounts[1]: 0xda65665fc30803cb1fb7e6d86691e20b1826dee0 balance: 0 ether - eth.accounts[2]: 0xe470b1a7d2c9c5c6f03bbaa8fa20db6d404a0c32 balance: 1 ether - eth.accounts[3]: 0xf4dd5c3794f1fd0cdc0327a83aa472609c806e99 balance: 6 ether - -Since this function will disappear after restarting geth, it can be -helpful to store commonly used functions to be recalled later. The -`loadScript `__ -function makes this very easy. - -First, save the ``checkAllBalances()`` function definition to a file on -your computer. For example, ``/Users/username/gethload.js``. Then load -the file from the interactive console: - -:: - - > loadScript("/Users/username/gethload.js") - true - -The file will modify your JavaScript environment as if you has typed the -commands manually. Feel free to experiment! diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Metrics-and-Monitoring.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Metrics-and-Monitoring.rst deleted file mode 100644 index 2bc8ba9..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Metrics-and-Monitoring.rst +++ /dev/null @@ -1,168 +0,0 @@ -Geth has quite a nice logging system, capable of creating leveled log -entries tagged with various parts of the system. This helps enormously -during debugging to see exactly what the system is doing, what branches -it's taking, etc. However, logs are not particularly useful when the -system does work correctly, just not very optimally: one - or even a -handful - of logged events is not really statistically relevant, and -tracing more in log files can quickly become unwieldy. - -The goal of the Geth metrics system is that - similar to logs - we -should be able to add arbitrary metric collection to any part of the -code without requiring fancy constructs to analyze them (counter -variables, public interfaces, crossing over the APIs, console hooks, -etc). Instead, we should just "update" metrics whenever and wherever -needed, and have them automatically collected, surfaced through the -APIs, queryable and visualizable for analysis. - -To that extent, Geth currently implement two types of metrics: \* -**Meters**: Analogous to physical meters (electricity, water, etc), they -are capable of measuring the *amount* of "things" that pass through and -at the *rate* at which they do that. A meter doesn't have a specific -unit of measure (byte, block, malloc, etc), it just counts arbitrary -*events*. At any point in time it can report: \* *Total number of -events* that passed through the meter \* *Mean throughput rate* of the -meter since startup (events / second) \* *Weighted throughput rate* in -the last *1*, *5* and *15* minutes (events / second) \* (*"weighted" -means that recent seconds count more that in older ones*) \* **Timers**: -Extension of *meters*, where not only the occurrence of some event is -measured, its *duration* is also collected. Similarly to meters, a timer -can also measure arbitrary events, but each requires a duration to be -assigned individually. Beside **all** the reports a meter can generate, -a timer has additionally: \* *Percentiles (5, 20, 50, 80, 95)*, -reporting that some percentage of the events took less than the reported -time to execute (*e.g. Percentile 20 = 1.5s would mean that 20% of the -measured events took less time than 1.5 seconds to execute; inherently -80%(=100%-20%) took more that 1.5s*) \* Percentile 5: minimum durations -(this is as fast as it gets) \* Percentile 50: well behaved samples -(boring, just to give an idea) \* Percentile 80: general performance -(these should be optimised) \* Percentile 95: worst case outliers (rare, -just handle gracefully) - -Creating and updating metrics ------------------------------ - -Although the Geth metrics system is based on the -```go-metrics`` `__ library, -custom metric constructors are used that take into consideration the CLI -flags to enable or disable metrics collection and reporting: - -.. code:: go - - meter := metrics.NewMeter("system/memory/allocs") - timer := metrics.NewTimer("chain/inserts") - -The name can be any arbitrary string, however since Geth assumes it to -be some meaningful sub-system hierarchy, please name accordingly. -Metrics can then be updated equally simply: - -.. code:: go - - meter.Mark(n) // Record the occurrence of `n` events - - timer.Update(duration) // Record an event that took `duration` - timer.UpdateSince(time) // Record an event that started at `time` - timer.Time(function) // Measure and record the execution of `function` - -Note, metrics collection is disabled by default in order not to incur -reporting overhead for the average user. To enable it please specify the -``--metrics`` flag to geth. - -Querying metrics ----------------- - -Geth automatically exposes all collected metrics in the ``debug`` RPC -API, through the ``metrics`` method, hence these can be queried simply -from the console in: - -.. code:: javascript - - > debug.metrics().p2p.InboundTraffic - { - Avg01Min: '169.12K (2.82K/s)', - Avg05Min: '1.92M (6.42K/s)', - Avg15Min: '3.57M (3.96K/s)', - Total: '5.83M (2.97K/s)' - } - > debug.metrics().chain.inserts - { - Avg01Min: '10 (0.17/s)', - Avg05Min: '61 (0.20/s)', - Avg15Min: '168 (0.19/s)', - Maximum: '2.157261657s', - Minimum: '2.271716ms', - Percentiles: { - 20: '6.993756ms', - 50: '12.342836ms', - 80: '21.765944ms', - 95: '218.500479ms', - 99: '376.015984ms' - }, - Total: '432 (0.22/s)' - } - -By default, the reported metrics are scaled and formatted in a user -friendly way to allow quick inspection. These are however not -appropriate for programmatic processing, so the raw values may be -retrieved via an optional flag: - -.. code:: javascript - - > debug.metrics(true).p2p.InboundTraffic - { - AvgRate01Min: 1599.6190029292586, - AvgRate05Min: 5367.754506658111, - AvgRate15Min: 3761.057607521597, - MeanRate: 2907.3919382272857, - Total: 5901154 - } - -Monitoring metrics ------------------- - -Although inspecting metrics via the console is very useful to gain an -insight into the internal state of Geth, it falls short of visualizing -how these metrics evolve over time, possibly under different -circumstances and events. To overcome this limitation, Geth introduces a -monitoring tool (``geth monitor``) that periodically queries a node for -the requested metrics and plots them on a terminal based UI. - -.. figure:: http://i.imgur.com/Nug0sPG.png - :alt: Monitoring tool - - Monitoring tool - -Monitoring can be started via: - -:: - - geth monitor [--attach=api-endpoint] metric1 metric2 ... metricN - -Where a metric may be: \* Full canonical metric (e.g. -``system/memory/allocs/AvgRate05Min``) \* Group of metrics (e.g. -``system/memory/allocs`` or ``system/memory``) \* Multiple branching -metrics (e.g. ``system/memory/allocs,frees/AvgRate01Min``) - -Not yet supported but planned: \* Wildcard pattern (e.g. -``system/memory/*/AvgRate01Min``) \* Exclusion pattern (e.g. -``system/memory/allocs/!AvgRate01Min``) - -By default ``geth monitor`` uses 5 chart rows. This makes comparative -charts easy as meters have 5 components, and timers 10 (out of which 5 -are throughput and 5 percentiles). For custom layout you can override -with ``--rows``. - -Available metrics ------------------ - -Metrics are a debugging tool, with every developer being free to add, -remove or modify them as seen fit. As they can change between commits, -the exactly available ones can be queried via ``geth monitor`` or via -``debug.metrics(false)`` in the console. A few however may warrant -longevity, so feel free to add to the below list if you feel it's worth -a more general audience: - -- system/memory/ -- allocs: number of memory allocations made -- frees: number of memory releases made -- inuse: memory currently being used -- pauses: time spent in the garbage collector diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Mining.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Mining.rst deleted file mode 100644 index f4ae489..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Mining.rst +++ /dev/null @@ -1,403 +0,0 @@ -- `Introduction to Ethereum - mining `__ - *(main wiki)* - -CPU Mining with Geth -==================== - -At Frontier, the first release of Ethereum, you'll just need a) a GPU -and b) an Ethereum client, Geth. CPU mining will be possible but too -inefficient to hold any value. - -At the moment, Geth only includes a CPU miner, and the team is testing a -`GPU miner -branch `__, but -this won't be part of Frontier. - -The C++ implementation of Ethereum also offers a GPU miner, both as part -of Eth (its CLI), AlethZero (its GUI) and EthMiner (the standalone -miner). - -***NOTE:** Ensure your blockchain is fully synchronized with the main -chain before starting to mine, otherwise you will not be mining on the -main chain.* - -When you start up your Ethereum node with ``geth`` it is not mining by -default. To start it in mining mode, you use the ``--mine`` `command -line -option `__. -The ``-minerthreads`` parameter can be used to set the number parallel -mining threads (defaulting to the total number of processor cores). - -``geth --mine --minerthreads=4`` - -You can also start and stop CPU mining at runtime using the -`console `__. -``miner.start`` takes an optional parameter for the number of miner -threads. - -:: - - > miner.start(8) - true - > miner.stop() - true - -Note that mining for real ether only makes sense if you are in sync with -the network (since you mine on top of the consensus block). Therefore -the eth blockchain downloader/synchroniser will delay mining until -syncing is complete, and after that mining automatically starts unless -you cancel your intention with ``miner.stop()``. - -In order to earn ether you must have your **etherbase** (or -**coinbase**) address set. This etherbase defaults to your `primary -account `__. -If you don't have an etherbase address, then ``geth --mine`` will not -start up. - -You can set your etherbase on the command line: - -:: - - geth --etherbase 1 --mine 2>> geth.log // 1 is index: second account by creation order OR - geth --etherbase '0xa4d8e9cae4d04b093aac82e6cd355b6b963fb7ff' --mine 2>> geth.log - -You can reset your etherbase on the console too: - -:: - - miner.setEtherbase(eth.accounts[2]) - -Note that your etherbase does not need to be an address of a local -account, just an existing one. - -There is an option `to add extra -Data `__ -(32 bytes only) to your mined blocks. By convention this is interpreted -as a unicode string, so you can set your short vanity tag. - -:: - - miner.setExtra("ΞTHΞЯSPHΞЯΞ") - ... - debug.printBlock(131805) - BLOCK(be465b020fdbedc4063756f0912b5a89bbb4735bd1d1df84363e05ade0195cb1): Size: 531.00 B TD: 643485290485 { - NoNonce: ee48752c3a0bfe3d85339451a5f3f411c21c8170353e450985e1faab0a9ac4cc - Header: - [ - ... - Coinbase: a4d8e9cae4d04b093aac82e6cd355b6b963fb7ff - Number: 131805 - Extra: ΞTHΞЯSPHΞЯΞ - ... - } - -See also `this -proposal `__ - -You can check your hashrate with -`miner.hashrate `__, -the result is in H/s (Hash operations per second). - -:: - - > miner.hashrate - 712000 - -After you successfully mined some blocks, you can check the ether -balance of your etherbase account. Now assuming your etherbase is a -local account: - -:: - - > eth.getBalance(eth.coinbase).toNumber(); - '34698870000000' - -In order to spend your earnings `on gas to -transact `__, -you will need to have this account unlocked. - -:: - - > personal.unlockAccount(eth.coinbase) - Password - true - -You can check which blocks are mined by a particular miner (address) -with the following code snippet on the console: - -:: - - function minedBlocks(lastn, addr) { - addrs = []; - if (!addr) { - addr = eth.coinbase - } - limit = eth.blockNumber - lastn - for (i = eth.blockNumber; i >= limit; i--) { - if (eth.getBlock(i).miner == addr) { - addrs.push(i) - } - } - return addrs - } - // scans the last 1000 blocks and returns the blocknumbers of blocks mined by your coinbase - // (more precisely blocks the mining reward for which is sent to your coinbase). - minedBlocks(1000, eth.coinbase); - //[352708, 352655, 352559] - -Note that it will happen often that you find a block yet it never makes -it to the canonical chain. This means when you locally include your -mined block, the current state will show the mining reward credited to -your account, however, after a while, the better chain is discovered and -we switch to a chain in which your block is not included and therefore -no mining reward is credited. Therefore it is quite possible that as a -miner monitoring their coinbase balance will find that it may fluctuate -quite a bit. - -The logs show locally mined blocks confirmed after 5 blocks. At the -moment you may find it easier and faster to generate the list of your -mined blocks from these logs. - -Mining success depends on the set block difficulty. Block difficulty -dynamically adjusts each block in order to regulate the network hashing -power to produce a 12 second blocktime. Your chances of finding a block -therefore follows from your hashrate relative to difficulty. The time -you need to wait you are expected to find a block can be estimated with -the following code: - -**INCORRECT...CHECKING** - -:: - - etm = eth.getBlock("latest").difficulty/miner.hashrate; // estimated time in seconds - Math.floor(etm / 3600.) + "h " + Math.floor((etm % 3600)/60) + "m " + Math.floor(etm % 60) + "s"; - // 1h 3m 30s - -Given a difficulty of 3 billion, a typical CPU with 800KH/s is expected -to find a block every ....? - -GPU mining -========== - --------------- - -Hardware --------- - -The algorithm is memory hard and in order to fit the DAG into memory, it -needs 1-2GB of RAM on each GPU. If you get -``Error GPU mining. GPU memory fragmentation?`` you havent got enough -memory. - -The GPU miner is implemented in OpenCL, so AMD GPUs will be 'faster' -than same-category NVIDIA GPUs. - -ASICs and FPGAs are relatively inefficient and therefore discouraged. - -To get openCL for your chipset and platform, try: \* `AMD SDK -openCL `__ -\* `NVIDIA CUDA openCL `__ - -On Ubuntu ---------- - -AMD -~~~ - -- http://developer.amd.com/tools-and-sdks/opencl-zone/amd-accelerated-parallel-processing -- http://developer.amd.com/tools-and-sdks/graphics-development/display-library-adl-sdk/ - -download: ``ADL_SDK8.zip`` and -``AMD-APP-SDK-v2.9-1.599.381-GA-linux64.sh`` - -:: - - ./AMD-APP-SDK-v2.9-1.599.381-GA-linux64.sh - ln -s /opt/AMDAPPSDK-2.9-1 /opt/AMDAPP - ln -s /opt/AMDAPP/include/CL /usr/include - ln -s /opt/AMDAPP/lib/x86_64/* /usr/lib/ - ldconfig - reboot - -:: - - apt-get install fglrx-updates - // wget, tar, opencl - sudo aticonfig --adapter=all --initial - sudo aticonfig --list-adapters - * 0. 01:00.0 AMD Radeon R9 200 Series - - * - Default adapter - -Nvidia -~~~~~~ - -The following instructions are, for the most part, relevant to any -system with Ubuntu 14.04 and a Nvidia GPU. `Setting up an EC2 instance -for -mining `__ - -On MacOSx ---------- - -:: - - wget http://developer.download.nvidia.com/compute/cuda/7_0/Prod/local_installers/cuda_7.0.29_mac.pkg - sudo installer -pkg ~/Desktop/cuda_7.0.29_mac.pkg -target / - brew update - brew tap ethereum/ethereum - brew reinstall cpp-ethereum --with-gpu-mining --devel --headless --build-from-source - -You check your cooling status: - -:: - - aticonfig --adapter=0 --od-gettemperature - -Mining Software ---------------- - -The official Frontier release of ``geth`` only supports a CPU miner -natively. We are working on a `GPU -miner `__, but it -may not be available for the Frontier release. Geth however can be used -in conjunction with ``ethminer``, using the standalone miner as workers -and ``geth`` as scheduler communicating via -`JSON-RPC `__. - -The `C++ implementation of -Ethereum `__ (not officially -released) however has a GPU miner. It can be used from ``eth``, -``AlethZero`` (GUI) and ``ethMiner`` (the standalone miner). - -`You can install -this `__ -via ppa on linux, brew tap on MacOS or from source. - -On MacOS: - -:: - - brew install cpp-ethereum --with-gpu-mining --devel --build-from-source - -On Linux: - -:: - - apt-get install cpp-ethereum - -On Windows: -https://github.com/ethereum/cpp-ethereum/wiki/Building-on-Windows - -GPU mining with ethminer ------------------------- - -To mine with ``eth``: - -:: - - eth -m on -G -a -i -v 8 // - -To install ``ethminer`` from source: - -:: - - cd cpp-ethereum - cmake -DETHASHCL=1 -DGUI=0 - make -j4 - make install - -To set up GPU mining you need a coinbase account. It can be an account -created locally or remotely. - -Using ethminer with geth -~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - geth account new - geth --rpc --rpccorsdomain localhost 2>> geth.log & - ethminer -G // -G for GPU, -M for benchmark - tail -f geth.log - -``ethminer`` communicates with geth on port 8545 (the default RPC port -in geth). You can change this by giving the ```--rpcport`` -option `__ -to ``geth``. Ethminer will find get on any port. Note that you need to -set the CORS header with ``--rpccorsdomain localhost``. You can also set -port on ``ethminer`` with ``-F http://127.0.0.1:3301``. Setting the -ports is necessary if you want several instances mining on the same -computer, although this is somewhat pointless. If you are testing on a -private cluster, we recommend you use CPU mining instead. - -Also note that you do **not** need to give ``geth`` the ``--mine`` -option or start the miner in the console unless you want to do CPU -mining on TOP of GPU mining. - -If the default for ``ethminer`` does not work try to specify the OpenCL -device with: ``--opencl-device X`` where X is 0, 1, 2, etc. When running -``ethminer`` with ``-M`` (benchmark), you should see something like: - -:: - - Benchmarking on platform: { "platform": "NVIDIA CUDA", "device": "GeForce GTX 750 Ti", "version": "OpenCL 1.1 CUDA" } - - - Benchmarking on platform: { "platform": "Apple", "device": "Intel(R) Xeon(R) CPU E5-1620 v2 @ 3.70GHz", "version": "OpenCL 1.2 " } - -To debug ``geth``: - -:: - - geth --rpccorsdomain "localhost" --verbosity 6 2>> geth.log - -To debug the miner: - -:: - - make -DCMAKE_BUILD_TYPE=Debug -DETHASHCL=1 -DGUI=0 - gdb --args ethminer -G -M - -**Note** hashrate info is not available in ``geth`` when GPU mining. -Check your hashrate with ``ethminer``, ``miner.hashrate`` will always -report 0. - -ethminer and eth -~~~~~~~~~~~~~~~~ - -``ethminer`` can be used in conjunction with ``eth`` via rpc - -:: - - eth -i -v 8 -j // -j for rpc - ethminer -G -M // -G for GPU, -M for benchmark - tail -f geth.log - -or you can use ``eth`` to GPU mine by itself: - -:: - - eth -m on -G -a -i -v 8 // - -Further Resources: -================== - -- `ether-proxy, a web interface for mining - rigs `__ (supports solo and - pool mining proxy with web interface and rigs availability - monitoring) -- `Ethereum forum mining FAQ live - update `__ -- `yates randall mining - video `__ -- https://blog.ethereum.org/2014/07/05/stake/ -- https://blog.ethereum.org/2014/10/03/slasher-ghost-developments-proof-stake/ -- https://blog.ethereum.org/2014/06/19/mining/ -- https://github.com/ethereum/wiki/wiki/Ethash -- `Benchmarking results for GPU - mining `__ -- `historic - moment `__ -- `live mining statistic `__ -- `netstat ethereum network monitor `__ diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Mist-build-instructions-for-Mac.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Mist-build-instructions-for-Mac.rst deleted file mode 100644 index bacbbe4..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Mist-build-instructions-for-Mac.rst +++ /dev/null @@ -1,46 +0,0 @@ -Building Mist (GUI) -~~~~~~~~~~~~~~~~~~~ - -**Note: Mist is currently a work in progress and might not always -work.** - -Clone the repository to a directory of your choosing: - -.. code:: shell - - git clone https://github.com/ethereum/go-ethereum - -Building ``mist`` requires some external libraries to be installed: - -- `GMP `__ -- `Qt 5 `__ -- `Qt 5 WebEngine `__ -- `Go `__ - -Install these first: - -.. code:: shell - - brew install gmp go qt5 - brew link -f qt5 # This is required, sorry. - -Finally, build the ``mist`` program using the following commands: - -.. code:: shell - - cd go-ethereum - make mist - -Mist does not automatically look in the right location for its GUI -assets. You can set the asset path on the command line. - -.. code:: shell - - build/bin/mist --asset_path cmd/mist/assets - -Or launch it from its source directory instead: - -.. code:: shell - - cd cmd/mist - ../../build/bin/mist diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Multi-protocol-peer-selection.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Multi-protocol-peer-selection.rst deleted file mode 100644 index ee915f4..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Multi-protocol-peer-selection.rst +++ /dev/null @@ -1,16 +0,0 @@ -In order for the network emerging from the peer selection algorithm in -p2p package to support multiple protocols that might require routing, -such as Swarm, the known node set must satisfy the following properties: -\* Peers should make it known which protocols they support (as a list of -identifiers) \* In each row of the Kademlia table, there should be a -sufficient number (as defined by the redundancy requirement *k*, which -might be distinct for each protocol) of node supporting *each* of the -protocols which the host itself supports. - -The second requirement is achieved by maintaining distinct redundancy -limits *k*\ \ *p*\ for each protocol *p*, with nodes supporting -multiple protocols counting towards the corresponding limits for each of -them. - -Thus, even nodes that do not support a specific protocol can help other -nodes in search of peers that do support it. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.2-Example.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.2-Example.rst deleted file mode 100644 index 0ad968c..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.2-Example.rst +++ /dev/null @@ -1,52 +0,0 @@ -Currency --------- - -.. code:: go - - this.store[this.origin()] = 10**20 - - exit compile { - var to = this.data[0] - var from = this.origin() - var value = this.data[1] - - if this.store[from] > value { - this.store[from] = this.store[from] - value - this.store[to] = this.store[to] + value - } - } - -Life Insurance --------------- - -\`\`\`go #define CLAIMER 0xd766c288f24b91ae9781fe2b155d3260b8674c62 -this.store[1000] = this.origin() - -func heartbeat() var { if this.store[1000] == this.origin() { -this.store[1002] = this.time() return true } else { if this.time() > -this.store[1002] - 2592000 { return false } else { return true } } } - -func claim() var { if this.origin() == CLAIMER { h := heartbeat() if h -== false { transact(CLAIMER, this.balance(), nil) return true } else { -return false } } } - -func withdraw(var amount, var address) var { if this.store[1000] == -this.origin() { h := heartbeat() if h == true { return transact(address, -amount, nil) } else { return false } } } - -func run() { if this.store[1000] == this.origin() { if this.data[0] == -"heartbeat" { h := heartbeat() return h } else { address := this.data[1] -amount := this.data[2] return withdraw(address, amount) } } - -:: - - if this.origin() == CLAIMER { - if this.data[0] == "claim" { - c := claim() - return c - } else { - return false - } - } - -} run() diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.2.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.2.rst deleted file mode 100644 index 260c7a0..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.2.rst +++ /dev/null @@ -1,471 +0,0 @@ -Compiler & Language definition for the Ethereum project -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Mutan is a C-Like language for the Ethereum project. Mutan supports a -full, dynamic higher level language that compiles to native Ethereum -Assembler. `Repo `__ will be moved. - -An online editor and compiler can be found -`here `__ - -Installation -~~~~~~~~~~~~ - -:: - - go get -u github.com/obscuren/mutan/mutan - -Notation -~~~~~~~~ - -The syntax is specified using Extended Backus-Naur Form (EBNF): - -:: - - digit excluding zero = "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ; - digit = "0" | digit excluding zero ; - -Keywords -~~~~~~~~ - -The following keywords are reserved and may not be used as identifiers - -:: - - this if else return exit for asm nil transact create call sizeof true false import - -Operators and delimiters -~~~~~~~~~~~~~~~~~~~~~~~~ - -Mutan contains the following operators and delimiters - -:: - - + ** = | ( ) - - ^ == & { } - * >= ++ ; << >> - / <= -- ! := - -Numeric types -------------- - -Numeric types in Mutan can only be represented by integer values and are -architecture-independent. They are all represented in big endian byte -order. Numbers may be specified in decimal and hexadecimal format. - -.. code:: go - - 10 0xabc 0xABC - -Pointer types -------------- - -A pointer type denotes the set of all pointer to variadics. The default -value of an uninitialised pointer is *nil*. - -:: - - Pointer = "*" Var . - -.. code:: go - - var *a - -Address operations ------------------- - -Address operations are performed with the ampersand "&". The operand -must be *addressable* (i.e, a variable). - -:: - - var a = 10 - var *b = &a - -The pointer indirection ``*x`` denotes the value pointed by ``x``. - -:: - - var old = *b - *b = 1 - -Arrays ------- - -Arrays are of theoretical unlimited length - -:: - - ArrayType = Var "[" Number "]" . - -The following is a valid array: - -.. code:: go - - var[10] a - -Declarations ------------- - -A declaration binds an identifier to a type. Every identifier must be -declared. No identifier may be declared twice and all variables are -scoped to the current executing frame (function). - -:: - - Declaration = TypeDecl . - -A declaration can be done in several ways. First and foremost every -identifier must be declared as a variant. Variants can be created in two -ways, either with the ``var`` keyword or by using the ``:=`` assignment -operator. - -.. code:: go - - var a = "a" - c := "c" - -Statements ----------- - -:: - - Statement = Declaration | Block | IfStmt | ForStmt | Expression | Compile - -Expression ----------- - -:: - - Expression = Ptr | Number | Hex | String | Identifier . - Ptr = Identifier | "nil" . - Number = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" . - Hex = "0x" "a" | "b" | "c" | "d" | "e" | "f" | Number . - String = """ * """ - Identifier = * . - -Blocks ------- - -Blocks contain, but not necessarily, contain lists of Statements within -matching brackets. - -:: - - Block = "{" StatementList "}" . - StatementList = { Statement ";" } . - -If statements -------------- - -If statements specify the conditional execution of two branches -according to the value of an expression. If the expression evaluated to -true, the "if" branch is executed, else, if present, the else branch is -executed. - -:: - - IfStmt = "if" [ SimpleStmt ";" ] Expression Block [ "else" Block ] . - -.. code:: go - - if x < 10 { - x = maximum - } - -The expression may be preceded by a simple statement which executes -before the boolean expression - -.. code:: go - - if x := this.Value(); x < 10 { - x = maximum - } else { - y = 10 - } - -For statement -------------- - -A "for" statements specifies repeated execution of a block, the -iteration is controlled by a conditional block. - -:: - - ForStmt = "for" [ InitStmt ] ";" [ Condition ] ";" [ PostStmt ] . - InitStmt = SimpleStmt . - PostStmt = SimpleStmt . - -A "for" in it's simplest form is a C-Like "while" statement (therefor -Mutan doesn't have a "while") - -.. code:: go - - for a < b { - a = a * 2 - } - -A "for" statement in it's purest form is controlled my a initialiser, -condition and a post statement which will be executed at the end of the -Block - -.. code:: go - - for var a = 0; a < b; a++ { - b = b - 1 - } - -:: - - for cond { T() } is the same as for ; cond ; { T() } - for cond; post { T() } is the same as for ; cond; post { T() } - -String literal --------------- - -String literals are supported by enclosing a line of text with matching -quotes ``"string"``. Strings can be assigned to variables and stored in -memory. Strings have a limitation in size. Strings can be no longer than -**32 bytes**. Attempting to create a string larger than 32 bytes will -result in a compile error. This is due to the limitation of the size -that is allowed to be stored in each storage location. - -.. code:: go - - str := "hello world" - this.store[0] = "hello world" - -Function Declarations ---------------------- - -A function declarations binds an identifier, *the function name*, to a -function. - -:: - - FunctionDecl = "func" FunctionName Signature . - Signature = Parameters [ Result ] . - Parameters = "(" [ ParameterList [ "," ] ] ")" . - ParameterList = ParemeterDecl { "," ParameterDecl } . - ParameterDecl = [ Var Identifier ] . - -If the function's signature declares a result parameter, the function -body's statement list must end with a return statement (**TODO**). - -.. code:: go - - func fib(var n) var { - if n == 0 { - return 0 - } else { - if n == 1 { - return 1 - } - } - - return fib(n-1) + fib(n-2) - } - -Compile -------- - -You can invoke the compiler from within mutan allowing you compile code -inline. At this time of writing compile can only be used in combination -with an ``exit`` statement. Compile will compile the given code, -enclosed by brackets. - -.. code:: go - - a := "hello" - - exit compile { - a := 20 - if a == 20 { - } - } - -Mutan code that is inline compiled does not share any memory outside of -its own scope, and thus can not use any variables outside the enclosed -brackets. - -.. code:: go - - var a = "hello" - return compile { - b := a // Undefined reference error - } - -Build in functions ------------------- - -Mutan comes with a couple build in functions for stopping, creating and -transacting between multiple objects and context functions. - -exit() -'''''' - -:: - - "exit()" - -Stops the execution of the current call - -call(addr, value, gas, in, out) -''''''''''''''''''''''''''''''' - -:: - - Success = "call(" Expression, Expression, Expression, Ptr, Ptr ")" - -Calls contract specified by the address and executes. Arguments can be -passed to the ``in`` argument and the return value can be specified by -the ``out`` parameters. Return a ``1`` or ``0`` depending whether this -call was success or not. - -transact(addr, gas, value, data) -'''''''''''''''''''''''''''''''' - -:: - - Success = "transact(" Expression, Expression, Expression, Ptr ")" - -Handles a transaction between two objects. - -create(value, script) -''''''''''''''''''''' - -:: - - Address = "create(" Expression, Expression ")" - -Creates a new contract given by ``script`` and returns the ``Address`` -of the transaction. - -Context functions -~~~~~~~~~~~~~~~~~ - -The following functions relate to the current executing context (i.e. -the closure). These build-in functions are prefixed with ``this.``. - -:: - - Method = "this" Dot MethodName "(" [ Expression ] ")" . - Dot = "." . - MethodName = "dataLoad" | "dataSize" | "origin" | "address" | "caller" | "gasPrice" | "value" | - "diff" | "prevHash" | "time" | "gasPrice" | "number" | "coinbase" | "gas" . - -:: - - data Returns the x'th value of the attached data of this call - dataSize Returns the size of the data attached to this call - origin Returns the original caller that initiated the first call - address Returns the direct address of this execution - caller Returns the current caller of the closure - gasPrice Returns the gas price attached to this call - value Returns the value attached to this call - balance Returns the value of the current call - diff Returns the current difficulty - prevHash Returns the previous block's hash - time Returns the current block's timestamp - gasPrice Returns the attached call's gas price - number Returns the current block's number - coinbase Returns the current block's coinbase - gas Returns the current call's attached amount of gas - -import ------- - -Importing sourcefiles can be done through the ``import`` keyword - -:: - - Import = "import" StringLiteral - -.. code:: go - - import "std.mu" - -Assembler ---------- - -Inline assembler is allowed through the ``asm`` keyword - -:: - - InlineAssembler = "asm" "{" Code "}" . - Code = "abcdefghijklmnopqrstuwvxyz" | "1234567890" . - -For a full list of ``asm`` opcodes see the -`Assembler `__ -page. - -Pre processor -------------- - -Mutan has a very basic pre processor that takes any ``#define`` and -replaces that throughout the source code - -:: - - Output = "#define" Word [ Expression ] . - -Basic syntax ------------- - -.. code:: go - - #define ADDR 0xe6716f9544a56c530d868e4bfbacb172315bdead - - import "std.mu" - - func pow(var x, var y) { - return x ** y - } - - p := pow(10, 2) - - var a = 20 - var b = 10 - - var str = "hello" - otherStr := "world" - - if a < b { - exit() - } else { - // :-) - if !a { - if this.data[0] ** 10 >= 10 { - this.data[0] = 1000; - } - } - } - - this.store[a] = 10000 - this.store[b] = this.origin() - - for i := 0; i < 10; i++ { - var[10] out - call(0xaabbccddeeff112233445566, 0, 10000, i, out) - } - - // tx without input data - transact(0xa78f6abe, 10000, nil) - // no args and return values - call(0xab, 0, 10000, nil, nil) - // create contract - big ret = create(value, 0xaabbccddeeff0099887766552211) - - var left = 8 << 2 - left = left >> 2 - - asm { - push1 10 - push1 0 - mstore - } - - return compile { - this.store[0] = "hello" - } - diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.4-Examples.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.4-Examples.rst deleted file mode 100644 index 2f9b900..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.4-Examples.rst +++ /dev/null @@ -1,173 +0,0 @@ -Register with NameReg ---------------------- - -.. code:: go - - #define CONFADDR 0x661005d2720d855f1d9976f88bb10c1a3398c77f - - var a = 0 - var nameRegAddr = 0 - - // Get NameReg's address - call(CONFADDR, 0, 1000, a, nameRegAddr) - - var[2] nameRegArgs - nameRegArgs[0] = "register" - nameRegArgs[1] = "MyName" - - // Register with NameReg - call(nameRegAddr, 0, 1000, nameRegArgs, nil) - -DNS ---- - -The DNS contract is currently in operation on the test net. Simply send -a transaction to "DnsReg" with "register", "your domain name" and 4 -bytes representing the IP. - -:: - - "register" - "your domain name" - 0x7f000001 - -.. code:: go - - #define CONFADDR 0x661005d2720d855f1d9976f88bb10c1a3398c77f - - var a = 0 - var nameRegAddr = 0 - - call(CONFADDR, 0, 1000, a, nameRegAddr) - - var[2] nameRegArgs - nameRegArgs[0] = "register" - nameRegArgs[1] = "DnsReg" - - call(nameRegAddr, 0, 1000, nameRegArgs, nil) - - contract.storage["owner"] = tx.sender() - - return compile { - if this.data[0] == "register" { - if contract.storage[this.data[1]] == 0 { - // Deregister old - if contract.storage[tx.sender()] != 0 { - contract.storage[contract.storage[tx.sender()]] = 0 - } - - // Ex. jeff.eth => "192.168.0.1" - // 0xac000001 - contract.storage[this.data[1]] = this.data[2] - contract.storage[tx.sender()] = this.data[1] - } - stop() - } - - if this.data[0] == "deregister" { - if contract.storage[tx.sender()] == this.data[1] { - contract.storage[tx.sender()] = 0 - contract.storage[this.data[1]] = 0 - } - } - - if this.data[0] == "kill" { - if contract.storage["owner"] == tx.sender() { - suicide(tx.sender()) - } - } - } - -Saving w/ lock --------------- - -.. code:: go - - #define CONFADDR 0x661005d2720d855f1d9976f88bb10c1a3398c77f - - var a = 0 - var nameRegAddr = 0 - - call(CONFADDR, 0, 1000, a, nameRegAddr) - - var[2] nameRegArgs - nameRegArgs[0] = "register" - nameRegArgs[1] = "TimeLock" - - call(nameRegAddr, 0, 1000, nameRegArgs, nil) - - contract.storage["owner"] = tx.sender() - contract.storage["period"] = 20 - contract.storage["initiated"] = block.time() - - return compile { - if this.data[0] == "lock" { - if tx.sender() == contract.storage["owner"] { - if contract.storage["recipient"] == 0 { - contract.storage["recipient"] = this.data[1] - } - } - - stop() - } - - if this.data[0] == "withdraw" { - if block.time() > contract.storage["period"] + contract.storage["initiated"] { - suicide(contract.storage["recipient"]) - } - } - } - -Currency --------- - -.. code:: go - - contract.storage[tx.sender()] = 10**20 - - return compile { - var to = this.data[0] - var from = tx.sender() - var value = this.data[1] - - if contract.storage[from] > value { - contract.storage[from] = contract.storage[from] - value - contract.storage[to] = contract.storage[to] + value - } - } - -Life Insurance --------------- - -\`\`\`go #define CLAIMER 0xd766c288f24b91ae9781fe2b155d3260b8674c62 -this.store[1000] = tx.origin() - -func heartbeat() var { if contract.storage[1000] == tx.origin() { -contract.storage[1002] = block.time() return true } else { if -block.time() > contract.storage[1002] - 2592000 { return false } else { -return true } } } - -func claim() var { if tx.origin() == CLAIMER { h := heartbeat() if h == -false { transact(CLAIMER, balance(contract.address()), nil) return true -} else { return false } } } - -func withdraw(var amount, var address) var { if contract.storage[1000] -== tx.origin() { h := heartbeat() if h == true { return -transact(address, amount, nil) } else { return false } } } - -func run() { if contract.storage[1000] == tx.origin() { if this.data[0] -== "heartbeat" { h := heartbeat() return h } else { address := -this.data[1] amount := this.data[2] return withdraw(address, amount) } } - -:: - - if tx.origin() == CLAIMER { - if this.data[0] == "claim" { - c := claim() - return c - } else { - return false - } - } - -} run() diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.4.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.4.rst deleted file mode 100644 index 96b41c0..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.4.rst +++ /dev/null @@ -1,505 +0,0 @@ -Compiler & Language definition for the Ethereum project -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Mutan is a C-Like language for the Ethereum project. Mutan supports a -full, dynamic higher level language that compiles to native Ethereum -Assembler. `Repo `__ will be moved. - -An online editor and compiler can be found -`here `__ - -Installation -~~~~~~~~~~~~ - -:: - - go get -u github.com/obscuren/mutan/mutan - -Notation -~~~~~~~~ - -The syntax is specified using Extended Backus-Naur Form (EBNF): - -:: - - digit excluding zero = "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ; - digit = "0" | digit excluding zero ; - -Keywords -~~~~~~~~ - -The following keywords are reserved and may not be used as identifiers - -:: - - block if true exit sizeof import - contract else false return byte asm - tx for var stop call - this return nil import create - -Operators and delimiters -~~~~~~~~~~~~~~~~~~~~~~~~ - -Mutan contains the following operators and delimiters - -:: - - + ** = | ( ) - - ^ == & { } - * >= ++ ; << >> - / <= -- ! := - -Numeric types -------------- - -Numeric types in Mutan can only be represented by integer values and are -architecture-independent. They are all represented in big endian byte -order. Numbers may be specified in decimal and hexadecimal format. - -.. code:: go - - 10 0xabc 0xABC - -Pointer types -------------- - -A pointer type denotes the set of all pointer to variadics. The default -value of an uninitialised pointer is *nil*. - -:: - - Pointer = "*" Var . - -.. code:: go - - var *a - -Address operations ------------------- - -Address operations are performed with the ampersand "&". The operand -must be *addressable* (i.e, a variable). - -:: - - var a = 10 - var *b = &a - -The pointer indirection ``*x`` denotes the value pointed by ``x``. - -:: - - var old = *b - *b = 1 - -Arrays ------- - -Arrays are of theoretical unlimited length - -:: - - ArrayType = Var "[" Number "]" . - -The following is a valid array: - -.. code:: go - - var[10] a - -Declarations ------------- - -A declaration binds an identifier to a type. Every identifier must be -declared. No identifier may be declared twice and all variables are -scoped to the current executing frame (function). - -:: - - Declaration = TypeDecl . - -A declaration can be done in several ways. First and foremost every -identifier must be declared as a variant. Variants can be created in two -ways, either with the ``var`` keyword or by using the ``:=`` assignment -operator. - -.. code:: go - - var a = "a" - c := "c" - -Statements ----------- - -:: - - Statement = Declaration | Block | IfStmt | ForStmt | Expression | Compile - -Expression ----------- - -:: - - Expression = Ptr | Number | Hex | String | Identifier . - Ptr = Identifier | "nil" . - Number = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" . - Hex = "0x" "a" | "b" | "c" | "d" | "e" | "f" | Number . - String = """ * """ - Identifier = * . - -Blocks ------- - -Blocks contain, but not necessarily, contain lists of Statements within -matching brackets. - -:: - - Block = "{" StatementList "}" . - StatementList = { Statement ";" } . - -If statements -------------- - -If statements specify the conditional execution of two branches -according to the value of an expression. If the expression evaluated to -true, the "if" branch is executed, else, if present, the else branch is -executed. - -:: - - IfStmt = "if" [ SimpleStmt ";" ] Expression Block [ "else" Block ] . - -.. code:: go - - if x < 10 { - x = maximum - } - -The expression may be preceded by a simple statement which executes -before the boolean expression - -.. code:: go - - if x := value(); x < 10 { - x = maximum - } else { - y = 10 - } - -For statement -------------- - -A "for" statements specifies repeated execution of a block, the -iteration is controlled by a conditional block. - -:: - - ForStmt = "for" [ InitStmt ] ";" [ Condition ] ";" [ PostStmt ] . - InitStmt = SimpleStmt . - PostStmt = SimpleStmt . - -A "for" in it's simplest form is a C-Like "while" statement (therefor -Mutan doesn't have a "while") - -.. code:: go - - for a < b { - a = a * 2 - } - -A "for" statement in it's purest form is controlled my a initialiser, -condition and a post statement which will be executed at the end of the -Block - -.. code:: go - - for var a = 0; a < b; a++ { - b = b - 1 - } - -:: - - for cond { T() } is the same as for ; cond ; { T() } - for cond; post { T() } is the same as for ; cond; post { T() } - -String literal --------------- - -String literals are supported by enclosing a line of text with matching -quotes ``"string"``. Strings can be assigned to variables and stored in -memory. Strings have a limitation in size. Strings can be no longer than -**32 bytes**. Attempting to create a string larger than 32 bytes will -result in a compile error. This is due to the limitation of the size -that is allowed to be stored in each storage location. - -.. code:: go - - str := "hello world" - contract.storage[0] = "hello world" - -Function Declarations ---------------------- - -A function declarations binds an identifier, *the function name*, to a -function. - -:: - - FunctionDecl = "func" FunctionName Signature . - Signature = Parameters [ Result ] . - Parameters = "(" [ ParameterList [ "," ] ] ")" . - ParameterList = ParemeterDecl { "," ParameterDecl } . - ParameterDecl = [ Var Identifier ] . - -If the function's signature declares a result parameter, the function -body's statement list must end with a return statement (**TODO**). - -.. code:: go - - func fib(var n) var { - if n == 0 { - return 0 - } else { - if n == 1 { - return 1 - } - } - - return fib(n-1) + fib(n-2) - } - -Compile -------- - -You can invoke the compiler from within mutan allowing you compile code -inline. At this time of writing compile can only be used in combination -with an ``exit`` statement. Compile will compile the given code, -enclosed by brackets. - -.. code:: go - - a := "hello" - - exit compile { - a := 20 - if a == 20 { - } - } - -Mutan code that is inline compiled does not share any memory outside of -its own scope, and thus can not use any variables outside the enclosed -brackets. - -.. code:: go - - var a = "hello" - return compile { - b := a // Undefined reference error - } - -Build in functions ------------------- - -Mutan comes with a couple build in functions for stopping, creating and -transacting between multiple objects and context functions. - -exit() / stop() -''''''''''''''' - -:: - - "exit(); stop()" - -Stops the execution of the current call - -byte(word, nth) -''''''''''''''' - -Returns the nth byte in the given word - -call(addr, value, gas, in, out) -''''''''''''''''''''''''''''''' - -:: - - Success = "call(" Expression, Expression, Expression, Ptr, Ptr ")" - -Calls contract specified by the address and executes. Arguments can be -passed to the ``in`` argument and the return value can be specified by -the ``out`` parameters. Return a ``1`` or ``0`` depending whether this -call was success or not. - -transact(addr, gas, value, data) -'''''''''''''''''''''''''''''''' - -:: - - Success = "transact(" Expression, Expression, Expression, Ptr ")" - -Handles a transaction between two objects. - -create(value, script) -''''''''''''''''''''' - -:: - - Address = "create(" Expression, Expression ")" - -Creates a new contract given by ``script`` and returns the ``Address`` -of the transaction. - -Transaction methods -^^^^^^^^^^^^^^^^^^^ - -:: - - TxMethod = "tx" "." MethodName [ "(" [ Expression ] ")" ] . - MethodName = "origin" | "gasPrice" | "value" . - - origin Returns the initiator of the first call (sender of the transaction) - gasPrice Returns the gas price set for the transaction - value Returns the value of the transaction - -Contract methods -^^^^^^^^^^^^^^^^ - -:: - - ContractMethod = "contract" "." MethodName "(" [ Expression ] ")" . - MethodName = "storage" | "address" . - - storage Returns the contract's storage given by the key - address Returns the direct address of this execution - -Call methods -^^^^^^^^^^^^ - -:: - - CallMethod = "this" "." MethodName "(" [ Expression ] ")" . - MethodName = "data" | "gas" . - - data Returns the x'th value of the attached data of this call - gas Returns the current call's attached amount of gas - -Block methods -^^^^^^^^^^^^^ - -:: - - BlockMethod = "block" "." MethodName "(" [ Expression ] ")" . - MethodName = "difficulty" | "prevHash" | "time" | "number" | "coinbase" . - - difficulty Returns the current difficulty - prevHash Returns the previous block's hash - time Returns the current block's timestamp - number Returns the current block's number - coinbase Returns the current block's coinbase - -import ------- - -Importing sourcefiles can be done through the ``import`` keyword - -:: - - Import = "import" StringLiteral - -.. code:: go - - import "std.mu" - -Assembler ---------- - -Inline assembler is allowed through the ``asm`` keyword - -:: - - InlineAssembler = "asm" "{" Code "}" . - Code = "abcdefghijklmnopqrstuwvxyz" | "1234567890" . - -For a full list of ``asm`` opcodes see the -`Assembler `__ -page. - -Pre processor -------------- - -Mutan has a very basic pre processor that takes any ``#define`` and -replaces that throughout the source code - -:: - - Output = "#define" Word [ Expression ] . - -Basic syntax ------------- - -.. code:: go - - #define ADDR 0xe6716f9544a56c530d868e4bfbacb172315bdead - - import "std.mu" - - func pow(var x, var y) { - return x ** y - } - - p := pow(10, 2) - - var a = 20 - var b = 10 - - var str = "hello" - otherStr := "world" - - if a < b { - exit() - } else { - // :-) - if !a { - if contract.data[0] ** 10 >= 10 { - contract.data[0] = 1000; - } - } - } - - contract.storage[a] = 10000 - contract.storage[b] = tx.origin() - - for i := 0; i < 10; i++ { - var[10] out - call(0xaabbccddeeff112233445566, 0, 10000, i, out) - } - - // tx without input data - transact(0xa78f6abe, 10000, nil) - // no args and return values - call(0xab, 0, 10000, nil, nil) - // create contract - big ret = create(value, compile { - var bt = block.time() - var dataLen = tx.data - var price = tx.gasPrice() - }) - - var left = 8 << 2 - left = left >> 2 - - var[2] array - array[0] = 42 - array[1] = 0 - var re = sha3(array, sizeof(array)) - - asm { - push1 10 - push1 0 - mstore - } - - return compile { - contract.storage[0] = "hello" - } - diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.5-Examples.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.5-Examples.rst deleted file mode 100644 index b084bbf..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.5-Examples.rst +++ /dev/null @@ -1,124 +0,0 @@ -Register with NameReg ---------------------- - -.. code:: go - - #define CONFADDR 0x661005d2720d855f1d9976f88bb10c1a3398c77f - - var a = 0 - var nameRegAddr = 0 - - // Get NameReg's address - call(CONFADDR, 0, 1000, a, nameRegAddr) - - var[2] nameRegArgs - nameRegArgs[0] = "register" - nameRegArgs[1] = "MyName" - - // Register with NameReg - call(nameRegAddr, 0, 1000, nameRegArgs, nil) - -DNS ---- - -The DNS contract is currently in operation on the test net. Simply send -a transaction to "DnsReg" with "register", "your domain name" and 4 -bytes representing the IP. - -:: - - "register" - "your domain name" - 0x7f000001 - -.. code:: go - - #define CONFADDR 0x661005d2720d855f1d9976f88bb10c1a3398c77f - - var a = 0 - var nameRegAddr = 0 - - call(CONFADDR, 0, 1000, a, nameRegAddr) - - var[2] nameRegArgs - nameRegArgs[0] = "register" - nameRegArgs[1] = "DnsReg" - - call(nameRegAddr, 0, 1000, nameRegArgs, nil) - - contract.storage["owner"] = tx.sender() - - return compile { - if message.data[0] == "register" && contract.storage[message.data[1]] == 0 { - // Deregister old - if contract.storage[tx.sender()] != 0 { - contract.storage[contract.storage[tx.sender()]] = 0 - } - - // Ex. jeff.eth => "192.168.0.1" - // 0xac000001 - contract.storage[message.data[1]] = message.data[2] - contract.storage[tx.sender()] = message.data[1] - } else if message.data[0] == "deregister" { - if contract.storage[tx.sender()] == message.data[1] { - contract.storage[tx.sender()] = 0 - contract.storage[message.data[1]] = 0 - } - } else if message.data[0] == "kill" { - if contract.storage["owner"] == tx.sender() { - suicide(tx.sender()) - } - } - } - -Saving w/ lock --------------- - -.. code:: go - - #define CONFADDR 0x661005d2720d855f1d9976f88bb10c1a3398c77f - - var a = 0 - var nameRegAddr = 0 - - call(CONFADDR, 0, 1000, a, nameRegAddr) - - var[2] nameRegArgs - nameRegArgs[0] = "register" - nameRegArgs[1] = "TimeLock" - - call(nameRegAddr, 0, 1000, nameRegArgs, nil) - - contract.storage["owner"] = tx.sender() - contract.storage["period"] = 20 - contract.storage["initiated"] = block.time() - - return compile { - if message.data[0] == "lock" { - if tx.sender() == contract.storage["owner"] && contract.storage["recipient"] == 0 { - contract.storage["recipient"] = message.data[1] - } - } else message.data[0] == "withdraw" { - if block.time() > contract.storage["period"] + contract.storage["initiated"] { - suicide(contract.storage["recipient"]) - } - } - } - -Currency --------- - -.. code:: go - - contract.storage[tx.sender()] = 10**12 - - return compile { - var to = message.data[0] - var from = tx.sender() - var value = message.data[1] - - if contract.storage[from] > value { - contract.storage[from] = contract.storage[from] - value - contract.storage[to] = contract.storage[to] + value - } - } diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.5.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.5.rst deleted file mode 100644 index e064bec..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.5.rst +++ /dev/null @@ -1,519 +0,0 @@ -Compiler & Language definition for the Ethereum project -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Mutan is a C-Like language for the Ethereum project. Mutan supports a -full, dynamic higher level language that compiles to native Ethereum -Assembler. `Repo `__ will be moved. - -An online editor and compiler can be found -`here `__ - -Installation -~~~~~~~~~~~~ - -:: - - go get -u github.com/obscuren/mutan/mutan - -Notation -~~~~~~~~ - -The syntax is specified using Extended Backus-Naur Form (EBNF): - -:: - - digit excluding zero = "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ; - digit = "0" | digit excluding zero ; - -Keywords -~~~~~~~~ - -The following keywords are reserved and may not be used as identifiers - -:: - - block if true exit sizeof import - contract else false return byte asm - tx for var stop call print - this(L) return nil import create - -``(L) = legacy`` - -Operators and delimiters -~~~~~~~~~~~~~~~~~~~~~~~~ - -Mutan contains the following operators and delimiters - -:: - - + ** = | ( ) || - - ^ == & { } && - * >= ++ ; << >> - / <= -- ! := - -Numeric types -------------- - -Numeric types in Mutan can only be represented by integer values and are -architecture-independent. They are all represented in big endian byte -order. Numbers may be specified in decimal and hexadecimal format. - -.. code:: go - - 10 0xabc 0xABC - -Pointer types -------------- - -A pointer type denotes the set of all pointer to variadics. The default -value of an uninitialised pointer is *nil*. - -:: - - Pointer = "*" Var . - -.. code:: go - - var *a - -Address operations ------------------- - -Address operations are performed with the ampersand "&". The operand -must be *addressable* (i.e, a variable). - -:: - - var a = 10 - var *b = &a - -The pointer indirection ``*x`` denotes the value pointed by ``x``. - -:: - - var old = *b - *b = 1 - -Arrays ------- - -Arrays are of theoretical unlimited length - -:: - - ArrayType = Var "[" Number "]" . - -The following is a valid array: - -.. code:: go - - var[10] a - -Declarations ------------- - -A declaration binds an identifier to a type. Every identifier must be -declared. No identifier may be declared twice and all variables are -scoped to the current executing frame (function). - -:: - - Declaration = TypeDecl . - -A declaration can be done in several ways. First and foremost every -identifier must be declared as a variant. Variants can be created in two -ways, either with the ``var`` keyword or by using the ``:=`` assignment -operator. - -.. code:: go - - var a = "a" - c := "c" - -Statements ----------- - -:: - - Statement = Declaration | Block | IfStmt | ForStmt | Expression | Compile - -Expression ----------- - -:: - - Expression = Ptr | Number | Hex | String | Identifier . - Ptr = Identifier | "nil" . - Number = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" . - Hex = "0x" "a" | "b" | "c" | "d" | "e" | "f" | Number . - String = """ * """ - Identifier = * . - -Blocks ------- - -Blocks contain, but not necessarily, contain lists of Statements within -matching brackets. - -:: - - Block = "{" StatementList "}" . - StatementList = { Statement ";" } . - -If statements -------------- - -If statements specify the conditional execution of two branches -according to the value of an expression. If the expression evaluated to -true, the "if" branch is executed, else, if present, the else branch is -executed. - -:: - - IfStmt = "if" [ SimpleStmt ";" ] Expression Block [ "else" ["if" [ SimpleStmt ";" ] ] Block ] . - -.. code:: go - - if x < 10 { - x = maximum - } - -The expression may be preceded by a simple statement which executes -before the boolean expression - -.. code:: go - - if x := value(); x < 10 { - x = maximum - } else { - y = 10 - } - -For statement -------------- - -A "for" statements specifies repeated execution of a block, the -iteration is controlled by a conditional block. - -:: - - ForStmt = "for" [ InitStmt ] ";" [ Condition ] ";" [ PostStmt ] . - InitStmt = SimpleStmt . - PostStmt = SimpleStmt . - -A "for" in it's simplest form is a C-Like "while" statement (therefor -Mutan doesn't have a "while") - -.. code:: go - - for a < b { - a = a * 2 - } - -A "for" statement in it's purest form is controlled my a initialiser, -condition and a post statement which will be executed at the end of the -Block - -.. code:: go - - for var a = 0; a < b; a++ { - b = b - 1 - } - -:: - - for cond { T() } is the same as for ; cond ; { T() } - for cond; post { T() } is the same as for ; cond; post { T() } - -String literal --------------- - -String literals are supported by enclosing a line of text with matching -quotes ``"string"``. Strings can be assigned to variables and stored in -memory. Strings have a limitation in size. Strings can be no longer than -**32 bytes**. Attempting to create a string larger than 32 bytes will -result in a compile error. This is due to the limitation of the size -that is allowed to be stored in each storage location. - -.. code:: go - - str := "hello world" - contract.storage[0] = "hello world" - -Function Declarations ---------------------- - -A function declarations binds an identifier, *the function name*, to a -function. - -:: - - FunctionDecl = "func" FunctionName Signature . - Signature = Parameters [ Result ] . - Parameters = "(" [ ParameterList [ "," ] ] ")" . - ParameterList = ParemeterDecl { "," ParameterDecl } . - ParameterDecl = [ Var Identifier ] . - -If the function's signature declares a result parameter, the function -body's statement list must end with a return statement (**TODO**). - -.. code:: go - - func fib(var n) var { - if n == 0 { - return 0 - } else { - if n == 1 { - return 1 - } - } - - return fib(n-1) + fib(n-2) - } - -Compile -------- - -You can invoke the compiler from within mutan allowing you compile code -inline. At this time of writing compile can only be used in combination -with an ``exit`` statement. Compile will compile the given code, -enclosed by brackets. - -.. code:: go - - a := "hello" - - exit compile { - a := 20 - if a == 20 { - } - } - -Mutan code that is inline compiled does not share any memory outside of -its own scope, and thus can not use any variables outside the enclosed -brackets. - -.. code:: go - - var a = "hello" - return compile { - b := a // Undefined reference error - } - -Build in functions ------------------- - -Mutan comes with a couple build in functions for stopping, creating and -transacting between multiple objects and context functions. - -print(expr) -''''''''''' - -:: - - print "(" Expression ")" - -Prints the given expression (given that the interpreters understands -this pseudo OP) - -exit() / stop() -''''''''''''''' - -:: - - "exit(); stop()" - -Stops the execution of the current call - -byte(word, nth) -''''''''''''''' - -Returns the nth byte in the given word - -call(addr, value, gas, in, out) -''''''''''''''''''''''''''''''' - -:: - - Success = "call(" Expression, Expression, Expression, Ptr, Ptr ")" - -Calls contract specified by the address and executes. Arguments can be -passed to the ``in`` argument and the return value can be specified by -the ``out`` parameters. Return a ``1`` or ``0`` depending whether this -call was success or not. - -transact(addr, gas, value, data) -'''''''''''''''''''''''''''''''' - -:: - - Success = "transact(" Expression, Expression, Expression, Ptr ")" - -Handles a transaction between two objects. - -create(value, script) -''''''''''''''''''''' - -:: - - Address = "create(" Expression, Expression ")" - -Creates a new contract given by ``script`` and returns the ``Address`` -of the transaction. - -Transaction methods -^^^^^^^^^^^^^^^^^^^ - -:: - - TxMethod = "tx" "." MethodName [ "(" [ Expression ] ")" ] . - MethodName = "origin" | "gasPrice" | "value" . - - origin Returns the initiator of the first call (sender of the transaction) - gasPrice Returns the gas price set for the transaction - value Returns the value of the transaction - -Contract methods -^^^^^^^^^^^^^^^^ - -:: - - ContractMethod = "contract" "." MethodName "(" [ Expression ] ")" . - MethodName = "storage" | "address" . - - storage Returns the contract's storage given by the key - address Returns the direct address of this execution - -Call methods -^^^^^^^^^^^^ - -:: - - CallMethod = "message" "." MethodName "(" [ Expression ] ")" . - MethodName = "data" | "gas" . - - data Returns the x'th value of the attached data of this call - gas Returns the current call's attached amount of gas - -Block methods -^^^^^^^^^^^^^ - -:: - - BlockMethod = "block" "." MethodName "(" [ Expression ] ")" . - MethodName = "difficulty" | "prevHash" | "time" | "number" | "coinbase" . - - difficulty Returns the current difficulty - prevHash Returns the previous block's hash - time Returns the current block's timestamp - number Returns the current block's number - coinbase Returns the current block's coinbase - -import ------- - -Importing sourcefiles can be done through the ``import`` keyword - -:: - - Import = "import" StringLiteral - -.. code:: go - - import "std.mu" - -Assembler ---------- - -Inline assembler is allowed through the ``asm`` keyword - -:: - - InlineAssembler = "asm" "{" Code "}" . - Code = "abcdefghijklmnopqrstuwvxyz" | "1234567890" . - -For a full list of ``asm`` opcodes see the -`Assembler `__ -page. - -Pre processor -------------- - -Mutan has a very basic pre processor that takes any ``#define`` and -replaces that throughout the source code - -:: - - Output = "#define" Word [ Expression ] . - -Basic syntax ------------- - -.. code:: go - - #define ADDR 0xe6716f9544a56c530d868e4bfbacb172315bdead - - import "std.mu" - - func pow(var x, var y) { - return x ** y - } - - p := pow(10, 2) - - var a = 20 - var b = 10 - - var str = "hello" - otherStr := "world" - - if a < b { - exit() - } else if 1 && 0 { - stop() - } else { - // :-) - if !a { - if contract.data[0] ** 10 >= 10 { - contract.data[0] = 1000; - } - } - } - - contract.storage[a] = 10000 - contract.storage[b] = tx.origin() - - for i := 0; i < 10; i++ { - var[10] out - call(0xaabbccddeeff112233445566, 0, 10000, i, out) - } - - // tx without input data - transact(0xa78f6abe, 10000, nil) - // no args and return values - call(0xab, 0, 10000, nil, nil) - // create contract - big ret = create(value, compile { - var bt = block.time() - var dataLen = tx.data - var price = tx.gasPrice() - }) - - var left = 8 << 2 - left = left >> 2 - - var[2] array - array[0] = 42 - array[1] = 0 - var re = sha3(array, sizeof(array)) - - asm { - push1 10 - push1 0 - mstore - } - - return compile { - contract.storage[0] = "hello" - } - diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.6-Examples.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.6-Examples.rst deleted file mode 100644 index 9cfe0a1..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.6-Examples.rst +++ /dev/null @@ -1,118 +0,0 @@ -Register with NameReg ---------------------- - -.. code:: go - - #define CONFADDR 0x661005d2720d855f1d9976f88bb10c1a3398c77f - - var a = 0 - var nameRegAddr = 0 - - // Get NameReg's address - call(CONFADDR, 0, 1000, a, nameRegAddr) - - var[2] nameRegArgs = { "register", "MyName" } - - // Register with NameReg - call(nameRegAddr, 0, 1000, nameRegArgs, nil) - -DNS ---- - -The DNS contract is currently in operation on the test net. Simply send -a transaction to "DnsReg" with "register", "your domain name" and 4 -bytes representing the IP. - -:: - - "register" - "your domain name" - 0x7f000001 - -.. code:: go - - #define CONFADDR 0x661005d2720d855f1d9976f88bb10c1a3398c77f - - var a = 0 - var nameRegAddr = 0 - - call(CONFADDR, 0, 1000, a, nameRegAddr) - - var[2] nameRegArgs = { "register", "DnsReg" } - - call(nameRegAddr, 0, 1000, nameRegArgs, nil) - - contract.storage["owner"] = tx.sender() - - return compile { - if message.data[0] == "register" && contract.storage[message.data[1]] == 0 { - // Deregister old - if contract.storage[tx.sender()] != 0 { - contract.storage[contract.storage[tx.sender()]] = 0 - } - - // Ex. jeff.eth => "192.168.0.1" - // 0xac000001 - contract.storage[message.data[1]] = message.data[2] - contract.storage[tx.sender()] = message.data[1] - } else if message.data[0] == "deregister" { - if contract.storage[tx.sender()] == message.data[1] { - contract.storage[tx.sender()] = 0 - contract.storage[message.data[1]] = 0 - } - } else if message.data[0] == "kill" { - if contract.storage["owner"] == tx.sender() { - suicide(tx.sender()) - } - } - } - -Saving w/ lock --------------- - -.. code:: go - - #define CONFADDR 0x661005d2720d855f1d9976f88bb10c1a3398c77f - - var a = 0 - var nameRegAddr = 0 - - call(CONFADDR, 0, 1000, a, nameRegAddr) - - var[2] nameRegArgs = { "register", "TimeLock" } - - call(nameRegAddr, 0, 1000, nameRegArgs, nil) - - contract.storage["owner"] = tx.sender() - contract.storage["period"] = 20 - contract.storage["initiated"] = block.time() - - return compile { - if message.data[0] == "lock" { - if tx.sender() == contract.storage["owner"] && contract.storage["recipient"] == 0 { - contract.storage["recipient"] = message.data[1] - } - } else message.data[0] == "withdraw" { - if block.time() > contract.storage["period"] + contract.storage["initiated"] { - suicide(contract.storage["recipient"]) - } - } - } - -Currency --------- - -.. code:: go - - contract.storage[tx.sender()] = 10**12 - - return compile { - var to = message.data[0] - var from = tx.sender() - var value = message.data[1] - - if contract.storage[from] > value { - contract.storage[from] = contract.storage[from] - value - contract.storage[to] = contract.storage[to] + value - } - } diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.6.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.6.rst deleted file mode 100644 index 9a0e322..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Mutan-0.6.rst +++ /dev/null @@ -1,521 +0,0 @@ -Compiler & Language definition for the Ethereum project -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Mutan is a C-Like language for the Ethereum project. Mutan supports a -full, dynamic higher level language that compiles to native Ethereum -Assembler. `Repo `__ will be moved. - -An online editor and compiler can be found -`here `__ - -Installation -~~~~~~~~~~~~ - -:: - - go get -u github.com/obscuren/mutan/mutan - -Notation -~~~~~~~~ - -The syntax is specified using Extended Backus-Naur Form (EBNF): - -:: - - digit excluding zero = "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ; - digit = "0" | digit excluding zero ; - -Keywords -~~~~~~~~ - -The following keywords are reserved and may not be used as identifiers - -:: - - block if true exit sizeof import - contract else false return byte asm - tx for var stop call print - this(L) return nil import create - -``(L) = legacy`` - -Operators and delimiters -~~~~~~~~~~~~~~~~~~~~~~~~ - -Mutan contains the following operators and delimiters - -:: - - + ** = | ( ) || - - ^ == & { } && - * >= ++ ; << >> - / <= -- ! := - -Numeric types -------------- - -Numeric types in Mutan can only be represented by integer values and are -architecture-independent. They are all represented in big endian byte -order. Numbers may be specified in decimal and hexadecimal format. - -.. code:: go - - 10 0xabc 0xABC - -Pointer types -------------- - -A pointer type denotes the set of all pointer to variadics. The default -value of an uninitialised pointer is *nil*. - -:: - - Pointer = "*" Var . - -.. code:: go - - var *a - -Address operations ------------------- - -Address operations are performed with the ampersand "&". The operand -must be *addressable* (i.e, a variable). - -:: - - var a = 10 - var *b = &a - -The pointer indirection ``*x`` denotes the value pointed by ``x``. - -:: - - var old = *b - *b = 1 - -Arrays ------- - -Arrays are of theoretical unlimited length - -:: - - ArrayType = Var "[" Number "]" [ "=" "{" List "}" ]. - List = Expression [ "," List ] - -The following is a valid array: - -.. code:: go - - var[10] a - - var[2] x = { "hello", "world" } - -Declarations ------------- - -A declaration binds an identifier to a type. Every identifier must be -declared. No identifier may be declared twice and all variables are -scoped to the current executing frame (function). - -:: - - Declaration = TypeDecl . - -A declaration can be done in several ways. First and foremost every -identifier must be declared as a variant. Variants can be created in two -ways, either with the ``var`` keyword or by using the ``:=`` assignment -operator. - -.. code:: go - - var a = "a" - c := "c" - -Statements ----------- - -:: - - Statement = Declaration | Block | IfStmt | ForStmt | Expression | Compile - -Expression ----------- - -:: - - Expression = Ptr | Number | Hex | String | Identifier . - Ptr = Identifier | "nil" . - Number = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" . - Hex = "0x" "a" | "b" | "c" | "d" | "e" | "f" | Number . - String = """ * """ - Identifier = * . - -Blocks ------- - -Blocks contain, but not necessarily, contain lists of Statements within -matching brackets. - -:: - - Block = "{" StatementList "}" . - StatementList = { Statement ";" } . - -If statements -------------- - -If statements specify the conditional execution of two branches -according to the value of an expression. If the expression evaluated to -true, the "if" branch is executed, else, if present, the else branch is -executed. - -:: - - IfStmt = "if" [ SimpleStmt ";" ] Expression Block [ "else" ["if" [ SimpleStmt ";" ] ] Block ] . - -.. code:: go - - if x < 10 { - x = maximum - } - -The expression may be preceded by a simple statement which executes -before the boolean expression - -.. code:: go - - if x := value(); x < 10 { - x = maximum - } else { - y = 10 - } - -For statement -------------- - -A "for" statements specifies repeated execution of a block, the -iteration is controlled by a conditional block. - -:: - - ForStmt = "for" [ InitStmt ] ";" [ Condition ] ";" [ PostStmt ] . - InitStmt = SimpleStmt . - PostStmt = SimpleStmt . - -A "for" in it's simplest form is a C-Like "while" statement (therefor -Mutan doesn't have a "while") - -.. code:: go - - for a < b { - a = a * 2 - } - -A "for" statement in it's purest form is controlled my a initialiser, -condition and a post statement which will be executed at the end of the -Block - -.. code:: go - - for var a = 0; a < b; a++ { - b = b - 1 - } - -:: - - for cond { T() } is the same as for ; cond ; { T() } - for cond; post { T() } is the same as for ; cond; post { T() } - -String literal --------------- - -String literals are supported by enclosing a line of text with matching -quotes ``"string"``. Strings can be assigned to variables and stored in -memory. Strings have a limitation in size. Strings can be no longer than -**32 bytes**. Attempting to create a string larger than 32 bytes will -result in a compile error. This is due to the limitation of the size -that is allowed to be stored in each storage location. - -.. code:: go - - str := "hello world" - contract.storage[0] = "hello world" - -Function Declarations ---------------------- - -A function declarations binds an identifier, *the function name*, to a -function. - -:: - - FunctionDecl = "func" FunctionName Signature . - Signature = Parameters [ Result ] . - Parameters = "(" [ ParameterList [ "," ] ] ")" . - ParameterList = ParemeterDecl { "," ParameterDecl } . - ParameterDecl = [ Var Identifier ] . - -If the function's signature declares a result parameter, the function -body's statement list must end with a return statement (**TODO**). - -.. code:: go - - func fib(var n) var { - if n == 0 { - return 0 - } else { - if n == 1 { - return 1 - } - } - - return fib(n-1) + fib(n-2) - } - -Compile -------- - -You can invoke the compiler from within mutan allowing you compile code -inline. At this time of writing compile can only be used in combination -with an ``exit`` statement. Compile will compile the given code, -enclosed by brackets. - -.. code:: go - - a := "hello" - - exit compile { - a := 20 - if a == 20 { - } - } - -Mutan code that is inline compiled does not share any memory outside of -its own scope, and thus can not use any variables outside the enclosed -brackets. - -.. code:: go - - var a = "hello" - return compile { - b := a // Undefined reference error - } - -Build in functions ------------------- - -Mutan comes with a couple build in functions for stopping, creating and -transacting between multiple objects and context functions. - -print(expr) -''''''''''' - -:: - - print "(" Expression ")" - -Prints the given expression (given that the interpreters understands -this pseudo OP) - -exit() / stop() -''''''''''''''' - -:: - - "exit(); stop()" - -Stops the execution of the current call - -byte(word, nth) -''''''''''''''' - -Returns the nth byte in the given word - -call(addr, value, gas, in, out) -''''''''''''''''''''''''''''''' - -:: - - Success = "call(" Expression, Expression, Expression, Ptr, Ptr ")" - -Calls contract specified by the address and executes. Arguments can be -passed to the ``in`` argument and the return value can be specified by -the ``out`` parameters. Return a ``1`` or ``0`` depending whether this -call was success or not. - -transact(addr, gas, value, data) -'''''''''''''''''''''''''''''''' - -:: - - Success = "transact(" Expression, Expression, Expression, Ptr ")" - -Handles a transaction between two objects. - -create(value, script) -''''''''''''''''''''' - -:: - - Address = "create(" Expression, Expression ")" - -Creates a new contract given by ``script`` and returns the ``Address`` -of the transaction. - -Transaction methods -^^^^^^^^^^^^^^^^^^^ - -:: - - TxMethod = "tx" "." MethodName [ "(" [ Expression ] ")" ] . - MethodName = "origin" | "gasPrice" | "value" . - - origin Returns the initiator of the first call (sender of the transaction) - gasPrice Returns the gas price set for the transaction - value Returns the value of the transaction - -Contract methods -^^^^^^^^^^^^^^^^ - -:: - - ContractMethod = "contract" "." MethodName "(" [ Expression ] ")" . - MethodName = "storage" | "address" . - - storage Returns the contract's storage given by the key - address Returns the direct address of this execution - -Call methods -^^^^^^^^^^^^ - -:: - - CallMethod = "message" "." MethodName "(" [ Expression ] ")" . - MethodName = "data" | "gas" . - - data Returns the x'th value of the attached data of this call - gas Returns the current call's attached amount of gas - -Block methods -^^^^^^^^^^^^^ - -:: - - BlockMethod = "block" "." MethodName "(" [ Expression ] ")" . - MethodName = "difficulty" | "prevHash" | "time" | "number" | "coinbase" . - - difficulty Returns the current difficulty - prevHash Returns the previous block's hash - time Returns the current block's timestamp - number Returns the current block's number - coinbase Returns the current block's coinbase - -import ------- - -Importing sourcefiles can be done through the ``import`` keyword - -:: - - Import = "import" StringLiteral - -.. code:: go - - import "std.mu" - -Assembler ---------- - -Inline assembler is allowed through the ``asm`` keyword - -:: - - InlineAssembler = "asm" "{" Code "}" . - Code = "abcdefghijklmnopqrstuwvxyz" | "1234567890" . - -For a full list of ``asm`` opcodes see the -`Assembler `__ -page. - -Pre processor -------------- - -Mutan has a very basic pre processor that takes any ``#define`` and -replaces that throughout the source code - -:: - - Output = "#define" Word [ Expression ] . - -Basic syntax ------------- - -.. code:: go - - #define ADDR 0xe6716f9544a56c530d868e4bfbacb172315bdead - - import "std.mu" - - func pow(var x, var y) { - return x ** y - } - - p := pow(10, 2) - - var a = 20 - var b = 10 - - var str = "hello" - otherStr := "world" - - if a < b { - exit() - } else if 1 && 0 { - stop() - } else { - // :-) - if !a { - if contract.data[0] ** 10 >= 10 { - contract.data[0] = 1000; - } - } - } - - contract.storage[a] = 10000 - contract.storage[b] = tx.origin() - - for i := 0; i < 10; i++ { - var[10] out - call(0xaabbccddeeff112233445566, 0, 10000, i, out) - } - - // tx without input data - transact(0xa78f6abe, 10000, nil) - // no args and return values - call(0xab, 0, 10000, nil, nil) - // create contract - big ret = create(value, compile { - var bt = block.time() - var dataLen = tx.data - var price = tx.gasPrice() - }) - - var left = 8 << 2 - left = left >> 2 - - var[3] array = { 42, 10 } - array[2] = 0 - var re = sha3(array, sizeof(array)) - - asm { - push1 10 - push1 0 - mstore - } - - return compile { - contract.storage[0] = "hello" - } - diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Mutan.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Mutan.rst deleted file mode 100644 index 02d78b2..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Mutan.rst +++ /dev/null @@ -1,410 +0,0 @@ -Compiler & Language definition for the Ethereum project -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Mutan is a C-Like language for the Ethereum project. Mutan supports a -full, statically typed higher level language that compiles to native -Ethereum Assembler. `Repo `__ will be -moved. - -An online editor and compiler can be found -`here `__ - -Installation -~~~~~~~~~~~~ - -:: - - go get -u github.com/obscuren/mutan/mutan - -Notation -~~~~~~~~ - -The syntax is specified using Extended Backus-Naur Form (EBNF): - -:: - - digit excluding zero = "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ; - digit = "0" | digit excluding zero ; - -Keywords -~~~~~~~~ - -The following keywords are reserved and may not be used as identifiers - -:: - - this if else return exit for asm nil transact create call sizeof true false - -Operators and delimiters ------------------------- - -Mutan contains the following operators and delimiters - -:: - - + ** = | ( ) - - ^ == & { } - * >= ++ ; << >> - / <= -- ! := - -Numeric types -------------- - -Numeric types in Mutan can only be represented by integer values and are -architecture-independent. They are all represented in big endian byte -order. Signed integers aren't supported (yet?) - -:: - - int8 the set of all _unsigned_ integers (0 to 255) - int16 the set of all _unsigned_ integers (0 to 65535) - int32 the set of all _unsigned_ integers (0 to 4294967295) - int64 the set of all _unsigned_ integers (0 to 18446744073709551615) - int256 the set of all _unsigned_ integers (0 to 1.1579209e+77) - addr special type for storing addresses with a size of 20 bytes - big type int256 - int type int32 - byte, bool type int8 - -Numbers may be specified in decimal and hexadecimal format. - -Arrays ------- - -Arrays are of theoretical unlimited length - -:: - - ArrayType = ElementType "[" Number "]" . - ElementType = Type . - -The following are all valid arrays: - -:: - - int16[10] a - int32[10] b - big[10] c - -Declarations ------------- - -A declaration binds an identifier to a type. Every identifier must be -declared. No identifier may be declared twice. All declarations are -global. - -:: - - Declaration = TypeDecl . - -A declaration can be done in several ways. First and foremost every -identifier must be declared either with a type or a variant. Variants -can be created in two separate ways, either with the ``var`` keyword or -by using the ``:=`` assignment operator. - -.. code:: go - - var a = "a" - string b = "b" - c := "c" - -If a variable has been declared as a variant and assigned, it's no -longer possible to re-assign it with a different type. - -.. code:: go - - a := 10 - a = "hello" // Error - -:: - - Types: - var bool int int8 int16 int32 int64 int256 big string - -Statements ----------- - -:: - - Statement = Declaration | Block | IfStmt | ForStmt | Expression | Lambda - -Expression ----------- - -:: - - Expression = Ptr | Number | Hex | String | Identifier . - Ptr = Identifier | "nil" . - Number = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" . - Hex = "0x" "a" | "b" | "c" | "d" | "e" | Number . - String = """ * """ - Identifier = * . - -Blocks ------- - -Blocks contain, but not necessarily, contain lists of Statements within -matching brackets. - -:: - - Block = "{" StatementList "}" . - StatementList = { Statement ";" } . - -If statements -------------- - -If statements specify the conditional execution of two branches -according to the value of an expression. If the expression evaluated to -true, the "if" branch is executed, else, if present, the else branch is -executed. - -:: - - IfStmt = "if" [ SimpleStmt ";" ] Expression Block [ "else" Block ] . - -.. code:: go - - if x < 10 { - x = maximum - } - -The expression may be preceded by a simple statement which executes -before the boolean expression - -.. code:: go - - if int8 x = this.Value(); x < 10 { - x = maximum - } else { - y = 10 - } - -For statement -------------- - -A "for" statements specifies repeated execution of a block, the -iteration is controlled by a conditional block. - -:: - - ForStmt = "for" [ InitStmt ] ";" [ Condition ] ";" [ PostStmt ] . - InitStmt = SimpleStmt . - PostStmt = SimpleStmt . - -A "for" in it's simplest form is a C-Like "while" statement (therefor -Mutan doesn't have a "while") - -.. code:: go - - for a < b { - a = a * 2 - } - -A "for" statement in it's purest form is controlled my a initialiser, -condition and a post statement which will be executed at the end of the -Block - -.. code:: go - - for int8 a = 0; a < b; a++ { - b = b - 1 - } - -:: - - for cond { T() } is the same as for ; cond ; { T() } - for cond; post { T() } is the same as for ; cond; post { T() } - -String literal --------------- - -String literals are supported by enclosing a line of text with matching -quotes ``"string"``. Strings can be assigned to variables and stored in -memory. Storing strings in memory only allows storing up to **32 -bytes**. This is due to the limitation of the size that is allowed to be -stored in each storage location. If a string with a size larger than 32 -bytes is assigned to a storage address it will throw an error. - -.. code:: go - - str := "hello world" - this.store[0] = "hello world" - -Lambda ------- - -A lambda in mutan is a semi lambda and, at the time of writing, can only -be used in a return statement. A lambda will compile the given code, -enclosed by brackets ``{ // code }``. Lambdas are allowed to be of -arbitrary size and take up as much memory as needed. - -.. code:: go - - a := "hello" - - return lambda { - a := 20 - if a == 20 { - } - } - -Lambdas have their own scope and do not share any memory outside of -their own scope, neither can they use any memory outside of their scope. -Lambdas should be viewed as separate instances of code. - -.. code:: go - - var a = "hello" - return lambda { - b := a // Undefined references error - } - -Build in functions ------------------- - -Mutan comes with a couple build in functions for stopping, creating and -transacting between multiple objects and context functions. - -exit() -'''''' - -:: - - "exit()" - -Stops the execution of the current call - -call(addr, value, gas, in, out) -''''''''''''''''''''''''''''''' - -:: - - Success = "call(" Expression, Expression, Expression, Ptr, Ptr ")" - -Calls contract specified by the address and executes. Arguments can be -passed to the ``in`` argument and the return value can be specified by -the ``out`` parameters. Return a ``1`` or ``0`` depending whether this -call was success or not. - -transact(addr, value, data) -''''''''''''''''''''''''''' - -:: - - Success = "transact(" Expression, Expression, Ptr ")" - -Handles a transaction between two objects. - -create(value, script) -''''''''''''''''''''' - -:: - - Address = "create(" Expression, Expression ")" - -Creates a new contract given by ``script`` and returns the ``Address`` -of the transaction. - -Context functions -~~~~~~~~~~~~~~~~~ - -The following functions relate to the current executing context (i.e. -the closure). These build-in functions are prefixed with ``this.``. - -:: - - Method = "this" Dot MethodName "(" [ Expression ] ")" . - Dot = "." . - MethodName = "dataLoad" | "dataSize" | "origin" | "caller" | "gasPrice" | "value" | - "diff" | "prevHash" | "time" | "gasPrice" | "number" | "coinbase" | "gas" . - -:: - - data Returns the x'th value of the attached data of this call - dataSize Returns the size of the data attached to this call - origin Returns the origin address of this execution - caller Returns the current caller of the closure - gasPrice Returns the gas price attached to this call - value Returns the value attached to this call - balance Returns the value of the current call - diff Returns the current difficulty - prevHash Returns the previous block's hash - time Returns the current block's timestamp - gasPrice Returns the attached call's gas price - number Returns the current block's number - coinbase Returns the current block's coinbase - gas Returns the current call's attached amount of gas - -Assembler ---------- - -Inline assembler is allowed through the ``asm`` keyword - -:: - - InlineAssembler = "asm" "(" Code ")" . - Code = "abcdefghijklmnopqrstuwvxyz" | "1234567890" . - -Pre processor -------------- - -Mutan has a very basic pre processor that takes any ``#define`` and -replaces that throughout the source code - -:: - - Output = "#define" Word [ Expression ] . - -Basic syntax ------------- - -.. code:: go - - #define ADDR 0xe6716f9544a56c530d868e4bfbacb172315bdead - - int32 a = 20 - int32 b = 10 - - var str = "hello" - otherStr := "world" - - if a < b { - exit() - } else { - // :-) - if !a { - if this.data[0] ** 10 >= 10 { - this.data[0] = 1000; - } - } - } - - this.store[a] = 10000 - this.store[b] = this.origin() - - for int8 i = 0; i < 10; i++ { - int32[10] out - call(0xaabbccddeeff112233445566, 0, 10000, i, out) - } - - // tx without input data - transact(0xa78f6abe, 10000, nil) - // no args and return values - call(0xab, 0, 10000, nil, nil) - // create contract - big ret = create(value, 0xaabbccddeeff0099887766552211) - - int8 left = 8 << 2 - left = left >> 2 - - asm ( - PUSH 10 - PUSH 0 - MSTORE - ) - - return lambda { - this.store[0] = "hello" - } - diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Passphrase-protected-key-store-spec.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Passphrase-protected-key-store-spec.rst deleted file mode 100644 index 07a5d61..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Passphrase-protected-key-store-spec.rst +++ /dev/null @@ -1,97 +0,0 @@ -**THIS VERSION IS OUTDATED! PLEASE SEE VERSION 3.** - -Version 3 documented -`here `__ - -Summary -======= - -This page details the crypto & encodings in the passphrase protected key -store in Go. To implement this in another Ethereum implementation the -steps below can be followed. The example JSON also acts as a test -vector. - -**TODO: update github links to mainline branch once the latest key store -PR is merged.** - -References -========== - -- **Go source code & cryptography notes:** - https://github.com/Gustav-Simonsson/go-ethereum/blob/improve\_key\_store\_crypto/crypto/key\_store\_passphrase.go#L29 - -The source code comments there have a list of further references. - -- **Discussion with Alex about the cryptography used:** - https://docs.google.com/document/d/179oqUuyePYp0xedF3JurpAPfrCEJJYWwMw-Q3NuL0s0/edit - -From JSON to privkey -==================== - -We start with the JSON in the key file on disk and list operations to -get a privkey for signing. - -**JSON in key file on disk (password is "foo") :** - -.. code:: json - - { - "Address": "d4584b5f6229b7be90727b0fc8c6b91bb427821f", - "Crypto": { - "CipherText": "07533e172414bfa50e99dba4a0ce603f654ebfa1ff46277c3e0c577fdc87f6bb4e4fe16c5a94ce6ce14cfa069821ef9b", - "IV": "16d67ba0ce5a339ff2f07951253e6ba8", - "KeyHeader": { - "Kdf": "scrypt", - "KdfParams": { - "DkLen": 32, - "N": 262144, - "P": 1, - "R": 8, - "SaltLen": 32 - }, - "Version": "1" - }, - "MAC": "8ccded24da2e99a11d48cda146f9cc8213eb423e2ea0d8427f41c3be414424dd", - "Salt": "06870e5e6a24e183a5c807bd1c43afd86d573f7db303ff4853d135cd0fd3fe91" - }, - "Id": "0498f19a-59db-4d54-ac95-33901b4f1870", - "Version": "1" - } - -Go code unmarshaling and decrypting this: -https://github.com/Gustav-Simonsson/go-ethereum/blob/improve\_key\_store\_crypto/crypto/key\_store\_passphrase.go#L199 - -1. Read in the JSON and parse out the KeyHeader field. Get the **JSON - representation of the KeyHeader as a string / byte array**. We need - this for MAC calculation. - -2. Get the derived key by calling scrypt with the scrypt params, the - salt and the passphrase. - -3. Calculate MAC by taking SHA3 of concatentation of KeyHeader JSON, - last 16 bytes of derived key and cipher text: - - .. code:: go - - SHA3( KeyHeaderJSON || derivedKey[16:32] || cipherText ) - -4. Compare calculated MAC with MAC from the JSON object. If not equal, - abort and return an error. - -5. Decrypt the cipherText using AES-128 with CBC mode and the IV from - the JSON. The key used to decrypt is the last 16 bytes of SHA3 of the - last 16 bytes of the scrypt derived key: - - .. code:: go - - AES_128_CBC_Decrypt( SHA3(derivedKey[:16])[:16], cipherText, iv ) - -6. The decrypted plaintext is the 32 bytes EC privkey. - -7. For encryption: reverse the above steps. Ensure both salt and iv are - generated by CSPRNG. - -**Further notes:** \* The "Address" is *OPTIONAL*. It is the Ethereum -address of the key. \* The **Id** is *OPTIONAL*. It is a UUID Version 4. -It is used to identify a key not using key-derived data such as the -Ethereum address, for e.g. key file names. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Peer-to-Peer.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Peer-to-Peer.rst deleted file mode 100644 index f645cef..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Peer-to-Peer.rst +++ /dev/null @@ -1,191 +0,0 @@ -The peer to peer package -(`go-ethereum/p2p `__) -allows you to rapidly and easily add peer to peer networking to any type -of application. The p2p package is set up in a modular structure and -extending the p2p with your own additional sub protocols is easy and -straight forward. - -Starting the p2p service only requires you setup a ``p2p.Server{}`` with -a few settings: - -.. code:: go - - import "github.com/ethereum/go-ethereum/crypto" - import "github.com/ethereum/go-ethereum/p2p" - - nodekey, _ := crypto.GenerateKey() - srv := p2p.Server{ - MaxPeers: 10, - PrivateKey: nodekey, - Name: "my node name", - ListenAddr: ":30300", - Protocols: []p2p.Protocol{}, - } - srv.Start() - -If we wanted to extend the capabilities of our p2p server we'd need to -pass it an additional sub protocol in the ``Protocol: []p2p.Protocol{}`` -array. - -An additional sub protocol that has the ability to respond to the -message "foo" with "bar" requires you to setup an ``p2p.Protocol{}``: - -.. code:: go - - func MyProtocol() p2p.Protocol { - return p2p.Protocol{ // 1. - Name: "MyProtocol", // 2. - Version: 1, // 3. - Length: 1, // 4. - Run: func(peer *p2p.Peer, ws p2p.MsgReadWriter) error { return nil }, // 5. - } - } - -1. A sub-protocol object in the p2p package is called ``Protocol{}``. - Each time a peer connects with the capability of handling this type - of protocol will use this; -2. The name of your protocol to identify the protocol on the network; -3. The version of the protocol. -4. The amount of messages this protocol relies on. Because the p2p is - extendible and thus has the ability to send an arbitrary amount of - messages (with a type, which we'll see later) the p2p handler needs - to know how much space it needs to reserve for your protocol, this to - ensure consensus can be reached between the peers doing a negotiation - over the message IDs. Our protocol supports only one; ``message`` (as - you'll see later). -5. The main handler of your protocol. We've left this intentionally - blank for now. The ``peer`` variable is the peer connected to you and - provides you with some basic information regarding the peer. The - ``ws`` variable which is a reader and a writer allows you to - communicate with the peer. If a message is being send to us by that - peer the ``MsgReadWriter`` will handle it and vice versa. - -Lets fill in the blanks and create a somewhat useful peer by allowing it -to communicate with another peer: - -.. code:: go - - const messageId = 0 // 1. - type Message string // 2. - - func msgHandler(peer *p2p.Peer, ws p2p.MsgReadWriter) error { - for { - msg, err := ws.ReadMsg() // 3. - if err != nil { // 4. - return err // if reading fails return err which will disconnect the peer. - } - - var myMessage [1]Message - err = msg.Decode(&myMessage) // 5. - if err != nil { - // handle decode error - continue - } - - switch myMessage[0] { - case "foo": - err := p2p.SendItems(ws, messageId, "bar") // 6. - if err != nil { - return err // return (and disconnect) error if writing fails. - } - default: - fmt.Println("recv:", myMessage) - } - } - - return nil - } - -1. The one and only message we know about; -2. A typed string we decode in to; -3. ``ReadMsg`` waits on the line until it receives a message, an error - or EOF. -4. In case of an error during reading it's best to return that error and - let the p2p server handle it. This usually results in a disconnect - from the peer. -5. ``msg`` contains two fields and a decoding method: - - - ``Code`` contains the message id, ``Code == messageId`` (i.e., 0) - - ``Payload`` the contents of the message. - - ``Decode()`` is a helper method for: take ``msg.Payload`` and - decodes the rest of the message in to the given interface. If it - fails it will return an error. - -6. If the message we decoded was ``foo`` respond with a ``NewMessage`` - using the ``messageId`` message identifier and respond with the - message ``bar``. The ``bar`` message would be handled in the - ``default`` case in the same switch. - -Now if we'd tie this all up we'd have a working p2p server with a -message passing sub protocol. - -.. code:: go - - package main - - import ( - "fmt" - "os" - - "github.com/ethereum/go-ethereum/crypto" - "github.com/ethereum/go-ethereum/p2p" - ) - - const messageId = 0 - - type Message string - - func MyProtocol() p2p.Protocol { - return p2p.Protocol{ - Name: "MyProtocol", - Version: 1, - Length: 1, - Run: msgHandler, - } - } - - func main() { - nodekey, _ := crypto.GenerateKey() - srv := p2p.Server{ - MaxPeers: 10, - PrivateKey: nodekey, - Name: "my node name", - ListenAddr: ":30300", - Protocols: []p2p.Protocol{MyProtocol()}, - } - - if err := srv.Start(); err != nil { - fmt.Println(err) - os.Exit(1) - } - - select {} - } - - func msgHandler(peer *p2p.Peer, ws p2p.MsgReadWriter) error { - for { - msg, err := ws.ReadMsg() - if err != nil { - return err - } - - var myMessage Message - err = msg.Decode(&myMessage) - if err != nil { - // handle decode error - continue - } - - switch myMessage { - case "foo": - err := p2p.SendItems(ws, messageId, "bar")) - if err != nil { - return err - } - default: - fmt.Println("recv:", myMessage) - } - } - - return nil - } diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Private-network.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Private-network.rst deleted file mode 100644 index 3716490..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Private-network.rst +++ /dev/null @@ -1,23 +0,0 @@ -Setting up a private network using Geth is relatively easy and -straightforward. Geth allows you to operate on multiple chains, although -not at the same time. It does so by allowing different genesis block to -be inserted in to the database. The only thing you need to do when -switching between chains is give up the path to the genesis block file -(in a later version of Geth a hash will suffice when it has previously -been imported). - -To set up and import a new genesis block please fetch an -`example `__ genesis block. You are -free to add any accounts to this block by inserting it within the -``alloc`` object: - -:: - - "alloc": { - "0xaddress": { "balance": "amount denoted in Wei" } - } - -Now start Geth with the genesis flag pointing to the genesis file -``geth --genesis /path/to/file``. This will import and set the canonical -genesis block for your chain or switches to a different previous imports -chain. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Provisional-JS-API.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Provisional-JS-API.rst deleted file mode 100644 index 4613ffb..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Provisional-JS-API.rst +++ /dev/null @@ -1,53 +0,0 @@ -The *provisional* JavaScript API is a purposed API for all things -JavaScript. JavaScript technologies can be embedded within Qt(QML) -technologies, local web and remote web and therefor the purposed API is -written in a ASYNC fashion so that it may be used across all -implementations. Hereby it should be known that all functions, unless -explicitly specified, take a callback as last function argument which -will be called when the operation has been completed. - -Please note that the provisional JavaScript API tries to leverage -existing JS idioms as much as possible. - -General API ------------ - -- ``getBlock (number or string)`` Retrieves a block by either the - address or the number. If supplied with a string it will assume - address, number otherwise. -- ``transact (sec, recipient, value, gas, gas price, data)`` Creates a - new transaction using your current key. -- ``create (sec, value, gas, gas price, init, body)`` Creates a new - contract using your current key. -- ``getKey (none)`` Retrieves your current key in hex format. -- ``getStorage (object address, storage address)`` Retrieves the - storage address of the given object. -- ``getBalance (object address)`` Retrieves the balance at the current - address -- ``watch (string [, string])`` Watches for changes on a specific - address' state object such as state root changes or value changes. -- ``disconnect (string [, string])`` Disconnects from a previous - ``watched`` address. - -Events ------- - -The provisional JavaScript API exposes certain events through a basic -eventing mechanism inspired by jQuery. - -- ``on (event)`` Subscribe to event which will be called whenever an - event of type is received. -- ``off (event)`` Unsubscribe to the given event -- ``trigger (event, data)`` Trigger event of type with the given data. - **note:** This function does not take a callback function. - -Event Types -~~~~~~~~~~~ - -All events are written in camel cased style beginning with a lowercase -letter. Subevents are denoted by a colon ``:``. - -- ``block:new`` Fired when a new valid block has been found on the - wire. The attached value of this call is a block. -- ``object:changed`` Fired when a watched address, specified through - ``watch``, changes in value. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/RLPx-----Node-Discovery-Protocol.rst b/old-docs-for-reference/go-ethereum-wiki.rst/RLPx-----Node-Discovery-Protocol.rst deleted file mode 100644 index e69de29..0000000 diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/RLPx-Encryption.rst b/old-docs-for-reference/go-ethereum-wiki.rst/RLPx-Encryption.rst deleted file mode 100644 index d62024e..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/RLPx-Encryption.rst +++ /dev/null @@ -1,324 +0,0 @@ -Establishing a connection -========================= - -This section describes how a peer session is created. - -It is assumed that the underlying trasport layer has an already -established connection between peers. A session is established in two -phases. The first phase is **peer authentication** with an encryption -handshake (or crypto handshake) and the second is the base protocol -handshake. - -The purpose of peer authentication is to establish a secure -communication channel by setting up an encrypted, authenticated message -stream. And the purpose of the encryption handshake is to exchange -ephemeral keys to set initial values for this secure session. - -The second phase is to negotiate supported protocols, checking versions -and network Ids and described in the DEVp2p wire protocol specification. - -From the point of view of one peer we will distinguish connections in -two ways. If the connection was initiated by a peer, we say that they -are the **initiator**, and the other peer is **receiver**. The word -**remote** is used to describe the 'other' peer in a connection when -talking from a point of view of a node. - -The other disinction is whether the remote peer is known or new. A known -peer is one which has previously been connected and for which a -corresponding **session token** is remembered. Session tokens are -assumed to be persisted across sessions. - -The protocol is somewhat different depending on whether the peer is -initiator or receiver on the one hand and whether the remote peer is -known or new on the other. - -Encryption handshake --------------------- - -Creating a secure connection consists of the following steps. - -1. Initiator sends an authentication message to receiver -2. Receiver responds with an authentication response message and sets up - a secure session -3. Initiator checks receiver's response and establishes a secure session -4. Receiver and Initiator then send base protocol handshake on the - established secure channel. - -Either side may disconnect if authentication fails or if the protocol -handshake isn’t appropriate. - -If the handshake fails, if and only if initiating a connection TO a -known peer, then the nodes information should be removed from the node -table and the connection MUST NOT be reattempted. Due to the limited -IPv4 space and common ISP practices, this is likely a common and normal -occurrence, therefore, no other action should occur. If a handshake -fails for a connection which is received, no action pertaining to the -node table should occur. - -All packets following the encryption handshake, including protocol -negotiation handshake in step 4, are framed, encrypted and authenticated -using the setup negotiated during the encryption handshake. - -If the handshakes succeed, the fixed array of protocols supported by -both peers will run on the connection paralelly to send and receive -messages. Once established, packets are encapsulated as frames which are -encrypted using AES-256 in CTR mode. Initial values for the message -authentication and cipher are never the same, key material for the -session is derived via a KDF and ECDHE-derived shared-secret. ECC uses -secp256k1 curve (ECP). It is the purpose of the encryption handshake to -negotiate these key values for a new secure session. - -Encryption handshake spec -------------------------- - -Initiator handshake -~~~~~~~~~~~~~~~~~~~ - -Initiator sends the following handshake. - -:: - - initiator-handshake := ECIES.Encrypt(remote-pubkey, auth) - -The initiator handshake is the authentication message ``auth`` encrypted -with the remote peer's known public key using ECIES (Elliptic Curve -Integrated Encryption System). Using AES256 in CTR mode with full MAC, -the ECIES encrypted payload will have the following structure: - -+----------+--------------+----------------------------------------------------------------------------+ -| Offset | Name | Description | -+==========+==============+============================================================================+ -| 0 | ``ecies-pubk | 65 byte representation of the pubkey needed for symmetric cipher | -| | ey`` | | -+----------+--------------+----------------------------------------------------------------------------+ -| 65 | ``AES-initia | 16 byte initial block for AES | -| | l-vector`` | | -+----------+--------------+----------------------------------------------------------------------------+ -| 81 | ``cipher-tex | ECIES ciphertext size identical to plain text (uses AES-256 CTR, blocksize | -| | t`` | 16) | -+----------+--------------+----------------------------------------------------------------------------+ -| 275 | ``ecies-mac` | ECIES message authentication code (256 bit) | -| | ` | | -+----------+--------------+----------------------------------------------------------------------------+ -| 307 | **Total** | -+----------+--------------+----------------------------------------------------------------------------+ - -This authentication message serves to prove the following: - the owner -of the private key wants a connection with the node controlling a -particular public key - that they want the connection now based on -common history - ... - -and has the following structure: - -+----------+--------------+----------------------------------------------------------------------------+ -| Offset | Name | Description | -+==========+==============+============================================================================+ -| 0 | ``signature` | ``Sign(ecdhe-random-key, shared-secret ^ init_nonce)`` | -| | ` | | -+----------+--------------+----------------------------------------------------------------------------+ -| 65 | ``ephemeral- | ``SHA3(initiator-ecdhe-random-pubkey)`` (256 bit) | -| | key-mac`` | | -+----------+--------------+----------------------------------------------------------------------------+ -| 97 | ``permanent- | NodeId public key (512 bit) | -| | public-key`` | | -+----------+--------------+----------------------------------------------------------------------------+ -| 161 | ``initiator- | a random key generated by the initiator for this session | -| | nonce`` | | -+----------+--------------+----------------------------------------------------------------------------+ -| 193 | ``known-peer | flag indicating if a token was used as shared secret, 0x00: no, 0x01: yes | -| | `` | | -+----------+--------------+----------------------------------------------------------------------------+ -| 194 | \*\*Total | -+----------+--------------+----------------------------------------------------------------------------+ - -The signature part is there to check if both parties agree on the same -shared secret. Initiator signs the shared secret with an ephemeral key -using standard ECDSA with P256 Curve. The signature length is therefore -exactly 65 bytes. - -:: - - signature := Sign(ecdhe-random-key, shared-secret ^ init_nonce) - -The shared secret is xor-ed with a random nonce to make signatures -non-reusable. Since the nonce is in the decrypted auth message and the -receiver owns and agrees on a shared secret with initiator, the message -text can be reconstructed by the receiver. Therefore the receiver is -able to verify the signature and recover initiator's ephemeral public -key using EC Recover. - -What the shared secret actually is depends on whether the remote peer is -a known peer or not. If a remote's public key is associated with a last -session token, then that token is used as shared secret. If the peer is -new, the initial shared secret is generated by ECDH based on the nodes' -public keys. - -:: - - shared-secret = session_token // for known peer - shared-secret = SSK(initiator-privkey, receiver-pubkey) // for new peers - -Where ``SSK(initiator-privkey, receiver-pubkey)`` is a symmetric shared -secret key as given by ECDH. - -Whether a token was used is indicated in the last byte (``known-peer``) -of the handshake. - -``ephemeral-key-mac`` is to authenticate the signature and is a Sha3 -hash of initiator's ephemeral public key. - -``permanent-public-key`` is used to facilitate lookup of a token, if IP -address and port is not reliable. - -``initiator-nonce`` is a 32 byte random nonce, used to derive session -key material. - -``known-peer`` is a byte indicating if a previous session token is used -(0x00 if not, 0x01 if yes), so basically signal whether the initiator -recognises the receiver as a known peer. - -Receiver handshake -~~~~~~~~~~~~~~~~~~ - -Receiver receives the initiator handshake and decrypts it with its own -public key. If the initiator indicated the use of a session token (last -byte is set to 0x01) and the receiver finds it (under -``persistent-public-key`` or otherwise), then it can recover initiator's -ephemeral public key with ECrecover by supplying the plain text which is -``shared_secret^initiator-nonce``: - -:: - - initiator-ecdhe-random-pubkey = ECRECOVER(signature, shared_secret^initiator-nonce) - -once this is done, the recipient has all information in order to set up -the secure session. See below. - -The receiver handshake is sent encrypted with the initiator's public key -using ECIES: - -:: - - receiver-handshake = ECIES.Encrypt(initiator-pubkey, receiver-handshake) - -+----------+--------------+----------------------------------------------------------------------------+ -| Offset | Name | Description | -+==========+==============+============================================================================+ -| 0 | ``ecies-pubk | 65 byte representation of the pubkey needed for symmetric cipher | -| | ey`` | | -+----------+--------------+----------------------------------------------------------------------------+ -| 65 | ``AES-initia | 16 byte initial block for AES | -| | l-vector`` | | -+----------+--------------+----------------------------------------------------------------------------+ -| 81 | ``cipher-tex | ECIES ciphertext size identical to plain text (uses AES-256 CTR, blocksize | -| | t`` | 16) | -+----------+--------------+----------------------------------------------------------------------------+ -| 178 | ``ecies-mac` | ECIES message authentication code (256 bit) | -| | ` | | -+----------+--------------+----------------------------------------------------------------------------+ -| 210 | **Total** | -+----------+--------------+----------------------------------------------------------------------------+ - -where ``receiver-handshake`` has the following structure: - -+----------------+---------+----------------------------------------------------------------------+ -| Offset | Name | Description | -+================+=========+======================================================================+ -| 0 | ``recei | newly generated ephemeral key to serve as basis for session-secret | -| | ver-ecd | | -| | he-rand | | -| | om-pubk | | -| | ey`` | | -+----------------+---------+----------------------------------------------------------------------+ -| 64 | ``recei | a randomly generated nonce | -| | ver-non | | -| | ce`` | | -+----------------+---------+----------------------------------------------------------------------+ -| 96 | ``recei | if receiver has found session token for initiator (0x00) or not | -| | ver-kno | (0x01) | -| | wn-peer | | -| | `` | | -+----------------+---------+----------------------------------------------------------------------+ -| 97 | **Total | -| | ** | -+----------------+---------+----------------------------------------------------------------------+ - -It is somewhat unclear what the expected behaviour is if initiator -submits an auth with session token, but receiver does not remember it -and responds with 0x00. Should the connection be terminated or is there -a fallback to shared secret? - -Originator needs to inspect the receiver handshake response to recover -``receiver-ecdhe-random-pubkey`` and ``receiver-nonce``. And this -completes the key exchange. - -Creating a new secure session -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Once the encryption handshake's been completed, both parties can -calculate the same initial values for encryption and authentication. - -First we need the remote ephemeral key to use it with ECDH. From the -ecdhe key we derive a shared secret. - -:: - - ecdhe-shared-secret = ecdh.agree(ecdhe-random-key, remote-ecdhe-random-pubkey) - shared-secret = sha3(ecdhe-shared-secret || sha3(receiver-nonce || initiator-nonce)) - -The session token is updated to be the sha3 hash of the new shared -secret and need to be remembered. - -:: - - token = sha3(shared-secret) - -It is unclear at exactly what point we should update this token, ie., -shall we somehow wait for the baseprotocol handshake to complete as -well? - -The other parameters are only relevant for this session: - -:: - - aes-secret = sha3(ecdhe-shared-secret || shared-secret) - mac-secret = sha3(ecdhe-shared-secret || aes-secret) - initiator-mac = sha3(mac-secret^receiver-nonce || init-auth) - receiver-mac = sha3(mac-secret^initiator-nonce || init-auth) - -Note that if any of these calculations do not match for the peers, frame -authentication will fail immediately, so the connection will be -terminated. - -Encryption and authentication -============================= - -The connection is secured by encryption and authentication. Encryption -and authentication is done frame by frame separately for headers and -payload. - -Authentication is using Keyed-Hash Message Authentication Code (HMAC -FIPS198) using SHA256. An HMAC is set up for incoming (**ingress**) and -outgoing (**egress**) traffic. - -Egress MAC is updated with the plaintext of the outgoing frame payload -and the checksum is sent appended to the frame (in cleartext). - -Ingress MAC is updated with the plaintext of the decrypted frame payload -and the checksum is verified against the MAC received appended to the -frame. If they do not match, the datastream has been tampered with, the -connection must be terminated. If they match, it proves the authenticity -of the frame since an attacker would need the entire history of this -session as well as the ephemeral keys exchanged during the handshake -even. - -For the MACs to match, we need to ensure that initiator's egress MAC is -identical to receiver's ingress MAC, and initiator's ingress MAC is -identical to receiver's egress MAC. So given the key definitions at the -end of the handshake, initiator initialises its ``egress-mac`` with -``initiator-mac`` and its ``ingress-mac`` with ``receiver-mac``, whereas -receiver initialises its ``egress-mac`` with ``receiver-mac`` and its -``ingress-mac`` with ``initiator-mac``. - -Encryption uses the AES-256 block cipher in CTR mode using -``aes-secret`` as key and initial vector ? diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/RLPx-Peer-Selection-Proposal.rst b/old-docs-for-reference/go-ethereum-wiki.rst/RLPx-Peer-Selection-Proposal.rst deleted file mode 100644 index faf2edf..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/RLPx-Peer-Selection-Proposal.rst +++ /dev/null @@ -1,33 +0,0 @@ -**This is a proposal about how we to select peers using the discovery -protocol. It is not implemented yet.** - -In this strategy the maximum number of active peers is ``N * 2``, where -``N`` is configurable and should typically be ``5 <= N <= 8``. - -Finding peers to dial ---------------------- - -The 512 bit (256 bit) space is divided into ``N`` ranges. The dialer -maintains ``N`` slots, one for each range. - -In order to find peers, it performs a node lookup with a random target -in reach range corresponding to an empty slot. The results of the lookup -are then dialed. If dialing does not succeed for any node, another -random lookup is performed in that range. Dialed addresses should be -cached for some amount of time to avoid re-dialing unreachable nodes -pointlessly. - -Handling incoming connections ------------------------------ - -Again, the 512 bit (256 bit) space is divided into ``N`` ranges. The -listener maintains ``N`` buckets, one for each range. - -For an incoming connection, after the remote identity has been verified -in the handshake, the listener should keep the new peer if the -corresponding bucket is empty or if the total number of inbound peers is -less than ``N``. - -When the number of inbound peers reaches ``N``, the new connection -replaces a random existing connection from any bucket with more than one -entry. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Running-in-Docker.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Running-in-Docker.rst deleted file mode 100644 index 58b475e..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Running-in-Docker.rst +++ /dev/null @@ -1,32 +0,0 @@ -Running in Docker -================= - -We keep a Docker image with recent snapshot builds from the ``develop`` -branch `on -DockerHub `__. Run -this first: - -.. code:: shell - - docker pull ethereum/client-go - -Start a node with: - -.. code:: shell - - docker run -it -p 30303:30303 ethereum/client-go - -To start a node that runs the JSON-RPC interface on port **8545**, run: - -.. code:: shell - - docker run -it -p 8545:8545 -p 30303:30303 ethereum/client-go --rpc --rpcaddr "0.0.0.0" - -**WARNING: This opens your container to external calls. "0.0.0.0" should -*not* be used when exposed to public networks** - -To use the interactive JavaScript console, run: - -.. code:: shell - - docker run -it -p 30303:30303 ethereum/client-go console diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Sending-ether.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Sending-ether.rst deleted file mode 100644 index 7260eb3..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Sending-ether.rst +++ /dev/null @@ -1,40 +0,0 @@ -Sending ether -============= - -The basic way of sending a simple transaction of ether using the console -is as follows: - -.. code:: JavaScript - - > eth.sendTransaction({from:sender, to:receiver, value: amount}) - -Using the built-in JavaScript, you can easily set variables to hold -these values. For example: - -.. code:: JavaScript - - > var sender = eth.accounts[0]; - > var receiver = eth.accounts[1]; - > var amount = web3.toWei(0.01, "ether") - -Alternatively, you can compose a transaction in a single line with: - -.. code:: JavaScript - - > eth.sendTransaction({from:eth.coinbase, to:eth.accounts[1], value: web3.toWei(0.05, "ether")}) - Please unlock account d1ade25ccd3d550a7eb532ac759cac7be09c2719. - Passphrase: - Account is now unlocked for this session. - '0xeeb66b211e7d9be55232ed70c2ebb1bcc5d5fd9ed01d876fac5cff45b5bf8bf4' - -The resulting transaction is -``0xeeb66b211e7d9be55232ed70c2ebb1bcc5d5fd9ed01d876fac5cff45b5bf8bf4`` - -If the password was incorrect you will instead receive an error: - -.. code:: JavaScript - - error: could not unlock sender account - -TODO: Do these console commands work in both geth and eth? What about other client commands? -TODO: Explain unlocking account or cross reference to section that highlights risks \ No newline at end of file diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Setting-up-Ethereum-(Native).rst b/old-docs-for-reference/go-ethereum-wiki.rst/Setting-up-Ethereum-(Native).rst deleted file mode 100644 index 7295763..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Setting-up-Ethereum-(Native).rst +++ /dev/null @@ -1,26 +0,0 @@ -Dream API ---------- - -i.e., something I'm envisioning for *soon*\ (tm) - -.. code:: go - - eth, err := eth.New(/*config*/) - if err != nil { - logger.Fatalln(err) - } - - // State holds accounts without matching private keys - state := eth.State() - // wallet holds accounts with matching private keys - wallet := eth.Wallet() - wallet.NewAccount() // create a new account (return Account) - wallet.Accounts() // return []Account - - acc := wallet.GetAcccount(0) // Get first account (return Account) - to := state.GetAccount(toAddr) - // Transact from the account - err := acc.Transact(to, big(100), big(10000), big(500), big(util.DefaultGasPrice), nil) - if err != nil { - logger.Fatalln(err) - } diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Setting-up-monitoring-on-local-cluster.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Setting-up-monitoring-on-local-cluster.rst deleted file mode 100644 index e24f859..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Setting-up-monitoring-on-local-cluster.rst +++ /dev/null @@ -1,91 +0,0 @@ -This page describes how to set up a monitoring site, `like this -one `__, for your private network. -It builds upon `this wiki -article `__ -and assumes you've created a local cluster using `this script -(gethcluster.sh) `__. - -The monitoring system consists of two components: - -1. **eth-netstats** - the monitoring site which lists the nodes. -2. **eth-net-intelligence-api** - these are processes that communicate - with the Ethereum client using RPC and push the data to the - monitoring site via websockets. - -Monitoring site -=============== - -Clone the repo and install dependencies: - -:: - - git clone https://github.com/cubedro/eth-netstats - cd eth-netstats - npm install - -Then choose a secret and start the app: - -:: - - WS_SECRET= npm start - -You can now access the (empty) monitoring site at -``http://localhost:3000``. - -You can also choose a different port: - -:: - - PORT= WS_SECRET= npm start - -Client-side information relays -============================== - -These processes will relay the information from each of your cluster -nodes to the monitoring site using websockets. - -Clone the repo, install dependencies and make sure you have pm2 -installed: - -:: - - git clone https://github.com/cubedro/eth-net-intelligence-api - cd eth-net-intelligence-api - npm install - sudo npm install -g pm2 - -Now, use `this script -(netstatconf.sh) `__ to create -an ``app.json`` suitable for pm2. - -Usage: - -:: - - bash netstatconf.sh - -- ``number_of_clusters`` is the number of nodes in the cluster. -- ``name_prefix`` is a prefix for the node names as will appear in the - listing. -- ``ws_server`` is the eth-netstats server. Make sure you write the - full URL, for example: http://localhost:3000. -- ``ws_secret`` is the eth-netstats secret. - -For example: - -:: - - bash netstatconf.sh 5 mynode http://localhost:3000 big-secret > app.json - -Run the script and copy the resulting ``app.json`` into the -``eth-net-intelligence-api`` directory. Afterwards, ``cd`` into -``eth-net-intelligence-api`` and run the relays using -``pm2 start app.json``. To stop the relays, you can use -``pm2 delete app.json``. - -**NOTE**: The script assumes the nodes have RPC ports 8101, 8102, ... . -If that's not the case, edit app.json and change it accordingly for each -peer. - -At this point, open ``http://localhost:3000`` and your monitoring site -should monitor all your nodes! diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Setting-up-private-network-or-local-cluster.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Setting-up-private-network-or-local-cluster.rst deleted file mode 100644 index 5bb53b4..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Setting-up-private-network-or-local-cluster.rst +++ /dev/null @@ -1,105 +0,0 @@ -This page describes how to set up a local cluster of nodes, advise how -to make it private, and how to hook up your nodes on the eth-netstat -network monitoring app. A fully controlled Ethereum network is useful as -a backend for network integration testing (core developers working on -issues related to networking/blockchain synching/message propagation, -etc or dapp developers testing multi-block and multi-user scenarios). - -We assume you are able to build ``geth`` following the `build -instructions `__ - -Setting up multiple nodes -------------------------- - -In order to run multiple Ethereum nodes locally, you have to make sure: -- each instance has a separate data directory (``--datadir``) - each -instance runs on a different port (both eth and rpc) -(``--port and --rpcport``) - in case of a cluster the instances must -know about each other - the ipc endpoint is unique or the ipc interface -is disabled (``--ipcpath or --ipcdisable``) - -You start the first node (let's make port explicit and disable ipc -interface) - -.. code:: bash - - geth --datadir="/tmp/eth/60/01" -verbosity 6 --ipcdisable --port 30301 --rpcport 8101 console 2>> /tmp/eth/60/01.log - -We started the node with the console, so that we can grab the enode url -for instance: - -:: - - > admin.nodeInfo.NodeUrl - enode://8c544b4a07da02a9ee024def6f3ba24b2747272b64e16ec5dd6b17b55992f8980b77938155169d9d33807e501729ecb42f5c0a61018898c32799ced152e9f0d7@9[::]:30301 - -``[::]`` will be parsed as localhost (``127.0.0.1``). If your nodes are -on a local network check each individual host machine and find your ip -with ``ifconfig`` (on Linux and MacOS): - -.. code:: bash - - $ ifconfig|grep netmask|awk '{print $2}' - 127.0.0.1 - 192.168.1.97 - -If your peers are not on the local network, you need to know your -external IP address (use a service) to construct the enode url. - -Now you can launch a second node with: - -.. code:: bash - - geth --datadir="/tmp/eth/60/02" --verbosity 6 --ipcdisable --port 30302 --rpcport 8102 console 2>> /tmp/eth/60/02.log - -If you want to connect this instance to the previously started node you -can add it as a peer from the console with -``admin.addPeer(enodeUrlOfFirstInstance)``. - -You can test the connection by typing in geth console: - -.. code:: javascript - - > net.listening - true - > net.peerCount - 1 - > admin.peers - ... - -Local cluster -------------- - -As an extention of the above, you can spawn a local cluster of nodes -easily. It can also be scripted including account creation which is -needed for mining. See -```gethcluster.sh`` `__ -script, and the README there for usage and examples. - -Private network ---------------- - -An Ethereum network is a private network if the nodes are not connected -to the main network nodes. In this context private only means reserved -or isolated, rather than protected or secure. Since connections between -nodes are valid only if peers have identical protocol version and -network id, you can effectively isolate your network by setting either -of these to a non default value. We recommend using the semantic -``networkid`` command line option for this. Its argument is an integer, -the main network has id 1 (the default). So if you supply your own -custom network id which is different than the main network your nodes -will not connect to other nodes and form a private network. - -Monitoring your nodes ---------------------- - -`This page `__ -describes how to use the `The Ethereum (centralised) network status -monitor (known sometimes as "eth-netstats") `__ -to monitor your nodes. - -`This -page `__ -or `this README `__ describes -how you set up your own monitoring service for a (private or public) -local cluster. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Swarm---TODO.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Swarm---TODO.rst deleted file mode 100644 index 7aa16d7..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Swarm---TODO.rst +++ /dev/null @@ -1,104 +0,0 @@ -Sprint plan -=========== - -scope -===== - -- forwarding only (no recursive lookup and no connecting to new nodes, - only working with active peers) - -TODO ----- - -- integrate new p2p -- write unit tests for protocol and netstore (without protocol) -- rework protocol errors using errs after PR merged -- integrate new p2p or develop branch after p2p merge -- integrate cademlia into hive / peer pool with new p2p -- work out timeouts and timeout encoding -- cli tools -- url bar and proxy - -CLI ---- - -- hooking into DPA local API -- running as a daemon accepting request via socket? - -Encryption ----------- - -- encryption gateway to incentivize encryption of public content -- xor encryption with random chunks -- in-memory encryption keys -- originator encryption for private content - -APIs ----- - -- Dapp API - js integration (Fabian, Alex) -- Mist dapp storage scheme, url->hash mapping (Fabian, Alex) - https://github.com/ethereum/go-ethereum/wiki/URL-Scheme - -Discuss alternatives -==================== - -I suggest we each pick 2/3 and read up on their project status, -features, usability, objectives, etc - Is it even worth it to -reinvent/reimplement the wheel? - what features do we want now and in -future - roadmap - -Brainstorming -============= - -- storage economy, incentivisation, examples: -- content owner pays - recurring ether fee for storage. -- scheme to reward content owner - each time content is accessed. i.e accessing content would requires - fee. this would reward popular content. should be optional though. -- dht - chain interaction -- proof of custody - https://docs.google.com/document/d/1F81ulKEZFPIGNEVRsx0H1gl2YRtf0mUMsX011BzSjnY/edit -- proof of resources - http://systemdocs.maidsafe.net/content/system\_components/proof\_of\_resources.html -- nonoutsourceable proofs of storage as mining criteria -- proof of storage capacity directly rewarded by contract -- streaming, hash chains -- routing and learning graph traversal -- minimizing hops -- forwarding strategies, optimizing dispersion of requests -- lifetime of requests, renewals (repeated retrieval requests), expiry, - reposting (repeated storage request) -- redundancy - store same data in multiple nodes (e.g 4x) -- the more accessed a content is, the more available it should be, - should increase performance for popular content. - -Simulations -=========== - -- full table homogeneous nodes network size vs density vs table size - expected row-sizes -- forwarding strategy vs latency vs traffic -- stable table, dropout rate vs routing optimization by precalculating - subtables for all peers. expected distance change (proximity delta) - per hop - -Swarm ------ - -How far does the analogy go? - -+--------------------------+--------------------------------------------------+ -| swarm of bees | a decentralized network of peers | -+==========================+==================================================+ -| living in a hive | form a distributed preimage archive | -+--------------------------+--------------------------------------------------+ -| where they | where they | -+--------------------------+--------------------------------------------------+ -| gather pollen | gather data chunks which they | -+--------------------------+--------------------------------------------------+ -| to produce honey | transform into a longer data stream (document) | -+--------------------------+--------------------------------------------------+ -| they consume and store | they serve and store | -+--------------------------+--------------------------------------------------+ -| buzzing bzz | using bzz as their communications protocol | -+--------------------------+--------------------------------------------------+ diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Swarm---distributed-preimage-archive.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Swarm---distributed-preimage-archive.rst deleted file mode 100644 index 29445b9..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Swarm---distributed-preimage-archive.rst +++ /dev/null @@ -1,104 +0,0 @@ -Resources -========= - -Swarm, the name ---------------- - -- https://www.facebook.com/swarmcorp, http://swarm.fund/ -- https://bitcointalk.org/index.php?topic=650143.0 -- https://bitcoinmagazine.com/17956/swarm-1-rick-falkvinges-swarmops-project/ -- http://www.amazon.co.uk/Swarmwise-Tactical-Manual-Changing-World/dp/1463533152/ - -Docs & specs ------------- - -- TODO: https://github.com/ethereum/go-ethereum/wiki/Swarm---TODO -- Dani & Viktor on public wiki: - https://github.com/ethereum/wiki/wiki/Distributed-Preimage-Archive -- Dani on swarm hash: https://github.com/ethereum/wiki/wiki/Swarm-Hash -- Dani on incentive system: - https://github.com/ethersphere/swarm/blob/master/doc/incentives.md -- The swarm smart contract: - https://github.com/ethereum/go-ethereum/wiki/Swarm-Contract -- gav on url-hint - https://github.com/ethereum/wiki/wiki/URL-Hint-Protocol -- Gav on public wiki: - https://github.com/ethereum/cpp-ethereum/wiki/Swarm -- network (DEVp2p) -- https://github.com/ethereum/go-ethereum/wiki/Peer-to-Peer -- Ethereum node discovery protocol on UDP: - https://github.com/ethereum/go-ethereum/wiki/RLPx-----Node-Discovery-Protocol -- on kademlia: - https://github.com/ethereum/wiki/wiki/Cademlia-Peer-Selection -- Multi-protocol peer selection - https://github.com/ethereum/go-ethereum/wiki/Multi-protocol-peer-selection - -Talks ------ - -- https://twitter.com/ethereumproject/status/538030376858693633 -- Dr. Daniel Nagy: Ethereum ÐΞVcon-0: Keeping the Public Record Safe - and Accessible - - https://www.youtube.com/watch?v=QzYZQ03ON2o&list=PLJqWcTqh\_zKEjpSej3ddtDOKPRGl\_7MhS&index=7&spfreload=10 - -Forum ------ - -- empty as of 01/2015: https://forum.ethereum.org/categories/swarm -- - -Mentions, discussions ---------------------- - -- http://www.reddit.com/r/ethereum/comments/2d4uyw/swarm\_and\_whisper/ -- http://www.reddit.com/r/ethereum/comments/2ityfz/ethereum\_swarm/ -- https://www.maidsafe.org/t/ethereums-swarm-p2p-storage-and-whisper-p2p-messaging/1528 -- Vitalik's blogpost of 08/2014 - - https://blog.ethereum.org/2014/08/16/secret-sharing-erasure-coding-guide-aspiring-dropbox-decentralizer/ -- Vitalik: 'Swarm is out-of-scope': - https://www.reddit.com/r/ethereum/comments/2phvml/constructive\_criticism\_of\_ethereum\_project\_not/cmwtfqq -- Vitalik on eth components, swarm at 4:00 - http://www.naation.com/2015/02/02/ethereum-explained-with-vitalik-buterin-inventor-and-leader-of-the-ethereum-project/5764/ -- https://www.youtube.com/watch?v=zgkmQ-jQJHk&feature=youtu.be - -Media ------ - -- https://twitter.com/jeffehh/status/565927366271467521 -- https://twitter.com/avsa/status/566255260713627648 -- https://twitter.com/zeligf/status/566042020909973504 -- https://www.reddit.com/r/ethereum/comments/2wryru/eli5\_how\_is\_ethereum\_supposed\_to\_be\_a\_dropbox -- https://forum.ethereum.org/discussion/comment/7593/#Comment\_7593 - -Code ----- - -- bzz PR: https://github.com/ethereum/go-ethereum/pull/255, -- repo https://github.com/ethersphere/go-ethereum/tree/bzz/ -- ethereum p2p: https://github.com/ethereum/go-ethereum/p2p -- peer selection, peer pool: - https://github.com/ethereum/go-ethereum/pull/253 -- p2p cademlia branch (discontinued): - https://github.com/ethersphere/go-ethereum/tree/kademlia -- Felix's node discovery code: - https://github.com/ethereum/go-ethereum/tree/develop/p2p/discover - -Alternatives -============ - -- storj - http://storj.io/ -- maidsafe - http://maidsafe.net/ -- ipfs - http://ipfs.io/, https://www.youtube.com/watch?v=Fa4pckodM9g, - http://static.benet.ai/t/ipfs.pdf, https://github.com/jbenet/go-ipfs, - https://www.youtube.com/watch?v=8CMxDNuuAiQ, - https://www.reddit.com/r/ethereum/comments/2wot2i/ipfs\_alpha\_demo/ -- filecoin - http://filecoin.io/ -- permacoin - https://www.cs.umd.edu/~elaine/docs/permacoin.pdf, - https://bitcointalk.org/index.php?topic=640410.0, - http://blog.dshr.org/2014/06/permacoin.html -- siacoin - http://www.siacoin.com/ -- riak - http://basho.com/riak/ -- BitTorrent http://www.bittorrent.com/ maelstrom - http://blog.bittorrent.com/2014/12/10/project-maelstrom-the-internet-we-build-next/ -- Tahoe-LAFS https://www.tahoe-lafs.org/trac/tahoe-lafs -- retroshare http://retroshare.sourceforge.net/ diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Swarm-Channels,-Namereg-resolution-draft.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Swarm-Channels,-Namereg-resolution-draft.rst deleted file mode 100644 index 6d34eeb..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Swarm-Channels,-Namereg-resolution-draft.rst +++ /dev/null @@ -1,239 +0,0 @@ -Channels and streams -==================== - -a *swarm chain* is an ordered list of content that are linked as a -forkless chain. . This is simply modeled as linked manifests. - -a *channel* is a sequence of manifests (*S*) and a relative path *P* -with a starting manifest *M* and a streamsize *n* (can be infinite). A -channel is well-formed or regular if in every manifest in the stream *P* -resolves to a consistent mime type *T* . For instance , if *T* is -``application/bzz-manifest+json``, we say the channel is a *manifest -channel*, if the mime-type is ``mpeg``, its a video channel. - -A *primary channel* is a channel that actually respect chronological -order of creation. - -A *live channel* is a primary channel that keeps updating (adding -episodes to the end of the chain) can have a (semi)-persistent mime-type -for path *P* - -A *blockstream channel* is a primary channel provable linked in time via -hashes. - -A *signed channel* is a primary channel provably linked by signatures -(sequence position index signed by the publisher) - -*Trackers* are a manifest channel which tracks updates to a primary -channel and provides forward linking . - -Example channels: ------------------ - -- name histories, e.g updates of a domain, temporal snapshots of - content -- blockchain: blockchain is a special case of blockstream -- git graph, versioning -- modeling a source of information: provable communication with hash - chain, not allowed to fork, numbered. - -content trackers -^^^^^^^^^^^^^^^^ - -reverse index of a stream - contains ``next`` links to following state - -published after next state - publish provable quality metrics: - age: -starting date of tracker vs date of orig content - neg exp -forgetting(track date vs primary date of next episode) ~ alertness, -puncuality (tracker - git version control - -every named host defines a timeline, - create a manifest stream tracking -a site - -Ways to link manifests ----------------------- - -examples -^^^^^^^^ - -.. code:: json - - { "entries": - [ - { - "host": "fefe.eth", - "number": 9067, - "previous": "ffca34987", - "next": "aefbc4569ab", - "this": "90daefaaabbc", - } - ], - "auth": "3628aeefbc7689523aebc2489", - } - -Name resolution -=============== - -The host part in a bzz webaddress should be resolved with our version of -DNS, ie. using both ``NameReg`` (name registration contract on ethereum) -and a simple mutable storage in swarm. - -signed version store --------------------- - -The point of channels -(https://github.com/ethereum/go-ethereum/wiki/Swarm---Channels ) is to -have a total order over a set of manifests. - -The typical usecase is that it should be enough to know the name of a -site or document to always see the latest version of a software or get -the current episode of your favourite series or the consensus state of a -blockchain. It should also be possible to deterministically derive the -key to future content... - -One possibility is to modify the NameReg entry in the blockchain to -point to a swarm hash. Recording each change on the blockchain results -in an implicit live channel linking. This scheme is simple inasmuch as -it puts authentication completely on the chain. However, it is expensive -and not viable given the number of publishers and typical rate of -update. - -Alternatively, swarm provides the protocol for associating a channel and -a position with a swarm hash. The versioning can be authenticated since -a message containing host name, sequence position index and swarm hash -is signed by the public key registered in ethereum NameReg for the host. - -Publishers, fans or paid bookkeepers track updates of a channel and wrap -accumulated messages into a tracker manifest. Most probably publishers -would broadcast updates of a channel manifest in the first place. - -This special key-value store can be implemented as a mutable store: the -value with a higher index will simply override the previous one. - -There can be various standards to derive lookup key deterministically -the simplest one is ``HASH(host:version)`` for a specific version and -``HASH(host)`` for the latest version. The content has the following -structure: - -:: - - sign[, , , ] - -Retrieve request for a signed version is the same as a request for a -hash. - -:: - - [RetrieveMsg, HASH(host:version), id, timeout, MUTABLE] - [RetrieveMsg, HASH(host:0), id, timeout, MUTABLE] - -Store request for a signed version is the same as for a hash: - -:: - - [StoreMsg, key, id, MUTABLE, Sign[host, version, time.Unix(), hash]] - -Format ------- - -It is up to debate how we distinguish names to be resolved. - -An early idea was to use a top level domain, such as ``.eth`` ( == -``.eth``) this might limit the possibilities - -Another idea was to have it as or part of the protocol: -``eth://my-website.home`` or ``eth+bzz://my-website.home``. This are -semantically incorrect, however. - -Third, put an *eth* inside the host somehow. - -Ad-hoc constructs like ``bzz://eth:my-website.home`` will be rejected by -host pattern matchers. - -Abusing subdomains ``bzz://eth.my-website.home`` would cause ambiguity -and potential collision. Abusing auth ``user:pass@my-website.home`` -would disable basic auth. - -A suggestion that most aligns with the *signed versioning* and very -simple is that we look up everything that is not a 32 byte hash format -for a public key. The version of the site is looked up using the port -part of the host. A specific version is given after the ``:``. - -The generic pattern then: - -:: - - (.)(:)(/) - -example 0 -~~~~~~~~~ - -:: - - bzz://breaking.bad.tv/s4/e2/video - -- *breaking.bad.tv* is looked up in NameReg to yield public key *P* -- *breaking.bad.tv* is looked up in the immutable store to yield a - message ``[_breaking.bad.tv_,0,3,aebf45fbf6ae6aaaafedcbcb467]`` -- ``aebf45fbf6ae6aaaafedcbcb467`` is looked up in swarm to yield the - manifest -- manifest entry for path ``/s4/e2/video`` results in the actual - document's root key - -example 1 -~~~~~~~~~ - -:: - - bzz://breaking.bad.tv/video - -resolves the following way: - *breaking.bad.tv* is looked up in NameReg -to yield public key *P* - *breaking.bad.tv* is looked up in the -immutable store to yield - by ``H(cookie)`` - a message -``[_breaking.bad.tv_,s5:e12,3,aebf45fbf6ae6aaaafedcbcb467]`` signed by -``P`` - ``aebf45fbf6ae6aaaafedcbcb467`` is looked up in swarm to yield -the manifest - manifest entry for path ``video`` results in the actual -document's root key - -example 2 -~~~~~~~~~ - -:: - - bzz://current.breaking.bad.tv:s4:e10/video - -- *breaking.bad.tv* is looked up in NameReg to yield public key *P* -- current.breaking.bad.tv:s4:e10 is looked up in the immutable store to - yield a message - ``[current.breaking.bad.tv,s4:e10,3,45fbf6ae6aaaafedcbcb467ccc]`` -- ``45fbf6ae6aaaafedcbcb467ccc`` is looked up in swarm to yield the - manifest -- manifest entry for path ``video`` results in the actual document's - root key - -example 3 -~~~~~~~~~ - -:: - - bzz://breaking.bad.tv/playlist - -- same as ex 2... -- manifest entry for path ``playlist`` results in a playlist manifest - -example 4 -~~~~~~~~~ - -:: - - bzz://stable.ethereum.org:8.1/download/go/mac-os - -- *stable.ethereum.org* is looked up in NameReg to yield public key *P* -- stable.ethereum.org:s4:e10 is looked up in the immutable store to - yield a message - ``[stable.ethereum.org,s4:e10,3,45fbf6ae6aaaafedcbcb467ccc]`` -- ``45fbf6ae6aaaafedcbcb467ccc`` is looked up in swarm to yield the - manifest -- manifest entry for path ``video`` results in the actual document's - root key - -Generalised content streaming, subscriptions. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Swarm-Contract.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Swarm-Contract.rst deleted file mode 100644 index 48fced8..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Swarm-Contract.rst +++ /dev/null @@ -1,77 +0,0 @@ -This one contract regulates the incentive structure of Swarm. - -The corresponding solidity code can be browsed -`here `__. - -Methods -======= - -Sign up as a node ------------------ - -Pay a deposit in Ether and register public key. Comes with an accessor -for checking that a node is signed up. - -Demand penalty for loss of chunk --------------------------------- - -Present a signed receipt by a signed up node and a deposit covering the -upload of a chunk. After a given deadline, the signer node's deposit is -taken and the presenting node's deposit refunded, unless the chunk is -presented. Comes with an accessor for checking that a given chunk has -been reported lost, so that holders of receipts by other swarm nodes can -punish them as well for losing the chunk, which, in turn, incentivizes -whoever holds the chunk to present it. - -Present chunk to avoid penalty ------------------------------- - -No penalty is paid for lost chunks, if chunk is presented within the -deadline. The cost of uploading the chunk is compensated exactly from -the demand's deposit, with the remainder refunded. Comes with an -accessor for checking that a given node is liable for penalty, so the -node is notified to present the chunk in a timely fashion. - -Price considerations -==================== - -For the price of accepting a chunk for storing, see -`Incentives `__ - -This price should be proportional to the sign-up deposit of the swarm -node. - -The deposit for compensating the swarm node for uploading the chunk into -the block chain should be substantially higher (e.g. a small integer -multiple) of the corresponding upload measured with the gas price used -to upload the demand to prevent DoS attacks. - -Termination -=========== - -Users of Swarm should be able to count on the loss of deposit as a -disincentive, so it should not be refunded before the term of Swarm -membership expires. If penalites were paid out as compensation to -holders of receipts of lost chunks, it would provide an avenue of early -exit for a Swarm member by "losing" chunks deposited by colluding users. -Since users of Swarm are interested in their information being reliably -stored, their primary incentive for keeping the receipts is to keep the -Swarm motivated, not the potential compensation. - -Receipt circulation -=================== - -End-users of Swarm keeping important information in it are obviously -interested in keeping as many receipts of it as possible available for -"litigation". The storage space required for storing a receipt is a -sizable fraction of that used for storing the information itself, so end -users can reduce their storage requirement further by storing the -receipts in Swarm as well. Doing this recursively would result in end -users only having to store a single receipt, yet being able to penalize -quite a few Swarm nodes, in case only a small part of their stored -information is lost. - -Swarm nodes that use the rest of Swarm as a backup may want to propagate -the receipts in the opposite direction of storage requests, so that the -cost of storing receipts is eventually paid by the end user either in -the form of allocated storage space or as a direct payment to Swarm. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Testing.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Testing.rst deleted file mode 100644 index af82832..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Testing.rst +++ /dev/null @@ -1,111 +0,0 @@ -Running tests on go-ethereum -============================ - -This page assumes go-ethereum has been configured according to the -`Developers -Guide `__. -All commands (unless stated otherwise) are assumed to be run from -``$GOPATH/src/github.com/ethereum/go-ethereum`` - -Unit tests ----------- - -See `Travis `__ or -`Coveralls `__ for status. - -Test the full codebase locally by changing to the repository directory -and running - -:: - - test ./... - -Integration tests ------------------ - -Integration tests for Go are included in the ``tests`` directory and can -be run with standard go testing (i.e. ``go test``). To run all the -integration tests simply run: - -:: - - go test ./tests/ - -Ethtest -~~~~~~~ - -Alternatively, there is a CLI application, ``ethtest`` who can be used -to run these tests without Go. The binary can be built from -``./cmd/ethtest`` and then run from anywhere (such as the root directory -of the test files). Some examples: - -Run all tests from current directory, looking in their respective sub -directories for json files: ``ethtest`` - -Run all VM json tests from ./VMTests/ directory -``ethtest --test "vm" --file "./VMTests/"`` - -Run all tests in a cousin directory supplied by environment variable -``ETHEREUM_TEST_PATH="../../tests/files" ethtest --test "all"`` - -Run a single transaction test -``ethtest --test "tx" --file "./TransactionTests/ttTransactionTest.json"`` - -Flags: - -:: - - --test "all" Test type (string): VMTests, TransactionTests, StateTests, BlockTests - --file "." Test file or directory. Directories are searched for .json files 1 level deep [$ETHEREUM_TEST_PATH] - --continue Continue running tests on error (true) or exit immediately (false) - -VM -^^ - -`VM Test wiki `__ - -:: - - go test ./tests/vm_test.go - -State -^^^^^ - -`State Test wiki `__ - -:: - - go test ./tests/state_test.go - -Transaction -^^^^^^^^^^^ - -`Transaction Test -wiki `__ - -:: - - go test ./tests/transaction_test.go - -Blockchain -^^^^^^^^^^ - -`Blockchain Test -wiki `__ - -:: - - go test ./tests/block_test.go - -RPC -~~~ - -`RPC Tests repo `__ - -1. Load test JSON with - - :: - - geth blocktest /BlockTests/bcRPC_API_Test.json RPC_API_Test rpc - -2. Run rpc-tests (https://github.com/ethereum/rpc-tests#usage) diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Troubleshooting.rst b/old-docs-for-reference/go-ethereum-wiki.rst/Troubleshooting.rst deleted file mode 100644 index 3b51dac..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Troubleshooting.rst +++ /dev/null @@ -1,2 +0,0 @@ -1603 sync.go:100] Synchronisation failed: peer's unknown or unhealthy -what does it mean? diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/URL-Scheme.rst b/old-docs-for-reference/go-ethereum-wiki.rst/URL-Scheme.rst deleted file mode 100644 index 138a168..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/URL-Scheme.rst +++ /dev/null @@ -1,333 +0,0 @@ -URLs in dapp browsers -===================== - -URLs should contain all allowable urls in browsers and *all* ``http(s)`` -urls that resolve in a usual browser must resolve the same way. - -All urls not conforming to the existing urls scheme must still resemble -the current urls scheme. - -:: - - :/// - -Irrespective of the main protocol, ```` should be resolved with -our version of DNS (``NameReg`` (ename registration contract on -Ethereum) and/or via swarm signed version stream. - -In the special case of the bzz protocol, ```` must resolve to a -Swarm hash of the content (in other words, the root key of the content). -This content is assumed to be of mime type -``application/bzz-sitemap+json`` the only mime-type directly handled by -Swarm. - -Swarm manifests -=============== - -A Swarm manifest is a json formatted description of url routing. The -swarm manifest allows swarm documents to act as file systems or -webservers. Their mime type is ``application/bzz-sitemap+json`` Manifest -has the following attributes: - -- ``entries``: an array of route configurations -- ``host``: eth host name registered (or to register) with NameReg -- ``number``: position index (increasing integers) of manifest within - channel, -- ``auth``: devp2p cryptohandshake public key(s), signed number -- ``first``: root key of initial state of the stream -- ``previous``: previous state of stream - -A route descriptor manifest entry json object has the following -attributes: - -- ``path``: a path relative to the url that resolved to the manifest - (*optional, with empty default*) -- ``hash``: key of the content to be looked up by swarm (*optional*) -- ``link``: relative path or external link (*optional*) -- ``contentType``: mime type of the content (*optional, - ``application/bzz-server`` by default*) -- ``status``: optional http status code to pass back to the server - (*optional, 200 by default*) -- ``cache``: cache entry, etag? and other header options (*optional*) -- ``www``: alternative old web address that the route replicates: e.g., - ``http://eth:bzz@google.com`` (*optional*) - -If ``path`` is an empty string or is missing, the path matches the -*document-root* of the dapp. If ``contentType`` is empty or missing, -manifest if assumed by default. - -(NOTE: Unclear. When no path matches and there is no fallback path e.g. -a root ``/`` path with hash specified, it should return a simple 404 -status code) - -Url resolution -============== - -Given - -:: - - bzz:/// - -in the browser, the following steps need to happen: - -- the browser sees that its bzz protocol ``/`` is passed - to the *bzz protocol handler*, -- the handler checks if ```` is a hash. If not it resolves to a - hash via NameReg and signed version table, see below -- the bzz protocol handler first retrieves the content for the hash - (with integrity check) which it interprets as a manifest file - (``application/bzz-sitemap+json``), -- this manifest file is then parsed, read and the json array element - with the longest prefix ``p`` of ```` is looked up. I.e., ``p`` - is the longest prefix such that `` == p'/p''``. (If the longest - prefix is 0 length, the row with `` == ""`` (or left out) is - chosen.) -- as a special case, trailing forward slashes are ignored so all - variants will match the directory, -- the protocol then looks up content for ``p'`` and serves it to the - browser together with the status code and content type. -- if content is of type manifest, bzz retrieves it and repeats the - steps using ``p''`` to match the manifest's ```` values - against, -- the url relative path is set to ``p''`` -- if the url looked up is an old-world http site, then a standard http - client call is sufficient. - -Example 1 -~~~~~~~~~ - -.. code:: js - - { - entries: [ - { - "path": "cv.pdf", - "contentType": "document/pdf", - "hash": "sdfhsd76ftsd86ft76sdgf78h7tg", - } - ] - } - -where the hash is the hash of the actual file ``cv.pdf``. - -If this manifest hashes to ``dafghjfgsdgfjfgsdjfgsd``, then -``bzz://dafghjfgsdgfjfgsdjfgsd/cv.pdf`` will serve ``cv.pdf`` - -Now you can register the manifest hash with NameReg to resolve -``my-website`` the file as follows: - -:: - - http://my-website/cv.pdf - -serves ``cv.pdf`` - -Example 2 -~~~~~~~~~ - -| Imagine you have a dapp called *chat* and host it under -| your local directory ```` looks like this: - -:: - - index.html - img/logo.gif - img/avatars/fefe.jpg - img/avatars/index.html - -the webserver has the following routing rules: - -:: - - -> /index.html - -> /index.html # where != index.html - img/logo.gif -> /img/logo.gif - img/avatars -> img/avatars/index.html - img/avatars/fefe.jpg -> /img/avatars/fefe.jpg - img/avatars/.jpg /img/avatars/index.html # where != fefe.jpg - -Now you can alternatively host your app in Swarm by creating the -following manifest: - -.. code:: js - - { - "entries": [ - { "hash": HASH(/index.html) }, - { "path": "index.html", "hash": HASH(/index.html) }, - { "path": "img/logo.gif", "hash": HASH(/img/logo.gif) }, - { "path": "img/avatars/", "hash": HASH(/img/avatars/index.html) }, - { "path": "img/avatars/fefe.jpg", "hash": HASH(img/avatars/fefe.jpg) } - ] - } - -Swarm webservers -================ - -Swarm webservers are simply bzz site manifest files routing relative -paths to static assets. Manifest route entries specify metadata: http -header values, etag, redirects, links, etc. - -In a typical scenario, the developer has a website within a working copy -directory on their dev environment and they want to create a -decentralised version of their site. - -They then register the host domain with ethereum NameReg or swarm signed -version stream, upload all desired static assets to swarm, and produce a -site manifest. - -In order to facilitate the creation of the manifest file for existing -web projects, a native API and a command line utility are provided to -automatically generate manifest files from a directory. - -ArcHive API ------------ - -A native API and a command line utility are provided to automatically -swarmify document collections. constructor parameters: - -- ``template``: manifest template: the entries found in the directory - scan are merged into this template to yield the resulting site-map. - Note that this template can be considered a config file to the - archiver. - -The archiver can be called multiple times scanning multiple directories. - -runtime parameters: - ``path``: path to directory relative routes in the -template matched against directory paths under ``path`` (*optional*, '.' -by default). - ``not-found``: errorchange to be used when asset is not -found: for 404, (*optional*, ``index.html``) - ``register-names`` use -eth NameReg to register public key and this version is pushed to swarm -mutable store (*optional*, *false*) - ``without-scan`` only consider -paths given in template (*optional*, by default *false*: in template, -scan directory and add/merge all readable content to manifest) - -``without-upload``: files are not uploaded, only hashes are calculated -and manifest is created (*optional*, *false*, upload every asset to -swarm) - -If both ``without-scan`` and ``without-upload`` are omitted then -``path`` is used to associate files, extend the manifest entries, and -upload content. - -if ``register-names`` is set all named nodes. - -Examples -~~~~~~~~ - -.. code:: js - - { - "entries": [ - { - "path": "chat", - "hash": "sdfhsd76ftsd86ft76sdgf78h7tg", - "status": 200, - "contentType": "document/pdf" - }, - ... - ] - } - -Without swarm, the zip fallback -------------------------------- - -namereg resolution: - -``contentOf('eth/wallet') -> 324234kj23h4kj2h3kj423kj4h23`` - -This name reg has also a ``urlOf`` where it can find the file (e.g. from -a raw pastebin) - -It then downloads the file, extracts it and resolves all -relative/absolute paths, based on the manifest it finds in it. - -For the developer, the upload mechanism in mix will be the same, as he -chooses a folder and can provide a ``serverconfig.json`` (or manfiest) - -The only difference is the lookup and where it gets the files from. - -:: - - swarm -> content hashes - before swarm -> zip file content - -And both are resolved through the same manifest scheme - -Server config examples: ------------------------ - -URL: bzz://dsf32f3cdsfsd/somefolder/other Same as: -eth://myname.reggae/somefolder/other - -We should also map folder with and without "/" so that the path lookup -for path: "/something/myfolder" is the same as "/something/myfolder/" - -.. code:: js - - { - previous: 'jgjgj67576576576567ytjy', - first: 'ds564rh5656hhfghfg', - entries:[{ - // Custom error page - path: '/i18n/', - file: '/errorpages/404.html', - // parses "file" when processing the folder and add: hash: '7685trgdrreewr34f34', contentType: 'text/html' - status: 404 - - },{ - // custom fallback file for this folder: "/images/sdffsdfds/" - path: '/images/sdffsdfds/', - file: '/index.html', - // parses "file" when processing the folder and add: hash: '345678678678678678tryrty', contentType: 'text/html' - - },{ - // custom fallback file with custom header. - path: '/', - file: '/index.html', - // parses "file" when processing the folder and add: hash: '434534534f34k234234hrkj34hkjrh34', contentType: 'text/html' - status: 500 - - },{ - // redirect (changing url after?) - path: '/somefolder/', - redirect: 'http://google.com' - - },{ - // linking? - path: '/somefolder/other/', - link: 'bzz://43greg45gerg5t45gerge/chat/' // hash to another manifest - - },{ - // downloading a file by pointing to a folder - path: '/somefolder/other/', - file: '/mybook.pdf', - // parses "file" when processing the folder and add: hash: '645325ytrhfgdge4tgre43f34', BUT no contentType, as its already present - contentType: 'application/octet-stream' // trigger a download in the browser for this link) - - },{ - // downloading - path: '/test.html', - file: '/test.html', - // parses "file" when processing the folder and add: hash: '645325ytrhfgdge4tgre43f34', BUT no contentType, as its already present - contentType: 'application/octet-stream' // trigger a download in the browser for this link) - - // automatic generated files - },{ - path: '/i18n/app.en.json', - hash: '456yrtgfds43534t45', - contentType: 'text/json', - },{ - path: '/somefolder/other/image.png', - hash: '434534534f34khrkj34hkjrh34', - contentType: 'image/png', - },{ - path: '/somefolder/other/343242.png', - hash: '434534534f34k234234hrkj34hkjrh34', - contentType: 'image/png', - },{ - path: '/somefold/frau.png', - hash: 'sdfsdfsdfsdfsdfsdfsd', - contentType: 'image/png', - }] - } diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/Wire-protocol-Extended-(Child-processes).rst b/old-docs-for-reference/go-ethereum-wiki.rst/Wire-protocol-Extended-(Child-processes).rst deleted file mode 100644 index 9a802be..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/Wire-protocol-Extended-(Child-processes).rst +++ /dev/null @@ -1,22 +0,0 @@ -Ethereum Child processes allow any node to connect to an existing node -and share it's parent process to handle all network communication and -data persisting. This will allow for multiple Ethereum light nodes on -the same host with full access to the block chain through the parent -process. - -Message Type -~~~~~~~~~~~~ - -Intercom messages range from 0x30 - X all messages are specified as - -Get block -^^^^^^^^^ - -- ``[0x30, [block hash]]`` -- Retrieve the block by hash or empty if block couldn't be found - -Block -^^^^^ - -- ``[0x31, [block]]`` -- Returns the given block as a reply on ``get block``. diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/XEth.rst b/old-docs-for-reference/go-ethereum-wiki.rst/XEth.rst deleted file mode 100644 index 1bfa6ca..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/XEth.rst +++ /dev/null @@ -1,137 +0,0 @@ -eXtended Ethereum API -===================== - -***NOTE:** This documentation is out-of-date and in need of refresh -against current codebase* - -General, easy to use, Ethereum query interface. This API allows you to -easily interface with Ethereum's state and their respective objects, -create transactions and directly evaluate contract code. - -.. code:: go - - import "github.com/ethereum/go-ethereum/xeth" - -Be aware that all methods return something. Nil isn't ever returned -unless explicitly specified. - -Objects -~~~~~~~ - -- ``XEth``: Top level query interface -- ``World``: world object through which you can query Ethereum's state - and objects. -- ``Config``: config object through which you can query the ``Config`` - contract if available. -- ``Object``: object which functions as a proxy for ``StateObject``. - Returned by ``config`` - -Functions -~~~~~~~~~ - -- ``New(ethchain.EthManager) *XEth``: instantiate a new ethpipe object. - -``XEth`` Methods -~~~~~~~~~~~~~~~~ - -- ``World() *world``: returns the world object through which you can - query Ethereum's state. -- ``Balance(address []byte) *Value``: returns the balance of the given - ``address``. -- ``Exists(address []byte) bool``: returns whether an object with the - given ``address`` exists. -- ``Nonce(address []byte) *uint64``: returns the the nonce of the given - ``address``. -- ``Block(hash []byte) *Block``: returns the given block by ``hash``. -- ``Storage(address, storage []byte) *Value``: returns the given object - by ``address``'s value given by the ``storage`` address. -- ``ToAddress(privateKey []byte) []byte``: converts a private key to an - Ethereum address. -- ``Execute(address, data []byte, value, gas, price *Value) []byte``: - Simulates an evaluation of the object's code given by the ``address`` - and returns the outcome. -- ``ExecuteObject(object *Object, data []byte, value, gas, price *Value) []byte``: - Similar to the above only takes an actual ``StateObject`` instead of - an address. -- ``Transact(key *KeyPair, address []byte, value, gas, price *Value, data []byte) ([]byte, error)``: - creates a new transaction using the given ``key``. - -``World`` Methods -~~~~~~~~~~~~~~~~~ - -- ``State() *State``: returns the current state of the Ethereum - ``world`` object. -- ``Get(addres []byte) *StateObject``: returns the object given by the - ``address``. Returns ``nil`` if no object associated with the - ``address`` can be found. -- ``Config() *config`` -- ``IsListening() bool``: returns whether the client is listening for - connections. -- ``IsMining() bool``: returns whether the client is mining. -- ``Peers() *list.List``: returns the current connected peers. -- ``Coinbase() *StateObject``: TODO - -``Config`` Methods -~~~~~~~~~~~~~~~~~~ - -- ``Get(name string) object``: returns the associated object given by - the ``name``. -- ``Exist() bool``: returns whether the config object exist in - Ethereum's present state. - -``Object`` Methods -~~~~~~~~~~~~~~~~~~ - -- ``StorageString(str string) *Value``: returns the storage value given - by the key as ``str`` (Note, right pads zero to length of 32). -- ``Storage(addr []byte)``: return the storage value given by the key - as ``address``. - -Example -------- - -.. code:: go - - import "github.com/ethereum/go-ethereum/xeth" - - xeth := xeth.New(ethereum) - - var addr, privy, recp, data []byte - var object *ethstate.StateObject - var key *ethcrypto.KeyPair - - world := xeth.World() - world.Get(addr) - world.Coinbase() - world.IsMining() - world.IsListening() - world.State() - peers := world.Peers() - peers.Len() - - // Shortcut functions - xeth.Balance(addr) - xeth.Nonce(addr) - xeth.Block(addr) - xeth.Storage(addr, addr) - xeth.ToAddress(privy) - // Doesn't change state - xeth.Execute(addr, nil, Val(0), Val(1000000), Val(10)) - // Doesn't change state - xeth.ExecuteObject(object, nil, Val(0), Val(1000000), Val(10)) - - conf := world.Config() - namereg := conf.Get("NameReg") - namereg.Storage(addr) - - var err error - // Transact - tx_hash, err = xeth.Transact(key, recp, ethutil.NewValue(0), ethutil.NewValue(0), ethutil.NewValue(0), nil) - if err != nil { - t.Error(err) - } - // Create - contract_addr, err = xeth.Transact(key, nil, ethutil.NewValue(0), ethutil.NewValue(0), ethutil.NewValue(0), data) - if err != nil { - t.Error(err) - } diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/_Footer.rst b/old-docs-for-reference/go-ethereum-wiki.rst/_Footer.rst deleted file mode 100644 index 72f726f..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/_Footer.rst +++ /dev/null @@ -1 +0,0 @@ -``golang <3`` diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/_Sidebar.rst b/old-docs-for-reference/go-ethereum-wiki.rst/_Sidebar.rst deleted file mode 100644 index c4b01f1..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/_Sidebar.rst +++ /dev/null @@ -1,59 +0,0 @@ -`Main Ethereum Wiki `__ - -`Frontier -Release `__ - -Install and build -~~~~~~~~~~~~~~~~~ - -`Installing -Ethereum `__ - -`Developers' -Guide `__ - -Usage -~~~~~ - -`Managing -Accounts `__ - -`Mining `__ - -`Contracts and -transactions `__ - -`Contract -Tutorial `__ - -Interface Documentation -~~~~~~~~~~~~~~~~~~~~~~~ - -`Command Line -Options `__ - -`JavaScript -Console `__ - -`Management -API `__ - -`JSON-RPC server `__ - -Issues -~~~~~~ - -`Troubleshooting `__ - -`FAQ `__ - -`Reporting -issues `__ - -`Community and -support `__ - -Legacy -~~~~~~ - -`Legacy pages `__ diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/bitchin-tricks.rst b/old-docs-for-reference/go-ethereum-wiki.rst/bitchin-tricks.rst deleted file mode 100644 index 8034ac8..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/bitchin-tricks.rst +++ /dev/null @@ -1,60 +0,0 @@ -Bitchin' tricks -=============== - -Geth -~~~~ - -General -^^^^^^^ - -- My [STRIKEOUT:shit] client doesn't work! :fu: - -:: - - git pull - -Mining -^^^^^^ - -- I only want to mine when there are transactions! - -.. code:: javascript - - var mining_threads = 1 - - function checkWork() { - if (eth.getBlock("pending").transactions.length > 0) { - if (eth.mining) return; - console.log("== Pending transactions! Mining..."); - miner.start(mining_threads); - } else { - miner.stop(0); // This param means nothing - console.log("== No transactions! Mining stopped."); - } - } - - eth.filter("latest", function(err, block) { checkWork(); }); - eth.filter("pending", function(err, block) { checkWork(); }); - - checkWork(); - -Curtesy @chfast - -Quick scripts -^^^^^^^^^^^^^ - -- I want to get some data out without running a node! - -:: - - $ geth --exec "eth.accounts" console 2>/dev/null - - ["0x0000000000000000000000000000000000000000"] - -- I want to get some data out without RPC magic! - -:: - - $ geth --exec "eth.accounts" attach - - ["0x0000000000000000000000000000000000000000"] diff --git a/old-docs-for-reference/go-ethereum-wiki.rst/iceCREAM-(debugger).rst b/old-docs-for-reference/go-ethereum-wiki.rst/iceCREAM-(debugger).rst deleted file mode 100644 index cb231d2..0000000 --- a/old-docs-for-reference/go-ethereum-wiki.rst/iceCREAM-(debugger).rst +++ /dev/null @@ -1,37 +0,0 @@ -**UPDATE** IceCream has been removed as of 0.9.0 in favour of more -advanced other tools. - -Go Ethereum comes with a handy EVM debugger called iceCREAM (after the -famous 'SoftICE' kernel debugger). This article will give you a basic -understanding of debugging EVM code and operating the iceCREAM debugger. - -.. figure:: https://photos-5.dropbox.com/t/0/AACUFqkxJZxCr0S_K-65D8lBwFcD9g2fXj0EM6VK8cosTA/12/4270001/png/1024x768/3/1404478800/0/2/Screenshot%202014-07-04%2013.46.16.png/b0UNfgLTmovpciCPHQwXjDKVM2NEUGG4bUuKDhC3jSk - :alt: - -The interface of the debugger is pretty straight forward and can be -accessed from within -`Ethereal `__ menu (⌘-D) - -- In the centre of the window you'll find the main editor which support - `mutan `__ and `serpent <>`__. -- On the left side you'll find the disassembled instruction sequence. -- Right top corner are pre-made snippets -- Right side you'll find the simulated data field, endowment, amount of - gas & gas price. -- Temp is the VM stack -- Memory is the current in-use memory. Each item is one word (32 bytes) -- Storage inspector -- Debugger CLI -- Debugger log - -The debugger supports ``break`` points on an instruction level (so don't -try to use line numbers). Adding a breakpoint through the debugger CLI -(⌘-L) can be done with ``break ``. When the EVM encounters -a breakpoint it will halt the execution and displays the current state -of the VM such as the current memory, storage and stack, and allows you -to step through the following instructions using the ``next`` button -(⌘-N). - -The debugger supports the following shortcut keys: - ⌘-L Debugger CLI - -⌘-R Debug run - ⌘-N Next sequence (during break) - ⌘-G Continue (during -break) - ⌘-1 Focus editor - ⌘-2 Focus data diff --git a/old-docs-for-reference/main-wiki.rst/Adaptive-Message-IDs.rst b/old-docs-for-reference/main-wiki.rst/Adaptive-Message-IDs.rst deleted file mode 100644 index f1c6909..0000000 --- a/old-docs-for-reference/main-wiki.rst/Adaptive-Message-IDs.rst +++ /dev/null @@ -1,87 +0,0 @@ -Goal -~~~~ - -Dynamic numeric identities for the sub protocol message types rather -than the current fixed id system. This way we don't have to reserve -parts of the message ID space up front and have a central entity to -police this space to prevent clashes. - -Overview -~~~~~~~~ - -All sub-protocol message IDs begin at 0x10 and count only those messages -in the shared protocols, in alphabetical order. Sub-protocol versioning -is provided in the base protocol to allow guarantees that there is -consensus over the number and order of messages for each sub-protocol -between peers. - -Needed Changes -~~~~~~~~~~~~~~ - -Wire protocol Hello package changed to (*note protocol version has -changed to 1*): - -**Hello** [``0x00``: ``P``, ``p2pVersion``: ``P``, ``clientId``: ``B``, -[[``cap1``: ``B_3``, ``capVersion1``: ``P``], [``cap2``: ``B_3``, -``capVersion2``: ``P``], ...], ``listenPort``: ``P``, ``nodeId``: -``B_64``] First packet sent over the connection, and sent once by both -sides. No other messages may be sent until a Hello is received. \* -``p2pVersion`` Specifies the implemented version of the P2P protocol. -Now must be 1. \* ``clientId`` Specifies the client software identity, -as a human-readable string (e.g. "Ethereum(++)/1.0.0"). \* ``cap`` -Specifies a peer capability name as a length-3 ASCII string. Current -supported capabilities are ``eth``, ``shh``. \* ``capVersion`` Specifies -a peer capability version as a positive integer. Current supported -versions are 35 for ``eth``, and 2 for ``shh``. \* ``listenPort`` -specifies the port that the client is listening on (on the interface -that the present connection traverses). If 0 it indicates the client is -not listening. \* ``nodeId`` is the Unique Identity of the node and -specifies a 512-bit hash that identifies this node. - -All ``eth`` sub-protocol message ids are lowered by ``0x10`` and have a -``+`` prepended to them to denote that the given ID is offset by some -dynamic amount. - -Conversation overview -~~~~~~~~~~~~~~~~~~~~~ - -:: - - [23:11:29] gavofyork: for each shared sub protocol, in alphabetic order, you deploy the subprotocol's messages - [23:11:40] gavofyork: (after the basic p2p messages) - [23:12:42] gavofyork: so for two whisper-only peers, defined message types are Hello = 0x00, Disconnect, Ping, Pong, GetPeers, Peers = 0x05, WhisperMessage1 = 0x06, ... - [23:13:50] gavofyork: but for two peers that have eth and shh, you'd get: Hello = 0x00, Disconnect, Ping, Pong, GetPeers, Peers = 0x05, Status = 0x06, GetTransactions = 0x07, Transactions = 0x08, GetBlockHashes = 0x09, BlockHashes = 0x0a, GetBlocks = 0x0b, Blocks = 0x0c, NewBlock = 0x0d, WhisperMessage1 = 0x0e, ... - [23:14:28] Jeffrey Wilcke: so what you mean is that you negotiate which message type gets what number - [23:14:34] gavofyork: exactamundo - [23:14:45] Jeffrey Wilcke: right interesting - [23:15:12] gavofyork: no arguing over what protocol gets what message-id space - [23:15:25] gavofyork: avoids any central registry or anything - [23:15:33] Jeffrey Wilcke: so receiving and sending might be completely different "numbers" but have the same meaning - [23:15:40] gavofyork: yup - [23:15:56] gavofyork: will make wire protocol analysis slightly harder - [23:16:02] gavofyork: though that's not necessarily a bad thing - [23:16:33] Jeffrey Wilcke: Ok so you tell a node that GetBlockHahses = 0x09 - [23:17:37] Jeffrey Wilcke: GetBlockHashes internally is say 0x03. We give it an array with [0x03, 0x09] meaning "map GetBlockHashes to 0x09" or "when you receive 0x09 I mean GetBlockHashes". - [23:18:12] gavofyork: don't even need to do that - [23:18:21] gavofyork: so we'll need a map internally - [23:18:28] gavofyork: but there's no need to ever serialise it - [23:18:46] Jeffrey Wilcke: No, well you have to let the other know how you understand messages - [23:18:54] Jeffrey Wilcke: meaning that get hashes = 9 - [23:19:01] gavofyork: "for each shared sub protocol, in alphabetic order, you deploy the subprotocol's messages" - [23:19:22] gavofyork: both form natural consensus on the alphabetic order of the shared subprotocols - [23:19:28] gavofyork: just from both Hello packets - [23:20:03] gavofyork: the one thing we should bring in is subprotocol versioning - [23:20:33] Jeffrey Wilcke: but how do we negotiate over the numbering? - [23:20:43] gavofyork: that is the negotiation :) - [23:21:04] gavofyork: you know the exact message type set & order in each subprotocol - [23:21:14] gavofyork: and you know the order they should be counted in - [23:21:26] gavofyork: and you know where to count from - [23:21:28] Jeffrey Wilcke: of course, but how do negotiate over the subprotocol - [23:21:33] gavofyork: oh - [23:21:36] gavofyork: that's in the Hello packet - [23:21:45] gavofyork: that contains the supported subprotocols - [23:21:52] gavofyork: e.g. A <=> B: - [23:21:53] Jeffrey Wilcke: aaah i follow - [23:21:56] gavofyork: ok - [23:22:11] Jeffrey Wilcke: right ok. i thought you meant alphabetical in the _messages_ - [23:22:19] Jeffrey Wilcke: ok makes sense diff --git a/old-docs-for-reference/main-wiki.rst/Adaptive-Peer-Time.rst b/old-docs-for-reference/main-wiki.rst/Adaptive-Peer-Time.rst deleted file mode 100644 index f13d666..0000000 --- a/old-docs-for-reference/main-wiki.rst/Adaptive-Peer-Time.rst +++ /dev/null @@ -1,31 +0,0 @@ -Goals -~~~~~ - -At present, a single mining peer with its clock substantially (> 25% of -the expected block time) ahead of the other peers will cause problems on -the network. Forks are common as peers are inconsistently forced to -ignore the future blocks. - -A system with multiple peers should be robust to a few peers having -substantially fast clocks. - -Basic Overview -~~~~~~~~~~~~~~ - -Each peer does a ping-sequence, each message timestamped with the -hardware clock (H) directly after handshake to determine both the -network traversal distance ("ping time") and an estimate of the peer's -hardware clock (Hp). - -The clock-offset (D) of the peer then becomes it's hardware clock (H) -corrected to become the median of the peer hardware clocks (median({H1, -H2, ...}) = M). - -The clock offset (D) is dynamically evaluated as the peer set changes. - -Required Changes -~~~~~~~~~~~~~~~~ - -Protocol changes: \* Ping & Pong packets include a timestamp. - -Rest to be implemented lazily. diff --git a/old-docs-for-reference/main-wiki.rst/Bad-Block-Reporting.rst b/old-docs-for-reference/main-wiki.rst/Bad-Block-Reporting.rst deleted file mode 100644 index b6a4c00..0000000 --- a/old-docs-for-reference/main-wiki.rst/Bad-Block-Reporting.rst +++ /dev/null @@ -1,178 +0,0 @@ -Send a JSONRPC request to ``https://badblocks.ethdev.com``: - -Call ``eth_badBlock(BADBLOCK)``, with ``BADBLOCK`` the object described -below: - -BADBLOCK Object Format ----------------------- - -NOTE: All hex is lower-case. - -Types -^^^^^ - -- ``DATA``: freeform byte array as a string of hex, *no 0x prefix*. -- ``DATA_20``: like DATA, always of length 40. -- ``HEX``: string of hex-encoded big-endian integer, used for VM - stack/memory/storage items, *no 0x prefix*, *no leading zeroes*. -- ``INT``: simple JS integer. -- ``BIGINT``: string of decimal-encoded integer, used for potentially - bigints. -- ``TAG_ERROR``: described later. -- ``TAG_INST``: string of an EVM instruction mnemonic, uppercase e.g. - ``"PUSH4"`` or ``"STOP"``. -- ``VMTRACE``: described later. - -Type modifiers -^^^^^^^^^^^^^^ - -- ``SOMETIMES``: field is omitted under certain circumstances. -- ``NONSTANDARD``: field may safely be omitted. - -BADBLOCKS object -^^^^^^^^^^^^^^^^ - -.. code:: json - - { - "block": DATA - "errortype": TAG_ERROR - "hints": { (all items OPTIONAL) - "receipts": [ DATA, ... ], OPTIONAL - "vmtrace": VMTRACE, OPTIONAL - }, OPTIONAL - } - -Where: - -``receipts`` is simply the array of RLP-encoded receipts. - -``TAG_ERROR`` is a string containing one of (specified roughly in order -of ability to detect): - -Generic: -^^^^^^^^ - -- ``RLPError``: One of the following: -- ``BadRLP``: Generally invalid RLP (e.g. 0x8100). -- ``BadCast``: Given RLP is of an incorrect type (e.g. 0x00 being - interpreted as an integer). -- ``OversizeRLP``: Additional bytes trailing an otherwise valid RLP - fragment (e.g. 0x8000). -- ``UndersizeRLP``: Bytes missing from the end of an otherwise valid - RLP fragment (e.g. 0x81). - -Block-specific: -^^^^^^^^^^^^^^^ - -- ``InvalidBlock``: One of the following: -- ``InvalidBlockFormat``: Block format is wrong (!= array, != 3 items - &c.). -- ``TooManyUncles``: More than 2 uncles mentioned. -- ``InvalidTransactionsRoot``: Transactions root is different to that - derived from transactions given in block. -- ``InvalidUnclesHash``: Uncles hash is different to that derived from - uncles given in block. -- ``InvalidGasUsed``: Gas used is not equal to the gasUsed in the last - receipt (or previous block if no transactions). -- ``InvalidStateRoot``: State root mentioned is different to that - calculated (i.e. reward application is incorrect). -- ``InvalidReceiptsRoot``: Receipts root mentioned is different to that - calculated (i.e. appliaction of a transaction resulted in different - logs, gas-used or state-root). "receipts" and "vmtrace" should be - hinted. - -Block-header-specific -^^^^^^^^^^^^^^^^^^^^^ - -- ``InvalidHeader``: One of the following: -- ``InvalidBlockHeaderItemCount``: Wrong item count in header. -- ``TooMuchGasUsed``: Header states gas used as bigger than gas limit. -- ``ExtraDataTooBig``: Header's extra data is greater than limit. -- ``InvalidDifficulty``: Difficulty is incorrect given previous block's - difficulty and timestamp. -- ``InvalidGasLimit``: Gas limit does not fall within bounds given - previous block's gas limit. -- ``InvalidBlockNonce``: Nonce does not result in a proof of work which - satisfies the given difficulty. -- ``InvalidNumber``: Number is not equal to parent number + 1. -- ``InvalidTimestamp``: Timestamp is not greater than parent's. -- ``InvalidLogBloom``: LogBloom is not equal to the bitwise-OR of all - receipts' LogBlooms. - -Transaction-specific -^^^^^^^^^^^^^^^^^^^^ - -- ``InvalidTransaction``: One of the following: -- ``OutOfGasIntrinsic``: GAS below amount required for any transaction. -- ``BlockGasLimitReached``: Too much gas being used for the transaction - within this block. -- ``InvalidSignature``: Transaction's signature is invalid. -- ``OutOfGasBase``: GAS below amount required for this transaction. -- ``NotEnoughCash``: Balance of sender too low. -- ``InvalidNonce``: Transaction nonce is wrong. - -Uncle-specific -^^^^^^^^^^^^^^ - -- ``InvalidUncle``: One of the following: -- ``UncleInChain``: Uncle has already been included in the current - chain (either as a direct ancestor or one of its included uncles). -- ``UncleTooOld``: Uncle is older than the 6th generation uncle. -- ``UncleIsBrother``: Uncle is newer than the 1st generation uncle. - -and ``VMTRACE`` is the object: - -.. code:: json - - [ - { - "stack": [ HEX, ... ] - "memory": HEX, SOMETIMES - "sha3memory": DATA_32, SOMETIMES - "storage": { HEX: HEX }, SOMETIMES - "gas": BIGINT - "pc": BIGINT - "inst": INT - "depth": INT, OPTIONAL - "steps": INT - "address": DATA_20, SOMETIMES - "memexpand": BIGINT, NONSTANDARD - "gascost": BIGINT, NONSTANDARD - "instname": STRING, NONSTANDARD - }, - ... - ] - -- ``stack``: The stack, prior to execution. -- ``memory``: The memory, prior to execution. Omitted when previous - operation was not memory-dependent - (MLOAD/MSTORE/MSTORE8/SHA3/CALL/CALLCODE/CREATE/CALLDATACOPY/CODECOPY/EXTCODECOPY), - not first operation of CALL/CREATE context or when memory >= 1024 - bytes large. -- ``sha3memory``: The Keccak hash of the memory, prior to execution. - Omitted when previous operation was not memory-dependent - (MLOAD/MSTORE/MSTORE8/SHA3/CALL/CALLCODE/CREATE/CALLDATACOPY/CODECOPY/EXTCODECOPY), - not first operation of CALL/CREATE context or when memory < 1024 - bytes large. -- ``storage``: The contents of storage that SSTOREs operate on (RE-READ - THAT!), prior to execution. Omitted when previous operation is not - storage-dependent (SLOAD/SSTORE) and not first operation of - CALL/CREATE context. -- ``gas``: The amount of gas available prior to this instruction. -- ``pc``: The program counter, immediately prior to execution. -- ``inst``: The instruction opcode index that is to be executed (e.g. - STOP would be 0). -- ``depth``: The depth of in present context in CALL/CREATE stack. - Omitted when no change since previous operation and not first - operation of CALL/CREATE context. -- ``steps``: The number of steps taken so far in present CALL/CREATE - context prior to executing the current instruction. -- ``address``: The address of account that would be returned by - ``MYADDRESS`` opcode. Omitted when no change since previous operation - and not first operation of CALL/CREATE context. -- ``memexpand``: The size that memory is to be expanded by in words for - this operation. Omitted when zero. -- ``gascost``: The total cost of gas for executing this instruction - (technically the /maximum/ total cost of gas - CALL/CREATE may return - gas). diff --git a/old-docs-for-reference/main-wiki.rst/Bad-Chain-Canary.rst b/old-docs-for-reference/main-wiki.rst/Bad-Chain-Canary.rst deleted file mode 100644 index 0be0065..0000000 --- a/old-docs-for-reference/main-wiki.rst/Bad-Chain-Canary.rst +++ /dev/null @@ -1,24 +0,0 @@ -There will be a canary contract to notify that a given chain is bad. -It's very easy to use; check storage location 0 of contract at the given -address (see below). If non-zero, client should not mine (at least -without a non-default option being given to ignore the canary and mine -on a known-bad chain). - -Specifically there are three modes it can be in: - -- ``0`` All fine. Carry on. -- ``1`` Bad chain. Client should not mine on it. Client upgrade not yet - available. -- ``2`` Update required. Just as for ``1``; additionally, an update to - your client is available and would be prudent. - -Clients implementing this protocol should display a message to the user -to make any non-zero status clear. For a status of 2, the user should be -notified than an immediate upgrade is required, regardless of whether -mining is enabled. - -Addresses -^^^^^^^^^ - -- For Olympic: ``0x6879392ee114f8a4e133f0ff3dc4bc1717fe9344`` -- For Frontier: TBC diff --git a/old-docs-for-reference/main-wiki.rst/Benchmarks.rst b/old-docs-for-reference/main-wiki.rst/Benchmarks.rst deleted file mode 100644 index 0e661c7..0000000 --- a/old-docs-for-reference/main-wiki.rst/Benchmarks.rst +++ /dev/null @@ -1,107 +0,0 @@ -Trie -==== - -Common Trie benchmarks. The point of this is to give a controlled test -between clients that reflects typical on-chain situations. We do this by -defining a common dataset of key/value pairs for insertion into the -trie. The dataset is then inserted into the trie with root hashes being -computed at specific intervals ("era\_size"). This number represents the -number of update operations per root calculation; three standard values -are provided to model a simple transaction (3), a contract transaction -making several ``SSTORE``\ s (5) and a more complex contract transaction -(9). - -Sensible implementations may precompute the dataset to avoid the -additional burden of SHA3 computation. - -Standard Dataset ----------------- - -.. code:: python - - from ethereum import trie, db, utils - import time - - MIN_COUNT = 32 - ROUNDS = 1000 - ERA_SIZE = 4 - MAX_COUNT = 32 - SYMMETRIC = True - a = time.time() - t = trie.Trie(db.EphemDB()) - seed = '\x00' * 32 - - for i in range(ROUNDS): - seed = utils.sha3(seed) - mykey = seed[:MIN_COUNT + ord(seed[-1]) % (MAX_COUNT + 1 - MIN_COUNT)] - if SYMMETRIC: - t.update(mykey, mykey) - else: - seed = utils.sha3(seed) - myval = seed[-1] if ord(seed[0]) % 2 else seed - t.update(mykey, myval) - if i % ERA_SIZE == 0 - seed = t.root() - print time.time() - a - print t.root_hash.encode('hex') - -The final trie root after 1000 rounds should be ``36f6...93a3`` for -``SYMMETRIC = True`` and ``da8a...0ca4`` for ``False``. - -Method ------- - -Tests run on: - -:: - - Linux gav-MacBookPro 4.4.0-040400rc7-lowlatency #201512272230 SMP PREEMPT Mon Dec 28 03:36:57 UTC 2015 x86_64 x86_64 x86_64 GNU/Linux - -CPU: - -:: - - model name : Intel(R) Core(TM) i7-4980HQ CPU @ 2.80GHz - cpu MHz : 3195.609 - cache size : 6144 KB - bogomips : 5587.06 - -C++ -~~~ - -:: - - cd libweb3core - cmake -DCMAKE_BUILD_TYPE=Release - make -j8 - sudo nice -n -19 ./libweb3core/bench/bench trie - -Go -~~ - -:: - - sudo nice -n -19 godep go test -run=- -bench=Std ./trie - -Results -------- - -Test ID is given as -``pair_count``-``era_size``-``key_size``-``value_type``, where valid -``value_type``\ s are ``ran`` (``SYMMETRIC = False``) and ``mir`` -(``SYMMETRIC = True``). Note clients which do not do bulk insertion -optimisations (C++, Python) will have the same time for each test. - -+----------------+-----------------+---------+--------------------+---------+----------------+---------+ -| Test ID | C++ time (ms) | SHA3s | Python time (ms) | SHA3s | Go time (ms) | SHA3s | -+================+=================+=========+====================+=========+================+=========+ -| 1k-3-32-ran | 23.8 | 8469 | 369 | 7079 | 45.7 | | -+----------------+-----------------+---------+--------------------+---------+----------------+---------+ -| 1k-5-32-ran | 23.8 | 8469 | 369 | 7079 | 28.5 | | -+----------------+-----------------+---------+--------------------+---------+----------------+---------+ -| 1k-9-32-ran | 23.8 | 8469 | 369 | 7079 | 23.6 | | -+----------------+-----------------+---------+--------------------+---------+----------------+---------+ -| 1k-1k-32-ran | 23.8 | 8469 | 369 | 7079 | 10.0 | | -+----------------+-----------------+---------+--------------------+---------+----------------+---------+ -| 1k-1k-32-mir | 23.9 | 8500 | 294 | 4228 | 8.0 | | -+----------------+-----------------+---------+--------------------+---------+----------------+---------+ diff --git a/old-docs-for-reference/main-wiki.rst/Block-Protocol-2.0.rst b/old-docs-for-reference/main-wiki.rst/Block-Protocol-2.0.rst deleted file mode 100644 index 5b18891..0000000 --- a/old-docs-for-reference/main-wiki.rst/Block-Protocol-2.0.rst +++ /dev/null @@ -1,424 +0,0 @@ -One of the main criticisms that has been made of Ethereum, and -Bitcoin-like blockchain protocols in general, is the issue of -scalability. Although Bitcoin's core developers, and other platforms -such as Ripple, have continued to make iterative improvements to the way -that the blockchain is stored, including innovations such as separating -the state ("ledger" or "UTXO set") from the transaction list or using -separate data structures to store the two on disk/memory, fundamentally -no one has successfully implemented any way to improve upon the -fundamental limitation that every full node must process every -transaction. At this point, Ethereum also does not solve this problem. -However, the block protocol described here, and specifically the stack -trace mechanism, allows for secure "light nodes" to exist, which -download only the headers of every block and not the full transaction -set but maintain the same security level for their users as full nodes -under the much weaker assumption that at least one node with -non-negligible (ie. >0.01%) mining power or ether inside the system is -honest. - -Data definitions -~~~~~~~~~~~~~~~~ - -A full block is stored as: - -:: - - [ - block_header, - transaction_list, - uncle_list, - stack_trace - ] - -Where: - -:: - - transaction_list = [ - transaction 0, - transaction 1, - ... - ] - - uncle list = [ - uncle_block_header_1, - uncle_block_header_2, - ... - ] - - block_header = [ - parent hash, - number, - TRIEHASH(transaction_list), - TRIEHASH(uncle_list), - TRIEHASH(stack_trace), - coinbase address, - state_root, - difficulty, - timestamp, - extra_data, - nonce - ] - - stack_trace = [ - [ medhash 0, stkhash 0 ], - [ medhash 1, stkhash 1 ], - ... - ] - -Each transaction and uncle block header is itself provided directly in -the form of a list, not in a serialized form. ``uncle_list`` and -``transaction_list`` are the lists of the uncle block headers and -transactions in the block, respectively. Note that the block number, -difficulty and timestamp are integers, and therefore cannot have leading -zeroes; ``extra_data`` and ``nonce`` can be byte arrays of at most 32 -bytes, NOT lists, although this particular check should not be performed -for the genesis block where the ``extra_data`` field will take up many -kilobytes. - -The ``state_root`` is the root of a `Patricia -Tree `__ -containing (key, value) pairs for all accounts where each address is -represented as a 20-byte binary string. At the address of each account, -the value stored in the Merkle Patricia tree is a string which is the -RLP-serialized form of an object of the form: - -:: - - [ balance, nonce, contract_root ] - -The ``nonce`` is the number of transactions made from the account, and -is incremented every time a transaction is made. The purpose of this is -to (1) make each transaction valid only once to prevent replay attacks, -and (2) to make it impossible (more precisely, cryptographically -infeasible) to construct a contract with the same hash as a pre-existing -contract. ``balance`` refers to the account's balance, denominated in -wei. ``contract_root`` is the root of yet another Patricia tree, -containing the contract's memory, if that account is controlled by a -contract. If an account is not controlled by a contract, the contract -root will simply be the empty string. - -In order to understand all of what is above, we also need a few function -definitions: - -:: - - def H(x): - if len(rlp.encode(x)) < 32: return x - else: return sha3(rlp.encode(x)) - - def H20(x): - if len(rlp.encode(x)) < 20: return x - else: return sha3(rlp.encode(x))[:12] - - def adjust_difficulty(pdiff,ptime,ntime): - if ntime > ptime + 42: return pdiff - int(pdiff / 1024) - else: return pdiff + int(pdiff / 1024) - - def int_to_bin(n,bytes): - return '' if bytes == 0 else int_to_bin(int(n / 256),bytes - 1) + chr(n % 256) - - def TRIE(objs): - t = Trie() - for i in range(len(objs)): - t.insert(int_to_bin(i,32),rlp.encode(objs[i])) - return t - - def TRIEHASH(objs): - return TRIE(objs).root - -We also want a few methods for dealing with tries as stacks: - -:: - - def TRIELEN(trie): - i = 0 - while trie.get(int_to_bin(i,32)): i += 1 - return i - - def TRIETOP(trie): - return trie.get(int_to_bin(TRIELEN(trie)-1,32)) - - def TRIEPOP(trie): - trie.update(int_to_bin(TRIELEN(trie)-1,32),'') - - def TRIEPUSH(trie,node): - trie.update(int_to_bin(TRIELEN(trie),3),node) - -The mining function is tentative, and will be replaced once we know that -we have better alternatives: - -:: - - def compute_valid_nonce(header): - header[10] = 0 - while not verify_pow(header): - header[10] += 1 - return header[10] - - def verify_pow(header): - return sha3(sha3(header[:10]) + header[10]) * header[7] <= 2**256 - -Mining Process -~~~~~~~~~~~~~~ - -.. figure:: https://www.ethereum.org/gh_wiki/500px-Minerchart3.png - :alt: Mining Process - - Mining Process - -When mining a block, a miner goes through the following process: - -1- Take as inputs: - -- ``uncle_headers`` to be the list of known unused valid uncle headers -- ``timestamp`` to be the current timestamp -- ``parent`` to be the parent block -- ``extra_data`` to be the extra data desired to be added to the block -- ``coinbase`` to be the desired coinbase address -- ``txlist`` to be the list of transactions to be added - -2- Set: - -- ``difficulty = adjust_difficulty(parent.difficulty,timestamp,parent.timestamp)`` -- ``reward = 15 * 10^18`` (tentatively) -- ``block_header = [ parent.hash, parent.number + 1, TRIEHASH(txlist), TRIEHASH(uncle_headers), 0, coinbase, 0, difficulty, timestamp, extra_data, 0 ]`` - -3- Initialize: - -- ``state`` to be the parent block state -- ``txstack = TRIE(txlist)`` -- ``stacktrace = TRIE([])`` - -4- While ``stacktrace.root != ''``: - -- ``TRIEPUSH(stacktrace,[state.root,txstack.root])`` -- Apply the transaction ``TRIETOP(txstack)`` to ``state``. -- ``TRIEPOP(txstack)`` -- Let ``L[0] ... L[m-1]`` be the list of new transactions spawned by - that transaction via ``MKTX``, in the order that they were produced - during script execution. -- Initialize ``j = m-1``. While ``j >= 0``, ``TRIEPUSH(txstack,L[j])`` - and ``j -= 1`` - -5- Make the following modifications to the state tree: - -- Increase the balance of ``coinbase`` by ``reward`` -- For each uncle ``u`` in ``uncle_headers``, increase the balance of - ``u.coinbase`` by ``reward * 13/16`` and increase the balance of - ``coinbase`` by ``reward * 1/16`` - -6- Fill in the first two zeroes in ``block_header`` with ``state.root`` -and ``TRIEHASH(stack_trace)`` - -7- Set ``nonce = compute_valid_nonce(block_header)``, and fill in the -remaining zero in the block header with this value - -Block Validation Algorithm -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. figure:: https://www.ethereum.org/gh_wiki/500px-Minerchart2.png - :alt: Mining Process - - Mining Process - -1- Take as inputs: - -- ``block`` to be the block header -- ``uncle_list`` to be the block's uncle list -- ``transaction_list`` to be the block's transaction list -- ``stacktrace`` to be the block's stack trace -- ``now`` to be the current time as measured by the miner's CPU - -2- Check the following: - -- Is there an object, which is a block, in the database with - ``block.prevhash`` as its hash? Let ``parent`` be that block. -- Is the proof of work on the block valid? -- Is the proof of work on all uncle headers valid? -- Are all uncles unique and actually uncles (ie. children of the parent - of the parent, but not the parent)? -- Is ``block.timestamp <= now + 900`` and is - ``block.timestamp >= parent.timestamp``? -- Is ``block.number == parent.number + 1``? -- Is - ``block.difficulty == adjust_difficulty(parent.difficulty,timestamp,parent.timestamp)``? -- Is ``block.transaction_hash = TRIEHASH(transaction_list)``? -- Is ``block.stacktrace_hash = TRIEHASH(stacktrace)``? -- Is ``block.uncle_hash = H(uncle_list)``? - -3- Initialize: - -- ``state`` to be block parent block's state -- ``txstack = TRIE(transaction_list)`` -- ``i = 0`` - -4- Let ``stacktrace[k] = [ M[k], H[k] ]``, defaulting to '' if ``k`` is -out of bounds. While ``i < len(stacktrace)``: - -- Check that ``state.root == M[i]`` and ``txstack.root == H[i]`` -- Apply ``transaction_list[i]`` to ``state``. -- Apply the transaction ``TRIETOP(txstack)`` to ``state``. -- ``TRIEPOP(txstack)`` -- Let ``L[0] ... L[m-1]`` be the list of new transactions spawned by - that transaction via ``MKTX``, in the order that they were produced - during script execution. -- Initialize ``j = m-1``. While ``j >= 0``, ``TRIEPUSH(txstack,L[j])`` - and ``j -= 1`` -- Set ``i += 1`` - -5- Make the following modifications to ``state``: - -- Increase the balance of ``coinbase`` by ``reward`` -- For each uncle ``u`` in ``uncle_headers``, increase the balance of - ``u.coinbase`` by ``reward * 13/16`` and increase the balance of - ``coinbase`` by ``reward * 1/16`` - -6- Check that ``txstack.root == ''`` - -7- Check that ``state.root == block.state_root`` - -8- If any check failed, return FALSE. Otherwise, return TRUE. - -If a block is valid, determine TD(block) ("total difficulty") for the -new block. TD is defined recursively by ``TD(genesis_block) = 0`` and -``TD(B) = TD(B.parent) + sum([u.difficulty for u in B.uncles]) + B.difficulty``. -If the new block has higher TD than the current block, set the current -block to the new block and continue to the next step. Otherwise, exit. - -Semi-collaborative Block Validation Via Challenge-Response Protocol -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In Ethereum, a ''light node'' can be defined as a node that accepts -block headers, and performs the verifications in (2) with the exception -of the transaction and stacktrace trie hash verifications but does not -perform the verifications in (4) and (6), similar to the headers-only -verification that light nodes do in Bitcoin. Light nodes would thus -store the state roots, and perhaps some portion of the state, but not -the entire state. If a light node wants to know the balance or contract -state of a given account, it can request the value from other nodes in -the network alongside the minimal subset of Patricia tree nodes that -prove that the given key/value pair is actually in the state. - -Although Ethereum cannot run without at least some full nodes processing -and verifying every transaction that takes place in the network, this -block protocol is designed to provide a somewhat weaker assurance: as -long as at least one honest full node exists, light clients can be just -as secure and provide the same incentives toward decentralization that -full nodes do. The mechanism relies on a challenge-response protocol in -which a full node can, subject to certain conditions, submit a challenge -that a certain part of a block is invalid, and it would be up to the -miner (or another good samaritan node) to provide a response which light -nodes can then efficiently verify. If a challenge goes uncontested, then -light nodes would distrust the block. - -In the validation algorithm described in the previous section, note that -there are a few specific places where a block can fail: - -1. One of the checks in (2), aside from the transaction list trie hash - or stack trace trie hash check, fails. -2. The transaction list trie hash check fails. -3. The stack trace trie hash check fails. -4. One of the checks in (4) fails for ``i=0`` -5. One of the checks in (4) succeeds for all ``i= k``, everything must be blank. - -A challenge of invalidity consists of either (1) an index ``i`` pointing -to a potential invalid transaction, or (2) an index ``i`` pointing to a -blank space and an index ``j > i`` pointing to a transaction. A response -should contain (1) ``i``, (2) ``j`` if applicable, (3) the subset of -Patricia tree nodes needed to verify the values at ``i`` and ``j`` in -the trie. - -For (5), a challenge of invalidity consists of an index ``k`` such that -everything up to index ``k`` is valid but index ``k`` is not. A response -consists of (1) ``k``, (2) the stack trace entries at ``k-1`` and ``k`` -along with a subset of Patricia tree nodes to verify them, (3) a subset -of Patricia tree nodes from the state tree needed to verify the -computation. For (4), a response consists simply of a subset of Patricia -tree nodes to prove the stack trace entry at index 0, from which the two -components can be checked against the transaction list hash in the block -header and the parent block state. For (6), a response functions in the -same way as in (4), except verifying the response requires both -processing the last transaction and giving the block rewards to the -coinbase and the uncles. - -Economics -~~~~~~~~~ - -There is one flaw in the protocol as described above: it is vulnerable -to denial of service attacks. Specifically, because challenges are much -easier to produce than responses are to produce or verify, it is -possible for nodes to pollute the network with false challenges, forcing -light nodes to reject every block as other nodes are unable to catch up -with verification. To remedy this, we introduce a simple fix: a -challenge must be signed by a node that either (1) mined one of the last -10000 blocks, or (2) owns at least 0.01% of all ether. Light nodes would -then keep quality scores for all peers, and downgrade peers if they -submit a challenge that is successfully countered. Because this method -is not anonymous, requiring nodes to submit proof of ownership of an -identity tied to the blockchain, it cannot be countered by reconnecting -under a new IP address or other such mechanisms. - -The protocol altogether can be shown to be incentive-compatible as -follows: - -1. Miners have the incentive to submit challenges to blocks mined by - other nodes because if a challenge is successful and then they mine - the next block they will have the opportunity to gain an extra - 0.0625X reward by including the header of the invalid block as an - uncle. -2. The miner of a block, and all uncles inside the block, at the very - least have the incentive to respond to challenges. -3. Light nodes have the incentive to respect the block validity rules - because everyone else does, an argument advanced in - http://themonetaryfuture.blogspot.ca/2011/07/bitcoin-decentralization-and-nash.html. - Without the challenge-response protocol, this argument does not apply - because the cost of determining whether or not a block is valid is - prohibitively high; with the protocol, this reasoning no longer - applies. -4. Substantial stakeholders have the incentive to promote the perceived - integrity of the system to maximize the value of their currency - units, and thus may want to help actively submit both challenges and - responses where possible. -5. Statistically speaking, far more than 0.01% of agents inside of - real-world economic agents, whether or not weighted by economic - power, tend to motivated by altruistic/ideological considerations. - The market share of charities around the world is sufficient evidence - of this. - -Comparison with Bitcoin -~~~~~~~~~~~~~~~~~~~~~~~ - -In Bitcoin, one can create a challenge-response protocol to achieve -similar functionality along very similar principles, but there is one -key way in which such a protocol in Bitcoin would be inadequate: miner -fees. Because Bitcoin does not include a Merkle-tree mechanism for -adding up transaction fees, the only way to prove that a block has a -certain quantity of transaction fees is to process every transaction. -Furthermore, in Bitcoin transaction fees all go to the miner. Thus, in -Bitcoin a light node has no way of knowing if a given block is valid or -if it gives its creator excessive fees, and can only rely on the -computational majority as a source of information for this. In Ethereum, -all changes to the state are incorporated into the stacktrace, so this -weakness does not exist and, given the weak security assumption that at -least one full node with at least 0.01% mining power or stake is honest, -have 100% of the security properties that full nodes have. diff --git a/old-docs-for-reference/main-wiki.rst/Blockchain-import-and-export-instructions.rst b/old-docs-for-reference/main-wiki.rst/Blockchain-import-and-export-instructions.rst deleted file mode 100644 index 9d3f91d..0000000 --- a/old-docs-for-reference/main-wiki.rst/Blockchain-import-and-export-instructions.rst +++ /dev/null @@ -1,50 +0,0 @@ -***Note:** Binary format is concatenated RLP-encoded blocks* - -C++ ---- - -Import: -~~~~~~~ - -:: - - eth --import - -*Formats supported: binary* - -Export: -~~~~~~~ - -:: - - eth --export Myfile --format binary --from 45 --to latest - -*Formats supported: hex (newlines separating), binary or JSON* -``--from`` and ``--to`` also support blockhashes - -Go --- - -Import -~~~~~~ - -:: - - geth import - -*Formats supported: binary* - -Genesis block: -~~~~~~~~~~~~~~ - -:: - - geth --genesis --genesisnonce - -*Formats supported: json* ### Export - -:: - - geth export - -*Formats supported: binary* ## Python diff --git a/old-docs-for-reference/main-wiki.rst/Brain-Wallet.rst b/old-docs-for-reference/main-wiki.rst/Brain-Wallet.rst deleted file mode 100644 index 1c525d9..0000000 --- a/old-docs-for-reference/main-wiki.rst/Brain-Wallet.rst +++ /dev/null @@ -1,49 +0,0 @@ -Ethereum brain wallets are formed through applying the SHA3 to a seed to -get a result ``R``, then using ``R`` as an accumulator for 16384 repeat -SHA3 operations. This process is continued until the result, when used -as a private key, forms a valid Direct ICAP (34 digit) address, defined -as the first byte of the address being 0. - -:: - - FUNCTION toBrain(STRING seed) RETURNS SECRET - A = SHA3(seed) - REPEAT 16384 TIMES - A = SHA3(A) - END REPEAT - WHILE SECRET_TO_ADDRESS(A)[0] != 0 DO - A = SHA3(A) - END WHILE - RETURN A - END FUNCTION - -See `C++ -implementation `__ -for an example. - -**Comments (Gustav):** -~~~~~~~~~~~~~~~~~~~~~~ - -Recent advancement in brain wallet cracking [1] show how vulnerable -brain wallets are to weak passwords. Applying a KDF hardens brain -wallets by reducing number of passwords an attacker can generate per -second. - -Even though the seed in AZ is generated for people and can thus be -designed to have enough entropy, it is desirable to configure a KDF to -be as strong as possible without impacting usability. - -Benchmarking SHA3 in Go [2] on a i5-4278U CPU @ 2.60GHz gives 16384 -hashes in 30ms. A C implementation on a high-end CPU would be -significantly faster. - -I would recommend we configure a KDF that is much harder (even up to -1-2s CPU time) and also has a memory cost. Scrypt comes to mind, which -we already specify in for the key storage [3]. - -This would make our brainwallets much harder to crack, and perhaps even -allowing the seed to be shorter, improving usability. - -1. https://rya.nc/cracking\_cryptocurrency\_brainwallets.pdf -2. https://github.com/ethereum/go-ethereum/blob/master/crypto/crypto\_test.go#L65 -3. https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition diff --git a/old-docs-for-reference/main-wiki.rst/Chain-Fibers-Redux.rst b/old-docs-for-reference/main-wiki.rst/Chain-Fibers-Redux.rst deleted file mode 100644 index 8c7b359..0000000 --- a/old-docs-for-reference/main-wiki.rst/Chain-Fibers-Redux.rst +++ /dev/null @@ -1,264 +0,0 @@ -Blockchain Scalability: Chain-Fibers Redux -========================================== - -History -------- - -I came up with the first seed of this idea while chatting to Janislav -Malahov in Berlin in Spring 2014. Unfortunately, the original article I -wrote was lost along with my laptop when it was stolen in Vienna. After -chatting over the principles with Vitalik more recently, we made a -number of alterations and formalisations, mainly to the validation and -the sub-state cutting mechanisms. What follows is a fairly complete -picture of one particular possible plan for block chain scalability in a -later version of Ethereum. - -Overview --------- - -The basic idea of Chain-Fibers is unchanged from a year ago; split the -state-space up into strata and have separate transaction collators -specialising in one or a number of state sub-spaces. Transactions -requiring interactions from many a subspace would be accordingly more -expensive (since collators would have to maintain presence on multiple -chains) and take longer to execute (since there is a lesser chance that -any given block would contain a superset of the transaction's -subspaces). Validity of a transaction is verifiable in isolation through -the provision of comprehensive Merkle proofs to its inputs alongside it -in the block in which it is included. - -The subtleties lie in precisely what governs the division of subspaces -(my original proposal included the automated splitting, merging and -rotation of subspace-divisions in order to best deliver internal -coherency), how security is maintained within comparatively worthless -subspaces and how this can play well with Proof-of-Stake (the original -was based upon a master PoW chain, feeding off an idea put forward by -Max Kaye in early 2014 to disassociate block chain archival from -transition semantics). - -Basic idea is to have a number of chains (e.g. N), each detailing the -state-transitions for only a strata of the entire system state (i.e. a -state subspace). Following from programming terminology, these might be -termed "fibers". Accounts thus belong to a subspace and as such a single -fiber; the fiber to which they belong can be determined simply from the -first log2(N) bits of the address. N can increase or decrease, and is a -value maintained within the housekeeping information on the "Master -Chain". - -The Master Chain in maintained by a set of bonded Validators V, with the -number of validators proportional to N. A random selection of validators -validate each block produced, and validators ultimately vote to form -consensus over the Master Chain. Each block of the Master Chain -maintains a reference to the header of each fiber. - -Transaction collators produce blocks (accepting fees from transactors), -and pay Validators some of the fees collected to include the hash of -their block in the main chain. Blocks are produced across a particular -"home set" of fibers; this is basically just the set of fibers of which -they maintain the State Trie. Their blocks may involve transactions over -one or many of these fibers, though none outside their "home set". - -"Fishermen" is a term given to freelance checkers. Since block -validation and availability are both important, and since it is possible -that sets of validators may be contractually bribed, it is important to -have a mechanism to involve additional rational individuals in acting as -"whistle-blowers" to avoid bogging the other validators needlessly -checking all blocks. The fishermen basically pay to attempt to convince -a quorum of validators that a previously validated block is invalid (or -unavailable, which we assume is equivalent). If a fisherman demonstrates -a validator (or, more likely, set of validators) acted in a -dishonourable fashion, then they get to claim all of their bonds. To -avoid DoSing the validators with spurious challenges, a fee is payable. - -Schematic ---------- - -Sorry for the not-quite ASCII-art. I'm not quite as 1337 at Inkscape as -Vitalik. - -:: - - Transactors ==TX+FEE==> Collators ==BLOCK+FEE==> Validators - make transaction validate transaction, random selection chosen to audit - produce Comprehensive Merkle TX/PSR/CMP contents & availability, - Proof and Post State Root, all placed in PoS-consensus master block - collate into X-fiber Block - - Fishermen ==CHALLENGE+FEE==> Validators - search for invalid or a selection adjudicate challenge - unavailable X-fiber blocks - -Transactors ------------ - -Transactors are pretty much exactly the same as in Ethereum 1.0 - they -are the users of the system. - -Transactors: make transaction -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Transactors make a transaction much like they do in the existing -Ethereum system. One or two minor differences - addresses can be used as -a distance metric; those sharing the same number of initial bits are -considered "closer", which means a greater certainty into the future -that they will continue to be contained in the same state subspace. -Contracts are naturally created in the same state subspace as the -creator. - -Transactions, like Collators, operate over a number of fibers; perhaps -one perhaps all, probably somewhere in between. Submission to collators -may be directed through fiber sub-network overlays. - -Submission and payment to the collators happens much as existing -transaction submission to miners happens in Ethereum 1.0. - -Collators ---------- - -Collators maintain presence on at least two peer sub-network overlays; -the Validators overlay, and one or more fiber overlays. The fiber -overlays may provide directed transaction propogation. Collators -"collate" on a set of fibers. They maintain a full fiber-chain for each -fiber they collate over, and can accept all transactions that involve -any combination of their fiber set. The greater this combination, then -the greater their "transaction net", but the greater their overall -disk/memory footprint. - -Collators: validate transaction -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -On receipt of a transaction, they go through the usual Ethereum 1.0 -rites of checking payment is enough, initial balances &c. Once basic -validation is done, they attempt to execute it, throwing it out if it -touches any fiber that is not part of collator's fiber set. - -Collators: produce Comprehensive Merkle Proof and Post State Root -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Collators provide each post-state-root (as is found in the transaction -receipt of Ethereum 1.0) and append to the block Merkle proofs and -associated hints (e.g. contract code) for all inputs (balance, nonce, -state, code) from all subspaces that are required for the evaluation of -each transaction from a previously known post-state-root. - -This allows an auditor to, without anything other than the previous -post-state-root for each fiber, determine the validity of the block. - -Collators: collate into X-fiber Block -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A Cross Fiber Block is created from the total information collated. This -includes transactions, transaction receipts (post-state-roots), -Comprehensive Merkle-Proofs and associated hash-hints. This block does -not include any consensus-specific information such as timestamping, -uncles &c. - -Validators ----------- - -Validators (who might be better named auditors) are bonded particpants, -chosen regularly from the highest bidders, who take a small fee for the -ultimate maintenence of the network. Their job, as a whole, is to form a -judiciary and ultimate authority over the validity and transaction -contents of the chain. We generally assume that they are mostly -benevolent and cannot all be bribed. Being bonded, validators may also -be called to audit and stake their bond on an opinion over validity or -information-availability. - -Validators: all placed in PoS-consensus master block -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -They maintain signing control over the Master Chain. The Master Chain -(MC) encodes all PoS/consensus stuff like timestamping and includes its -own little state root for recording validator's bond balances, ongoing -challenges, fiber block header-hashes and any other housekeeping -information. - -Each master block (MB), a set of collated X-Fiber Blocks (XBs) are -taken; these must be non-overlapping, so that each fiber belongs to only -a single XB. - -Validators: random selection chosen to audit TX/PSR/CMP contents & availability -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For each MB we have a number of XSBs referenced from the MB's Trie. Each -fiber is assigned a randomly selected set of validators, and the -validators must review whatever XB contains their assigned fiber. -Validation includes attaining the XB, finding the previous PSRs for each -of the fibers (placed in the MB) and checking that the proofs in its -CMP, cover all required inputs to the transactions collated within and -that the PSR is indeed the final state root when all are executed. - -The block is considered valid iff all assigned validators sign it. -Signing it is considered an assertion that the block contents are both -valid and available for a probabilistically long "challenge period" in -which a Fisherman may challenge. Any challenge to the block's validity -which is ultimately upheld by a full consensus of a randomly selected -set of validators (ultimately ending with a majority vote, should it be -doggedly contested) will mean the instant loss of the bond. - -Fishermen ---------- - -Fishermen (who might be called bounty hunters) are the freelance -error-checkers of the system. The watch the validators in the hope that -they can find wrong-doing. To help guarantee presence, payouts are -designed to be huge. The costs of challenging are small but not -insignificant. - -Fishermen: search for invalid or unavailable X-fiber blocks -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -They check the X-fiber blocks looking for validity errors and/or -inavailability of data. When they find an invalid block or unavailable -data, they launch a challenge (for a small fee, paid to validators) in -the hope that a sufficiently large portion of validators will concur. If -they succeed and validators ultimately uphold the challenge, then they -receive the bonds of all validators who had previously asserted -validity/availability of the information. - -Fishermen's Challenge: -~~~~~~~~~~~~~~~~~~~~~~ - -1. Fisherman finds an invalid/unavailable block not yet outside its - "challenge period" (10-30 blocks); pays a fee, submits a challenge - transaction into the master chain; -2. A randomly selected set of validators (e.g. of order e.g. sqrt(N)) ++ - any validators that self-select (through doubling their bond), check - the block that was challenged; each votes Y or N to the block's - validity; - -- If N, the validator receives a small payment Pn. -- If Y, the validator stakes their bond, though receives a larger - payment Py (perhaps Py = 2Pn). - -3. The outcome of the challenge (probably accumulated into the following - block) is: - -- If more than 66% of validators vote Y (valid), then the challenge - ends. The Fisherman loses their fee, but may reinitiate a challenge. -- If at least one validator votes Y (valid), then the challenge - continues with a second, larger set of randomly selected validators. - All bonds are staked. -- If all validators vote N (invalid), then the block is recorded as - invalid and the Fishermen receives the bond of all validators that - have asserted the blocks validity. This is a very large payoff. -- NOTE: If the set includes all validators, then it's a simple - majority-carries rule. - -Other differences ------------------ - -- All addresses are contained in a lookup table unique to each state - subspace; this means they can be referenced through a small number of - bits and avoid large amounts of wasted entropy in the RLP for proofs - &c. - -Notes ------ - -- Once a block is out of the challenge period, it is considered - unassailable. If it does turn out to be bad, then it must be fixed in - the same way as a protocol upgrade. As such it is likely that - validators and other large stakeholder would act as Fishermen to - protect their investment. diff --git a/old-docs-for-reference/main-wiki.rst/Client-Version-Strings.rst b/old-docs-for-reference/main-wiki.rst/Client-Version-Strings.rst deleted file mode 100644 index 55defbb..0000000 --- a/old-docs-for-reference/main-wiki.rst/Client-Version-Strings.rst +++ /dev/null @@ -1,67 +0,0 @@ -Every client implementation of the Ethereum protocol – along with every -version of it – has a *human readable* string identifier. Although this -ID is exchanged in the `P2P -protocol `__, -it itself isn't used by the protocol for anything, rather it enables -easily localizing issues with a particular client, or a particular -version of a client. - -Still, there tools popping up that analyze and create various statistics -about the network topology itself, which have a hard time conforming to -the identifier/versioning schema employed by each implementation. To -avoid requiring each such tool to implement a full ID parsing for every -type of node in the network, this document outlines a **suggested** -schema, part of which would be common among all implementations, and -some would be specific to one or the other. This would allow simple -tools to properly parse the common information out of each client's ID -string, whereas more complex tools might also further inspect the client -specific metadata. - -*Please note, this document should be perceived as a guideline at most, -and definitely not a golden standard to be enforced by any -implementation or tool. The goal is to aid the ecosystem relying on it, -but it is not something set in stone.* - -Suggested identifier schema -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -All identifier strings should be a slash separated list of metadata -fields: ``metadata-1/metadata-2/.../metadata-n``, where the first few -fields are fixed among all clients, whereas the latter ones (both in -meaning and in count) are up to each implementation to use as seen fit. - -The fixed fields are: 1. Display name of the client, without any version -numbering \* E.g. ``Geth``, ``++eth``, ``Ethereum(J)`` 2. Semantic -version, prefixed with ``v``, *optionally* suffixed by ``-`` -\* E.g. ``v1.3.3``, ``v0.9.41-ed7a8a35``, ``v1.4.0-unstable`` 3. Name of -the operating system the client is running on \* E.g. ``Linux``, -``Windows``, ``Darwin``, ``Android`` - -As there might be differences in implementation as to how one language -or another retrieves the name of the operating system – among others – -we recommend tools using the IDs to convert the strings internally to -lowercase before making aggregations. - -A few examples conforming to the above schema spec: - -:: - - Geth/v1.3.3/darwin - ++eth/v0.9.41-ed7a8a35/Windows - Ethereum(J)/v1.0.0/Linux - -Optional extensions -~~~~~~~~~~~~~~~~~~~ - -Beside the above defined fixed metadata fields, an identifier string may -contain arbitrarily many implementation specific metadata entries (the -order and index of which should desirably be maintained by the -developers of said client implementations). To help developers working -on analysis tools have a central repository of the metadata semantics, -the rest of this document describes the extra fields used by each -implementation. Feel free to add your own implementation to the below -list, but please maintain alphabetical ordering and please be concise. - -- **Geth**: ```` / ```` / ```` -- ``Geth/v1.3.3-c541b38/linux/go1.5.5`` -- ``Geth/v1.4.0-unstable/android/go1.6beta2/jit/gopher-power`` diff --git a/old-docs-for-reference/main-wiki.rst/Contract-Metadata-Docs-(NatSpec,-ABI).rst b/old-docs-for-reference/main-wiki.rst/Contract-Metadata-Docs-(NatSpec,-ABI).rst deleted file mode 100644 index 73128de..0000000 --- a/old-docs-for-reference/main-wiki.rst/Contract-Metadata-Docs-(NatSpec,-ABI).rst +++ /dev/null @@ -1,150 +0,0 @@ -This is the main entry point for NatSpec and generally details a safe -and efficient *standard* for Ethereum contract metadata distribution. - -By metadata we mean all information related to a contract that is -thought to be relevant to and immutably linked to a specific version of -a contract on the Ethereum blockchain. This includes: - -- Contract source code -- `ABI - definition `__ -- `NatSpec user - doc `__ -- `NatSpec developer's - doc `__ - -These resources have their *standard specification* in json format, -ideally meant to be produced by IDE infrastructures or compilers -directly. - -For instance, the -`solidity `__ -compiler offers a ``doxygen`` style way of specifying natspec with -inline smart comments. Upon compilation it creates both NatSpec user doc -as well ABI definition. But note that there is nothing inherently -solidity specific about these data, and other contract languages are -encouraged to implement their NatSpec/ABI support potentially with IDE-s -extending it. - -Since dapps and IDEs will typically want to interact with these -resources, standardising their deployment and distribution is important -for a smooth Ethereum experience. - -A specially important example of this is the **NatSpec transaction -confirmation notice scheme**, which we will use to illustrate the point. -However, the strategy described here trivially extends to arbitrary -immutable metadata fixed to an Ethereum contract. - -Transaction Confirmation Notice -=============================== - -The NatSpec user doc allows contract creators to attach custom -confirmation notices to each method. A powerful feature of NatSpec is to -provide templating which allows parts of the user notice to be -instantiated depending on the parameters of the actual transaction sent -to the contract. - -Trusted Ethereum client implementations are required to call back from -their backend instantiating the natspec transaction notice from actual -transaction data and present it to the user for confirmation. - -This serves as a first line of defense against illegitimate transactions -sent by malicious dapps in the user's name. - -Surely, this is only feasible if - the node can trust the authenticity -of metadata sources. - nodes have secure reliable access to the metadata -resources - -Let's see how this is achieved. - -Metadata Authentication ------------------------ - -**Proposal** The metadocs are assumed to be in a single JSON structure -called ``cmd`` file, that stands for *contract metadata doc*. - -The ``cmd`` file's content is hashed and content hash is registered on a -name registry via a contract on the Ethereum blockchain under the code -hash, see -https://github.com/ethereum/dapp-bin/blob/master/NatSpecReg/contract.sol -*Registering* in this context will simply mean a key value pair is -recorded in an immutable contract storage as a result of a transaction -sent to the registry contract. - -This provides a public immutable authentication for contract metadata, -since: - the authenticity of the link between the contract and metadata -is secured by Ethereum consensus - the authenticity of actual metadata -content is secured by content hashing - the binding is tamper proof - -Dapp IDE environments are supposed to support the functionality, that -when you create a contract, all its standard metadata is - bundled in a -single ``cmd`` json file - compiled source code is keccak hashed -> -``Sha3()`` - ``cmd`` json is keccak hashed -> -``Sha3()`` - the metadata is registered with the contract by -sending a transaction to a trusted name registry. The transaction simply -records ``Sha3() -> Sha3()`` as a key value pair in -contract storage. - -In order to avoid malicious agents hijacking metadata by overwriting the -namereg entry, we propose the following business process: - -- the link should be registered before a contract is deployed and is - immutable from then on. -- before the corresponding contract is deployed, we check if the - correct metadata bundle is found in the registry and confirmed to a - satisfying level of certainty (X blocks). - -How it looks like in ``Alethzero`` is illustrated [here]\|( -https://github.com/ethereum/wiki/wiki/NatSpec-Example) - -Metadata Access ---------------- - -In order to provide a robust (failure resistant, 100% uptime) service, -decentralised file storage services can and will be used. In the case of -content addressed systems like Swarm, accessing and fetching the -resource you will only need the ``cmd`` content hash (using -``BZZHASH(``). - -Until that point is reached, we will fall back to using HTTP -distribution. To enable this we will include one or many URLHint -contracts, which provide hints of URLs that allow downloading of -particular content hashes. Find the contract in dapp-bin. - -The content downloaded should be treated in many ways (and hashed) to -discover what the content is. Possible ways include base 64 encoding, -hex encoding and raw, and any content-cropping needed (e.g. a HTML page -should have everything up to body tags removed). - -It will be up to the dapp/content uploader to keep URLHint entries -updated. - -The address of the URLHint contract will be specified on an ad-hoc basis -and users will be able to enter additional ones into their browser. - -This functionality of uploading and registering location is supposed to -be also supported by IDE and dev infrastructures. Developers (or IDE) -are encouraged to register cmd location *before* content hash -registration (and therefore before actual contract creation) in order to -avoid metadata hijacking. Note that if content hash registration is -correct, hijacking the location cannot allow malicious content (since -content hash authenticates the ``cmd``), however it can still prevent -your metadata from being accessible. Therefore - the url-hint contract -storage should be by definition immutable - content-hash to url-hint -should be registered before contract creation - -(surely with old web urls, we are always exposed to server -failure/hacking, etc) - -Read more -`here `__ - -Name registry contracts ------------------------ - -Interoperability requires that clients know where to look to resolve a -contract's metadata, i.e., which name registry to use. Currently, we -solve this by - creating the two registry contracts after the genesis -block - and hardwiring their addresses in the client code (e.g., in the -natspec transaction confirmation notice module on the client side and -the deployment module on the dev/IDE side). diff --git a/old-docs-for-reference/main-wiki.rst/Dapp-Developer-Resources.rst b/old-docs-for-reference/main-wiki.rst/Dapp-Developer-Resources.rst deleted file mode 100644 index 1586ca8..0000000 --- a/old-docs-for-reference/main-wiki.rst/Dapp-Developer-Resources.rst +++ /dev/null @@ -1,61 +0,0 @@ -As a Ðapp developer you have three main resources which allow Ðapp -development. - -Main Resources -~~~~~~~~~~~~~~ - -- `Web3 JavaScript - API `__ - This - is the main JavaScript SDK to use when you want to interact with a - nodes API -- `JSON RPC API `__ - - This is the low level JSON RPC 2.0 interface to interface with a - node. This API is used by the `Web3 JavaScript - API `__. -- `Solidity - Documentation `__ - - Solidity is the Ethereum developed Smart Contract language, which - compiles to EVM (Ethereum Virtual Machine) opcodes. - -Other Resources: -~~~~~~~~~~~~~~~~ - -- `Standardized Contract - APIs `__ - - Standard contract API, which should be used to make some contract - types accessible by other Ðapps. (Not yet finalised) -- `Useful Ðapp - Patterns `__ - - Code snippets which are useful for Ðapp development. -- `Dapp using - Meteor `__ - - This short tutorial gives an intro on how to start building a dapp - using `Meteor `__, and also why Meteor is a - good fit for dapps. - -Useful read -~~~~~~~~~~~ - -- `FAQ `__ - Collection of - links, useful for understanding the Ethereum eco system. -- `Glossary `__ - Great - explanation of Blockchain related terms. - -Gitter Chats -~~~~~~~~~~~~ - -- web3.js |Gitter| -- Mist |Gitter| -- GO Ethereum |Gitter| -- C++ Ethereum |Gitter| -- `Swarm `__ -- `Whisper `__ - -.. |Gitter| image:: https://badges.gitter.im/Join%20Chat.svg - :target: https://gitter.im/ethereum/web3.js?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge -.. |Gitter| image:: https://badges.gitter.im/Join%20Chat.svg - :target: https://gitter.im/ethereum/mist?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge -.. |Gitter| image:: https://badges.gitter.im/Join%20Chat.svg - :target: https://gitter.im/ethereum/go-ethereum?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge -.. |Gitter| image:: https://badges.gitter.im/Join%20Chat.svg - :target: https://gitter.im/ethereum/cpp-ethereum?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge diff --git a/old-docs-for-reference/main-wiki.rst/Dapp-using-Meteor.rst b/old-docs-for-reference/main-wiki.rst/Dapp-using-Meteor.rst deleted file mode 100644 index b5dc69f..0000000 --- a/old-docs-for-reference/main-wiki.rst/Dapp-using-Meteor.rst +++ /dev/null @@ -1,314 +0,0 @@ -This tutorial will show you how to setup a Meteor app to be used as a -dapp and probably answer a few questions on why Meteor should be used. - -1. `Create your dapp <#create-your-%C3%90app>`__ -2. `Start your dapp <#start-your-%C3%90app>`__ -3. `Connect your dapp <#connect-your-%C3%90app>`__ -4. `Run your dapp <#run-your-%C3%90app>`__ -5. `Add dapp styles <#add-%C3%90app-styles>`__ -6. `Using Ethereum:elements <#using-ethereumelements>`__ -7. `Dapp code structure <#%C3%90app-code-structure>`__ -8. `Bundle your dapp <#bundle-your-%C3%90app>`__ - -FAQ ---- - -Isn't Meteor a full stack framework, how does that fit into dapp development -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -True, Meteor is a full stack framework and its main improvement is -realtime web applications, but Meteor is also the first framework (i -know of), which fully embraced *s*\ ingle *p*\ age *a*\ pp (SPA) -development and provided all necessary tools. - -5 reasons why Meteor is a perfect fit: - -1. Its purely written in JS and has all the tools a SPA needs - (Templating engine, Model, on-the-fly compiling, bundling) -2. You get a development environment, which has live reload, CSS - injection and support for many pre-compilers (LESS, Coffeescript, - etc) out of the box -3. You can get all frontend code as single ``index.html`` with one - ``js`` and ``css`` file plus your assets, using - `meteor-build-client `__. - You can then host it everywhere or simple run the ``index.html`` - itself or distribute it later on *swarm*. -4. It embraces full reactivity, which make building consistent interface - much easier (similar to angualr.js ``$scope`` or binding) -5. It has a great model called Minimongo, which gives you a mongoDB like - interface for a reactive in-memory database, which can also be - `auto-persistet to - localstorage `__ - or - `indexedDB `__ - -Do I need to host my dapp on a server? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -No, using -`meteor-build-client `__ -you can get all the static assets of you dapp to run without any server, -though if you use a router like -`iron- `__ or -`flow-router `__, you -need to use hash (``index.html#!/mypath``) routes instead of clean HTML5 -pushstate routes. - --------------- - -Create your dapp ----------------- - -Install Meteor if don't have already: - -.. code:: bash - - $ curl https://install.meteor.com/ | sh - -Then create an app: - -.. code:: bash - - $ meteor create myDapp - $ cd myDapp - -Next add the web3 package: - -.. code:: bash - - $ meteor add ethereum:web3 - -I recommend also to add the following packages: - -- `ethereum:dapp-styles `__ - - The LESS/CSS framework which gives your dapp a nice Mist-consistent - look. -- `ethereum:tools `__ - This - package gives you the ``EthTools`` object with a set of formatting an - conversion functions and template helpers for ether. -- `ethereum:elements `__ - - A set of interface elements specifically made for Ethereum, see this - `Demo `__ for more. -- `ethereum:accounts `__ - - Gives you the reactive ``EthAccounts`` collection with all current - available Ethereum accounts, where balances will be automatically - updated. -- `ethereum:blocks `__ - - Gives you the reactive ``EthBlocks`` collection with the latest 50 - blocks. To get the lastest block use ``EthBlocks.latest`` (It will - also have the latest default gasPrice) -- `frozeman:template-var `__ - - Gives you the ``TemplateVar`` object, that allows you to set - reactive variables, which are template instance specific. See the - `readme `__ for more. -- `frozeman:persistent-minimongo2 `__ - - Allows you to auto persist your minimongo collection in local - storage - -Start your dapp ---------------- - -A short excursion into Meteors folder structure -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Meteor doesn't force you to have a specific folder structure, though some -folders have specific meaning and will be treated differently when -bundling/running your application. - -Folders with specific treatment - ``client`` - files in a folder called -``client`` will only be loaded by the client part of your app and as we -are building a dapp, thats where most of our files go. - ``lib`` - files -in folders called ``lib`` will load before other files in the same -folder. This is an ideal place your init files, libraries, or Ethereum -specific files. - ``public`` - a folder called ``public`` contains assets -meteor will make available on the root of your webserver (or later -bundled dapp) - There are a few more specific folders like ``server``, -``tests``, ``packages``, etc. If you want to get to know them take a -look at the `Meteor -docs `__ - -So to build a dapp we ideally create the following folder structure in -our ``myDapp`` folder: - -:: - - - myDapp - - client - - lib - - myDapp.html - - myDapp.js - - myDapp.css - - public - -**Note** The community provides also Meteor dapp Boilerplates like this -on from Nick Dodson: -https://github.com/SilentCicero/meteor-dapp-boilerplate - -Connect your dapp -~~~~~~~~~~~~~~~~~ - -To connect our dapp we need to start ``geth`` with the right CORS -headers in another terminal: - -.. code:: bash - - $ geth --rpc --rpccorsdomain "http://localhost:3000" - -We also need to set the provider. Ideally we create a file in our lib -folder called ``init.js`` and add the following line: - -.. code:: js - - if(typeof web3 === 'undefined') - web3 = new Web3(new Web3.providers.HttpProvider('http://localhost:8545')); - -Run your dapp -~~~~~~~~~~~~~ - -Now we can run our dapp by simply running: - -.. code:: bash - - $ meteor - -If we go to ``http://localhost:3000``, we should see a website appear -and if we open the browser console we can use the web3 object to query -the geth node: - -.. code:: js - - > web3.eth.accounts - ['0xfff2b43a7433ddf50bb82227ed519cd6b142d382'] - -Add dapp styles ---------------- - -If you want your dapp to nicely fit later into Mist and have follow the -official look use the `dapp-styles css css/less -framework `__. - -*Note that they are under heavy development and the class names and -elements may change.* - -To add it simple add the following packages to your dapp: - -.. code:: bash - - $ meteor add less - $ meteor add ethereum:dapp-styles - -Now rename you ``myDapp.css`` to ``myDapp.less`` and add the following -line inside: - -.. code:: css - - // libs - @import '{ethereum:dapp-styles}/dapp-styles.less'; - -Now you can use all ``dapp-styles`` classes and also overwrite all variables -of the framework. You can find them `in the -repo `__. -Overwrite them by copying them to your ``myDapp.less`` file and set -different values. - -Using Ethereum packages ------------------------ - -To make your live as a dapp developer easier we provide some packages -that help you build dapps faster. - -If you add the recommended packages above you should have the -`ethereum:tools `__, -`accounts `__ and -`ethereum:blocks `__ packages -available. - -These 3 packages give you the ``EthTools``, ``EthAccounts`` and -``Ethblocks`` objects, which give you formatter functions, a collection -with the accounts from ``web3.eth.accounts`` (with auto updated balance) -and a collection of the last 50 blocks. - -Most of these functions are reactive so they should make building -interfaces a breeze. - -Example usage -~~~~~~~~~~~~~ - -If you look into you ``myDapp.html`` you will find the ``hello`` -template. Just add a helper called ``{{currentBlock}}`` some where -between the ```` tags. - -Now open the ``myDapp.js`` and add after the ``counter: function..`` the -``currentBlock`` helper: - -.. code:: js - - Template.elements.helpers({ - counter: function () { - ... - }, - currentBlock: function(){ - return EthBlocks.latest.number; - } - }); - -Then initialize EthBlocks by adding ``EthBlocks.init();`` after -``Session.setDefault('counter', 0);`` - -If you now check your dapp in the browser you should see the latest -block number, which will increase once you mine. - -*For more examples please checkout the packages readmes and the -`demo `__ -(`source `__) -for more.* - -Dapp code structure -------------------- - -*This tutorial won't go into building apps with Meteor. For this please -refer to the `Meteor's -tutorials `__, -`A list of good resources `__, -`EventMinded `__ (payed tutorials) or books -like `Building Single-page Web Apps with -Meteor `__ -or `Discover Meteor `__.* - -TODO Short: - put Ethereum related stuff into -``client/lib/ethereum/somefile.js`` - use -``myCollection.observe({added: func, changed: func, removed: func})`` to -communicate to Ethereum, keep Ethereum logic out of your app as much as -possible. This way you just write and read from your reactive -collections and the observe functions will handle the rest (e.g. -sendTransactions) - Filters etc will add logs etc to your collections. -So you keep all the callback mess out of your app logic. - -For an example see the -`Ethereum-Wallet `__. - -Bundle your dapp ----------------- - -To bundle your dapp into a local standalone file use -`meteor-build-client `__: - -.. code:: bash - - $ npm install -g meteor-build-client - $ cd myDapp - $ meteor-build-client ../build --path "" - -This will put your dapps static files into the build folder, above your -``myDapp`` folder. - -The last option ``--path`` will make the linking of all files relative, -allowing you to start the app by simply clicking the -``build/index.html``. - -Be aware that when running your app on the ``file://`` protocol, you -won't be able to use client side routing, due to web security. Later in -mist you will be able to use client side routing, as dapps are severed -over the ``eth://`` protocol. - -In the future you will be able to simply upload your dapp on swarm. diff --git a/old-docs-for-reference/main-wiki.rst/Default-Extra-Data-Standard.rst b/old-docs-for-reference/main-wiki.rst/Default-Extra-Data-Standard.rst deleted file mode 100644 index 3e88428..0000000 --- a/old-docs-for-reference/main-wiki.rst/Default-Extra-Data-Standard.rst +++ /dev/null @@ -1,17 +0,0 @@ -Implementations are encouraged to follow this protocol for populating -the ``extraData`` field of mined blocks. - -``extraData`` should be an RLP list whose first element is a version -identifier encoded as a canonical RLP positive integer. All other items -in the list are determined by the version ID. - -``[`` version: ``P``, ... ``]`` - -Version 0 -~~~~~~~~~ - -``[`` version: ``P``, clientIdentity: ``B`` ``]`` - -One further argument, a raw representation of a string to identify the -client (this would usually be a shortened form of the client identifier -as returned by the JSON RPC's ``web3_clientVersion``). diff --git a/old-docs-for-reference/main-wiki.rst/Design-Rationale.rst b/old-docs-for-reference/main-wiki.rst/Design-Rationale.rst deleted file mode 100644 index e49ec44..0000000 --- a/old-docs-for-reference/main-wiki.rst/Design-Rationale.rst +++ /dev/null @@ -1,840 +0,0 @@ -Although Ethereum borrows many ideas that have already been tried and -tested for half a decade in older cryptocurrencies like Bitcoin, there -are a number of places in which Ethereum diverges from the most common -way of handling certain protocol features, and there are also many -situations in which Ethereum has been forced to develop completely new -economic approaches because it offers functionality that is not offered -by other existing systems. The purpose of this document will be to -detail all of the finer potentially nonobvious or in some cases -controversial decisions that were made in the process of building the -Ethereum protocol, as well as showing the risks involved in both our -approach and possible alternatives. - -Principles ----------- - -The Ethereum protocol design process follows a number of principles: - -1. **Sandwich complexity model**: we believe that the bottom level - architecture of Ethereum should be as simple as possible, and the - interfaces to Ethereum (including high level programming languages - for developers and the user interface for users) should be as easy to - understand as possible. Where complexity is inevitable, it should be - pushed into the "middle layers" of the protocol, that are not part of - the core consensus but are also not seen by end users - - high-level-language compilers, argument serialization and - deserialization scripts, storage data structure models, the leveldb - storage interface and the wire protocol, etc. However, this - preference is not absolute. -2. **Freedom**: users should not be restricted in what they use the - Ethereum protocol for, and we should not attempt to preferentially - favor or disfavor certain kinds of Ethereum contracts or transactions - based on the nature of their purpose. This is similar to the guiding - principle behind the concept of "net neutrality". One example of this - principle *not* being followed is the situation in the Bitcoin - transaction protocol where use of the blockchain for "off-label" - purposes (eg. data storage, meta-protocols) is discouraged, and in - some cases explicit quasi-protocol changes (eg. OP\_RETURN - restriction to 40 bytes) are made to attempt to attack applications - using the blockchain in "unauthorized" ways. In Ethereum, we instead - strongly favor the approach of setting up transaction fees in such a - way as to be roughly incentive-compatible, such that users that use - the blockchain in bloat-producing ways internalize the cost of their - activities (ie. Pigovian taxation). -3. **Generalization**: protocol features and opcodes in Ethereum should - embody maximally low-level concepts, so that they can be combined in - arbitrary ways including ways that may not seem useful today but - which may become useful later, and so that a bundle of low-level - concepts can be made more efficient by stripping out some of its - functionality when it is not necessary. An example of this principle - being followed is our choice of a LOG opcode as a way of feeding - information to (particularly light client) dapps, as opposed to - simply logging all transactions and messages as was internally - suggested earlier - the concept of "message" is really the - agglomeration of multiple concepts, including "function call" and - "event interesting to outside watchers", and it is worth separating - the two. -4. **We Have No Features**: as a corollary to generalization, we often - refuse to build in even very common high-level use cases as intrinsic - parts of the protocol, with the understanding that if people really - want to do it they can always create a sub-protocol (eg. ether-backed - subcurrency, bitcoin/litecoin/dogecoin sidechain, etc) inside of a - contract. An example of this is the lack of a Bitcoin-like "locktime" - feature in Ethereum, as such a feature can be simulated via a - protocol where users send "signed data packets" and those data - packets can be fed into a specialized contract that processes them - and performs some corresponding function if the data packet is in - some contract-specific sense valid. -5. **Non-risk-aversion**: we are okay with higher degrees of risk if a - risk-increasing change provides very substantial benefits (eg. - generalized state transitions, 50x faster block times, consensus - efficiency, etc) - -These principles are all involved in guiding Ethereum development, but -they are not absolute; in some cases, desire to reduce development time -or not to try too many radical things at once has led us to delay -certain changes, even some that are obviously beneficial, to a future -release (eg. Ethereum 1.1). - -Blockchain-level protocol -------------------------- - -This section provides a description of some of the blockchain-level -protocol changes made in Ethereum, including how blocks and transactions -work, how data is serialized and stored, and the mechanisms behind -accounts. - -Accounts and not UTXOs -~~~~~~~~~~~~~~~~~~~~~~ - -Bitcoin, along with many of its derivatives, stores data about users' -balances in a structure based on *unspent transaction outputs* (UTXOs): -the entire state of the system consists of a set of "unspent outputs" -(think, "coins"), such that each coin has an owner and a value, and a -transaction spends one or more coins and creates one or more new coins, -subject to the validity constraints: - -1. Every referenced input must be valid and not yet spent -2. The transaction must have a signature matching the owner of the input - for every input -3. The total value of the inputs must equal or exceed the total value of - the outputs - -A user's "balance" in the system is thus the total value of the set of -coins for which the user has a private key capable of producing a valid -signature. - -| |image0| -| (Image from https://bitcoin.org/en/developer-guide) - -Ethereum jettisons this scheme in favor of a simpler approach: the state -stores a list of accounts where each account has a balance, as well as -Ethereum-specific data (code and internal storage), and a transaction is -valid if the sending account has enough balance to pay for it, in which -case the sending account is debited and the receiving account is -credited with the value. If the receiving account has code, the code -runs, and internal storage may also be changed, or the code may even -create additional messages to other accounts which lead to further -debits and credits. - -The benefits of UTXOs are: - -1. **Higher degree of privacy**: if a user uses a new address for each - transaction that they receive then it will often be difficult to link - accounts to each other. This applies greatly to currency, but less to - arbitrary dapps, as arbitrary dapps often necessarily involve keeping - track of complex bundled state of users and there may not exist such - an easy user state partitioning scheme as in currency. -2. **Potential scalability paradigms**: UTXOs are more theoretically - compatible with certain kinds of scalability paradigms, as we can - rely on only the owner of some coins maintaining a Merkle proof of - ownership, and even if everyone including the owner decides to forget - that data then only the owner is harmed. In an account paradigm, - everyone losing the portion of a Merkle tree corresponding to an - account would make it impossible to process messages that affect that - account at all in any way, including sending to it. However, - non-UTXO-dependent scalability paradigms do exist. - -The benefits of accounts are: - -1. **Large space savings**: for example, if an account has 5 UTXO, then - switching from a UTXO model to an account model would reduce the - space requirements from (20 + 32 + 8) \* 5 = 300 bytes (20 for the - address, 32 for the txid and 8 for the value) to 20 + 8 + 2 = 30 - bytes (20 for the address, 8 for the value, 2 for a nonce(see - below)). In reality savings are not nearly this massive because - accounts need to be stored in a Patricia tree (see below) but they - are nevertheless large. Additionally, transactions can be smaller - (eg. 100 bytes in Ethereum vs. 200-250 bytes in Bitcoin) because - every transaction need only make one reference and one signature and - produces one output. -2. **Greater fungibility**: because there is no blockchain-level concept - of the source of a specific set of coins, it becomes less practical, - both technically and legally, to institute a redlist/blacklisting - scheme and to draw a distinction between coins depending on where - they come from. -3. **Simplicity**: easier to code and understand, especially once more - complex scripts become involved. Although it is possible to shoehorn - arbitrary decentralized applications into a UTXO paradigm, - essentially by giving scripts the ability to restrict what kinds of - UTXO a given UTXO can be spent to, and requiring spends to include - Merkle tree proofs of change-of-application-state-root that scripts - evaluate, such a paradigm is much more complicated and ugly than just - using accounts. -4. **Constant light client reference**: light clients can at any point - access all data related to an account by scanning down the state tree - in a specific direction. In a UTXO paradigm, the references change - with each transaction, a particularly burdensome problem for - long-running dapps that try to use the above mentioned - state-root-in-UTXO propagation mechanism. - -We have decided that, particularly because we are dealing with dapps -containing arbitrary state and code, the benefits of accounts massively -outweigh the alternatives. Additionally, in the spirit of the We Have No -Features principle, we note that if people really do care about privacy -then mixers and coinjoin can be built via signed-data-packet protocols -inside of contracts. - -One weakness of the account paradigm is that in order to prevent replay -attacks, every transaction must have a "nonce", such that the account -keeps track of the nonces used and only accepts a transaction if its -nonce is 1 after the last nonce used. This means that even -no-longer-used accounts can never be pruned from the account state. A -simple solution to this problem is to require transactions to contain a -block number, making them un-replayable after some period of time, and -reset nonces once every period. Miners or other users will need to -"ping" unused accounts in order to delete them from the state, as it -would be too expensive to do a full sweep as part of the blockchain -protocol itself. We did not go with this mechanism only to speed up -development for 1.0; 1.1 and beyond will likely use such a system. - -Merkle Patricia Trees ---------------------- - -The Merkle Patricia tree/trie, previously envisioned by Alan Reiner and -implemented in the Ripple protocol, is the primary data structure of -Ethereum, and is used to store all account state, as well as -transactions and receipts in each block. The MPT is a combination of a -`Merkle tree `__ and -`Patricia tree `__, taking the -elements of both to create a structure that has both of the following -properties: - -1. Every unique set of key/value pairs maps uniquely to a root hash, and - it is not possible to spoof membership of a key/value pair in a trie - (unless an attacker has ~2^128 computing power) -2. It is possible to change, add or delete key/value pairs in - logarithmic time - -This gives us a way of providing an efficient, easily updateable, -"fingerprint" of our entire state tree. The Ethereum MPT is formally -described here: https://github.com/ethereum/wiki/wiki/Patricia-Tree - -Specific design decisions in the MPT include: - -1. **Having two classes of nodes**, kv nodes and diverge nodes (see MPT - spec for more details). The presence of kv nodes increases efficiency - because if a tree is sparse in a particular area the kv node will - serve as a "shortcut" removing the need to have a tree of depth 64. -2. **Making diverge nodes hexary and not binary**: this was done to - improve lookup efficiency. We now recognize that this choice was - suboptimal, as the lookup efficiency of a hexary tree can be - simulated in a binary paradigm by storing nodes batched. However, - because the trie construction is so easy to implement incorrectly and - end up with at the very least state root mismatches, we have decided - to table such a reorganization until 1.1. -3. **No distinction between empty value and non-membership**: this was - done for simplicity, and because it works well with Ethereum's - default that values that are unset (eg. balances) generally mean zero - and the empty string is used to represent zero. However, we do note - that it sacrifices some generality and is thus slightly suboptimal. -4. **Distinction between terminating and non-terminating nodes**: - technically, the "is this node terminating" flag is unnecessary, as - all tries in Ethereum are used to store static key lengths, but we - added it anyway to increase generality, hoping that the Ethereum MPT - implementations will be used as-is by other cryptographic protocols. -5. **Using sha3(k) as the key in the "secure tree"** (used in the state - and account storage tries): this makes it much more difficult to DoS - the trie by setting up maximally unfavorable chains of diverge nodes - 64 levels deep and repeatedly calling SLOAD and SSTORE on them. Note - that this makes it more difficult to enumerate the tree; if you want - to have enumeration capability in your client, the simplest approach - is to maintain a database mapping ``sha3(k) -> k``. - -RLP ---- - -RLP ("recursive length prefix") encoding is the main serialization -format used in Ethereum, and is used everywhere - for blocks, -transactions, account state data and wire protocol messages. RLP is -formally described here: https://github.com/ethereum/wiki/wiki/RLP - -RLP is intended to be a highly minimalistic serialization format; its -sole purpose is to store nested arrays of bytes. Unlike -`protobuf `__, -`BSON `__ and other existing solutions, RLP does -not attempt to define any specific data types such as booleans, floats, -doubles or even integers; instead, it simply exists to store structure, -in the form of nested arrays, and leaves it up to the protocol to -determine the meaning of the arrays. Key/value maps are also not -explicitly supported; the semi-official suggestion for supporting -key/value maps is to represent such maps as -``[[k1, v1], [k2, v2], ...]`` where ``k1, k2...`` are sorted using the -standard ordering for strings. - -The alternative to RLP would have been using an existing algorithm such -as protobuf or BSON; however, we prefer RLP because of (1) simplicity of -implementation, and (2) guaranteed absolute byte-perfect consistency. -Key/value maps in many languages don't have an explicit ordering, and -floating point formats have many special cases, potentially leading to -the same data leading to different encodings and thus different hashes. -By developing a protocol in-house we can be assured that it is designed -with these goals in mind (this is a general principle that applies also -to other parts of the code, eg. the VM). Note that bencode, used by -BitTorrent, may have provided a passable alternative for RLP, although -its use of decimal encoding for lengths makes it slightly suboptimal -compared to the binary RLP. - -Compression algorithm ---------------------- - -The wire protocol and the database both use a custom compression -algorithm to store data. The algorithm can best be described as -run-length-encoding zeroes and leaving other values as they are, with -the exception of a few special cases for common values like -``sha3('')``. For example: - -:: - - >>> compress('horse') - 'horse' - >>> compress('donkey dragon 1231231243') - 'donkey dragon 1231231243' - >>> compress('\xf8\xaf\xf8\xab\xa0\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xbe{b\xd5\xcd\x8d\x87\x97') - '\xf8\xaf\xf8\xab\xa0\xfe\x9e\xbe{b\xd5\xcd\x8d\x87\x97' - >>> compress("\xc5\xd2F\x01\x86\xf7#<\x92~}\xb2\xdc\xc7\x03\xc0\xe5\x00\xb6S\xca\x82';{\xfa\xd8\x04]\x85\xa4p") - '\xfe\x01' - -Before the compression algorithm existed, many parts of the Ethereum -protocol had a number of special cases; for example, ``sha3`` was often -overridden so that ``sha3('') = ''``, as that would save 64 bytes from -not needing to store code or storage in accounts. However, a change was -made recently where all of these special cases were removed, making -Ethereum data structures much bulkier by default, instead adding the -data saving functionality to a layer outside the blockchain protocol by -putting it on the wire protocol and seamlessly inserting it into users' -database implementations. This adds modularity, simplifying the -consensus layer, and also allows continued upgrades to the compression -algorithm to be deployed relatively easily (eg. via network protocol -versions). - -Trie Usage ----------- - -Warning: this section assumes knowledge of how bloom filters work. For -an introduction, see http://en.wikipedia.org/wiki/Bloom\_filter - -Every block header in the Ethereum blockchain contains pointers to three -tries: the *state trie*, representing the entire state after accessing -the block, the *transaction trie*, representing all transactions in the -block keyed by index (ie. key 0: the first transaction to execute, key -1: the second transaction, etc), and the *receipt tree*, representing -the "receipts" corresponding to each transaction. A receipt for a -transaction is an RLP-encoded data structure: - -:: - - [ medstate, gas_used, logbloom, logs ] - -Where: - -- ``medstate`` is the state trie root after processing the transaction -- ``gas_used`` is the amount of gas used after processing the - transaction -- ``logs`` is a list of items of the form - ``[address, [topic1, topic2...], data]`` that are produced by the - ``LOG0`` ... ``LOG4`` opcodes during the execution of the transaction - (including by the main call and sub-calls). ``address`` is the - address of the contract that produced the log, the topics are up to 4 - 32-byte values, and the data is an arbitrarily sized byte array. -- ``logbloom`` is a bloom filter made up of the addresses and topics of - all logs in the transaction. - -There is also a bloom in the block header, which is the OR of all of the -blooms for the transactions in the block. The purpose of this -construction is to make the Ethereum protocol light-client friendly in -as many ways as possible. For more details on Ethereum light clients and -their use cases, see the `light client page (principles -section) `__. - -Uncle incentivization ---------------------- - -The "Greedy Heaviest Observed Subtree" (GHOST) protocol is an innovation -`first introduced `__ by Yonatan -Sompolinsky and Aviv Zohar in December 2013, and is the first serious -attempt at solving the issues preventing much faster block times. The -motivation behind GHOST is that blockchains with fast confirmation times -currently suffer from reduced security due to a high stale rate - -because blocks take a certain time to propagate through the network, if -miner A mines a block and then miner B happens to mine another block -before miner A's block propagates to B, miner B's block will end up -wasted ("stale") and will not contribute to network security. -Furthermore, there is a centralization issue: if miner A is a mining -pool with 30% hashpower and B has 10% hashpower, A will have a risk of -producing a stale block 70% of the time (since the other 30% of the time -A produced the last block and so will get mining data immediately) -whereas B will have a risk of producing a stale block 90% of the time. -Thus, if the block interval is short enough for the stale rate to be -high, A will be substantially more efficient simply by virtue of its -size. With these two effects combined, blockchains which produce blocks -quickly are very likely to lead to one mining pool having a large enough -percentage of the network hashpower to have de facto control over the -mining process. - -As described by Sompolinsky and Zohar, GHOST solves the first issue of -network security loss by including stale blocks in the calculation of -which chain is the "longest"; that is to say, not just the parent and -further ancestors of a block, but also the stale descendants of the -block's ancestor (in Ethereum jargon, "uncles") are added to the -calculation of which block has the largest total proof of work backing -it. - -To solve the second issue of centralization bias, we adopt a different -strategy: we provide block rewards to stales: a stale block receives 7/8 -(87.5%) of its base reward, and the nephew that includes the stale block -receives 1/32 (3.125%) of the base reward as an inclusion bounty. -Transaction fees, however, are not awarded to uncles or nephews. - -In Ethereum, stale block can only be included as an uncle by up to the -seventh-generation descendant of one of its direct siblings, and not any -block with a more distant relation. This was done for several reasons. -First, unlimited GHOST would include too many complications into the -calculation of which uncles for a given block are valid. Second, -unlimited uncle incentivization as used in Ethereum removes the -incentive for a miner to mine on the main chain and not the chain of a -public attacker. Finally, calculations show that restricting to seven -levels provides most of the desired effect without many of the negative -consequences. - -- A simulator that measures centralization risks is available at - https://github.com/ethereum/economic-modeling/blob/master/ghost.py -- A high-level discussion can be found at - https://blog.ethereum.org/2014/07/11/toward-a-12-second-block-time/ - -Design decisions in our block time algorithm include: - -- **12 second block time**: 12 seconds was chosen as a time that is as - fast as possible, but is at the same time substantially longer than - network latency. A `2013 - paper `__ - by Decker and Wattenhofer in Zurich measures Bitcoin network latency, - and determines that 12.6 seconds is the time it takes for a new block - to propagate to 95% of nodes; however, the paper also points out that - the bulk of the propagation time is proportional to block size, and - thus in a faster currency we can expect the propagation time to be - drastically reduced. The constant portion of the propagation interval - is about 2 seconds; however, for safety we assume that blocks take 12 - seconds to propagate in our analysis. -- **7 block ancestor limit**: this is part of a design goal of wanting - to make block history very quickly "forgettable" after a small number - of blocks, and 7 blocks has been proven to provide most of the - desired effect -- **1 block descendant limit** (eg. ``c(c(p(p(p(head)))))``, where c = - child and p = parent, is invalid): this is part of a design goal of - simplicity, and the simulator above shows that it does not pose large - centralization risks. -- **Uncle validity requirements**: uncles have to be valid headers, not - valid blocks. This is done for simplicity, and to maintain the model - of a blockchain as being a linear data structure (and not a - block-DAG, as in Sompolinsky and Zohar's newer models). Requiring - uncles to be valid blocks is also a valid approach. -- **Reward distribution**: 7/8 of the base mining reward to the uncle, - 1/32 to the nephew, 0% of transaction fees to either. This will make - uncle incentivization ineffective from a centralization perspective - if fees dominate; however, this is one of the reasons why Ethereum is - meant to continue issuing ether for as long as we continue using PoW. - -Difficulty Update Algorithm ---------------------------- - -The difficulty in Ethereum is currently updated according to the -following rule: - -:: - - diff(genesis) = 2^32 - - diff(block) = diff.block.parent + floor(diff.block.parent / 1024) * - 1 if block.timestamp - block.parent.timestamp < 9 else - -1 if block.timestamp - block.parent.timestamp >= 9 - -The design goals behind the difficulty update rule are: - -- **Fast updating**: the time between blocks should readjust quickly - given increasing or decreasing hashpower -- **Low volatility**: the difficulty should not bounce excessively if - the hashpower is constant -- **Simplicity**: the algorithm should be relatively simple to - implement -- **Low memory**: the algorithm should not rely on more than a few - blocks of history, and should include as few "memory variables" as - possible. Assume that the last ten blocks, plus all memory variables - placed in the block headers of the last ten blocks, are all that is - available for the algorithm to work with -- **Non-exploitability**: the algorithm should not excessively - encourage miners to fiddle with timestamps, or mining pools to - repeatedly add and remove hashpower, in an attempt to maximize their - revenue - -We have already determined that our current algorithm is highly -suboptimal on low volatility and non-exploitability, and at the very -least we plan to switch the timestamps compares to be the parent and -grandparent, so that miners only have the incentive to modify timestamps -if they are mining two blocks in a row. Another more powerful formula -with simulations is located at -https://github.com/ethereum/economic-modeling/blob/master/diffadjust/blkdiff.py -(the simulator uses Bitcoin mining power, but uses the per-day average -for the entire day; it at one point simulates a 95% crash in a single -day). - -Gas and Fees ------------- - -Whereas all transactions in Bitcoin are roughly the same, and thus their -cost to the network can be modeled to a single unit, transactions in -Ethereum are more complex, and so a transaction fee system needs to take -into account many ingredients, including cost of bandwidth, cost of -storage and cost of computation. Of particular importance is the fact -that the Ethereum programming language is Turing-complete, and so -transactions may use bandwidth, storage and computation in arbitrary -quantities, and the latter may end up being used in quantities that due -to the halting problem cannot even be reliably predicted ahead of time. -Preventing denial-of-service attacks via infinite loops is a key -objective. - -The basic mechanism behind transaction fees is as follows: - -- Every transaction must specify a quantity of "gas" that it is willing - to consume (called ``startgas``), and the fee that it is willing to - pay per unit gas (``gasprice``). At the start of execution, - ``startgas * gasprice`` ether are removed from the transaction - sender's account. -- All operations during transaction execution, including database reads - and writes, messages, and every computational step taken by the - virtual machine consumes a certain quantity of gas. -- If a transaction execution processes fully, consuming less gas than - its specified limit, say with ``gas_rem`` gas remaining, then the - transaction executes normally, and at the end of the execution the - transaction sender receives a refund of ``gas_rem * gasprice`` and - the miner of the block receives a reward of - ``(startgas - gas_rem) * gasprice``. -- If a transaction "runs out of gas" mid-execution, then all execution - reverts, but the transaction is nevertheless valid, and the only - effect of the transaction is to transfer the entire sum - ``startgas * gasprice`` to the miner. -- When a contract sends a message to the other contract, it also has - the option to set a gas limit specifically on the sub-execution - arising out of that message. If the sub-execution runs out of gas, - then the sub-execution is reverted, but the gas is nevertheless - consumed. - -Each of the above components is necessary. For example: - -- If transactions did not need to specify a gas limit, then a malicious - user could send a transaction that makes a multi-billion round loop, - and no one would be able to process it since processing such a - transaction would take longer than a block interval, but miners would - not be able to tell beforehand, leading to a denial-of-service - vulnerability. -- The alternative to strict gas-counting, time-limiting, does not work - because it is too highly subjective (some machines are faster than - others, and even among identical machines close-calls will always - exist) -- The entire value ``startgas * gasprice`` has to be taken out at the - start as a deposit so that there arise no situations where an account - "bankrupts" itself mid-execution and becomes unable to pay for its - gas costs. Note that balance checking is not sufficient, because an - account can send its balance somewhere else. -- If execution did not revert in the event of an insufficient gas - error, then contracts would need to take strong and difficult - security measures to prevent themselves from being exploited by - transactions or messages that provide only enough gas halfway - through, thereby leading to some of the changes in a contract - execution being executed but not others. -- If sub-limits did not exist, then hostile accounts could enact a - denial-of-service attack against other contracts by entering into - agreements with them, and then inserting an infinite loop at the - beginning of computation so that any attempts by the victim contract - to compensate the attack contract or send a message to it would - starve the entire transaction execution. -- Requiring transaction senders to pay for gas instead of contracts - substantially increases developer usability. Very early versions of - Ethereum had contracts pay for gas, but this led to the rather ugly - problem that every contract had to implement "guard" code that would - make sure that every incoming message compensated the contract with - enough ether to pay for the gas that it consumed. - -Note the following particular features in gas costs: - -- 21000 gas is charged for any transaction as a "base fee". This covers - the cost of an elliptic curve operation to recover the sender address - from the signature as well as the disk and bandwidth space of storing - the transaction. -- A transaction can include an unlimited amount of "data", and there - exist opcodes in the virtual machine which allow the contract - receiving a transaction to access this data. The gas fee for data is - 1 gas per zero byte and 5 gas per nonzero byte. This formula arose - because we saw that most transaction data in contracts written by - users was organized into a series of 32-byte arguments, most of which - had many leading zero bytes, and given that such constructions seem - inefficient but are actually efficient due to compression algorithms, - we wanted to encourage their use in place of more complicated - mechanisms which would try to tightly pack arguments according to the - expected number of bytes, leading to very substantial complexity - increase at compiler level. This is an exception to the sandwich - complexity model, but a justified one due to the ratio of cost to - benefit. -- The cost of the SSTORE opcode, which sets values in account storage, - is either: (i) 20000 gas when changing a zero value to a nonzero - value, (ii) 5000 gas when changing a zero value to a zero value or a - nonzero value to a nonzero value, or (iii) 5000 gas when changing a - nonzero value to a zero value, plus a 20000 gas refund to be given at - the end of successful transaction execution (ie. NOT an execution - leading to an out-of-gas exception). Refunds are capped at 50% of the - total gas spent by a transaction. This provides a small incentive to - clear storage, as we noticed that lacking such an incentive many - contracts would leave storage unused, leading to quickly increasing - bloat, providing most of the benefits of "charging rent" for storage - without the cost of losing the assurance that a contract once placed - will continue to exist forever. The delayed refund mechanism is - necessary to prevent denial-of-service attacks where the attacker - sends a transaction with a low amount of gas that repeatedly clears a - large number of storage slots as part of a long-running loop, and - then runs out of gas, consuming a large amount of verifiers' - computing power without actually clearing storage or spending a lot - of gas. The 50% cap is needed to ensure that a miner given a - transaction with some quantity of gas can still determine an upper - bound on the computational time to execute the transaction. -- There is no gas cost to data in messages provided by contracts. This - is because there is no need to actually "copy" any data during a - message call, as the call data can simply be viewed as a pointer to - the parent contract's memory which will not change while the child - execution is in progress. -- Memory is an infinitely expandable array. However, there is a gas - cost of 1 per 32 bytes of memory expansion, rounding up. -- Some opcodes, whose computation time is highly argument-dependent, - have variable gas costs. For example, the gas cost of EXP is 10 + 10 - per byte in the exponent (ie. x^0 = 1 gas, x^1 ... x^255 = 2 gas, - x^256 ... x^65535 = 3 gas, etc), and the gas cost of the copy opcodes - (CALLDATACOPY, CODECOPY, EXTCODECOPY) is 1 + 1 per 32 bytes copies, - rounding up (LOG also has a similar rule). The memory expansion gas - cost is not sufficient to cover this, as it opens up a quadratic - attack (50000 rounds of CALLDATACOPY of 50000 gas ~= 50000^2 - computing effort, but only ~50000 gas before the variable gas cost - was introduced) -- The CALL opcode (and CALLCODE for symmetry) costs an additional 9000 - gas if the value is nonzero. This is because any value transfer - causes significant bloat to history storage for an archival node. - Note that the actual fee *charged* is 6700; on top of this we add a - mandatory 2300 gas minimum that is automatically given to the - recipient. This is in order to ensure that wallets that receive - transactions to at least have enough gas to make a log of the - transaction. - -The other important part of the gas mechanism is the economics of the -gas price itself. The default approach, used in Bitcoin, is to have -purely voluntary fees, relying on miners to act as the gatekeepers and -set dynamic minimums; the equivalent in Ethereum would be allowing -transaction senders to set arbitrary gas costs. This approach has been -received very favorably in the Bitcoin community particularly because it -is "market-based", allowing supply and demand between miners and -transaction senders determine the price. The problem with this line of -reasoning is, however, that transaction processing is not a market; -although it is intuitively attractive to construe transaction processing -as a service that the miner is offering to the sender, in reality every -transaction that a miner includes will need to be processed by every -node in the network, so the vast majority of the cost of transaction -processing is borne by third parties and not the miner that is making -the decision of whether or not to include it. Hence, -tragedy-of-the-commons problems are very likely to occur. - -Currently, due to a lack of clear information about how miners will -behave in reality, we are going with a fairly simple approach: a voting -system. Miners have the right to set the gas limit for the current block -to be within ~0.0975% (1/1024) of the gas limit of the last block, and -so the resulting gas limit should be the median of miners' preferences. -The hope is that in the future we will be able to soft-fork this into a -more precise algorithm. - -Virtual Machine ---------------- - -The Ethereum virtual machine is the engine in which transaction code -gets executed, and is the core differentiating feature between Ethereum -and other systems. Note that the *virtual machine* should be considered -separately from the *contract and message model* - for example, the -SIGNEXTEND opcode is a feature of the VM, but the fact that contracts -can call other contracts and specify gas limits to sub-calls is part of -the contract and message model. Design goals in the EVM include: - -- **Simplicity**: as few and as low-level opcodes as possible, as few - data types as possible and as few virtual-machine-level constructs as - possible -- **Total determinism**: there should be absolutely no room for - ambiguity in any part of the VM specification, and the results should - be completely deterministic. Additionally, there should be a precise - concept of computational step which can be measured so as to compute - gas consumption. -- **Space savings**: EVM assembly should be as compact as possible (eg. - the 4000 byte base size of default C programs is NOT acceptable) -- **Specialization to expected applications**: the ability to handle - 20-byte addresses and custom cryptography with 32-byte values, - modular arithmetic used in custom cryptography, read block and - transaction data, interact with state, etc -- **Simple security**: it should be easy to come up with a gas cost - model for operations that makes the VM non-exploitable -- **Optimization-friendliness**: it should be easy to apply - optimizations so that JIT-compiled and otherwise sped-up versions of - the VM can be built. - -Some particular design decisions that were made: - -- **Temporary/permanent storage distinction** - a distinction exists - between temporary storage, which exists within each instance of the - VM and disappears when VM execution finishes, and permanent storage, - which exists on the blockchain state level on a per-account basis. - For example, suppose the following tree of execution takes place - (using S for permanent storage and M for temporary): (i) A calls B, - (ii) B sets ``B.S[0] = 5``, ``B.M[0] = 9``, (iii) B calls C, (iv) C - calls B. At this point, if B tries to read ``B.S[0]``, it will - receive the value stored in B earlier, 5, but is B tries to read - ``B.M[0]`` it will receive 0 because it is a new instance of the - virtual machine with fresh temporary storage. If B now sets - ``B.M[0] = 13`` and ``B.S[0] = 17`` in this inner call, and then both - this inner call and C's call terminate, bringing the execution back - to B's outer call, then B reading M will see ``B.M[0] = 9`` (since - the last time this value was set was in the same VM execution - instance) and ``B.S[0] = 17``. If B's outer call ends and A calls B - again, then B will see ``B.M[0] = 0`` and ``B.S[0] = 17``. The - purpose of this distinction is to (1) provide each execution instance - with its own memory that is not subject to corruption by recursive - calls, making secure programming easier, and (2) to provide a form of - memory which can be manipulated very quickly, as storage updates are - necessarily slow due to the need to modify the trie. -- **Stack/memory model** - the decision was made early on to have three - types of computational state (aside from the program counter which - points to the next instruction): stack (a standard LIFO stack of - 32-byte values), memory (an infinitely expandable temporary byte - array) and storage (permanent storage). On the temporary storage - side, the alternative to stack and memory is a memory-only paradigm, - or some hybrid of registers and memory (not very different, as - registers basically are a kind of memory). In such a case, every - instruction would have three arguments, eg. - ``ADD R1 R2 R3: M[R1] = M[R2] + M[R3]``. The stack paradigm was - chosen for the obvious reason that it makes the code four times - smaller. -- **32 byte word size** - the alternative is 4 or 8 byte words, as in - most other architectures, or unlimited, as in Bitcoin. 4 or 8 byte - words are too restrictive to store addresses and big values for - crypto computations, and unlimited values are too hard to make a - secure gas model around. 32 bytes is ideal because it is just large - enough to store 32 byte values common in many crypto implementations, - as well as addresses (and provides the ability to pack address and - value into a single storage index as an optimization), but not so - large as to be extremely inefficient. -- **Having our own VM at all** - the alternative is reusing Java, or - some Lisp dialect, or Lua. We decided that having a specialized VM - was appropriate because (i) our VM spec is much simpler than many - other virtual machines, because other virtual machines have to pay a - much lower cost for complexity, whereas in our case every additional - unit of complexity is a step toward high barriers of entry creating - development centralization and potential for security flaws including - consensus failures, (ii) it allows us to specialize the VM much more, - eg. by having a 32 byte word size, (iii) it allows us not to have a - very complex external dependency which may lead to installation - difficulties, and (iv) a full security review of Ethereum specific to - our particular security needs would necessitate a security review of - the external VM anyway, so the effort savings are not that large. -- **Using a variable extendable memory size** - we deemed a fixed - memory size unnecessarily restrictive if the size is small and - unnecessarily expensive if the size is large, and noted that if - statements for memory access are necessary in any case to check for - out-of-bounds access, so fixed size would not even make execution - more efficient. -- **Not having a stack size limit** - no particular justification - either way; note that limits are not strictly necessary in many cases - as the combination of gas costs and a block-level gas limit will - always act as a ceiling on the consumption of every resource. -- **Having a 1024 call depth limit** - many programing languages break - at high stack depths much more quickly than they break at high levels - of memory usage or computational load, so the implied limit from the - block gas limit may not be sufficient. -- **No types** - done for simplicity. Instead, signed and unsigned - opcodes for DIV, SDIV, MOD, SMOD are used instead (it turns out that - for ADD and MUL the behavior of signed and unsigned opcodes is - equivalent), and the transformations for fixed point arithmetic - (high-depth fixed-point arithmetic is another benefit of 32-byte - words) are in all cases simple, eg. at 32 bits of depth, - ``a * b -> (a * b) / 2^32``, ``a / b -> a * 2^32 / b``, and +, - and - \* are unchanged from integer cases. - -The function and purpose of some opcodes in the VM is obvious, however -other opcodes are less so. Some particular justifications are given -below: - -- **ADDMOD**, **MULMOD**: in most cases, - ``addmod(a, b, c) = a * b % c``. However, in the specific case of - many classes of elliptic curve cryptography, 32-byte modular - arithmetic is used, and doing ``a * b % c`` directly is therefore - actually doing ``((a * b) % 2^256) % c``, which gives a completely - different result. A formula that calculates ``a * b % c`` with - 32-byte values in 32 bytes of space is rather nontrivial and bulky. -- **SIGNEXTEND**: the purpose of SIGNEXTEND is to facilitate - typecasting from a larger signed integer to a smaller signed integer. - Small signed integers are useful because JIT-compiled virtual - machines may in the future be able to detect long-running chunks of - code that deals primarily with 32-byte integers and speed it up - considerably. -- **SHA3**: SHA3 is very highly applicable in Ethereum code as secure - infinite-sized hash maps that use storage will likely need to use a - secure hash function so as to prevent malicious collisions, as well - as for verifying Merkle trees and even verifying Ethereum-like data - structures. A key point is that its companions ``SHA256``, - ``ECRECOVER`` and ``RIPEMD160`` are included not as opcodes but as - pseudo-contracts. The purpose of this is to place them into a - separate category so that, if/when we come up with a proper "native - extensions" system later, more such contracts can be added without - filling up the opcode space. -- **ORIGIN**: the primary use of the ORIGIN opcode, which provides the - sender of a transaction, is to allow contracts to make refund - payments for gas. -- **COINBASE**: the primary uses of the COINBASE opcode are to (i) - allow sub-currencies to contribute to network security if they so - choose, and (ii) open up the use of miners as a decentralized - economic set for sub-consensus-based applications like Schellingcoin. -- **PREVHASH**: used as a semi-secure source of randomness, and to - allow contracts to evaluate Merkle tree proofs of state in the - previous block without requiring a highly complex recursive "Ethereum - light client in Ethereum" construction. -- **EXTCODESIZE**, **EXTCODECOPY**: the primary uses here are to allow - contracts to check the code of other contracts against a template, or - even simulating them, before interacting with them. See - http://lesswrong.com/lw/aq9/decision\_theories\_a\_less\_wrong\_primer/ - for applications. -- **JUMPDEST**: JIT-compiled virtual machines become much easier to - implement when jump destinations are restricted to a few indices - (specifically, the computational complexity of a variable-destination - jump is roughly O(log(number of valid jump destinations)), although - static jumps are always constant-time). Hence, we need (i) a - restriction on valid variable jump destinations, and (ii) an - incentive to use static over dynamic jumps. To meet both goals, we - have the rules that (i) jumps that are immediately preceded by a push - can jump anywhere but another jump, and (ii) other jumps can only - jump to a JUMPDEST. The restriction against jumping on jumps is - needed so that the question of whether a jump is dynamic or static - can be determined by simply looking at the previous operation in the - code. The lack of a need for JUMPDEST operations for static jumps is - the incentive to use them. The prohibition against jumping into push - data also speeds up JIT VM compilation and execution. -- **LOG**: LOG is meant to log events, see trie usage section above. -- **CALLCODE**: the purpose of this is to allow contracts to call - "functions" in the form of code stored in other contracts, with a - separate stack and memory, but using the contract's own storage. This - makes it much easier to scalably implement "standard libraries" of - code on the blockchain. -- **SUICIDE**: an opcode which allows a contract to quickly delete - itself if it is no longer needed. The fact that SUICIDES are - processed at the end of transaction execution, and not immediately, - is motivated by the fact that having the ability to revert suicides - that were already executed would substantially increase the - complexity of the cache that would be required in an efficient VM - implementation. -- **PC**: although theoretically not necessary, as all instances of the - PC opcode can be replaced by simply putting in the actual program - counter at that index as a push, using PC in code allows for the - creation of position-independent code (ie. compiled functions which - can be copy/pasted into other contracts, and do not break if they end - up at different indices). - -.. |image0| image:: https://bitcoin.org/img/dev/en-transaction-propagation.svg diff --git a/old-docs-for-reference/main-wiki.rst/Deterministic_Wallet_Spec.rst b/old-docs-for-reference/main-wiki.rst/Deterministic_Wallet_Spec.rst deleted file mode 100644 index 0c5c3a9..0000000 --- a/old-docs-for-reference/main-wiki.rst/Deterministic_Wallet_Spec.rst +++ /dev/null @@ -1,23 +0,0 @@ -Address/key generation - -The following is a proposed deterministic wallet specification. - -Let ``S`` be the secret. We define -``key(i) = sha3(S + zpad(int_to_big_endian(i), 32))``, where ``i`` is an -incrementing index starting at 0 - -Assuming ``S = "123dog"``, we thus have: - -:: - - key(0) = sha3("123dog\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00") - -Note that the big endian representation of 0 is the empty string. - -:: - - key(1) = sha3("123dog\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01") - key(2) = sha3("123dog\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02") - key(255) = sha3("123dog\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff") - key(256) = sha3("123dog\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00") - key(4294967297) = sha3("123dog\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x01") diff --git a/old-docs-for-reference/main-wiki.rst/Distributed-Preimage-Archive.rst b/old-docs-for-reference/main-wiki.rst/Distributed-Preimage-Archive.rst deleted file mode 100644 index 0b528c0..0000000 --- a/old-docs-for-reference/main-wiki.rst/Distributed-Preimage-Archive.rst +++ /dev/null @@ -1,160 +0,0 @@ -Purpose -======= - -DPA stores small pieces of information (preimage objects, arbitrary -strings of bytes of limited length) retrievable by their (cryptographic) -hash value. Thus, preimage objects stored in DPA have implicit integrity -protection. The hash function used for key assignment is assumed to be -collision-free, meaning that colliding keys for different preimage -objects are assumed to be practically impossible. - -DPA serves as a fast, redundant store optimized for speedy retrieval and -long-term reliability. Its most frequent use within Ethereum is to cache -objects that can be retrieved and/or re-constructed by other means at -significant cost. Since the key is derived from the preimage, there is -no sense in which we can talk about multiple or alternative values for -keys, the store is immutable. - -High-level design -================= - -DPA is organized as a DHT (Distributed Hash Table): each participating -node has an address (resolved into a network address by the p2p layer) -coming from the same value set as the range of the hash function. In -particular it is the hash of the public key (NodeID field of the DEVP2P -handshake). - -There is a distance measure defined over this value set that is a proper -metric satisfying the triangle inequality. It is always possible to tell -how far another node or another preimage object is from a given address -or hash value. The distance from self is zero. - -Each node is interested in being able to find preimages to hash values -as fast as possible and therefore stores as many preimages as it can -itself. Whenever it must decide which preimage object to store and which -to discard, preference is given to objects with an address that is -closer. In practical terms, it is always the farthest preimage object -that is discarded when a node runs short of storage capacity. Thus, each -node ends up storing preimage objects within a given radius limited by -available storage capacity. The cryptographic hash function takes care -of randomization and fair load balancing. - -Nodes provide the following services through a public network API: - -1. Inserting new preimages into DPA -2. Retrieving preimages from their own storage, if they have it. -3. Sharing routing information to a given node address - -Locally, in addition to the above, nodes also provide the service of -storing and retrieving large chunks of data. When storing, the data is -disassembled into a tree of blocks according to a scheme resulting in -the key corresponding to the root block. Given the key of the root block -the data can then can be reassembled with the help of recursively -retrieving the blocks in the tree. - -Queries -------- - -Insert -~~~~~~ - -When receiving a preimage that is not already present in its local -storage, the node stores it locally. If the storage allocated by the -node for the archive is full, the object accessed the longest time ago -is discarded. Note that this policy implicitly results in storing the -objects closer to the node's address, as - all else being equal - those -are the ones which are most likely to get queried from this particular -node, due to the lookup strategy detailed below. - -After storing the preimage, the insert request is also forwarded to all -the nodes in the corresponding row of the routing table. Note that the -kademlia routing makes sure that the row in the close proximity of a -node actually contains nodes further out than self thereby taking care -of storage redundancy. However, in order to mitigate against node drop -out preimages, especially those with hashes in the node's proximity, -need to be re-broadcast, albeit with a very low frequency. - -When a node received a store request, it remembers it for a while and -does not forward the same request. This is needed to avoid redundant -network traffic. - -Retrieve -~~~~~~~~ - -Retrieval requests have the following parameters: - -1. The hash of the queried pre-image -2. Timeout value for routed retrieval, zero if routing is not required - -If the node has the pre-image, it is returned, called a delivery. -Otherwise, the following happens: - -1. The entire row in the Kademlia table corresponding to the queried - hash is returned. -2. If routing is deemed not worth the effort (timeout is too short), - this fact is also communicated. -3. Otherwise, the same query is recursively done and if it succeeds - within the specified timeout, the result is sent to the querying - node. - -Successfully found pre-images are automatically re-inserted into DPA. - -A default time estimate for retrieval is calculated in proportion to the -expected hop-distance from the node closest to the queried preimage. If -this time is outside of the timeout parameter in the request, the -request is not routed. - -Each node in the row corresponding to the queried preimage is -sequentially queried in order of increasing distance from the target -hash. The query is forwarded with a timeout value set to the maximum of -the above estimate and the total timeout divided by the number of nodes -in the row. If the preimage is found or the time elapsed is in excess of -the received timeout value, processing of the query is aborted with -timeout. - -From the set up of the first forward onwards, all retrieval requests of -the same target are remembered in a request pool. If the data results in -successful retrieval and the preimage is stored, the requests are -answered by returning the preimage object to each requesting node -whether forwarding or originator. The pool of requesting nodes then can -be forgotten, since all further queries can be responded with the object -delivery. - -BZZ protocol spec ------------------ - -**Handshake** - -``[0x01, protocolVersion: B_32, strategy: B_32, capacity: B_64, peers: B_8]`` - -**Storing** - -``[+0x02, key: B_256, metadata: [], data: B_4k]``: the data chunk to be -stored, preceded by its key. - -**Retrieving** - -``[0x03, key: B_256, timeout: B_64, metadata: []]``: key of the data -chunk to be retrieved, timeout in milliseconds. Note that zero timeout -retrievals serve also as messages to retrieve peers. - -**Peers** - -``[0x04, key: B_256, timeout: B_64, peers: [[peer], [peer], .... ]]`` -the encoding of a peer is identical to that in the devp2p base protocol -peers messages: ``[IP, Port, NodeID]`` note that a node's DPA address is -not the NodeID but the hash of the NodeID. Timeout serves to indicate -whether the responder is forwarding the query within the timeout or not. - -**Delivery** - -``[0x05, key: B_256, metadata: [], data: B_4k]``: the delivery response -to retrieval queries. - -Routing -------- - -It is based on Kademlia's routing. -`details `__ - -*to be continued...* diff --git a/old-docs-for-reference/main-wiki.rst/Ethash-C-API.rst b/old-docs-for-reference/main-wiki.rst/Ethash-C-API.rst deleted file mode 100644 index 80ba6a8..0000000 --- a/old-docs-for-reference/main-wiki.rst/Ethash-C-API.rst +++ /dev/null @@ -1,58 +0,0 @@ -This is just a documentation of the request of the C API described in -`this PR `__. - -.. code:: c - - typedef int(*Callback)(unsigned); - typedef /*...*/ ethash_light_t; - typedef /*...*/ ethash_full_t; - typedef struct ethash_h256 { uint8_t b[32]; } ethash_h256_t; - typedef struct ethash_result { ethash_h256_t value; ethash_h256_t hixhash; } ethash_result_t; - - ethash_light_t ethash_light_new(unsigned number); - ethash_result_t ethash_light_compute(ethash_light_t light, ethash_h256_t header_hash, uint64_t nonce); - void ethash_light_delete(ethash_light_t light); - - ethash_full_t ethash_full_new(ethash_light_t light, CallBack c); - uint64_t ethash_full_dag_size(ethash_full_t full); - void const* ethash_full_dag(ethash_full_t full); - ethash_result_t ethash_full_compute(ethash_full_t full, ethash_h256_t header_hash, uint64_t nonce); - void ethash_full_delete(ethash_full_t full); - -non-zero return from Callback means "cancel DAG creation" - this should -cause an immediate return of ``ethash_full_new`` with 0. - -an object of type ``ethash_full_t`` may be tested for validity with != 0 - -Example usage: -~~~~~~~~~~~~~~ - -.. code:: c - - int callback(unsigned _progress) - { - printf("\rGenerating DAG. %d%% done...", _progress); - return 0; - } - void main() - { - ethash_light_t light; - ethash_h256_t seed; - // TODO: populate p, seed, light - ethash_full_t dag = ethash_full_new(light, seed, &callback); - if (!dag) - { - printf("Failed generating DAG :-(\n"); - exit(-1); - } - printf("DAG Generated OK!\n"); - - ethash_h256_t headerHash; - // TODO: populate headerHash - uint64_t nonce = time(0); - ethash_result ret; - for (; !isWinner(ret); nonce++) - ret = ethash_full_compute(dag, headerHash, nonce); - printf("Got winner! nonce is %d\n", nonce); - ethash_full_delete(dag); - } diff --git a/old-docs-for-reference/main-wiki.rst/Ethash-DAG-Disk-Storage-Format.rst b/old-docs-for-reference/main-wiki.rst/Ethash-DAG-Disk-Storage-Format.rst deleted file mode 100644 index 045adf1..0000000 --- a/old-docs-for-reference/main-wiki.rst/Ethash-DAG-Disk-Storage-Format.rst +++ /dev/null @@ -1,39 +0,0 @@ -Ethash is the PoW system. It requires a great huge dataset known as the -DAG (name refers to `Dagger -Hashimoto `__). -This takes a good long while to generate which is a pain. As such we -tend to memoise it. Clients wishing to store the DAG in a cache should -conform to this spec in order to share the cache with other clients: - -Location -^^^^^^^^ - -The DAG should be stored in a 1GB dump (for the initial epoch, anyway), -in a file: - -- Mac/Linux: ``$(HOME)/.ethash/full-R-`` -- Windows: ``$(HOME)/Appdata/Local/Ethash/full-R-`` - -Where: - -- ```` is a decimal integer, given as the C-constant - ``REVISION`` in ``libethash/ethash.h``; -- ```` is 16 lowercase hex digits specifying the first 8 - bytes of the epoch's seed hash. - -There may be many such DAGs stored in this directory; it is up to the -client and/or user to remove out of date ones. - -Format -^^^^^^ - -Each file should begin with an 8-byte magic number, -``0xfee1deadbaddcafe``, written in little-endian format (i.e., bytes -``fe ca dd ba ad de e1 fe``). - -The Ethash algorithm expects the DAG as a two-dimensional array of -uint32s (4-byte unsigned ints), with dimension (n × 16) where n is a -large number. (n starts at 16777186 and grows from there.) Following the -magic number, the rows of the DAG should be written sequentially into -the file, with no delimiter between rows and each unint32 encoded in -little-endian format. diff --git a/old-docs-for-reference/main-wiki.rst/Ethash-DAG.rst b/old-docs-for-reference/main-wiki.rst/Ethash-DAG.rst deleted file mode 100644 index 9720ddd..0000000 --- a/old-docs-for-reference/main-wiki.rst/Ethash-DAG.rst +++ /dev/null @@ -1,5 +0,0 @@ -assasallah - -hu - -akbar diff --git a/old-docs-for-reference/main-wiki.rst/Ethash-Design-Rationale.rst b/old-docs-for-reference/main-wiki.rst/Ethash-Design-Rationale.rst deleted file mode 100644 index 88ec4e9..0000000 --- a/old-docs-for-reference/main-wiki.rst/Ethash-Design-Rationale.rst +++ /dev/null @@ -1,66 +0,0 @@ -Ethash is intended to satisfy the following goals: - -1. **IO saturation**: The algorithm should consume nearly the entire - available memory access bandwidth (this is a strategy toward - achieving ASIC resistance, the argument being that commodity RAM, - especially in GPUs, is much closer to the theoretical optimum than - commodity computing capacity) -2. **GPU friendliness**: We try to make it as easy as possible to mine - with GPUs. Targeting CPUs is almost certainly impossible, as - potential specialization gains are too great, and there do exist - criticisms of CPU-friendly algorithms that they are vulnerable to - botnets, so we target GPUs as a compromise. -3. **Light client verifiability**: a light client should be able to - verify a round of mining in under 0.01 seconds on a desktop in C, and - under 0.1 seconds in Python or Javascript, with at most 1 MB of - memory (but exponentially increasing) -4. **Light client slowdown**: the process of running the algorithm with - a light client should be much slower than the process with a full - client, to the point that the light client algorithm is not an - economically viable route toward making a mining implementation, - including via specialized hardware. -5. **Light client fast startup**: a light client should be able to - become fully operational and able to verify blocks within 40 seconds - in Javascript. - -FNV -~~~ - -FNV was used to provide a data aggregation function which is (i) -non-associative, and (ii) easy to compute. A commutative and associative -alternative to FNV would be XOR. - -Parameters -~~~~~~~~~~ - -- A 16 MB cache was chosen because a smaller cache would allow for an - ASIC to be produced far too easily using the light-evaluation method. - The 16 MB cache still requires a very high bandwidth of cache - reading, whereas a smaller cache could be much more easily optimized. - A larger cache would lead to the algorithm being too hard to evaluate - with a light client. -- 256 parents per DAG item was chosen in order to ensure that - time-memory tradeoffs can only be made at a worse-than-1:1 ratio. -- The 1 GB DAG size was chosen in order to require a level of memory - larger than the size at which most specialized memories and caches - are built, but still small enough for ordinary computers to be able - to mine with it. -- The ~0.73x per year growth level was chosen to roughly be balanced - with Moore's law increases at least initially (exponential growth has - a risk of overshooting Moore's law, leading to a situation where - mining requires very large amounts of memory and ordinary GPUs are no - longer usable for mining). -- 64 accesses was chosen because a larger number of accesses would lead - to light verification taking too long, and a smaller number would - mean that the bulk of the time consumption is the SHA3 at the end, - not the memory reads, making the algorithm not so strongly IO-bound. -- The epoch length cannot be infinite (ie. constant dataset) because - then the algorithm could be optimized via ROM, and very long epoch - lengths make it easier to create memory which is designed to be - updated very infrequently and only read often. Excessively short - epochs would increase barriers to entry as weak machines would need - to spend much of their time on a fixed cost of updating the dataset. - The epoch length can probably be reduced or increased substantially - if design considerations require it. -- The cache size and dataset size is prime in order to help mitigate - the risk of cycles appearing in dataset item generation or mining. diff --git a/old-docs-for-reference/main-wiki.rst/Ethash.rst b/old-docs-for-reference/main-wiki.rst/Ethash.rst deleted file mode 100644 index db47c68..0000000 --- a/old-docs-for-reference/main-wiki.rst/Ethash.rst +++ /dev/null @@ -1,1057 +0,0 @@ -**This spec is REVISION 23. Whenever you substantively (ie. not -clarifications) update the algorithm, please update the revision number -in this sentence. Also, in all implementations please include a spec -revision number** - -Ethash is the planned PoW algorithm for Ethereum 1.0. It is the latest -version of Dagger-Hashimoto, although it can no longer appropriately be -called that since many of the original features of both algorithms have -been drastically changed in the last month of research and development. -See https://github.com/ethereum/wiki/wiki/Dagger-Hashimoto for the -original version. - -The general route that the algorithm takes is as follows: - -1. There exists a **seed** which can be computed for each block by - scanning through the block headers up until that point. -2. From the seed, one can compute a **16 MB pseudorandom cache**. Light - clients store the cache. -3. From the cache, we can generate a **1 GB dataset**, with the property - that each item in the dataset depends on only a small number of items - from the cache. Full clients and miners store the dataset. The - dataset grows linearly with time. -4. Mining involves grabbing random slices of the dataset and hashing - them together. Verification can be done with low memory by using the - cache to regenerate the specific pieces of the dataset that you need, - so you only need to store the cache. - -The large dataset is updated once every 30000 blocks, so the vast -majority of a miner's effort will be reading the dataset, not making -changes to it. - -See https://github.com/ethereum/wiki/wiki/Ethash-Design-Rationale for -design rationale considerations for this algorithm. - -Definitions -~~~~~~~~~~~ - -We employ the following definitions: - -:: - - WORD_BYTES = 4 # bytes in word - DATASET_BYTES_INIT = 2**30 # bytes in dataset at genesis - DATASET_BYTES_GROWTH = 2**23 # dataset growth per epoch - CACHE_BYTES_INIT = 2**24 # bytes in dataset at genesis - CACHE_BYTES_GROWTH = 2**17 # cache growth per epoch - CACHE_MULTIPLIER=1024 # Size of the DAG relative to the cache - EPOCH_LENGTH = 30000 # blocks per epoch - MIX_BYTES = 128 # width of mix - HASH_BYTES = 64 # hash length in bytes - DATASET_PARENTS = 256 # number of parents of each dataset element - CACHE_ROUNDS = 3 # number of rounds in cache production - ACCESSES = 64 # number of accesses in hashimoto loop - -Parameters -~~~~~~~~~~ - -The parameters for Ethash's cache and dataset depend on the block -number. The cache size and dataset size both grow linearly; however, we -always take the highest prime below the linearly growing threshold in -order to reduce the risk of accidental regularities leading to cyclic -behavior. - -.. code:: python - - def get_cache_size(block_number): - sz = CACHE_BYTES_INIT + CACHE_BYTES_GROWTH * (block_number // EPOCH_LENGTH) - sz -= HASH_BYTES - while not isprime(sz / HASH_BYTES): - sz -= 2 * HASH_BYTES - return sz - - def get_full_size(block_number): - sz = DATASET_BYTES_INIT + DATASET_BYTES_GROWTH * (block_number // EPOCH_LENGTH) - sz -= MIX_BYTES - while not isprime(sz / MIX_BYTES): - sz -= 2 * MIX_BYTES - return sz - -Tables of dataset and cache size values are provided in the appendix. - -Cache Generation -~~~~~~~~~~~~~~~~ - -Now, we specify the function for producing a cache: - -.. code:: python - - def mkcache(cache_size, seed): - n = cache_size // HASH_BYTES - - # Sequentially produce the initial dataset - o = [sha3_512(seed)] - for i in range(1, n): - o.append(sha3_512(o[-1])) - - # Use a low-round version of randmemohash - for _ in range(CACHE_ROUNDS): - for i in range(n): - v = o[i][0] % n - o[i] = sha3_512(map(xor, o[(i-1+n) % n], o[v])) - - return o - -The cache production process involves first sequentially filling up 32 -MB of memory, then performing two passes of Sergio Demian Lerner's -*RandMemoHash* algorithm from `*Strict Memory Hard Hashing Functions* -(2014) `__. The output is a -set of 524288 64-byte values. - -Data aggregation function -~~~~~~~~~~~~~~~~~~~~~~~~~ - -We use an algorithm inspired by the `FNV -hash `__ -in some cases as a non-associative substitute for XOR. Note that we -multiply the prime with the full 32-bit input, in contrast with the -FNV-1 spec which multiplies the prime with one byte (octet) in turn. - -.. code:: python - - FNV_PRIME = 0x01000193 - - def fnv(v1, v2): - return (v1 * FNV_PRIME ^ v2) % 2**32 - -Full dataset calculation -~~~~~~~~~~~~~~~~~~~~~~~~ - -Each 64-byte item in the full 1 GB dataset is computed as follows: - -.. code:: python - - def calc_dataset_item(cache, i): - n = len(cache) - r = HASH_BYTES // WORD_BYTES - # initialize the mix - mix = copy.copy(cache[i % n]) - mix[0] ^= i - mix = sha3_512(mix) - # fnv it with a lot of random cache nodes based on i - for j in range(DATASET_PARENTS): - cache_index = fnv(i ^ j, mix[j % r]) - mix = map(fnv, mix, cache[cache_index % n]) - return sha3_512(mix) - -Essentially, we combine data from 256 pseudorandomly selected cache -nodes, and hash that to compute the dataset node. The entire dataset is -then generated by: - -.. code:: python - - def calc_dataset(full_size, cache): - return [calc_dataset_item(cache, i) for i in range(full_size // HASH_BYTES)] - -Main Loop -~~~~~~~~~ - -Now, we specify the main "hashimoto"-like loop, where we aggregate data -from the full dataset in order to produce our final value for a -particular header and nonce. In the code below, ``header`` represents -the SHA3-256 *hash* of the RLP representation of a *truncated* block -header, that is, of a header excluding the fields **mixHash** and -**nonce**. ``nonce`` is the eight bytes of a 64 bit unsigned integer in -big-endian order. So ``nonce[::-1]`` is the eight-byte little-endian -representation of that value: - -.. code:: python - - def hashimoto(header, nonce, full_size, dataset_lookup): - n = full_size / HASH_BYTES - w = MIX_BYTES // WORD_BYTES - mixhashes = MIX_BYTES / HASH_BYTES - # combine header+nonce into a 64 byte seed - s = sha3_512(header + nonce[::-1]) - # start the mix with replicated s - mix = [] - for _ in range(MIX_BYTES / HASH_BYTES): - mix.extend(s) - # mix in random dataset nodes - for i in range(ACCESSES): - p = fnv(i ^ s[0], mix[i % w]) % (n // mixhashes) * mixhashes - newdata = [] - for j in range(MIX_BYTES / HASH_BYTES): - newdata.extend(dataset_lookup(p + j)) - mix = map(fnv, mix, newdata) - # compress mix - cmix = [] - for i in range(0, len(mix), 4): - cmix.append(fnv(fnv(fnv(mix[i], mix[i+1]), mix[i+2]), mix[i+3])) - return { - "mix digest": serialize_hash(cmix), - "result": serialize_hash(sha3_256(s+cmix)) - } - - def hashimoto_light(full_size, cache, header, nonce): - return hashimoto(header, nonce, full_size, lambda x: calc_dataset_item(cache, x)) - - def hashimoto_full(full_size, dataset, header, nonce): - return hashimoto(header, nonce, full_size, lambda x: dataset[x]) - -Essentially, we maintain a "mix" 128 bytes wide, and repeatedly -sequentially fetch 128 bytes from the full dataset and use the ``fnv`` -function to combine it with the mix. 128 bytes of sequential access are -used so that each round of the algorithm always fetches a full page from -RAM, minimizing translation lookaside buffer misses which ASICs would -theoretically be able to avoid. - -If the output of this algorithm is below the desired target, then the -nonce is valid. Note that the extra application of ``sha3_256`` at the -end ensures that there exists an intermediate nonce which can be -provided to prove that at least a small amount of work was done; this -quick outer PoW verification can be used for anti-DDoS purposes. It also -serves to provide statistical assurance that the result is an unbiased, -256 bit number. - -Mining -~~~~~~ - -The mining algorithm is defined as follows: - -.. code:: python - - def mine(full_size, dataset, header, difficulty): - target = zpad(encode_int(2**256 // difficulty), 64)[::-1] - from random import randint - nonce = randint(0, 2**64) - while hashimoto_full(full_size, dataset, header, nonce) > target: - nonce = (nonce + 1) % 2**64 - return nonce - -Defining the Seed Hash -~~~~~~~~~~~~~~~~~~~~~~ - -In order to compute the seed hash that would be used to mine on top of a -given block, we use the following algorithm: - -.. code:: python - - def get_seedhash(block): - s = '\x00' * 32 - for i in range(block.number // EPOCH_LENGTH): - s = serialize_hash(sha3_256(s)) - return s - -Note that for smooth mining and verifying, we recommend pre-computing -future seedhashes and datasets in a separate thread. - -Appendix -~~~~~~~~ - -The following code should be prepended if you are interested in running -the above python spec as code. - -.. code:: python - - import sha3, copy - - # Assumes little endian bit ordering (same as Intel architectures) - def decode_int(s): - return int(s[::-1].encode('hex'), 16) if s else 0 - - def encode_int(s): - a = "%x" % s - return '' if s == 0 else ('0' * (len(a) % 2) + a).decode('hex')[::-1] - - def zpad(s, length): - return s + '\x00' * max(0, length - len(s)) - - def serialize_hash(h): - return ''.join([zpad(encode_int(x), 4) for x in h]) - - def deserialize_hash(h): - return [decode_int(h[i:i+WORD_BYTES]) for i in range(0, len(h), WORD_BYTES)] - - def hash_words(h, sz, x): - if isinstance(x, list): - x = serialize_hash(x) - y = h(x) - return deserialize_hash(y) - - def serialize_cache(ds): - return ''.join([serialize_hash(h) for h in ds]) - - serialize_dataset = serialize_cache - - # sha3 hash function, outputs 64 bytes - def sha3_512(x): - return hash_words(lambda v: sha3.sha3_512(v).digest(), 64, x) - - def sha3_256(x): - return hash_words(lambda v: sha3.sha3_256(v).digest(), 32, x) - - def xor(a, b): - return a ^ b - - def isprime(x): - for i in range(2, int(x**0.5)): - if x % i == 0: - return False - return True - -Data Sizes -~~~~~~~~~~ - -The following lookup tables provide approximately 2048 tabulated epochs -of data sizes and cache sizes. They were generated with the -*Mathematica* function provided here: - -.. code:: python - - def get_datasize(block_number): - return data_sizes[block_number // EPOCH_LENGTH] - - def get_cachesize(block_number): - return cache_sizes[block_number // EPOCH_LENGTH] - - data_sizes = [ - 1073739904, 1082130304, 1090514816, 1098906752, 1107293056, - 1115684224, 1124070016, 1132461952, 1140849536, 1149232768, - 1157627776, 1166013824, 1174404736, 1182786944, 1191180416, - 1199568512, 1207958912, 1216345216, 1224732032, 1233124736, - 1241513344, 1249902464, 1258290304, 1266673792, 1275067264, - 1283453312, 1291844992, 1300234112, 1308619904, 1317010048, - 1325397376, 1333787776, 1342176128, 1350561664, 1358954368, - 1367339392, 1375731584, 1384118144, 1392507008, 1400897408, - 1409284736, 1417673344, 1426062464, 1434451072, 1442839168, - 1451229056, 1459615616, 1468006016, 1476394112, 1484782976, - 1493171584, 1501559168, 1509948032, 1518337664, 1526726528, - 1535114624, 1543503488, 1551892096, 1560278656, 1568669056, - 1577056384, 1585446272, 1593831296, 1602219392, 1610610304, - 1619000192, 1627386752, 1635773824, 1644164224, 1652555648, - 1660943488, 1669332608, 1677721216, 1686109312, 1694497664, - 1702886272, 1711274624, 1719661184, 1728047744, 1736434816, - 1744829056, 1753218944, 1761606272, 1769995904, 1778382464, - 1786772864, 1795157888, 1803550592, 1811937664, 1820327552, - 1828711552, 1837102976, 1845488768, 1853879936, 1862269312, - 1870656896, 1879048064, 1887431552, 1895825024, 1904212096, - 1912601216, 1920988544, 1929379456, 1937765504, 1946156672, - 1954543232, 1962932096, 1971321728, 1979707264, 1988093056, - 1996487552, 2004874624, 2013262208, 2021653888, 2030039936, - 2038430848, 2046819968, 2055208576, 2063596672, 2071981952, - 2080373632, 2088762752, 2097149056, 2105539712, 2113928576, - 2122315136, 2130700672, 2139092608, 2147483264, 2155872128, - 2164257664, 2172642176, 2181035392, 2189426048, 2197814912, - 2206203008, 2214587264, 2222979712, 2231367808, 2239758208, - 2248145024, 2256527744, 2264922752, 2273312128, 2281701248, - 2290086272, 2298476672, 2306867072, 2315251072, 2323639168, - 2332032128, 2340420224, 2348808064, 2357196416, 2365580416, - 2373966976, 2382363008, 2390748544, 2399139968, 2407530368, - 2415918976, 2424307328, 2432695424, 2441084288, 2449472384, - 2457861248, 2466247808, 2474637184, 2483026816, 2491414144, - 2499803776, 2508191872, 2516582272, 2524970368, 2533359232, - 2541743488, 2550134144, 2558525056, 2566913408, 2575301504, - 2583686528, 2592073856, 2600467328, 2608856192, 2617240448, - 2625631616, 2634022016, 2642407552, 2650796416, 2659188352, - 2667574912, 2675965312, 2684352896, 2692738688, 2701130624, - 2709518464, 2717907328, 2726293376, 2734685056, 2743073152, - 2751462016, 2759851648, 2768232832, 2776625536, 2785017728, - 2793401984, 2801794432, 2810182016, 2818571648, 2826959488, - 2835349376, 2843734144, 2852121472, 2860514432, 2868900992, - 2877286784, 2885676928, 2894069632, 2902451584, 2910843008, - 2919234688, 2927622784, 2936011648, 2944400768, 2952789376, - 2961177728, 2969565568, 2977951616, 2986338944, 2994731392, - 3003120256, 3011508352, 3019895936, 3028287104, 3036675968, - 3045063808, 3053452928, 3061837696, 3070228352, 3078615424, - 3087003776, 3095394944, 3103782272, 3112173184, 3120562048, - 3128944768, 3137339264, 3145725056, 3154109312, 3162505088, - 3170893184, 3179280256, 3187669376, 3196056704, 3204445568, - 3212836736, 3221224064, 3229612928, 3238002304, 3246391168, - 3254778496, 3263165824, 3271556224, 3279944576, 3288332416, - 3296719232, 3305110912, 3313500032, 3321887104, 3330273152, - 3338658944, 3347053184, 3355440512, 3363827072, 3372220288, - 3380608384, 3388997504, 3397384576, 3405774208, 3414163072, - 3422551936, 3430937984, 3439328384, 3447714176, 3456104576, - 3464493952, 3472883584, 3481268864, 3489655168, 3498048896, - 3506434432, 3514826368, 3523213952, 3531603584, 3539987072, - 3548380288, 3556763264, 3565157248, 3573545344, 3581934464, - 3590324096, 3598712704, 3607098752, 3615488384, 3623877248, - 3632265856, 3640646528, 3649043584, 3657430144, 3665821568, - 3674207872, 3682597504, 3690984832, 3699367808, 3707764352, - 3716152448, 3724541056, 3732925568, 3741318016, 3749706368, - 3758091136, 3766481536, 3774872704, 3783260032, 3791650432, - 3800036224, 3808427648, 3816815488, 3825204608, 3833592704, - 3841981568, 3850370432, 3858755968, 3867147904, 3875536256, - 3883920512, 3892313728, 3900702592, 3909087872, 3917478784, - 3925868416, 3934256512, 3942645376, 3951032192, 3959422336, - 3967809152, 3976200064, 3984588416, 3992974976, 4001363584, - 4009751168, 4018141312, 4026530432, 4034911616, 4043308928, - 4051695488, 4060084352, 4068472448, 4076862848, 4085249408, - 4093640576, 4102028416, 4110413696, 4118805632, 4127194496, - 4135583104, 4143971968, 4152360832, 4160746112, 4169135744, - 4177525888, 4185912704, 4194303616, 4202691968, 4211076736, - 4219463552, 4227855488, 4236246656, 4244633728, 4253022848, - 4261412224, 4269799808, 4278184832, 4286578048, 4294962304, - 4303349632, 4311743104, 4320130432, 4328521088, 4336909184, - 4345295488, 4353687424, 4362073472, 4370458496, 4378852736, - 4387238528, 4395630208, 4404019072, 4412407424, 4420790656, - 4429182848, 4437571456, 4445962112, 4454344064, 4462738048, - 4471119232, 4479516544, 4487904128, 4496289664, 4504682368, - 4513068416, 4521459584, 4529846144, 4538232704, 4546619776, - 4555010176, 4563402112, 4571790208, 4580174464, 4588567936, - 4596957056, 4605344896, 4613734016, 4622119808, 4630511488, - 4638898816, 4647287936, 4655675264, 4664065664, 4672451968, - 4680842624, 4689231488, 4697620352, 4706007424, 4714397056, - 4722786176, 4731173248, 4739562368, 4747951744, 4756340608, - 4764727936, 4773114496, 4781504384, 4789894784, 4798283648, - 4806667648, 4815059584, 4823449472, 4831835776, 4840226176, - 4848612224, 4857003392, 4865391488, 4873780096, 4882169728, - 4890557312, 4898946944, 4907333248, 4915722368, 4924110976, - 4932499328, 4940889728, 4949276032, 4957666432, 4966054784, - 4974438016, 4982831488, 4991221376, 4999607168, 5007998848, - 5016386432, 5024763776, 5033164672, 5041544576, 5049941888, - 5058329728, 5066717056, 5075107456, 5083494272, 5091883904, - 5100273536, 5108662144, 5117048192, 5125436032, 5133827456, - 5142215296, 5150605184, 5158993024, 5167382144, 5175769472, - 5184157568, 5192543872, 5200936064, 5209324928, 5217711232, - 5226102656, 5234490496, 5242877312, 5251263872, 5259654016, - 5268040832, 5276434304, 5284819328, 5293209728, 5301598592, - 5309986688, 5318374784, 5326764416, 5335151488, 5343542144, - 5351929472, 5360319872, 5368706944, 5377096576, 5385484928, - 5393871232, 5402263424, 5410650496, 5419040384, 5427426944, - 5435816576, 5444205952, 5452594816, 5460981376, 5469367936, - 5477760896, 5486148736, 5494536832, 5502925952, 5511315328, - 5519703424, 5528089984, 5536481152, 5544869504, 5553256064, - 5561645696, 5570032768, 5578423936, 5586811264, 5595193216, - 5603585408, 5611972736, 5620366208, 5628750464, 5637143936, - 5645528192, 5653921408, 5662310272, 5670694784, 5679082624, - 5687474048, 5695864448, 5704251008, 5712641408, 5721030272, - 5729416832, 5737806208, 5746194304, 5754583936, 5762969984, - 5771358592, 5779748224, 5788137856, 5796527488, 5804911232, - 5813300608, 5821692544, 5830082176, 5838468992, 5846855552, - 5855247488, 5863636096, 5872024448, 5880411008, 5888799872, - 5897186432, 5905576832, 5913966976, 5922352768, 5930744704, - 5939132288, 5947522432, 5955911296, 5964299392, 5972688256, - 5981074304, 5989465472, 5997851008, 6006241408, 6014627968, - 6023015552, 6031408256, 6039796096, 6048185216, 6056574848, - 6064963456, 6073351808, 6081736064, 6090128768, 6098517632, - 6106906496, 6115289216, 6123680896, 6132070016, 6140459648, - 6148849024, 6157237376, 6165624704, 6174009728, 6182403712, - 6190792064, 6199176064, 6207569792, 6215952256, 6224345216, - 6232732544, 6241124224, 6249510272, 6257899136, 6266287744, - 6274676864, 6283065728, 6291454336, 6299843456, 6308232064, - 6316620928, 6325006208, 6333395584, 6341784704, 6350174848, - 6358562176, 6366951296, 6375337856, 6383729536, 6392119168, - 6400504192, 6408895616, 6417283456, 6425673344, 6434059136, - 6442444672, 6450837376, 6459223424, 6467613056, 6476004224, - 6484393088, 6492781952, 6501170048, 6509555072, 6517947008, - 6526336384, 6534725504, 6543112832, 6551500672, 6559888768, - 6568278656, 6576662912, 6585055616, 6593443456, 6601834112, - 6610219648, 6618610304, 6626999168, 6635385472, 6643777408, - 6652164224, 6660552832, 6668941952, 6677330048, 6685719424, - 6694107776, 6702493568, 6710882176, 6719274112, 6727662976, - 6736052096, 6744437632, 6752825984, 6761213824, 6769604224, - 6777993856, 6786383488, 6794770816, 6803158144, 6811549312, - 6819937664, 6828326528, 6836706176, 6845101696, 6853491328, - 6861880448, 6870269312, 6878655104, 6887046272, 6895433344, - 6903822208, 6912212864, 6920596864, 6928988288, 6937377152, - 6945764992, 6954149248, 6962544256, 6970928768, 6979317376, - 6987709312, 6996093824, 7004487296, 7012875392, 7021258624, - 7029652352, 7038038912, 7046427776, 7054818944, 7063207808, - 7071595136, 7079980928, 7088372608, 7096759424, 7105149824, - 7113536896, 7121928064, 7130315392, 7138699648, 7147092352, - 7155479168, 7163865728, 7172249984, 7180648064, 7189036672, - 7197424768, 7205810816, 7214196608, 7222589824, 7230975104, - 7239367552, 7247755904, 7256145536, 7264533376, 7272921472, - 7281308032, 7289694848, 7298088832, 7306471808, 7314864512, - 7323253888, 7331643008, 7340029568, 7348419712, 7356808832, - 7365196672, 7373585792, 7381973888, 7390362752, 7398750592, - 7407138944, 7415528576, 7423915648, 7432302208, 7440690304, - 7449080192, 7457472128, 7465860992, 7474249088, 7482635648, - 7491023744, 7499412608, 7507803008, 7516192384, 7524579968, - 7532967296, 7541358464, 7549745792, 7558134656, 7566524032, - 7574912896, 7583300992, 7591690112, 7600075136, 7608466816, - 7616854912, 7625244544, 7633629824, 7642020992, 7650410368, - 7658794112, 7667187328, 7675574912, 7683961984, 7692349568, - 7700739712, 7709130368, 7717519232, 7725905536, 7734295424, - 7742683264, 7751069056, 7759457408, 7767849088, 7776238208, - 7784626816, 7793014912, 7801405312, 7809792128, 7818179968, - 7826571136, 7834957184, 7843347328, 7851732352, 7860124544, - 7868512384, 7876902016, 7885287808, 7893679744, 7902067072, - 7910455936, 7918844288, 7927230848, 7935622784, 7944009344, - 7952400256, 7960786048, 7969176704, 7977565312, 7985953408, - 7994339968, 8002730368, 8011119488, 8019508096, 8027896192, - 8036285056, 8044674688, 8053062272, 8061448832, 8069838464, - 8078227328, 8086616704, 8095006592, 8103393664, 8111783552, - 8120171392, 8128560256, 8136949376, 8145336704, 8153726848, - 8162114944, 8170503296, 8178891904, 8187280768, 8195669632, - 8204058496, 8212444544, 8220834176, 8229222272, 8237612672, - 8246000768, 8254389376, 8262775168, 8271167104, 8279553664, - 8287944064, 8296333184, 8304715136, 8313108352, 8321497984, - 8329885568, 8338274432, 8346663296, 8355052928, 8363441536, - 8371828352, 8380217984, 8388606592, 8396996224, 8405384576, - 8413772672, 8422161536, 8430549376, 8438939008, 8447326592, - 8455715456, 8464104832, 8472492928, 8480882048, 8489270656, - 8497659776, 8506045312, 8514434944, 8522823808, 8531208832, - 8539602304, 8547990656, 8556378752, 8564768384, 8573154176, - 8581542784, 8589933952, 8598322816, 8606705024, 8615099264, - 8623487872, 8631876992, 8640264064, 8648653952, 8657040256, - 8665430656, 8673820544, 8682209152, 8690592128, 8698977152, - 8707374464, 8715763328, 8724151424, 8732540032, 8740928384, - 8749315712, 8757704576, 8766089344, 8774480768, 8782871936, - 8791260032, 8799645824, 8808034432, 8816426368, 8824812928, - 8833199488, 8841591424, 8849976448, 8858366336, 8866757248, - 8875147136, 8883532928, 8891923328, 8900306816, 8908700288, - 8917088384, 8925478784, 8933867392, 8942250368, 8950644608, - 8959032704, 8967420544, 8975809664, 8984197504, 8992584064, - 9000976256, 9009362048, 9017752448, 9026141312, 9034530688, - 9042917504, 9051307904, 9059694208, 9068084864, 9076471424, - 9084861824, 9093250688, 9101638528, 9110027648, 9118416512, - 9126803584, 9135188096, 9143581312, 9151969664, 9160356224, - 9168747136, 9177134464, 9185525632, 9193910144, 9202302848, - 9210690688, 9219079552, 9227465344, 9235854464, 9244244864, - 9252633472, 9261021824, 9269411456, 9277799296, 9286188928, - 9294574208, 9302965888, 9311351936, 9319740032, 9328131968, - 9336516736, 9344907392, 9353296768, 9361685888, 9370074752, - 9378463616, 9386849408, 9395239808, 9403629184, 9412016512, - 9420405376, 9428795008, 9437181568, 9445570688, 9453960832, - 9462346624, 9470738048, 9479121536, 9487515008, 9495903616, - 9504289664, 9512678528, 9521067904, 9529456256, 9537843584, - 9546233728, 9554621312, 9563011456, 9571398784, 9579788672, - 9588178304, 9596567168, 9604954496, 9613343104, 9621732992, - 9630121856, 9638508416, 9646898816, 9655283584, 9663675776, - 9672061312, 9680449664, 9688840064, 9697230464, 9705617536, - 9714003584, 9722393984, 9730772608, 9739172224, 9747561088, - 9755945344, 9764338816, 9772726144, 9781116544, 9789503872, - 9797892992, 9806282624, 9814670464, 9823056512, 9831439232, - 9839833984, 9848224384, 9856613504, 9865000576, 9873391232, - 9881772416, 9890162816, 9898556288, 9906940544, 9915333248, - 9923721088, 9932108672, 9940496512, 9948888448, 9957276544, - 9965666176, 9974048384, 9982441088, 9990830464, 9999219584, - 10007602816, 10015996544, 10024385152, 10032774016, 10041163648, - 10049548928, 10057940096, 10066329472, 10074717824, 10083105152, - 10091495296, 10099878784, 10108272256, 10116660608, 10125049216, - 10133437312, 10141825664, 10150213504, 10158601088, 10166991232, - 10175378816, 10183766144, 10192157312, 10200545408, 10208935552, - 10217322112, 10225712768, 10234099328, 10242489472, 10250876032, - 10259264896, 10267656064, 10276042624, 10284429184, 10292820352, - 10301209472, 10309598848, 10317987712, 10326375296, 10334763392, - 10343153536, 10351541632, 10359930752, 10368318592, 10376707456, - 10385096576, 10393484672, 10401867136, 10410262144, 10418647424, - 10427039104, 10435425664, 10443810176, 10452203648, 10460589952, - 10468982144, 10477369472, 10485759104, 10494147712, 10502533504, - 10510923392, 10519313536, 10527702656, 10536091264, 10544478592, - 10552867712, 10561255808, 10569642368, 10578032768, 10586423168, - 10594805632, 10603200128, 10611588992, 10619976064, 10628361344, - 10636754048, 10645143424, 10653531776, 10661920384, 10670307968, - 10678696832, 10687086464, 10695475072, 10703863168, 10712246144, - 10720639616, 10729026688, 10737414784, 10745806208, 10754190976, - 10762581376, 10770971264, 10779356288, 10787747456, 10796135552, - 10804525184, 10812915584, 10821301888, 10829692288, 10838078336, - 10846469248, 10854858368, 10863247232, 10871631488, 10880023424, - 10888412032, 10896799616, 10905188992, 10913574016, 10921964672, - 10930352768, 10938742912, 10947132544, 10955518592, 10963909504, - 10972298368, 10980687488, 10989074816, 10997462912, 11005851776, - 11014241152, 11022627712, 11031017344, 11039403904, 11047793024, - 11056184704, 11064570752, 11072960896, 11081343872, 11089737856, - 11098128256, 11106514816, 11114904448, 11123293568, 11131680128, - 11140065152, 11148458368, 11156845696, 11165236864, 11173624192, - 11182013824, 11190402688, 11198790784, 11207179136, 11215568768, - 11223957376, 11232345728, 11240734592, 11249122688, 11257511296, - 11265899648, 11274285952, 11282675584, 11291065472, 11299452544, - 11307842432, 11316231296, 11324616832, 11333009024, 11341395584, - 11349782656, 11358172288, 11366560384, 11374950016, 11383339648, - 11391721856, 11400117376, 11408504192, 11416893568, 11425283456, - 11433671552, 11442061184, 11450444672, 11458837888, 11467226752, - 11475611776, 11484003968, 11492392064, 11500780672, 11509169024, - 11517550976, 11525944448, 11534335616, 11542724224, 11551111808, - 11559500672, 11567890304, 11576277376, 11584667008, 11593056128, - 11601443456, 11609830016, 11618221952, 11626607488, 11634995072, - 11643387776, 11651775104, 11660161664, 11668552576, 11676940928, - 11685330304, 11693718656, 11702106496, 11710496128, 11718882688, - 11727273088, 11735660416, 11744050048, 11752437376, 11760824704, - 11769216128, 11777604736, 11785991296, 11794381952, 11802770048, - 11811157888, 11819548544, 11827932544, 11836324736, 11844713344, - 11853100928, 11861486464, 11869879936, 11878268032, 11886656896, - 11895044992, 11903433088, 11911822976, 11920210816, 11928600448, - 11936987264, 11945375872, 11953761152, 11962151296, 11970543488, - 11978928512, 11987320448, 11995708288, 12004095104, 12012486272, - 12020875136, 12029255552, 12037652096, 12046039168, 12054429568, - 12062813824, 12071206528, 12079594624, 12087983744, 12096371072, - 12104759936, 12113147264, 12121534592, 12129924992, 12138314624, - 12146703232, 12155091584, 12163481216, 12171864704, 12180255872, - 12188643968, 12197034112, 12205424512, 12213811328, 12222199424, - 12230590336, 12238977664, 12247365248, 12255755392, 12264143488, - 12272531584, 12280920448, 12289309568, 12297694592, 12306086528, - 12314475392, 12322865024, 12331253632, 12339640448, 12348029312, - 12356418944, 12364805248, 12373196672, 12381580928, 12389969024, - 12398357632, 12406750592, 12415138432, 12423527552, 12431916416, - 12440304512, 12448692352, 12457081216, 12465467776, 12473859968, - 12482245504, 12490636672, 12499025536, 12507411584, 12515801728, - 12524190592, 12532577152, 12540966272, 12549354368, 12557743232, - 12566129536, 12574523264, 12582911872, 12591299456, 12599688064, - 12608074624, 12616463488, 12624845696, 12633239936, 12641631616, - 12650019968, 12658407296, 12666795136, 12675183232, 12683574656, - 12691960192, 12700350592, 12708740224, 12717128576, 12725515904, - 12733906816, 12742295168, 12750680192, 12759071872, 12767460736, - 12775848832, 12784236928, 12792626816, 12801014656, 12809404288, - 12817789312, 12826181504, 12834568832, 12842954624, 12851345792, - 12859732352, 12868122496, 12876512128, 12884901248, 12893289088, - 12901672832, 12910067584, 12918455168, 12926842496, 12935232896, - 12943620736, 12952009856, 12960396928, 12968786816, 12977176192, - 12985563776, 12993951104, 13002341504, 13010730368, 13019115392, - 13027506304, 13035895168, 13044272512, 13052673152, 13061062528, - 13069446272, 13077838976, 13086227072, 13094613632, 13103000192, - 13111393664, 13119782528, 13128157568, 13136559232, 13144945024, - 13153329536, 13161724288, 13170111872, 13178502784, 13186884736, - 13195279744, 13203667072, 13212057472, 13220445824, 13228832128, - 13237221248, 13245610624, 13254000512, 13262388352, 13270777472, - 13279166336, 13287553408, 13295943296, 13304331904, 13312719488, - 13321108096, 13329494656, 13337885824, 13346274944, 13354663808, - 13363051136, 13371439232, 13379825024, 13388210816, 13396605056, - 13404995456, 13413380224, 13421771392, 13430159744, 13438546048, - 13446937216, 13455326848, 13463708288, 13472103808, 13480492672, - 13488875648, 13497269888, 13505657728, 13514045312, 13522435712, - 13530824576, 13539210112, 13547599232, 13555989376, 13564379008, - 13572766336, 13581154432, 13589544832, 13597932928, 13606320512, - 13614710656, 13623097472, 13631477632, 13639874944, 13648264064, - 13656652928, 13665041792, 13673430656, 13681818496, 13690207616, - 13698595712, 13706982272, 13715373184, 13723762048, 13732150144, - 13740536704, 13748926592, 13757316224, 13765700992, 13774090112, - 13782477952, 13790869376, 13799259008, 13807647872, 13816036736, - 13824425344, 13832814208, 13841202304, 13849591424, 13857978752, - 13866368896, 13874754688, 13883145344, 13891533184, 13899919232, - 13908311168, 13916692096, 13925085056, 13933473152, 13941866368, - 13950253696, 13958643584, 13967032192, 13975417216, 13983807616, - 13992197504, 14000582272, 14008973696, 14017363072, 14025752192, - 14034137984, 14042528384, 14050918016, 14059301504, 14067691648, - 14076083584, 14084470144, 14092852352, 14101249664, 14109635968, - 14118024832, 14126407552, 14134804352, 14143188608, 14151577984, - 14159968384, 14168357248, 14176741504, 14185127296, 14193521024, - 14201911424, 14210301824, 14218685056, 14227067264, 14235467392, - 14243855488, 14252243072, 14260630144, 14269021568, 14277409408, - 14285799296, 14294187904, 14302571392, 14310961792, 14319353728, - 14327738752, 14336130944, 14344518784, 14352906368, 14361296512, - 14369685376, 14378071424, 14386462592, 14394848128, 14403230848, - 14411627392, 14420013952, 14428402304, 14436793472, 14445181568, - 14453569664, 14461959808, 14470347904, 14478737024, 14487122816, - 14495511424, 14503901824, 14512291712, 14520677504, 14529064832, - 14537456768, 14545845632, 14554234496, 14562618496, 14571011456, - 14579398784, 14587789184, 14596172672, 14604564608, 14612953984, - 14621341312, 14629724288, 14638120832, 14646503296, 14654897536, - 14663284864, 14671675264, 14680061056, 14688447616, 14696835968, - 14705228416, 14713616768, 14722003328, 14730392192, 14738784128, - 14747172736, 14755561088, 14763947648, 14772336512, 14780725376, - 14789110144, 14797499776, 14805892736, 14814276992, 14822670208, - 14831056256, 14839444352, 14847836032, 14856222848, 14864612992, - 14872997504, 14881388672, 14889775744, 14898165376, 14906553472, - 14914944896, 14923329664, 14931721856, 14940109696, 14948497024, - 14956887424, 14965276544, 14973663616, 14982053248, 14990439808, - 14998830976, 15007216768, 15015605888, 15023995264, 15032385152, - 15040768384, 15049154944, 15057549184, 15065939072, 15074328448, - 15082715008, 15091104128, 15099493504, 15107879296, 15116269184, - 15124659584, 15133042304, 15141431936, 15149824384, 15158214272, - 15166602368, 15174991232, 15183378304, 15191760512, 15200154496, - 15208542592, 15216931712, 15225323392, 15233708416, 15242098048, - 15250489216, 15258875264, 15267265408, 15275654528, 15284043136, - 15292431488, 15300819584, 15309208192, 15317596544, 15325986176, - 15334374784, 15342763648, 15351151744, 15359540608, 15367929728, - 15376318336, 15384706432, 15393092992, 15401481856, 15409869952, - 15418258816, 15426649984, 15435037568, 15443425664, 15451815296, - 15460203392, 15468589184, 15476979328, 15485369216, 15493755776, - 15502146944, 15510534272, 15518924416, 15527311232, 15535699072, - 15544089472, 15552478336, 15560866688, 15569254528, 15577642624, - 15586031488, 15594419072, 15602809472, 15611199104, 15619586432, - 15627975296, 15636364928, 15644753792, 15653141888, 15661529216, - 15669918848, 15678305152, 15686696576, 15695083136, 15703474048, - 15711861632, 15720251264, 15728636288, 15737027456, 15745417088, - 15753804928, 15762194048, 15770582656, 15778971008, 15787358336, - 15795747712, 15804132224, 15812523392, 15820909696, 15829300096, - 15837691264, 15846071936, 15854466944, 15862855808, 15871244672, - 15879634816, 15888020608, 15896409728, 15904799104, 15913185152, - 15921577088, 15929966464, 15938354816, 15946743424, 15955129472, - 15963519872, 15971907968, 15980296064, 15988684928, 15997073024, - 16005460864, 16013851264, 16022241152, 16030629248, 16039012736, - 16047406976, 16055794816, 16064181376, 16072571264, 16080957824, - 16089346688, 16097737856, 16106125184, 16114514816, 16122904192, - 16131292544, 16139678848, 16148066944, 16156453504, 16164839552, - 16173236096, 16181623424, 16190012032, 16198401152, 16206790528, - 16215177344, 16223567744, 16231956352, 16240344704, 16248731008, - 16257117824, 16265504384, 16273898624, 16282281856, 16290668672, - 16299064192, 16307449216, 16315842176, 16324230016, 16332613504, - 16341006464, 16349394304, 16357783168, 16366172288, 16374561664, - 16382951296, 16391337856, 16399726208, 16408116352, 16416505472, - 16424892032, 16433282176, 16441668224, 16450058624, 16458448768, - 16466836864, 16475224448, 16483613056, 16492001408, 16500391808, - 16508779648, 16517166976, 16525555328, 16533944192, 16542330752, - 16550719616, 16559110528, 16567497088, 16575888512, 16584274816, - 16592665472, 16601051008, 16609442944, 16617832064, 16626218624, - 16634607488, 16642996096, 16651385728, 16659773824, 16668163712, - 16676552576, 16684938112, 16693328768, 16701718144, 16710095488, - 16718492288, 16726883968, 16735272832, 16743661184, 16752049792, - 16760436608, 16768827008, 16777214336, 16785599104, 16793992832, - 16802381696, 16810768768, 16819151744, 16827542656, 16835934848, - 16844323712, 16852711552, 16861101952, 16869489536, 16877876864, - 16886265728, 16894653056, 16903044736, 16911431296, 16919821696, - 16928207488, 16936592768, 16944987776, 16953375616, 16961763968, - 16970152832, 16978540928, 16986929536, 16995319168, 17003704448, - 17012096896, 17020481152, 17028870784, 17037262208, 17045649536, - 17054039936, 17062426496, 17070814336, 17079205504, 17087592064, - 17095978112, 17104369024, 17112759424, 17121147776, 17129536384, - 17137926016, 17146314368, 17154700928, 17163089792, 17171480192, - 17179864192, 17188256896, 17196644992, 17205033856, 17213423488, - 17221811072, 17230198912, 17238588032, 17246976896, 17255360384, - 17263754624, 17272143232, 17280530048, 17288918912, 17297309312, - 17305696384, 17314085504, 17322475136, 17330863744, 17339252096, - 17347640192, 17356026496, 17364413824, 17372796544, 17381190016, - 17389583488, 17397972608, 17406360704, 17414748544, 17423135872, - 17431527296, 17439915904, 17448303232, 17456691584, 17465081728, - 17473468288, 17481857408, 17490247552, 17498635904, 17507022464, - 17515409024, 17523801728, 17532189824, 17540577664, 17548966016, - 17557353344, 17565741184, 17574131584, 17582519168, 17590907008, - 17599296128, 17607687808, 17616076672, 17624455808, 17632852352, - 17641238656, 17649630848, 17658018944, 17666403968, 17674794112, - 17683178368, 17691573376, 17699962496, 17708350592, 17716739968, - 17725126528, 17733517184, 17741898112, 17750293888, 17758673024, - 17767070336, 17775458432, 17783848832, 17792236928, 17800625536, - 17809012352, 17817402752, 17825785984, 17834178944, 17842563968, - 17850955648, 17859344512, 17867732864, 17876119424, 17884511872, - 17892900224, 17901287296, 17909677696, 17918058112, 17926451072, - 17934843776, 17943230848, 17951609216, 17960008576, 17968397696, - 17976784256, 17985175424, 17993564032, 18001952128, 18010339712, - 18018728576, 18027116672, 18035503232, 18043894144, 18052283264, - 18060672128, 18069056384, 18077449856, 18085837184, 18094225792, - 18102613376, 18111004544, 18119388544, 18127781248, 18136170368, - 18144558976, 18152947328, 18161336192, 18169724288, 18178108544, - 18186498944, 18194886784, 18203275648, 18211666048, 18220048768, - 18228444544, 18236833408, 18245220736] - - cache_sizes = [ - 16776896, 16907456, 17039296, 17170112, 17301056, 17432512, 17563072, - 17693888, 17824192, 17955904, 18087488, 18218176, 18349504, 18481088, - 18611392, 18742336, 18874304, 19004224, 19135936, 19267264, 19398208, - 19529408, 19660096, 19791424, 19922752, 20053952, 20184896, 20315968, - 20446912, 20576576, 20709184, 20840384, 20971072, 21102272, 21233216, - 21364544, 21494848, 21626816, 21757376, 21887552, 22019392, 22151104, - 22281536, 22412224, 22543936, 22675264, 22806464, 22935872, 23068096, - 23198272, 23330752, 23459008, 23592512, 23723968, 23854912, 23986112, - 24116672, 24247616, 24378688, 24509504, 24640832, 24772544, 24903488, - 25034432, 25165376, 25296704, 25427392, 25558592, 25690048, 25820096, - 25951936, 26081728, 26214208, 26345024, 26476096, 26606656, 26737472, - 26869184, 26998208, 27131584, 27262528, 27393728, 27523904, 27655744, - 27786688, 27917888, 28049344, 28179904, 28311488, 28441792, 28573504, - 28700864, 28835648, 28966208, 29096768, 29228608, 29359808, 29490752, - 29621824, 29752256, 29882816, 30014912, 30144448, 30273728, 30406976, - 30538432, 30670784, 30799936, 30932672, 31063744, 31195072, 31325248, - 31456192, 31588288, 31719232, 31850432, 31981504, 32110784, 32243392, - 32372672, 32505664, 32636608, 32767808, 32897344, 33029824, 33160768, - 33289664, 33423296, 33554368, 33683648, 33816512, 33947456, 34076992, - 34208704, 34340032, 34471744, 34600256, 34734016, 34864576, 34993984, - 35127104, 35258176, 35386688, 35518528, 35650624, 35782336, 35910976, - 36044608, 36175808, 36305728, 36436672, 36568384, 36699968, 36830656, - 36961984, 37093312, 37223488, 37355072, 37486528, 37617472, 37747904, - 37879232, 38009792, 38141888, 38272448, 38403392, 38535104, 38660672, - 38795584, 38925632, 39059264, 39190336, 39320768, 39452096, 39581632, - 39713984, 39844928, 39974848, 40107968, 40238144, 40367168, 40500032, - 40631744, 40762816, 40894144, 41023552, 41155904, 41286208, 41418304, - 41547712, 41680448, 41811904, 41942848, 42073792, 42204992, 42334912, - 42467008, 42597824, 42729152, 42860096, 42991552, 43122368, 43253696, - 43382848, 43515712, 43646912, 43777088, 43907648, 44039104, 44170432, - 44302144, 44433344, 44564288, 44694976, 44825152, 44956864, 45088448, - 45219008, 45350464, 45481024, 45612608, 45744064, 45874496, 46006208, - 46136768, 46267712, 46399424, 46529344, 46660672, 46791488, 46923328, - 47053504, 47185856, 47316928, 47447872, 47579072, 47710144, 47839936, - 47971648, 48103232, 48234176, 48365248, 48496192, 48627136, 48757312, - 48889664, 49020736, 49149248, 49283008, 49413824, 49545152, 49675712, - 49807168, 49938368, 50069056, 50200256, 50331584, 50462656, 50593472, - 50724032, 50853952, 50986048, 51117632, 51248576, 51379904, 51510848, - 51641792, 51773248, 51903296, 52035136, 52164032, 52297664, 52427968, - 52557376, 52690112, 52821952, 52952896, 53081536, 53213504, 53344576, - 53475776, 53608384, 53738816, 53870528, 54000832, 54131776, 54263744, - 54394688, 54525248, 54655936, 54787904, 54918592, 55049152, 55181248, - 55312064, 55442752, 55574336, 55705024, 55836224, 55967168, 56097856, - 56228672, 56358592, 56490176, 56621888, 56753728, 56884928, 57015488, - 57146816, 57278272, 57409216, 57540416, 57671104, 57802432, 57933632, - 58064576, 58195264, 58326976, 58457408, 58588864, 58720192, 58849984, - 58981696, 59113024, 59243456, 59375552, 59506624, 59637568, 59768512, - 59897792, 60030016, 60161984, 60293056, 60423872, 60554432, 60683968, - 60817216, 60948032, 61079488, 61209664, 61341376, 61471936, 61602752, - 61733696, 61865792, 61996736, 62127808, 62259136, 62389568, 62520512, - 62651584, 62781632, 62910784, 63045056, 63176128, 63307072, 63438656, - 63569216, 63700928, 63831616, 63960896, 64093888, 64225088, 64355392, - 64486976, 64617664, 64748608, 64879424, 65009216, 65142464, 65273792, - 65402816, 65535424, 65666752, 65797696, 65927744, 66060224, 66191296, - 66321344, 66453056, 66584384, 66715328, 66846656, 66977728, 67108672, - 67239104, 67370432, 67501888, 67631296, 67763776, 67895104, 68026304, - 68157248, 68287936, 68419264, 68548288, 68681408, 68811968, 68942912, - 69074624, 69205568, 69337024, 69467584, 69599168, 69729472, 69861184, - 69989824, 70122944, 70253888, 70385344, 70515904, 70647232, 70778816, - 70907968, 71040832, 71171648, 71303104, 71432512, 71564992, 71695168, - 71826368, 71958464, 72089536, 72219712, 72350144, 72482624, 72613568, - 72744512, 72875584, 73006144, 73138112, 73268672, 73400128, 73530944, - 73662272, 73793344, 73924544, 74055104, 74185792, 74316992, 74448832, - 74579392, 74710976, 74841664, 74972864, 75102784, 75233344, 75364544, - 75497024, 75627584, 75759296, 75890624, 76021696, 76152256, 76283072, - 76414144, 76545856, 76676672, 76806976, 76937792, 77070016, 77200832, - 77331392, 77462464, 77593664, 77725376, 77856448, 77987776, 78118336, - 78249664, 78380992, 78511424, 78642496, 78773056, 78905152, 79033664, - 79166656, 79297472, 79429568, 79560512, 79690816, 79822784, 79953472, - 80084672, 80214208, 80346944, 80477632, 80608576, 80740288, 80870848, - 81002048, 81133504, 81264448, 81395648, 81525952, 81657536, 81786304, - 81919808, 82050112, 82181312, 82311616, 82443968, 82573376, 82705984, - 82835776, 82967744, 83096768, 83230528, 83359552, 83491264, 83622464, - 83753536, 83886016, 84015296, 84147776, 84277184, 84409792, 84540608, - 84672064, 84803008, 84934336, 85065152, 85193792, 85326784, 85458496, - 85589312, 85721024, 85851968, 85982656, 86112448, 86244416, 86370112, - 86506688, 86637632, 86769344, 86900672, 87031744, 87162304, 87293632, - 87424576, 87555392, 87687104, 87816896, 87947968, 88079168, 88211264, - 88341824, 88473152, 88603712, 88735424, 88862912, 88996672, 89128384, - 89259712, 89390272, 89521984, 89652544, 89783872, 89914816, 90045376, - 90177088, 90307904, 90438848, 90569152, 90700096, 90832832, 90963776, - 91093696, 91223744, 91356992, 91486784, 91618496, 91749824, 91880384, - 92012224, 92143552, 92273344, 92405696, 92536768, 92666432, 92798912, - 92926016, 93060544, 93192128, 93322816, 93453632, 93583936, 93715136, - 93845056, 93977792, 94109504, 94240448, 94371776, 94501184, 94632896, - 94764224, 94895552, 95023424, 95158208, 95287744, 95420224, 95550016, - 95681216, 95811904, 95943872, 96075328, 96203584, 96337856, 96468544, - 96599744, 96731072, 96860992, 96992576, 97124288, 97254848, 97385536, - 97517248, 97647808, 97779392, 97910464, 98041408, 98172608, 98303168, - 98434496, 98565568, 98696768, 98827328, 98958784, 99089728, 99220928, - 99352384, 99482816, 99614272, 99745472, 99876416, 100007104, - 100138048, 100267072, 100401088, 100529984, 100662592, 100791872, - 100925248, 101056064, 101187392, 101317952, 101449408, 101580608, - 101711296, 101841728, 101973824, 102104896, 102235712, 102366016, - 102498112, 102628672, 102760384, 102890432, 103021888, 103153472, - 103284032, 103415744, 103545152, 103677248, 103808576, 103939648, - 104070976, 104201792, 104332736, 104462528, 104594752, 104725952, - 104854592, 104988608, 105118912, 105247808, 105381184, 105511232, - 105643072, 105774784, 105903296, 106037056, 106167872, 106298944, - 106429504, 106561472, 106691392, 106822592, 106954304, 107085376, - 107216576, 107346368, 107478464, 107609792, 107739712, 107872192, - 108003136, 108131392, 108265408, 108396224, 108527168, 108657344, - 108789568, 108920384, 109049792, 109182272, 109312576, 109444928, - 109572928, 109706944, 109837888, 109969088, 110099648, 110230976, - 110362432, 110492992, 110624704, 110755264, 110886208, 111017408, - 111148864, 111279296, 111410752, 111541952, 111673024, 111803456, - 111933632, 112066496, 112196416, 112328512, 112457792, 112590784, - 112715968, 112852672, 112983616, 113114944, 113244224, 113376448, - 113505472, 113639104, 113770304, 113901376, 114031552, 114163264, - 114294592, 114425536, 114556864, 114687424, 114818624, 114948544, - 115080512, 115212224, 115343296, 115473472, 115605184, 115736128, - 115867072, 115997248, 116128576, 116260288, 116391488, 116522944, - 116652992, 116784704, 116915648, 117046208, 117178304, 117308608, - 117440192, 117569728, 117701824, 117833024, 117964096, 118094656, - 118225984, 118357312, 118489024, 118617536, 118749632, 118882112, - 119012416, 119144384, 119275328, 119406016, 119537344, 119668672, - 119798464, 119928896, 120061376, 120192832, 120321728, 120454336, - 120584512, 120716608, 120848192, 120979136, 121109056, 121241408, - 121372352, 121502912, 121634752, 121764416, 121895744, 122027072, - 122157632, 122289088, 122421184, 122550592, 122682944, 122813888, - 122945344, 123075776, 123207488, 123338048, 123468736, 123600704, - 123731264, 123861952, 123993664, 124124608, 124256192, 124386368, - 124518208, 124649024, 124778048, 124911296, 125041088, 125173696, - 125303744, 125432896, 125566912, 125696576, 125829056, 125958592, - 126090304, 126221248, 126352832, 126483776, 126615232, 126746432, - 126876608, 127008704, 127139392, 127270336, 127401152, 127532224, - 127663552, 127794752, 127925696, 128055232, 128188096, 128319424, - 128449856, 128581312, 128712256, 128843584, 128973632, 129103808, - 129236288, 129365696, 129498944, 129629888, 129760832, 129892288, - 130023104, 130154048, 130283968, 130416448, 130547008, 130678336, - 130807616, 130939456, 131071552, 131202112, 131331776, 131464384, - 131594048, 131727296, 131858368, 131987392, 132120256, 132250816, - 132382528, 132513728, 132644672, 132774976, 132905792, 133038016, - 133168832, 133299392, 133429312, 133562048, 133692992, 133823296, - 133954624, 134086336, 134217152, 134348608, 134479808, 134607296, - 134741056, 134872384, 135002944, 135134144, 135265472, 135396544, - 135527872, 135659072, 135787712, 135921472, 136052416, 136182848, - 136313792, 136444864, 136576448, 136707904, 136837952, 136970048, - 137099584, 137232064, 137363392, 137494208, 137625536, 137755712, - 137887424, 138018368, 138149824, 138280256, 138411584, 138539584, - 138672832, 138804928, 138936128, 139066688, 139196864, 139328704, - 139460032, 139590208, 139721024, 139852864, 139984576, 140115776, - 140245696, 140376512, 140508352, 140640064, 140769856, 140902336, - 141032768, 141162688, 141294016, 141426496, 141556544, 141687488, - 141819584, 141949888, 142080448, 142212544, 142342336, 142474432, - 142606144, 142736192, 142868288, 142997824, 143129408, 143258944, - 143392448, 143523136, 143653696, 143785024, 143916992, 144045632, - 144177856, 144309184, 144440768, 144570688, 144701888, 144832448, - 144965056, 145096384, 145227584, 145358656, 145489856, 145620928, - 145751488, 145883072, 146011456, 146144704, 146275264, 146407232, - 146538176, 146668736, 146800448, 146931392, 147062336, 147193664, - 147324224, 147455936, 147586624, 147717056, 147848768, 147979456, - 148110784, 148242368, 148373312, 148503232, 148635584, 148766144, - 148897088, 149028416, 149159488, 149290688, 149420224, 149551552, - 149683136, 149814976, 149943616, 150076352, 150208064, 150338624, - 150470464, 150600256, 150732224, 150862784, 150993088, 151125952, - 151254976, 151388096, 151519168, 151649728, 151778752, 151911104, - 152042944, 152174144, 152304704, 152435648, 152567488, 152698816, - 152828992, 152960576, 153091648, 153222976, 153353792, 153484096, - 153616192, 153747008, 153878336, 154008256, 154139968, 154270912, - 154402624, 154533824, 154663616, 154795712, 154926272, 155057984, - 155188928, 155319872, 155450816, 155580608, 155712064, 155843392, - 155971136, 156106688, 156237376, 156367424, 156499264, 156630976, - 156761536, 156892352, 157024064, 157155008, 157284416, 157415872, - 157545536, 157677248, 157810496, 157938112, 158071744, 158203328, - 158334656, 158464832, 158596288, 158727616, 158858048, 158988992, - 159121216, 159252416, 159381568, 159513152, 159645632, 159776192, - 159906496, 160038464, 160169536, 160300352, 160430656, 160563008, - 160693952, 160822208, 160956352, 161086784, 161217344, 161349184, - 161480512, 161611456, 161742272, 161873216, 162002752, 162135872, - 162266432, 162397888, 162529216, 162660032, 162790976, 162922048, - 163052096, 163184576, 163314752, 163446592, 163577408, 163707968, - 163839296, 163969984, 164100928, 164233024, 164364224, 164494912, - 164625856, 164756672, 164887616, 165019072, 165150016, 165280064, - 165412672, 165543104, 165674944, 165805888, 165936832, 166067648, - 166198336, 166330048, 166461248, 166591552, 166722496, 166854208, - 166985408, 167116736, 167246656, 167378368, 167508416, 167641024, - 167771584, 167903168, 168034112, 168164032, 168295744, 168427456, - 168557632, 168688448, 168819136, 168951616, 169082176, 169213504, - 169344832, 169475648, 169605952, 169738048, 169866304, 169999552, - 170131264, 170262464, 170393536, 170524352, 170655424, 170782016, - 170917696, 171048896, 171179072, 171310784, 171439936, 171573184, - 171702976, 171835072, 171966272, 172097216, 172228288, 172359232, - 172489664, 172621376, 172747712, 172883264, 173014208, 173144512, - 173275072, 173407424, 173539136, 173669696, 173800768, 173931712, - 174063424, 174193472, 174325696, 174455744, 174586816, 174718912, - 174849728, 174977728, 175109696, 175242688, 175374272, 175504832, - 175636288, 175765696, 175898432, 176028992, 176159936, 176291264, - 176422592, 176552512, 176684864, 176815424, 176946496, 177076544, - 177209152, 177340096, 177470528, 177600704, 177731648, 177864256, - 177994816, 178126528, 178257472, 178387648, 178518464, 178650176, - 178781888, 178912064, 179044288, 179174848, 179305024, 179436736, - 179568448, 179698496, 179830208, 179960512, 180092608, 180223808, - 180354752, 180485696, 180617152, 180748096, 180877504, 181009984, - 181139264, 181272512, 181402688, 181532608, 181663168, 181795136, - 181926592, 182057536, 182190016, 182320192, 182451904, 182582336, - 182713792, 182843072, 182976064, 183107264, 183237056, 183368384, - 183494848, 183631424, 183762752, 183893824, 184024768, 184154816, - 184286656, 184417984, 184548928, 184680128, 184810816, 184941248, - 185072704, 185203904, 185335616, 185465408, 185596352, 185727296, - 185859904, 185989696, 186121664, 186252992, 186383552, 186514112, - 186645952, 186777152, 186907328, 187037504, 187170112, 187301824, - 187429184, 187562048, 187693504, 187825472, 187957184, 188087104, - 188218304, 188349376, 188481344, 188609728, 188743616, 188874304, - 189005248, 189136448, 189265088, 189396544, 189528128, 189660992, - 189791936, 189923264, 190054208, 190182848, 190315072, 190447424, - 190577984, 190709312, 190840768, 190971328, 191102656, 191233472, - 191364032, 191495872, 191626816, 191758016, 191888192, 192020288, - 192148928, 192282176, 192413504, 192542528, 192674752, 192805952, - 192937792, 193068608, 193198912, 193330496, 193462208, 193592384, - 193723456, 193854272, 193985984, 194116672, 194247232, 194379712, - 194508352, 194641856, 194772544, 194900672, 195035072, 195166016, - 195296704, 195428032, 195558592, 195690304, 195818176, 195952576, - 196083392, 196214336, 196345792, 196476736, 196607552, 196739008, - 196869952, 197000768, 197130688, 197262784, 197394368, 197523904, - 197656384, 197787584, 197916608, 198049472, 198180544, 198310208, - 198442432, 198573632, 198705088, 198834368, 198967232, 199097792, - 199228352, 199360192, 199491392, 199621696, 199751744, 199883968, - 200014016, 200146624, 200276672, 200408128, 200540096, 200671168, - 200801984, 200933312, 201062464, 201194944, 201326144, 201457472, - 201588544, 201719744, 201850816, 201981632, 202111552, 202244032, - 202374464, 202505152, 202636352, 202767808, 202898368, 203030336, - 203159872, 203292608, 203423296, 203553472, 203685824, 203816896, - 203947712, 204078272, 204208192, 204341056, 204472256, 204603328, - 204733888, 204864448, 204996544, 205125568, 205258304, 205388864, - 205517632, 205650112, 205782208, 205913536, 206044736, 206176192, - 206307008, 206434496, 206569024, 206700224, 206831168, 206961856, - 207093056, 207223616, 207355328, 207486784, 207616832, 207749056, - 207879104, 208010048, 208141888, 208273216, 208404032, 208534336, - 208666048, 208796864, 208927424, 209059264, 209189824, 209321792, - 209451584, 209582656, 209715136, 209845568, 209976896, 210106432, - 210239296, 210370112, 210501568, 210630976, 210763712, 210894272, - 211024832, 211156672, 211287616, 211418176, 211549376, 211679296, - 211812032, 211942592, 212074432, 212204864, 212334016, 212467648, - 212597824, 212727616, 212860352, 212991424, 213120832, 213253952, - 213385024, 213515584, 213645632, 213777728, 213909184, 214040128, - 214170688, 214302656, 214433728, 214564544, 214695232, 214826048, - 214956992, 215089088, 215219776, 215350592, 215482304, 215613248, - 215743552, 215874752, 216005312, 216137024, 216267328, 216399296, - 216530752, 216661696, 216790592, 216923968, 217054528, 217183168, - 217316672, 217448128, 217579072, 217709504, 217838912, 217972672, - 218102848, 218233024, 218364736, 218496832, 218627776, 218759104, - 218888896, 219021248, 219151936, 219281728, 219413056, 219545024, - 219675968, 219807296, 219938624, 220069312, 220200128, 220331456, - 220461632, 220592704, 220725184, 220855744, 220987072, 221117888, - 221249216, 221378368, 221510336, 221642048, 221772736, 221904832, - 222031808, 222166976, 222297536, 222428992, 222559936, 222690368, - 222820672, 222953152, 223083968, 223213376, 223345984, 223476928, - 223608512, 223738688, 223869376, 224001472, 224132672, 224262848, - 224394944, 224524864, 224657344, 224788288, 224919488, 225050432, - 225181504, 225312704, 225443776, 225574592, 225704768, 225834176, - 225966784, 226097216, 226229824, 226360384, 226491712, 226623424, - 226754368, 226885312, 227015104, 227147456, 227278528, 227409472, - 227539904, 227669696, 227802944, 227932352, 228065216, 228196288, - 228326464, 228457792, 228588736, 228720064, 228850112, 228981056, - 229113152, 229243328, 229375936, 229505344, 229636928, 229769152, - 229894976, 230030272, 230162368, 230292416, 230424512, 230553152, - 230684864, 230816704, 230948416, 231079616, 231210944, 231342016, - 231472448, 231603776, 231733952, 231866176, 231996736, 232127296, - 232259392, 232388672, 232521664, 232652608, 232782272, 232914496, - 233043904, 233175616, 233306816, 233438528, 233569984, 233699776, - 233830592, 233962688, 234092224, 234221888, 234353984, 234485312, - 234618304, 234749888, 234880832, 235011776, 235142464, 235274048, - 235403456, 235535936, 235667392, 235797568, 235928768, 236057152, - 236190272, 236322752, 236453312, 236583616, 236715712, 236846528, - 236976448, 237108544, 237239104, 237371072, 237501632, 237630784, - 237764416, 237895232, 238026688, 238157632, 238286912, 238419392, - 238548032, 238681024, 238812608, 238941632, 239075008, 239206336, - 239335232, 239466944, 239599168, 239730496, 239861312, 239992384, - 240122816, 240254656, 240385856, 240516928, 240647872, 240779072, - 240909632, 241040704, 241171904, 241302848, 241433408, 241565248, - 241696192, 241825984, 241958848, 242088256, 242220224, 242352064, - 242481856, 242611648, 242744896, 242876224, 243005632, 243138496, - 243268672, 243400384, 243531712, 243662656, 243793856, 243924544, - 244054592, 244187072, 244316608, 244448704, 244580032, 244710976, - 244841536, 244972864, 245104448, 245233984, 245365312, 245497792, - 245628736, 245759936, 245889856, 246021056, 246152512, 246284224, - 246415168, 246545344, 246675904, 246808384, 246939584, 247070144, - 247199552, 247331648, 247463872, 247593536, 247726016, 247857088, - 247987648, 248116928, 248249536, 248380736, 248512064, 248643008, - 248773312, 248901056, 249036608, 249167552, 249298624, 249429184, - 249560512, 249692096, 249822784, 249954112, 250085312, 250215488, - 250345792, 250478528, 250608704, 250739264, 250870976, 251002816, - 251133632, 251263552, 251395136, 251523904, 251657792, 251789248, - 251919424, 252051392, 252182464, 252313408, 252444224, 252575552, - 252706624, 252836032, 252968512, 253099712, 253227584, 253361728, - 253493056, 253623488, 253754432, 253885504, 254017216, 254148032, - 254279488, 254410432, 254541376, 254672576, 254803264, 254933824, - 255065792, 255196736, 255326528, 255458752, 255589952, 255721408, - 255851072, 255983296, 256114624, 256244416, 256374208, 256507712, - 256636096, 256768832, 256900544, 257031616, 257162176, 257294272, - 257424448, 257555776, 257686976, 257818432, 257949632, 258079552, - 258211136, 258342464, 258473408, 258603712, 258734656, 258867008, - 258996544, 259127744, 259260224, 259391296, 259522112, 259651904, - 259784384, 259915328, 260045888, 260175424, 260308544, 260438336, - 260570944, 260700992, 260832448, 260963776, 261092672, 261226304, - 261356864, 261487936, 261619648, 261750592, 261879872, 262011968, - 262143424, 262274752, 262404416, 262537024, 262667968, 262799296, - 262928704, 263061184, 263191744, 263322944, 263454656, 263585216, - 263716672, 263847872, 263978944, 264108608, 264241088, 264371648, - 264501184, 264632768, 264764096, 264895936, 265024576, 265158464, - 265287488, 265418432, 265550528, 265681216, 265813312, 265943488, - 266075968, 266206144, 266337728, 266468032, 266600384, 266731072, - 266862272, 266993344, 267124288, 267255616, 267386432, 267516992, - 267648704, 267777728, 267910592, 268040512, 268172096, 268302784, - 268435264, 268566208, 268696256, 268828096, 268959296, 269090368, - 269221312, 269352256, 269482688, 269614784, 269745856, 269876416, - 270007616, 270139328, 270270272, 270401216, 270531904, 270663616, - 270791744, 270924736, 271056832, 271186112, 271317184, 271449536, - 271580992, 271711936, 271843136, 271973056, 272105408, 272236352, - 272367296, 272498368, 272629568, 272759488, 272891456, 273022784, - 273153856, 273284672, 273415616, 273547072, 273677632, 273808448, - 273937088, 274071488, 274200896, 274332992, 274463296, 274595392, - 274726208, 274857536, 274988992, 275118656, 275250496, 275382208, - 275513024, 275643968, 275775296, 275906368, 276037184, 276167872, - 276297664, 276429376, 276560576, 276692672, 276822976, 276955072, - 277085632, 277216832, 277347008, 277478848, 277609664, 277740992, - 277868608, 278002624, 278134336, 278265536, 278395328, 278526784, - 278657728, 278789824, 278921152, 279052096, 279182912, 279313088, - 279443776, 279576256, 279706048, 279838528, 279969728, 280099648, - 280230976, 280361408, 280493632, 280622528, 280755392, 280887104, - 281018176, 281147968, 281278912, 281411392, 281542592, 281673152, - 281803712, 281935552, 282066496, 282197312, 282329024, 282458816, - 282590272, 282720832, 282853184, 282983744, 283115072, 283246144, - 283377344, 283508416, 283639744, 283770304, 283901504, 284032576, - 284163136, 284294848, 284426176, 284556992, 284687296, 284819264, - 284950208, 285081536] diff --git a/old-docs-for-reference/main-wiki.rst/Ethereum-Contract-ABI.rst b/old-docs-for-reference/main-wiki.rst/Ethereum-Contract-ABI.rst deleted file mode 100644 index b8fe710..0000000 --- a/old-docs-for-reference/main-wiki.rst/Ethereum-Contract-ABI.rst +++ /dev/null @@ -1,519 +0,0 @@ -Functions -========= - -Basic design ------------- - -We assume the ABI is strongly typed, known at compilation time and -static. No introspection mechanism will be provided. We assert that all -contracts will have the interface definitions of any contracts they call -available at compile-time. - -This specification does not address contracts whose interface is dynamic -or otherwise known only at run-time. Should these cases become important -they can be adequately handled as facilities built within the Ethereum -ecosystem. - -Function Selector ------------------ - -The first four bytes of the call data for a function call specifies the -function to be called. It is the first (left, high-order in big-endian) -four bytes of the Keccak (SHA-3) hash of the signature of the function. -The signature is defined as the canonical expression of the basic -prototype, i.e. the function name with the parenthesised list of -parameter types. Parameter types are split by a single comma - no spaces -are used. - -Argument Encoding ------------------ - -Starting from the fifth byte, the encoded arguments follow. This -encoding is also used in other places, e.g. the return values and also -event arguments are encoded in the same way, without the four bytes -specifying the function. - -Types -~~~~~ - -The following elementary types exist: - ``uint``: unsigned integer -type of ``N`` bits, ``0 < N <= 256``, ``N % 8 == 0``. e.g. ``uint32``, -``uint8``, ``uint256``. - ``int``: two's complement signed integer -type of ``N`` bits, ``0 < N <= 256``, ``N % 8 == 0``. - ``address``: -equivalent to ``uint160``, except for the assumed interpretation and -language typing. - ``uint``, ``int``: synonyms for ``uint256``, -``int256`` respectively (not to be used for computing the function -selector). - ``bool``: equivalent to ``uint8`` restricted to the values -0 and 1 - ``realx``: fixed-point signed number of ``N+M`` bits, -``0 < N + M <= 256``, ``N % 8 == M % 8 == 0``. Corresponds to the int256 -equivalent binary value divided by ``2^M``. - ``urealx``: unsigned -variant of ``realx``. - ``real``, ``ureal``: synonyms for -``real128x128``, ``ureal128x128`` respectively (not to be used for -computing the function selector). - ``bytes``: binary type of ``N`` -bytes, ``0 < N <= 32``. - -The following (fixed-size) array type exists: - ``[N]``: a -fixed-length array of the given fixed-length type. - -The following non-fixed-size types exist: - ``bytes``: dynamic sized -byte sequence. - ``string``: dynamic sized unicode string assumed to be -UTF-8 encoded. - ``[]``: a variable-length array of the given -fixed-length type. - -Formal Specification of the Encoding -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -We will now formally specify the encoding, such that it will have the -following properties, which are especially useful if some arguments are -nested arrays: - -**Properties:** - -1. The number of reads necessary to access a value is at most the depth - of the value inside the argument array structure, i.e. four reads are - needed to retrieve ``a_i[k][l][r]``. In a previous version of the - ABI, the number of reads scaled linearly with the total number of - dynamic parameters in the worst case. - -2. The data of a variable or array element is not interleaved with other - data and it is relocatable, i.e. it only uses relative "addresses" - -We distinguish static and dynamic types. Static types are encoded -in-place and dynamic types are encoded at a separately allocated -location after the current block. - -**Definition:** The following types are called "dynamic": \* ``bytes`` -\* ``string`` \* ``T[]`` for any ``T`` \* ``T[k]`` for any dynamic ``T`` -and any ``k > 0`` - -All other types are called "static". - -**Definition:** ``len(a)`` is the number of bytes in a binary string -``a``. The type of ``len(a)`` is assumed to be ``uint256``. - -We define ``enc``, the actual encoding, as a mapping of values of the -ABI types to binary strings such that ``len(enc(X))`` depends on the -value of ``X`` if and only if the type of ``X`` is dynamic. - -**Definition:** For any ABI value ``X``, we recursively define -``enc(X)``, depending on the type of ``X`` being - -- ``T[k]`` for any ``T`` and ``k``: - -``enc(X) = head(X[0]) ... head(X[k-1]) tail(X[0]) ... tail(X[k-1])`` - -where ``head`` and ``tail`` are defined for ``X[i]`` being of a static -type as ``head(X[i]) = enc(X[i])`` and ``tail(X[i]) = ""`` (the empty -string) and as -``head(X[i]) = enc(len(head(X[0]) ... head(X[k-1]) tail(X[0]) ... tail(X[i-1])))`` -``tail(X[i]) = enc(X[i])`` otherwise. - -Note that in the dynamic case, ``head(X[i])`` is well-defined since the -lengths of the head parts only depend on the types and not the values. -Its value is the offset of the beginning of ``tail(X[i])`` relative to -the start of ``enc(X)``. - -- ``T[]`` where ``X`` has ``k`` elements (``k`` is assumed to be of - type ``uint256``): - -``enc(X) = enc(k) enc([X[1], ..., X[k]])`` - -i.e. it is encoded as if it were an array of static size ``k``, prefixed -with the number of elements. - -- ``bytes``, of length ``k`` (which is assumed to be of type - ``uint256``): - -``enc(X) = enc(k) pad_right(X)``, i.e. the number of bytes is encoded as -a ``uint256`` followed by the actual value of ``X`` as a byte sequence, -followed by the minimum number of zero-bytes such that ``len(enc(X))`` -is a multiple of 32. - -- ``string``: - -``enc(X) = enc(enc_utf8(X))``, i.e. ``X`` is utf-8 encoded and this -value is interpreted as of ``bytes`` type and encoded further. Note that -the length used in this subsequent encoding is the number of bytes of -the utf-8 encoded string, not its number of characters. - -- ``uint``: ``enc(X)`` is the big-endian encoding of ``X``, padded - on the higher-order (left) side with zero-bytes such that the length - is a multiple of 32 bytes. -- ``address``: as in the ``uint160`` case -- ``int``: ``enc(X)`` is the big-endian two's complement encoding of - ``X``, padded on the higher-oder (left) side with ``0xff`` for - negative ``X`` and with zero bytes for positive ``X`` such that the - length is a multiple of 32 bytes. -- ``bool``: as in the ``uint8`` case, where ``1`` is used for ``true`` - and ``0`` for ``false`` -- ``realx``: ``enc(X)`` is ``enc(X * 2**M)`` where ``X * 2**M`` - is interpreted as a ``int256``. -- ``real``: as in the ``real128x128`` case -- ``urealx``: ``enc(X)`` is ``enc(X * 2**M)`` where ``X * 2**M`` - is interpreted as a ``uint256``. -- ``ureal``: as in the ``ureal128x128`` case -- ``bytes``: ``enc(X)`` is the sequence of bytes in ``X`` padded - with zero-bytes to a length of 32. - -Note that for any ``X``, ``len(enc(X))`` is a multiple of 32. - -Function Selector and Argument Encoding ---------------------------------------- - -All in all, a call to the function ``f`` with parameters -``a_1, ..., a_n`` is encoded as - -``function_selector(f) enc([a_1, ..., a_n])`` - -and the return values ``v_1, ..., v_k`` of ``f`` are encoded as - -``enc([v_1, ..., v_k])`` - -where the types of ``[a_1, ..., a_n]`` and ``[v_1, ..., v_k]`` are -assumed to be fixed-size arrays of length ``n`` and ``k``, respectively. -Note that strictly, ``[a_1, ..., a_n]`` can be an "array" with elements -of different types, but the encoding is still well-defined as the -assumed common type ``T`` (above) is not actually used. - -Examples --------- - -Given the contract: - -.. code:: js - - contract Foo { - function bar(real[2] xy) {} - function baz(uint32 x, bool y) returns (bool r) { r = x > 32 || y; } - function sam(bytes name, bool z, uint[] data) {} - } - -Thus for our ``Foo`` example if we wanted to call ``baz`` with the -parameters ``69`` and ``true``, we would pass 68 bytes total, which can -be broken down into: - -- ``0xcdcd77c0``: the Method ID. This is derived as the first 4 bytes - of the Keccak hash of the ASCII form of the signature - ``baz(uint32,bool)``. -- ``0x0000000000000000000000000000000000000000000000000000000000000045``: - the first parameter, a uint32 value ``69`` padded to 32 bytes -- ``0x0000000000000000000000000000000000000000000000000000000000000001``: - the second parameter - boolean ``true``, padded to 32 bytes - -In total: - -:: - - 0xcdcd77c000000000000000000000000000000000000000000000000000000000000000450000000000000000000000000000000000000000000000000000000000000001 - -It returns a single ``bool``. If, for example, it were to return -``false``, its output would be the single byte array -``0x0000000000000000000000000000000000000000000000000000000000000000``, -a single bool. - -If we wanted to call ``bar`` with the argument ``[2.125, 8.5]``, we -would pass 68 bytes total, broken down into: - ``0x3e279860``: the -Method ID. This is derived from the signature ``bar(real128x128[2])``. -Note that ``real`` is substituted for its canonical representation -``real128x128``. - -``0x0000000000000000000000000000000240000000000000000000000000000000``: -the first part of the first parameter, a real128x128 value ``2.125``. - -``0x0000000000000000000000000000000880000000000000000000000000000000``: -the first part of the first parameter, a real128x128 value ``8.5``. - -In total: - -:: - - 0x3e27986000000000000000000000000000000002400000000000000000000000000000000000000000000000000000000000000880000000000000000000000000000000 - -If we wanted to call ``sam`` with the arguments ``"dave"``, ``true`` and -``[1,2,3]``, we would pass 292 bytes total, broken down into: - -``0xa5643bf2``: the Method ID. This is derived from the signature -``sam(bytes,bool,uint256[])``. Note that ``uint`` is substituted for its -canonical representation ``uint256``. - -``0x0000000000000000000000000000000000000000000000000000000000000060``: -the location of the data part of the first parameter (dynamic type), -measured in bytes from the start of the arguments block. In this case, -``0x60``. - -``0x0000000000000000000000000000000000000000000000000000000000000001``: -the second parameter: boolean true. - -``0x00000000000000000000000000000000000000000000000000000000000000a0``: -the location of the data part of the third parameter (dynamic type), -measured in bytes. In this case, ``0xa0``. - -``0x0000000000000000000000000000000000000000000000000000000000000004``: -the data part of the first argument, it starts with the length of the -byte array in elements, in this case, 4. - -``0x6461766500000000000000000000000000000000000000000000000000000000``: -the contents of the first argument: the UTF-8 (equal to ASCII in this -case) encoding of ``"dave"``, padded on the right to 32 bytes. - -``0x0000000000000000000000000000000000000000000000000000000000000003``: -the data part of the third argument, it starts with the length of the -array in elements, in this case, 3. - -``0x0000000000000000000000000000000000000000000000000000000000000001``: -the first entry of the third parameter. - -``0x0000000000000000000000000000000000000000000000000000000000000002``: -the second entry of the third parameter. - -``0x0000000000000000000000000000000000000000000000000000000000000003``: -the third entry of the third parameter. - -In total: - -:: - - 0xa5643bf20000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000000000000464617665000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000003 - -Use of Dynamic Types -~~~~~~~~~~~~~~~~~~~~ - -A call to a function with the signature -``f(uint,uint32[],bytes10,bytes)`` with values -``(0x123, [0x456, 0x789], "1234567890", "Hello, world!")`` is encoded in -the following way: - -We take the first four bytes of -``sha3("f(uint256,uint32[],bytes10,bytes)")``, i.e. ``0x8be65246``. Then -we encode the head parts of all four arguments. For the static types -``uint256`` and ``bytes10``, these are directly the values we want to -pass, whereas for the dynamic types ``uint32[]`` and ``bytes``, we use -the offset in bytes to the start of their data area, measured from the -start of the value encoding (i.e. not counting the first four bytes -containing the hash of the function signature). These are: - -- ``0x0000000000000000000000000000000000000000000000000000000000000123`` - (``0x123`` padded to 32 bytes) -- ``0x0000000000000000000000000000000000000000000000000000000000000080`` - (offset to start of data part of second parameter, 4\*32 bytes, - exactly the size of the head part) -- ``0x3132333435363738393000000000000000000000000000000000000000000000`` - (``"1234567890"`` padded to 32 bytes on the right) -- ``0x00000000000000000000000000000000000000000000000000000000000000e0`` - (offset to start of data part of fourth parameter = offset to start - of data part of first dynamic parameter + size of data part of first - dynamic parameter = 4\ *32 + 3*\ 32 (see below)) - -After this, the data part of the first dynamic argument, -``[0x456, 0x789]`` follows: - -- ``0x0000000000000000000000000000000000000000000000000000000000000002`` - (number of elements of the array, 2) -- ``0x0000000000000000000000000000000000000000000000000000000000000456`` - (first element) -- ``0x0000000000000000000000000000000000000000000000000000000000000789`` - (second element) - -Finally, we encode the data part of the second dynamic argument, -``"Hello, world!"``: - -- ``0x000000000000000000000000000000000000000000000000000000000000000d`` - (number of elements (bytes in this case): 13) -- ``0x48656c6c6f2c20776f726c642100000000000000000000000000000000000000`` - (``"Hello, world!"`` padded to 32 bytes on the right) - -All together, the encoding is (spaces added for clarity): - -``0x8be65246 0000000000000000000000000000000000000000000000000000000000000123 0000000000000000000000000000000000000000000000000000000000000080 3132333435363738393000000000000000000000000000000000000000000000 00000000000000000000000000000000000000000000000000000000000000e0 0000000000000000000000000000000000000000000000000000000000000002 0000000000000000000000000000000000000000000000000000000000000456 0000000000000000000000000000000000000000000000000000000000000789 000000000000000000000000000000000000000000000000000000000000000d 48656c6c6f2c20776f726c642100000000000000000000000000000000000000`` - -Events -====== - -Events are an abstraction of the Ethereum logging/event-watching -protocol. Log entries provide the contract's address, a series of up to -four topics and some arbitrary length binary data. Events leverage the -existing function ABI in order to interpret this (together with an -interface spec) as a properly typed structure. - -Given an event name and series of event parameters, we split them into -two sub-series: those which are indexed and those which are not. Those -which are indexed, which may number up to 3, are used alongside the -Keccak hash of the event signature to form the topics of the log entry. -Those which as not indexed form the byte array of the event. - -In effect, a log entry using this ABI is described as: - -- ``address``: the address of the contract (intrinsically provided by - Ethereum); -- ``topics[0]``: - ``keccak(EVENT_NAME+"("+EVENT_ARGS.map(canonical_type_of).join(",")+")")`` - (``canonical_type_of`` is a function that simply returns the - canonical type of a given argument, e.g. for ``uint indexed foo``, it - would return ``uint256``). If the event is declared as ``anonymous`` - the ``topics[0]`` is not generated; -- ``topics[n]``: ``EVENT_INDEXED_ARGS[n - 1]`` (``EVENT_INDEXED_ARGS`` - is the series of ``EVENT_ARGS`` that are indexed); -- ``data``: ``abi_serialise(EVENT_NON_INDEXED_ARGS)`` - (``EVENT_NON_INDEXED_ARGS`` is the series of ``EVENT_ARGS`` that are - not indexed, ``abi_serialise`` is the ABI serialisation function used - for returning a series of typed values from a function, as described - above). - -JSON -==== - -The JSON format for a contract's interface is given by an array of -function and/or event descriptions. A function description is a JSON -object with the fields: - -- ``type``: ``"function"`` or ``"constructor"`` (can be omitted, - defaulting to function); -- ``name``: the name of the function (only present for function types); -- ``inputs``: an array of objects, each of which contains: -- ``name``: the name of the parameter; -- ``type``: the canonical type of the parameter. -- ``outputs``: an array of objects similar to ``inputs``, can be - omitted. - -An event description is a JSON object with fairly similar fields: - -- ``type``: always ``"event"`` -- ``name``: the name of the event; -- ``inputs``: an array of objects, each of which contains: -- ``name``: the name of the parameter; -- ``type``: the canonical type of the parameter. -- ``indexed``: ``true`` if the field is part of the log's topics, - ``false`` if it one of the log's data segment. -- ``anonymous``: ``true`` if the event was declared as ``anonymous``. - -For example, - -.. code:: js - - contract Test { - function Test(){ b = 0x12345678901234567890123456789012; } - event Event(uint indexed a, bytes32 b) - event Event2(uint indexed a, bytes32 b) - function foo(uint a) { Event(a, b); } - bytes32 b; - } - -would result in the JSON: - -.. code:: js - - [{ - "type":"event", - "inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}], - "name":"Event" - }, { - "type":"event", - "inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}], - "name":"Event2" - }, { - "type":"event", - "inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}], - "name":"Event2" - }, { - "type":"function", - "inputs": [{"name":"a","type":"uint256"}], - "name":"foo", - "outputs": [] - }] - -Example Javascript Usage -======================== - -.. code:: js - - var Test = eth.contract( - [{ - "type":"event", - "inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}], - "name":"Event" - }, { - "type":"event", - "inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}], - "name":"Event2" - }, { - "type":"function", - "inputs": [{"name":"a","type":"uint256"}], - "name":"foo", - "outputs": [] - }]); - var theTest = new Test(addrTest); - - // examples of usage: - // every log entry ("event") coming from theTest (i.e. Event & Event2): - var f0 = eth.filter(theTest); - // just log entries ("events") of type "Event" coming from theTest: - var f1 = eth.filter(theTest.Event); - // also written as - var f1 = theTest.Event(); - // just log entries ("events") of type "Event" and "Event2" coming from theTest: - var f2 = eth.filter([theTest.Event, theTest.Event2]); - // just log entries ("events") of type "Event" coming from theTest with indexed parameter 'a' equal to 69: - var f3 = eth.filter(theTest.Event, {'a': 69}); - // also written as - var f3 = theTest.Event({'a': 69}); - // just log entries ("events") of type "Event" coming from theTest with indexed parameter 'a' equal to 69 or 42: - var f4 = eth.filter(theTest.Event, {'a': [69, 42]}); - // also written as - var f4 = theTest.Event({'a': [69, 42]}); - - // options may also be supplied as a second parameter with `earliest`, `latest`, `offset` and `max`, as defined for `eth.filter`. - var options = { 'max': 100 }; - var f4 = theTest.Event({'a': [69, 42]}, options); - - var trigger; - f4.watch(trigger); - - // call foo to make an Event: - theTest.foo(69); - - // would call trigger like: - //trigger(theTest.Event, {'a': 69, 'b': '0x12345678901234567890123456789012'}, n); - // where n is the block number that the event triggered in. - -Implementation: - -.. code:: js - - // e.g. f4 would be similar to: - web3.eth.filter({'max': 100, 'address': theTest.address, 'topics': [ [69, 42] ]}); - // except that the resultant data would need to be converted from the basic log entry format like: - { - 'address': theTest.address, - 'topics': [web3.sha3("Event(uint256,bytes32)"), 0x00...0045 /* 69 in hex format */], - 'data': '0x12345678901234567890123456789012', - 'number': n - } - // into data good for the trigger, specifically the three fields: - Test.Event // derivable from the first topic - {'a': 69, 'b': '0x12345678901234567890123456789012'} // derivable from the 'indexed' bool in the interface, the later 'topics' and the 'data' - n // from the 'number' - -Event result: - -.. code:: js - - [ { - 'event': Test.Event, - 'args': {'a': 69, 'b': '0x12345678901234567890123456789012'}, - 'number': n - }, - { ... - } ... - ] - -JUST DONE! [develop branch] -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**NOTE: THIS IS OLD - IGNORE IT unless reading for historical purposes** - -- Internal LogFilter, log-entry matching mechanism and - eth\_installFilter needs to support matching multiple values (OR - semantics) *per* topic index (at present it will only match topics - with AND semantics and set-inclusion, not per-index). - -i.e. at present you can only ask for each of a number of given topic -values to be matched throughout each topic: - -- ``topics: [69, 42, "Gav"]`` would match against logs with 3 topics - ``[42, 69, "Gav"]``, ``["Gav", 69, 42]`` but **not** against logs - with topics ``[42, 70, "Gav"]``. - -we need to be able to provide one of a number of topic values, and, each -of these options for each topic index: - -- ``topics: [[69, 42], [] /* anything */, "Gav"]`` should match against - logs with 3 topics ``[42, 69, "Gav"]``, ``[42, 70, "Gav"]`` but - **not** against ``["Gav", 69, 42]``. diff --git a/old-docs-for-reference/main-wiki.rst/Ethereum-Development-Tutorial.rst b/old-docs-for-reference/main-wiki.rst/Ethereum-Development-Tutorial.rst deleted file mode 100644 index 4548770..0000000 --- a/old-docs-for-reference/main-wiki.rst/Ethereum-Development-Tutorial.rst +++ /dev/null @@ -1,487 +0,0 @@ -**OUTDATED** *This document can contain outdated information, specific -API's might be different.* - -The purpose of this page is to serve as an introduction to the basics of -Ethereum that you will need to understand from a development standpoint, -in order to produce contracts and decentralized applications. For a -general introduction to Ethereum, see `the white -paper `__, and for a -full technical spec see the `yellow `__ -papers, although those are not prerequisites for this page; that is to -say, this page is meant as an alternative introduction to Ethereum -specifically targeted towards application developers. - -Introduction -~~~~~~~~~~~~ - -Ethereum is a platform that is intended to allow people to easily write -decentralized applications (dapps) using blockchain technology. A -decentralized application is an application which serves some specific -purpose to its users, but which has the important property that the -application itself does not depend on any specific party existing. -Rather than serving as a front-end for selling or providing a specific -party's services, a dapp is a tool for people and organizations on -different sides of an interaction use to come together without any -centralized intermediary. - -Even necessary "intermediary" functions that are typically the domain of -centralized providers, such as filtering, identity management, escrow -and dispute resolution, are either handled directly by the network or -left open for anyone to participate, using tools like internal token -systems and reputation systems to ensure that users get access to -high-quality services. Early examples of dapps include BitTorrent for -file sharing and Bitcoin for currency. Ethereum takes the primary -developments used by BitTorrent and Bitcoin, the peer to peer network -and the blockchain, and generalizes them in order to allow developers to -use these technologies for any purpose. - -The Ethereum blockchain can be alternately described as a blockchain -with a built-in programming language, or as a consensus-based globally -executed virtual machine. The part of the protocol that actually handles -internal state and computation is referred to as the Ethereum Virtual -Machine (EVM). From a practical standpoint, the EVM can be thought of as -a large decentralized computer containing millions of objects, called -"accounts", which have the ability to maintain an internal database, -execute code and talk to each other. - -There are two types of accounts: - -1. **Externally owned account (EOAs)**: an account controlled by a - private key, and if you own the private key associated with the EOA - you have the ability to send ether and messages from it. -2. **Contract**: an account that has its own code, and is controlled by - code. - -By default, the Ethereum execution environment is lifeless; nothing -happens and the state of every account remains the same. However, any -user can trigger an action by sending a transaction from an externally -owned account, setting Ethereum's wheels in motion. If the destination -of the transaction is another EOA, then the transaction may transfer -some ether but otherwise does nothing. However, if the destination is a -contract, then the contract in turn activates, and automatically runs -its code. - -The code has the ability to read/write to its own internal storage (a -database mapping 32-byte keys to 32-byte values), read the storage of -the received message, and send messages to other contracts, triggering -their execution in turn. Once execution stops, and all sub-executions -triggered by a message sent by a contract stop (this all happens in a -deterministic and synchronous order, ie. a sub-call completes fully -before the parent call goes any further), the execution environment -halts once again, until woken by the next transaction. - -Contracts generally serve four purposes: - -1. Maintain a data store representing something which is useful to - either other contracts or to the outside world; one example of this - is a contract that simulates a currency, and another is a contract - that records membership in a particular organization. - -2. Serve as a sort of externally owned account with a more complicated - access policy; this is called a "forwarding contract" and typically - involves simply resending incoming messages to some desired - destination only if certain conditions are met; for example, one can - have a forwarding contract that waits until two out of a given three - private keys have confirmed a particular message before resending it - (ie. multisig). More complex forwarding contracts have different - conditions based on the nature of the message sent; the simplest use - case for this functionality is a withdrawal limit that is - overrideable via some more complicated access procedure. - -3. Manage an ongoing contract or relationship between multiple users. - Examples of this include a financial contract, an escrow with some - particular set of mediators, or some kind of insurance. One can also - have an open contract that one party leaves open for any other party - to engage with at any time; one example of this is a contract that - automatically pays a bounty to whoever submits a valid solution to - some mathematical problem, or proves that it is providing some - computational resource. - -4. Provide functions to other contracts; essentially serving as a - software library. - -Contracts interact with each other through an activity that is -alternately called either "calling" or "sending messages". A "message" -is an object containing some quantity of ether (a special internal -currency used in Ethereum with the primary purpose of paying transaction -fees), a byte-array of data of any size, the addresses of a sender and a -recipient. When a contract receives a message it has the option of -returning some data, which the original sender of the message can then -immediately use. In this way, sending a message is exactly like calling -a function. - -Because contracts can play such different roles, we expect that -contracts will be interacting with each other. As an example, consider a -situation where Alice and Bob are betting 100 GavCoin that the -temperature in San Francisco will not exceed 35ºC at any point in the -next year. However, Alice is very security-conscious, and as her primary -account uses a forwarding contract which only sends messages with the -approval of two out of three private keys. Bob is paranoid about quantum -cryptography, so he uses a forwarding contract which passes along only -messages that have been signed with `Lamport -signatures `__ -alongside traditional ECDSA (but because he's old fashioned, he prefers -to use a version of Lamport sigs based on SHA256, which is not supported -in Ethereum directly). - -The betting contract itself needs to fetch data about the San Francisco -weather from some contract, and it also needs to talk to the GavCoin -contract when it wants to actually send the GavCoin to either Alice or -Bob (or, more precisely, Alice or Bob's forwarding contract). We can -show the relationships between the accounts thus: - -.. figure:: https://raw.githubusercontent.com/ethereumbuilders/GitBook/master/en/vitalik-diagrams/contract_relationship.png - :alt: img - - img - -When Bob wants to finalize the bet, the following steps happen: - -1. A transaction is sent, triggering a message from Bob's EOA to Bob's - forwarding contract. -2. Bob's forwarding contract sends the hash of the message and the - Lamport signature to a contract which functions as a Lamport - signature verification library. -3. The Lamport signature verification library sees that Bob wants a - SHA256-based Lamport sig, so it calls the SHA256 library many times - as needed to verify the signature. -4. Once the Lamport signature verification library returns 1, signifying - that the signature has been verified, it sends a message to the - contract representing the bet. -5. The bet contract checks the contract providing the San Francisco - temperature to see what the temperature is. -6. The bet contract sees that the response to the messages shows that - the temperature is above 35ºC, so it sends a message to the GavCoin - contract to move the GavCoin from its account to Bob's forwarding - contract. - -Note that the GavCoin is all "stored" as entries in the GavCoin -contract's database; the word "account" in the context of step 6 simply -means that there is a data entry in the GavCoin contract storage with a -key for the bet contract's address and a value for its balance. After -receiving this message, the GavCoin contract decreases this value by -some amount and increases the value in the entry corresponding to Bob's -forwarding contract's address. We can see these steps in the following -diagram: - -.. figure:: https://raw.githubusercontent.com/ethereumbuilders/GitBook/master/en/vitalik-diagrams/contract_relationship2.png?1 - :alt: img - - img - -State Machine -~~~~~~~~~~~~~ - -Computation in the EVM is done using a stack-based bytecode language -that is like a cross between Bitcoin Script, traditional assembly and -Lisp (the Lisp part being due to the recursive message-sending -functionality). A program in EVM is a sequence of opcodes, like this: - -:: - - PUSH1 0 CALLDATALOAD SLOAD NOT PUSH1 9 JUMPI STOP JUMPDEST PUSH1 32 CALLDATALOAD PUSH1 0 CALLDATALOAD SSTORE - -The purpose of this particular contract is to serve as a name registry; -anyone can send a message containing 64 bytes of data, 32 for the key -and 32 for the value. The contract checks if the key has already been -registered in storage, and if it has not been then the contract -registers the value at that key. - -During execution, an infinitely expandable byte-array called "memory", -the "program counter" pointing to the current instruction, and a stack -of 32-byte values is maintained. At the start of execution, memory and -stack are empty and the PC is zero. Now, let us suppose the contract -with this code is being accessed for the first time, and a message is -sent in with 123 wei (1018 wei = 1 ether) and 64 bytes of data where the -first 32 bytes encode the number 54 and the second 32 bytes encode the -number 2020202020. - -Thus, the state at the start is: - -:: - - PC: 0 STACK: [] MEM: [], STORAGE: {} - -The instruction at position 0 is PUSH1, which pushes a one-byte value -onto the stack and jumps two steps in the code. Thus, we have: - -:: - - PC: 2 STACK: [0] MEM: [], STORAGE: {} - -The instruction at position 2 is CALLDATALOAD, which pops one value from -the stack, loads the 32 bytes of message data starting from that index, -and pushes that on to the stack. Recall that the first 32 bytes here -encode 54. - -:: - - PC: 3 STACK: [54] MEM: [], STORAGE: {} - -SLOAD pops one from the stack, and pushes the value in contract storage -at that index. Since the contract is used for the first time, it has -nothing there, so zero. - -:: - - PC: 4 STACK: [0] MEM: [], STORAGE: {} - -NOT pops one value and pushes 1 if the value is zero, else 0 - -:: - - PC: 5 STACK: [1] MEM: [], STORAGE: {} - -Next, we PUSH1 9. - -:: - - PC: 7 STACK: [1, 9] MEM: [], STORAGE: {} - -The JUMPI instruction pops 2 values and jumps to the instruction -designated by the first only if the second is nonzero. Here, the second -is nonzero, so we jump. If the value in storage index 54 had not been -zero, then the second value from top on the stack would have been 0 (due -to NOT), so we would not have jumped, and we would have advanced to the -STOP instruction which would have led to us stopping execution. - -:: - - PC: 9 STACK: [] MEM: [], STORAGE: {} - -Here, we PUSH1 32. - -:: - - PC: 11 STACK: [32] MEM: [], STORAGE: {} - -Now, we CALLDATALOAD again, popping 32 and pushing the bytes in message -data starting from byte 32 until byte 63. - -:: - - PC: 13 STACK: [2020202020] MEM: [], STORAGE: {} - -Next, we PUSH1 0. - -:: - - PC: 14 STACK: [2020202020, 0] MEM: [], STORAGE: {} - -Now, we load message data bytes 0-31 again (loading message data is just -as cheap as loading memory, so we don't bother to save it in memory) - -:: - - PC: 16 STACK: [2020202020, 54] MEM: [], STORAGE: {} - -Finally, we SSTORE to save the value 2020202020 in storage at index 54. - -:: - - PC: 17 STACK: [] MEM: [], STORAGE: {54: 2020202020} - -At index 17, there is no instruction, so we stop. If there was anything -left in the stack or memory, it would be deleted, but the storage will -stay and be available next time someone sends a message. Thus, if the -sender of this message sends the same message again (or perhaps someone -else tries to reregister 54 to 3030303030), the next time the ``JUMPI`` -at position 7 would not process, and execution would STOP early at -position 8. - -Fortunately, you do not have to program in low-level assembly; a -high-level language exists, especially designed for writing contracts, -known as `Solidity `__ -exists to make it much easier for you to write contracts (there are -several others, too, including -`LLL `__, -`Serpent `__ and -`Mutan `__, -which you may find easier to learn or use depending on your experience). -Any code you write in these languages gets compiled into EVM, and to -create the contracts you send the transaction containing the EVM -bytecode. - -There are two types of transactions: a sending transaction and a -contract creating transaction. A sending transaction is a standard -transaction, containing a receiving address, an ether amount, a data -bytearray and some other parameters, and a signature from the private -key associated with the sender account. A contract creating transaction -looks like a standard transaction, except the receiving address is -blank. When a contract creating transaction makes its way into the -blockchain, the data bytearray in the transaction is interpreted as EVM -code, and the value returned by that EVM execution is taken to be the -code of the new contract; hence, you can have a transaction do certain -things during initialization. The address of the new contract is -deterministically calculated based on the sending address and the number -of times that the sending account has made a transaction before (this -value, called the account nonce, is also kept for unrelated security -reasons). Thus, the full code that you need to put onto the blockchain -to produce the above name registry is as follows: - -:: - - PUSH1 16 DUP PUSH1 12 PUSH1 0 CODECOPY PUSH1 0 RETURN STOP PUSH1 0 CALLDATALOAD SLOAD NOT PUSH1 9 JUMPI STOP PUSH1 32 CALLDATALOAD PUSH1 0 CALLDATALOAD SSTORE - -The key opcodes are CODECOPY, copying the 16 bytes of code starting from -byte 12 into memory starting at index 0, and RETURN, returning memory -bytes 0-16, ie. code bytes 12-28 (feel free to "run" the execution -manually on paper to verify that those parts of the code and memory -actually get copied and returned). Code bytes 12-28 are, of course, the -actual code as we saw above. - -Gas -~~~ - -One important aspect of the way the EVM works is that every single -operation that is executed inside the EVM is actually simultaneously -executed by every full node. This is a necessary component of the -Ethereum 1.0 consensus model, and has the benefit that any contract on -the EVM can call any other contract at almost zero cost, but also has -the drawback that computational steps on the EVM are very expensive. -Roughly, a good heuristic to use is that you will not be able to do -anything on the EVM that you cannot do on a smartphone from 1999. -Acceptable uses of the EVM include running business logic ("if this then -that") and verifying signatures and other cryptographic objects; at the -upper limit of this are applications that verify parts of other -blockchains (eg. a decentralized ether-to-bitcoin exchange); -unacceptable uses include using the EVM as a file storage, email or text -messaging system, anything to do with graphical interfaces, and -applications best suited for cloud computing like genetic algorithms, -graph analysis or machine learning. - -In order to prevent deliberate attacks and abuse, the Ethereum protocol -charges a fee per computational step. The fee is market-based, though -mandatory in practice; a floating limit on the number of operations that -can be contained in a block forces even miners who can afford to include -transactions at close to no cost to charge a fee commensurate with the -cost of the transaction to the entire network; see `the whitepaper -section on -fees `__ -for more details on the economic underpinnings of our fee and block -operation limit system. - -The way the fee works is as follows. Every transaction must contain, -alongside its other data, a ``GASPRICE`` and ``STARTGAS`` value. -``STARTGAS`` is the amount of "gas" that the transaction assigns itself, -and ``GASPRICE`` is the fee that the transaction pays per unit of gas; -thus, when a transaction is sent, the first thing that is done during -evaluation is subtracting ``STARTGAS * GASPRICE`` wei plus the -transaction's value from the sending account balance. ``GASPRICE`` is -set by the transaction sender, but miners will likely refuse to process -transactions whose ``GASPRICE`` is too low. - -Gas can be roughly thought of as a counter of computational steps, and -is something that exists during transaction execution but not outside of -it. When transaction execution starts, the gas remaining is set to -``STARTGAS - 21000 - 68 * TXDATALEN`` where ``TXDATALEN`` is the number -of bytes in transaction data (note: zero bytes are charged only 4 gas -due to the greater compressibility of long strings of zero bytes). Every -computational step, a certain amount (usually 1, sometimes more -depending on the operation) of gas is subtracted from the total. If gas -goes down to zero, then all execution reverts, but the transaction is -still valid and the sender still has to pay for gas. If transaction -execution finishes with ``N >= 0`` gas remaining, then the sending -account is refunded with ``N * GASPRICE`` wei. - -During contract execution, when a contract sends a message, that message -call itself comes with a gas limit, and the sub-execution works the same -way (namely, it can either run out of gas and revert or execute -successfully and return a value). If sub-execution runs out of gas, the -parent execution continues; thus, it is perfectly "safe" for a contract -to call another contract if you set a gas limit on the sub-execution. If -sub-execution has some gas remaining, then that gas is returned to the -parent execution to continue using. - -Virtual machine opcodes -~~~~~~~~~~~~~~~~~~~~~~~ - -A complete listing of the opcodes in the EVM can be found in the `yellow -paper `__. Note that high-level languages -will often have their own wrappers for these opcodes, sometimes with -very different interfaces. - -Basics of the Ethereum Blockchain -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The Ethereum blockchain (or "ledger") is the decentralized, massively -replicated database in which the current state of all accounts is -stored. The blockchain uses a database called a `Patricia -tree `__ (or -"trie") to store all accounts; this is essentially a specialized kind of -Merkle tree that acts as a generic key/value store. Like a standard -Merkle tree, a Patricia tree has a "root hash" that can be used to refer -to the entire tree, and the contents of the tree cannot be modified -without changing the root hash. For each account, the tree stores a -4-tuple containing -``[account_nonce, ether_balance, code_hash, storage_root]``, where -``account_nonce`` is the number of transactions sent from the account -(kept to prevent replay attacks), ``ether_balance`` is the balance of -the account, ``code_hash`` the hash of the code if the account is a -contract and "" otherwise, and ``storage_root`` is the root of yet -another Patricia tree which stores the storage data. - -.. figure:: https://raw.githubusercontent.com/ethereumbuilders/GitBook/master/en/vitalik-diagrams/chaindiag.png - :alt: we - - we - -Every minute, a miner produces a new block (the concept of mining in -Ethereum is exactly the same as in Bitcoin; see any Bitcoin tutorial for -more info on this), and that block contains a list of transactions that -happened since the last block and the root hash of the Patricia tree -representing the new state ("state tree") after applying those -transactions and giving the miner an ether reward for creating the -block. - -Because of the way the Patricia tree works, if few changes are made then -most parts of the tree will be exactly the same as in the last block; -hence, there is no need to store data twice as nodes in the new tree -will simply be able to point back to the same memory address that stores -the nodes of the old tree in places where the new tree and the old tree -are exactly the same. If a thousand pieces of data are changed between -block ``N`` and block ``N + 1``, even if the total size of the tree is -many gigabytes, the amount of new data that needs to be stored for block -``N + 1`` is at most a few hundred kilobytes and often substantially -less (especially if multiple changes happen inside the same contract). -Every block contains the hash of the previous block (this is what makes -the block set a "chain") as well as ancillary data like the block -number, timestamp, address of the miner and gas limit. - -Graphical Interfaces (*OUTDATED API*) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A contract by itself is a powerful thing, but it is not a complete dapp. -A dapp, rather, is defined as a combination of a contract and a -graphical interface for using that contract (note: this is only true for -now; future versions of Ethereum will include whisper, a protocol for -allowing nodes in a dapp to send direct peer-to-peer messages to each -other without the blockchain). Right now, the interface is implemented -as an HTML/CSS/JS webpage, with a special Javascript API in the form of -the ``eth`` object for working with the Ethereum blockchain. The key -parts of the Javascript API are as follows: - -- ``eth.transact(from, ethervalue, to, data, gaslimit, gasprice)`` - - sends a transaction to the desired address from the desired address - (note: ``from`` must be a private key and ``to`` must be an address - in hex form) with the desired parameters -- ``(string).pad(n)`` - converts a number, encoded as a string, to - binary form ``n`` bytes long -- ``eth.gasPrice`` - returns the current gas price -- ``eth.secretToAddress(key)`` - converts a private key into an address -- ``eth.storageAt(acct, index)`` - returns the desired account's - storage entry at the desired index -- ``eth.key`` - the user's private key -- ``eth.watch(acct, index, f)`` - calls ``f`` when the given storage - entry of the given account changes - -You do not need any special source file or library to use the ``eth`` -object; however, your dapp will only work when opened in an Ethereum -client, not a regular web browser. For an example of the Javascript API -being used in practice, see `the source code of this -webpage `__. - -Fine Points To Keep Track Of -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -See https://github.com/ethereum/wiki/wiki/Subtleties diff --git a/old-docs-for-reference/main-wiki.rst/Ethereum-Natural-Specification-Format.rst b/old-docs-for-reference/main-wiki.rst/Ethereum-Natural-Specification-Format.rst deleted file mode 100644 index 847a232..0000000 --- a/old-docs-for-reference/main-wiki.rst/Ethereum-Natural-Specification-Format.rst +++ /dev/null @@ -1,157 +0,0 @@ -Solidity contracts can have a special form of comments that form the -basis of the Ethereum Natural Specification Format. For a usage example -please check -`here `__. - -Documentation Example -===================== - -Documentation is inserted above the function following the doxygen -notation of either one or multiple lines starting with ``///`` or a -multiline comment starting with ``/**`` and ending with ``*/``. - -As an example consider the documentation of the following function: - -:: - - /// @notice Send `(valueInmGAV / 1000).fixed(0,3)` GAV from the account of - /// `message.caller.address()`, to an account accessible only by `to.address() - /// @dev This should be the documentation of the function for the developer docs - /// @param to The address of the recipient of the GavCoin - /// @param valueInmGav The GavCoin value to send - function send(address to, uint256 valueInmGAV) { - if (balances[message.caller] >= valueInmGAV) { - balances[to] += valueInmGAV; - balances[message.caller] -= valueInmGAV; - } - -There are a few things to note about the above example. - Natspec format -uses doxygen tags with some special meaning. These are: + @title: This -is a title that should describe the contract and go above the contract -definition + @author: The name of the author of the contract. Should -also go above the contract definition. + @notice: Represents user -documentation. This is the text that will appear to the user to notify -him of what the function he is about to execute is doing + @dev: -Represents developer documentation. This is documentation that would -only be visible to the developer. + @param: Documents a parameter just -like in doxygen. Has to be followed by the parameter name. + @return: -Documents the return type of a contract's function. - -- If any of the above are missing they are simply considered as blank - and it's not illegal to omit any of them - -- ``(valueInmGAV / 1000).fixed(0,3)`` A dynamic expression. This should - be a valid Javascript/Paperscript expression, which when evaluated in - an EVM Javascript environment initialised with various system values - (such as parameters). - -Documentation Output -==================== - -When parsed, documentation such as the one from the above example will -produce 2 different json files. One is meant to be consumed by the user -as a notice when a function is executed and the other to be used by the -developer. - -Let us see a more full contract example. - -:: - - /// @title This is the contract title. - /// @author Homer Simpson - contract GavCoin - { - /// @notice Send `(valueInmGAV / 1000).fixed(0,3)` GAV from the account of - /// `message.caller.address()`, to an account accessible only by `to.address() - /// @dev This should be the documentation of the function for the developer docs - /// @param to The address of the recipient of the GavCoin - /// @param valueInmGav The GavCoin value to send - function send(address to, uint256 valueInmGAV) { - if (balances[message.caller] >= valueInmGAV) { - balances[to] += valueInmGAV; - balances[message.caller] -= valueInmGAV; - } - } - - /// @notice `(balanceInmGAV / 1000).fixed(0,3)` GAV is the total funds available to `who.address()`. - /// @param who The address of the person whose balance we check - /// @return The balance of the user provided as argument - function balance(address who) constant returns (uint256 balanceInmGAV) { - balanceInmGAV = balances[who]; - } - - invariants: - /// @notice The sum total amount of GAV in the system is 1 million. - /// @dev This is the invariant development documentation - reduce(0, add, map(valueOf, balances)) == 100000000000; - - construction: - /// @notice Endows `message.caller.address()` with 1m GAV. - balances[message.caller] = 100000000000; - - state: - mapping balances(address) returns uint256 with function(address a) returns uint256 { return a; }; - }; - -User Documentation ------------------- - -The above documentation will produce the following user documentation -json file as output: - -:: - - { - "source": "...", - "language": "Solidity", - "languageVersion": 1, - "methods": { - "send(address,uint256)": { "notice": "Send `(valueInmGAV / 1000).fixed(0,3)` GAV from the account of `message.caller.address()`, to an account accessible only by `to.address()`." }, - "balance(address)": { "notice": "`(balanceInmGAV / 1000).fixed(0,3)` GAV is the total funds available to `who.address()`." } - }, - "invariants": [ - { "notice": "The sum total amount of GAV in the system is 1 million." } - ], - "construction": [ - { "notice": "Endows `message.caller.address()` with 1m GAV." } - ] - } - -Note that the key by which to find the methods is the function's -canonical signature as defined in the `Contract -ABI `__ -and not simply the function's name. - -Developer Documentation ------------------------ - -Apart from the user documentation file, a developer documentation json -file should also be produced and should look like this: - -:: - - { - "author": "Homer Simpson", - "title": "This is the contract title.", - "methods": { - "send(uint256)": { - "details": "This should be the documentation of the function for the developer docs" - }, - "balance": { - "details": "" - } - }, - "invariants": [ - { "details": "This is the invariant development documentation"} - ], - "construction": { - "details": "" - } - } - -Example usage -------------- - -There is a detailed example of using the Natspec feature with the cpp -client -`here `__. diff --git a/old-docs-for-reference/main-wiki.rst/Ethereum-Wire-Protocol.rst b/old-docs-for-reference/main-wiki.rst/Ethereum-Wire-Protocol.rst deleted file mode 100644 index 49100ac..0000000 --- a/old-docs-for-reference/main-wiki.rst/Ethereum-Wire-Protocol.rst +++ /dev/null @@ -1,193 +0,0 @@ -Peer-to-peer communications between nodes running Ethereum clients run -using the underlying `ÐΞVp2p Wire -Protocol `__. - -Basic Chain Syncing -~~~~~~~~~~~~~~~~~~~ - -- Two peers connect & say Hello and send their Status message. Status - includes the Total Difficulty(TD) & hash of their best block. -- The client with the worst TD asks peer for full chain of just block - hashes. -- Chain of hashes is stored in space shared by all peer connections, - and used as a "work pool". -- While there are hashes in the chain of hashes that we don't have in - our chain: -- Ask for N blocks from our peer using the hashes. Mark them as on - their way so we don't get them from another peer. - -Ethereum Sub-protocol -~~~~~~~~~~~~~~~~~~~~~ - -**Status** [``+0x00``: ``P``, ``protocolVersion``: ``P``, ``networkId``: -``P``, ``td``: ``P``, ``bestHash``: ``B_32``, ``genesisHash``: ``B_32``] -Inform a peer of it's current **ethereum** state. This message should be -sent *after* the initial handshake and *prior* to any **ethereum** -related messages. \* ``protocolVersion`` is one of: \* ``0x00`` for -PoC-1; \* ``0x01`` for PoC-2; \* ``0x07`` for PoC-3; \* ``0x09`` for -PoC-4. \* ``0x17`` for PoC-5. \* ``0x1c`` for PoC-6. \* ``networkId`` -should be 0 for testnet, 1 for mainnet. \* ``td``: Total Difficulty of -the best chain. Integer, as found in block header. \* ``bestHash``: The -hash of the best (i.e. highest TD) known block. \* ``genesisHash``: The -hash of the Genesis block. - -**NewBlockHashes** [``+0x01``: ``P``, ``hash1``: ``B_32``, ``hash2``: -``B_32``, ``...``] Specify one or more new blocks which have appeared on -the network. The list may contain 256 hashes at most. To be maximally -helpful, nodes should inform peers of all blocks that they may not be -aware of. Including hashes that the sending peer could reasonably be -considered to know (due to the fact they were previously informed of -because that node has itself advertised knowledge of the hashes through -``NewBlockHashes``) is considered Bad Form, and may reduce the -reputation of the sending node. Including hashes that the sending node -later refuses to honour with a proceeding ``GetBlocks`` message is -considered Bad Form, and may reduce the reputation of the sending node. - -**Transactions** [``+0x02``: ``P``, [``nonce``: ``P``, -``receivingAddress``: ``B_20``, ``value``: ``P``, ``...``], ``...``] -Specify (a) transaction(s) that the peer should make sure is included on -its transaction queue. The items in the list (following the first item -``0x12``) are transactions in the format described in the main Ethereum -specification. Nodes must not resend the same transaction to a peer in -the same session. This packet must contain at least one (new) -transaction. - -**GetBlockHashes** [``+0x03``: ``P``, ``hash`` : ``B_32``, -``maxBlocks``: ``P``] Requests a ``BlockHashes`` message of at most -``maxBlocks`` entries, of block hashes from the blockchain, starting at -the parent of block ``hash``. Does not *require* the peer to give -``maxBlocks`` hashes - they could give somewhat fewer. - -**BlockHashes** [``+0x04``: ``P``, ``hash_0``: ``B_32``, ``hash_1``: -``B_32``, ``...``] Gives a series of hashes of blocks (each the child of -the next). This implies that the blocks are ordered from youngest to -oldest. - -**GetBlocks** [``+0x05``: ``P``, ``hash_0``: ``B_32``, ``hash_1``: -``B_32``, ``...``] Requests a ``Blocks`` message detailing a number of -blocks to be sent, each referred to by a hash. Note: Don't expect that -the peer necessarily give you all these blocks in a single message - you -might have to re-request them. - -**Blocks** [``+0x06``, [``blockHeader``, ``transactionList``, -``uncleList``], ``...``] Specify (a) block(s) as an answer to -``GetBlocks``. The items in the list (following the message ID) are -blocks in the format described in the main Ethereum specification. This -may validly contain no blocks if no blocks were able to be returned for -the ``GetBlocks`` query. - -**NewBlock** [``+0x07``, [``blockHeader``, ``transactionList``, -``uncleList``], ``totalDifficulty``] Specify a single block that the -peer should know about. The composite item in the list (following the -message ID) is a block in the format described in the main Ethereum -specification. - ``totalDifficulty`` is the total difficulty of the -block (aka score). - -PV61 specific -~~~~~~~~~~~~~ - -**BlockHashesFromNumber** [``+0x08``: ``P``, ``number``: ``P``, -``maxBlocks``: ``P``] Requires peer to reply with a ``BlockHashes`` -message. Message should contain block with that of number ``number`` on -the canonical chain. Should also be followed by subsequent blocks, on -the same chain, detailing a number of the first block hash and a total -of hashes to be sent. Returned hash list must be ordered by block number -in ascending order. - -New model syncing (PV62) -~~~~~~~~~~~~~~~~~~~~~~~~ - -**NewBlockHashes** [``+0x01``: ``P``, [``hash_0``: ``B_32``, -``number_0``: ``P``], [``hash_1``: ``B_32``, ``number_1``: ``P``], ...] -Specify one or more new blocks which have appeared on the network. To be -maximally helpful, nodes should inform peers of all blocks that they may -not be aware of. Including hashes that the sending peer could reasonably -be considered to know (due to the fact they were previously informed of -because that node has itself advertised knowledge of the hashes through -``NewBlockHashes``) is considered Bad Form, and may reduce the -reputation of the sending node. Including hashes that the sending node -later refuses to honour with a proceeding ``GetBlockHeaders`` message is -considered Bad Form, and may reduce the reputation of the sending node. - -**GetBlockHeaders** [``+0x03``: ``P``, ``block``: { ``P`` , ``B_32`` }, -``maxHeaders``: ``P``, ``skip``: ``P``, ``reverse``: ``P`` in { ``0`` , -``1`` } ] Require peer to return a ``BlockHeaders`` message. Reply must -contain a number of block headers, of rising number when ``reverse`` is -``0``, falling when ``1``, ``skip`` blocks apart, beginning at block -``block`` (denoted by either number or hash) in the canonical chain, and -with at most ``maxHeaders`` items. - -**BlockHeaders** [``+0x04``, ``blockHeader_0``, ``blockHeader_1``, -``...``] Reply to ``GetBlockHeaders``. The items in the list (following -the message ID) are block headers in the format described in the main -Ethereum specification, previously asked for in a ``GetBlockHeaders`` -message. This may validly contain no block headers if no block headers -were able to be returned for the ``GetBlockHeaders`` query. - -**GetBlockBodies** [``+0x05``, ``hash_0``: ``B_32``, ``hash_1``: -``B_32``, ``...``] Require peer to return a ``BlockBodies`` message. -Specify the set of blocks that we're interested in with the hashes. - -**BlockBodies** [``+0x06``, [``transactions_0``, ``uncles_0``] , -``...``] Reply to ``GetBlockBodies``. The items in the list (following -the message ID) are some of the blocks, minus the header, in the format -described in the main Ethereum specification, previously asked for in a -``GetBlockBodies`` message. This may validly contain no items if no -blocks were able to be returned for the ``GetBlockBodies`` query. - -ELIMINATED: ``GetBlockHashes``, ``BlockHashes``, ``GetBlocks``, -``Blocks``, ``BlockHashesFromNumber`` - -Fast synchronization (PV63) -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**GetNodeData** [``+0x0d``, ``hash_0``: ``B_32``, ``hash_1``: ``B_32``, -``...``] Require peer to return a ``NodeData`` message. Hint that useful -values in it are those which correspond to given hashes. - -**NodeData** [``+0x0e``, ``value_0``: ``B``, ``value_1``: ``B``, -``...``] Provide a set of values which correspond to previously asked -node data hashes from ``GetNodeData``. Does not need to contain all; -best effort is fine. If it contains none, then has no information for -previous ``GetNodeData`` hashes. - -**GetReceipts** [``+0x0f``, ``hash_0``: ``B_32``, ``hash_1``: ``B_32``, -``...``] Require peer to return a ``Receipts`` message. Hint that useful -values in it are those which correspond to blocks of the given hashes. - -**Receipts** [``+0x10``, [``receipt_0``, ``receipt_1``], ``...``] -Provide a set of receipts which correspond to previously asked in -``GetReceipts``. - -Session Management -~~~~~~~~~~~~~~~~~~ - -For the Ethereum sub-protocol, upon an active session, a ``Status`` -message must be sent. Following the reception of the peer's ``Status`` -message, the Ethereum session is active and any other messages may be -sent. All transactions should initially be sent with one or more -Transactions messages. - -Transactions messages should also be sent periodically as the node has -new transactions to disseminate. A node should never send a transaction -back to the peer that it can determine already knows of it (either -because it was previously sent or because it was informed from this peer -originally). - -Upcoming changes -~~~~~~~~~~~~~~~~ - -- `Light Client - Protocol `__ - -Changes (PoC-7) -~~~~~~~~~~~~~~~ - -- `NewBlock - Message `__ - -Changed (PoC-6) -~~~~~~~~~~~~~~~ - -- `Parallel Block - Downloads `__ diff --git a/old-docs-for-reference/main-wiki.rst/FAQ.rst b/old-docs-for-reference/main-wiki.rst/FAQ.rst deleted file mode 100644 index 406521b..0000000 --- a/old-docs-for-reference/main-wiki.rst/FAQ.rst +++ /dev/null @@ -1,410 +0,0 @@ -Answers to questions about Ethereum - -.. raw:: html - - - -.. raw:: html - - - -- `Ethereum <#ethereum>`__ -- `What is Ethereum? <#what-is-ethereum>`__ -- `Where can I learn more about - Ethereum? <#where-can-i-learn-more-about-ethereum>`__ -- `Where can I find the main project - repositories? <#where-can-i-find-the-main-project-repositories>`__ -- `Where can I learn about the Ether sale and - mining? <#where-can-i-learn-about-the-ether-sale-and-mining>`__ -- `Clients <#clients>`__ -- `Where can I find official - releases? <#where-can-i-find-official-releases>`__ -- `How to install development - builds? <#how-to-install-development-builds>`__ -- `How to install the clients from - source? <#how-to-install-the-clients-from-source>`__ -- `Mining <#mining>`__ -- `How can I mine Ether? <#how-can-i-mine-ether>`__ -- `How to get free testnet Ether? <#how-to-get-free-testnet-ether>`__ -- `Contracts <#contracts>`__ -- `Where can I learn about contract - development? <#where-can-i-learn-about-contract-development>`__ -- `Where can I learn Solidity? <#where-can-i-learn-solidity>`__ -- `Where can I learn Serpent? <#where-can-i-learn-serpent>`__ -- `Where can I learn LLL? <#where-can-i-learn-lll>`__ -- `Where can I learn Solidity? <#where-can-i-learn-solidity>`__ -- `How to test contracts? <#how-to-test-contracts>`__ -- `How to deploy contracts - automatically? <#how-to-deploy-contracts-automatically>`__ -- `Where to find example - contracts? <#where-to-find-example-contracts>`__ -- `Dapps <#dapps>`__ -- `Where can I learn about the Ethereum - APIs? <#where-can-i-learn-about-the-ethereum-apis>`__ -- `Where can I learn about dapp - development? <#where-can-i-learn-about-dapp-development>`__ -- `Where can I find dapp development - tools? <#where-can-i-find-dapp-development-tools>`__ -- `Where can I find example dapps? <#where-can-i-find-example-dapps>`__ -- `IRC <#irc>`__ -- `How can I join the Ethereum IRC - channels? <#how-can-i-join-the-ethereum-irc-channels>`__ -- `Where can I find the Ethereum IRC - logs? <#where-can-i-find-the-ethereum-irc-logs>`__ -- `Where can I learn about the ZeroGox - bot? <#where-can-i-learn-about-the-zerogox-bot>`__ -- `More Questions and Answers <#more-questions-and-answers>`__ - -.. raw:: html - - - -Ethereum --------- - -What is Ethereum? -~~~~~~~~~~~~~~~~~ - -There are several ways to answer this question, which are introduced on -the dedicated `What is -Ethereum `__ wiki -page. - -If you prefer to learn by watching videos, see: + `Introducing -Ethereum `__ (Video, 10min) + `Vitalik -Buterin reveals Ethereum at Bitcoin Miami -2014 `__ (Video, 28min) + `Singularity 1 on -1: Ethereum is a Decentralized Consensus -Platform `__ (Video, 69min) + `Our second -Reddit "Ask Me Anything" for community selected -questions `__ -(not actually a video) - -Where can I learn more about Ethereum? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- Main site: https://www.ethereum.org -- Forums: https://forum.ethereum.org -- Github: https://github.com/ethereum -- Blog: https://blog.ethereum.org -- Wiki: http://wiki.ethereum.org -- Meetups: http://ethereum.meetup.com -- Whitepaper: http://ethereum.org/ethereum.html -- Yellow Paper: http://gavwood.com/paper.pdf -- Facebook: https://www.facebook.com/ethereumproject -- Youtube: http://www.youtube.com/ethereumproject -- Google+: http://google.com/+EthereumOrgOfficial -- IRC Freenode: #ethereum (http://bitly.com/IRC\_ethereum for weblink) - -Where can I find the main project repositories? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- `cpp-ethereum `__ - ([@gavofyork](https://github.com/gavofyork), - [@programmerTim](https://github.com/programmerTim), - [@caktux](https://github.com/caktux)) -- `go-ethereum `__ - ([@obscuren](https://github.com/obscuren), - [@maran](https://github.com/maran)) -- `pyethereum `__ - ([@vbuterin](https://github.com/vbuterin), - [@heikoheiko](https://github.com/heikoheiko), - [@chenhouwu](https://github.com/chenhouwu)) -- `ethereumj `__ - ([@romanman](https://github.com/romanman), - [@nicksavers](https://github.com/nicksavers)) -- `ethereumjs-lib `__ - ([@ethers](https://github.com/ethers), - [@wanderer](https://github.com/wanderer)) - -Where can I learn about the Ether sale and mining? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- `The Ether Sale - FAQ `__ -- `The Mining - FAQ `__ - -Clients -------- - -Where can I find official releases? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- `Releases for - AlethZero `__ -- `Releases for - Mist `__ -- `Releases for - Pyethereum `__ - -How to install development builds? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- Homebrew -- `Homebrew Ethereum `__ - ([@caktux](https://github.com/caktux)) -- Guides -- `AlethZero super easy install guide for - OSX `__ - ([@stephantual](https://github.com/stephantual)) -- `Go-Ethereum simple build guide for - OSX `__ - ([@stephantual](https://github.com/stephantual)) -- `Building on - Ubuntu `__ -- Builds -- `Ethdev Buildbot `__ - -How to install the clients from source? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- `Building AlethZero - (C++) `__ -- `Building Mist - (Go) `__ -- `Installing Pyethereum - (Python) `__ -- `Installing EthereumJ - (Java) `__ -- `Installing Ethereumjs-lib (JavaScript for Browser and - Node) `__ - -Mining ------- - -How can I mine Ether? -~~~~~~~~~~~~~~~~~~~~~ - -With AlethZero - -- To process transactions -- Disable "Debug" > "Force Mining" -- Click "Mine" -- To force mine (Use sparingly, unless stress testing) -- Enable "Debug" > "Force Mining" -- Click "Mine" - -With the eth client - -:: - - # Only force mine to acquire ether or stress test - $ eth --force-mining --mining on [YOUR OPTIONS...] - -How to get free testnet Ether? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- `ZeroGox Wei Faucet `__ - ([@caktux](https://github.com/caktux)) - -Contracts ---------- - -Where can I learn about contract development? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- Articles -- `Ethereum Development - Tutorial `__ -- Videos -- `Ethereum `__ -- `EtherCasts `__ - -Where can I learn Serpent, the Python-like language? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- Specifications -- `The Serpent - Language `__ -- Examples -- `Vitalik's Serpent - examples `__ -- Tutorials -- `Pyethereum and Serpent Programming - Guide `__ -- Videos -- `Learn Ethereum with - Vitalik `__ - -Where can I learn LLL, the Lisp-like language? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- Specifications -- `The LLL - Language `__ -- Examples -- `LLL examples for PoC - 6 `__ -- Videos -- `Programming Society with - Asm `__ - -Where can I learn Solidity, the JavaScript-like language? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- Specifications -- `Solidity, Docs and - ABI `__ -- `Solidity - Features `__ -- Tutorials -- `Solidity - Tutorial `__ -- `Contract Writing in - Solidity `__ - -How to test contracts? -~~~~~~~~~~~~~~~~~~~~~~ - -- `EVM Contract Simulator `__ - ([@EtherCasts](https://github.com/EtherCasts)) -- `Pyethereum - Tester `__ - ([@ethereum](https://github.com/ethereum)) - -How to deploy contracts automatically? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- `Ethereum Package Manager `__ - -Where to find example contracts? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- Serpent -- `By Vitalik - Buterin `__ - ([@vbuterin](https://github.com/vbuterin)) -- `By EtherCasts `__ - ([@EtherCasts](https://github.com/EtherCasts)) -- `By Rob Myers `__ - ([@robmyers](https://github.com/robmyers)) -- `By Tyler - Florez `__ - ([@qualiabyte](https://github.com/qualiabyte)) -- LLL -- `By Gavin - Wood `__ - ([@gavofyork](https://github.com/gavofyork)) -- `By Dennis - Mckinnon `__ - ([@dennismckinnon](https://github.com/dennismckinnon)) -- `By Project - Douglas `__ - ([@project-douglas](https://github.com/project-douglas)) -- `By Doug A. `__ - ([@dlle9](https://github.com/d11e9)) - -Dapps ------ - -Where can I learn about the Ethereum APIs? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- `The PoC 6 API for - C++ `__ -- `The PoC 5 API for - Go `__ -- `The PoC 6 API for - QML `__ -- `The PoC 7 API for - JavaScript `__ - -Where can I learn about dapp development? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- `Writing Your Own - Currency `__ - ([@maran](https://github.com/maran)) - -Where can I find dapp development tools? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Official - -- `AlethZero GUI client - (C++) `__ -- `Eth command-line client - (C++) `__ -- `LLLC Compiler - (C++) `__ -- `Ethereum command-line client - (Go) `__ -- `Mist Browser (Go) `__ -- `Pyeth command-line client - (Python) `__ -- `Serpent Compiler - (Python) `__ - -Community - -- `C3D `__ - ([@project-douglas](https://github.com/project-douglas)) -- `Emacs LLL Mode `__ - ([@robmyers](https://github.com/robmyers)) -- `Emacs Serpent Mode `__ - ([@robmyers](https://github.com/robmyers)) -- `EPM `__ - ([@project-douglas](https://github.com/project-douglas)) -- `EPM Sublime - Plugin `__ - ([@project-douglas](https://github.com/project-douglas)) -- `Ethos Browser `__ - ([@projectdnet](https://github.com/projectdnet)) -- `EVM-Sim `__ - ([@EtherCasts](https://github.com/EtherCasts)) -- `MintChalk `__ - ([@mintchalk](https://github.com/mintchalk)) -- `Poly-Eth `__ - ([@projectdnet](https://github.com/projectdnet)) - -Where can I find example dapps? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- `dapp-bin `__ - ([@ethereum](https://github.com/ethereum)) -- `GavCoin `__ - ([@gavofyork](https://github.com/gavofyork)) -- `JeffCoin `__ - ([@obscuren](https://github.com/obscuren)) -- `Make It Rain `__ - ([@EtherCasts](https://github.com/EtherCasts)) -- `Chronos `__ - ([@mquandalle](https://github.com/mquandalle)) -- `Artworld-Ethereum `__ - ([@robmyers](https://github.com/robmyers)) -- `Eris `__ - ([@project-douglas](https://github.com/project-douglas), - [@compleatang](https://github.com/compleatang), - [@dennismckinnon](https://github.com/dennismckinnon)) -- `CryptoCoinWatch `__ - ([@EtherCasts](https://github.com/EtherCasts)) -- `Occam's Run `__ - ([@d11e9](https://github.com/d11e9)) -- `TrustDavis `__ - ([@EtherCasts](https://github.com/EtherCasts)) - -IRC ---- - -How can I join the Ethereum IRC channels? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- `Chat with the Ethereum dev community on - IRC! `__ - -Where can I find the Ethereum IRC logs? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- `The ZeroGox logs `__ - -Where can I learn about the ZeroGox bot? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- `The ZeroGox bot `__ - -More Questions and Answers -========================== - -- [FAQ by - @fivedogit](https://docs.google.com/document/d/14EIe984\_86Y-uuNm-a4EsVeD3eI4qAAlz\_MZof1qkqM/) diff --git a/old-docs-for-reference/main-wiki.rst/Geth-Dapp-loading-proposal.rst b/old-docs-for-reference/main-wiki.rst/Geth-Dapp-loading-proposal.rst deleted file mode 100644 index b7874f6..0000000 --- a/old-docs-for-reference/main-wiki.rst/Geth-Dapp-loading-proposal.rst +++ /dev/null @@ -1,38 +0,0 @@ -To have a simple way to load and start dapps vinay and I came up with a -great idea: - -1. Dapp packages can be downloaded as .zip/.rlp/.dapp - - - they will contain a ``dapp.json`` with author info and a dapp name - and version. - - and a ``swarm.json``, with all the file paths and hashes, `see - here `__) - -2. | run ``$ geth install mydapp.zip``, which will verify, extract and - copy the dapp locally somewhere. - | **Note** This could also get a name reg domain and looks up the - hash an content online, fetches it and installs it. - -3. run ``$ geth start mydapp`` will start a node, with the correct - options (rpc, corsdomain etc) and start a local server which points - with its root into the dapps folder and resolves path and files - through the ``swarm.json`` - -4. goto ``http://localhost:5555`` to see you dapp running (needs to be - thought of, as dapps would share localstorage, maybe use a different - and reusable port per dapp) - -Update ------- - -- run ``$ geth update mydapp.zip``, which will extract, and overwrites - the old dapp files - -Bundle dapp ------------ - -- run ``$ geth bundle myDappFolder/dist/``, which will create a dapp - bundle from a folder, to share with others. - -- run ``$ geth deploy myDappFolder/dist/`` could save it to pastebin - and register it in namereg. diff --git a/old-docs-for-reference/main-wiki.rst/Gitter-Channels.rst b/old-docs-for-reference/main-wiki.rst/Gitter-Channels.rst deleted file mode 100644 index 2cffc3e..0000000 --- a/old-docs-for-reference/main-wiki.rst/Gitter-Channels.rst +++ /dev/null @@ -1,49 +0,0 @@ -https://gitter.im/ethereum - -Node Software ("Clients") -========================= - -Go --- - -https://gitter.im/ethereum/go-ethereum - -CPP ---- - -https://gitter.im/ethereum/cpp-ethereum - -Python ------- - -https://gitter.im/ethereum/pyethapp - the client - -https://gitter.im/ethereum/pyethereum - the core library (evm, blocks, -txs, ...) - -https://gitter.im/ethereum/pydevp2p - p2p network - -Dapp Development -================ - -https://gitter.im/ethereum/web3.js - -https://gitter.im/ethereum/mist - -https://gitter.im/ethereum/solidity - -https://gitter.im/ethereum/serpent - -Other -===== - -https://gitter.im/ethereum/porting - -https://gitter.im/ethereum/research - -Protocol -======== - -https://gitter.im/ethereum/devp2p - -https://gitter.im/ethereum/light-client diff --git a/old-docs-for-reference/main-wiki.rst/Glossary.rst b/old-docs-for-reference/main-wiki.rst/Glossary.rst deleted file mode 100644 index 9657ece..0000000 --- a/old-docs-for-reference/main-wiki.rst/Glossary.rst +++ /dev/null @@ -1,393 +0,0 @@ -One of the things that cryptocurrency, and really any new genre of -technology, is notorious for is the sheer quantity of vocabulary that -gets generated to describe all of the new concepts. Anyone dealing with -peer-to-peer internet software on anything more than a casual basis -needs to deal with concepts of cryptography, including hashes, -signatures and public and private keys, symmetric and asymmetric -encryption, denial of service protection, as well as arcane -constructions such as distributed hash tables and webs of trust. New -Bitcoin users are forced to contend with learning not just the common -basics of cryptography, but also additional internal jargon such as -"blocks", "confirmations", "mining", "SPV clients" and "51% attacks", as -well as economic concepts like incentive-compatibility and the fine -nuances of centralization and decentralization. Ethereum, being a -decentralized application development platform based on a generalization -of a cryptocurrency, necessarily incorporates both of these sets of -concepts, as well as adding many of its own. To help anyone new to -Ethereum, whether they are in it as cryptocurrency enthusiasts, business -owners, social or political visionaries, web developers or are simply -ordinary people looking to see how the technology can improve their -lives, the following list is intended to provide a basic summary of the -vocabulary that Ethereum users often tend to use: - -Cryptography -~~~~~~~~~~~~ - -See also: http://en.wikipedia.org/wiki/Public-key\_cryptography - -- **Computational infeasibility**: a process is computationally - infeasible if it would take an impracticably long time (eg. billions - of years) to do it for anyone who might conceivably have an interest - in carrying it out. Generally, 280 computational steps is considered - the lower bound for computational infeasibility. -- **Hash**: a hash function (or hash algorithm) is a process by which a - document (ie. a piece of data or file) is processed into a small - piece of data (usually 32 bytes) which looks completely random, and - from which no meaningful data can be recovered about the document, - but which has the important property that the result of hashing one - particular document is always the same. Additionally, it is crucially - important that it is computationally infeasible to find two documents - that have the same hash. Generally, changing even one letter in a - document will completely randomize the hash; for example, the SHA3 - hash of "Saturday" is - ``c38bbc8e93c09f6ed3fe39b5135da91ad1a99d397ef16948606cdcbd14929f9d``, - whereas the SHA3 hash of Caturday is - ``b4013c0eed56d5a0b448b02ec1d10dd18c1b3832068fbbdc65b98fa9b14b6dbf``. - Hashes are usually used as a way of creating a globally agreed-upon - identifier for a particular document that cannot be forged. -- **Encryption**: encryption is a process by which a document - (**plaintext**) is combined with a shorter string of data, called a - **key** (eg. - ``c85ef7d79691fe79573b1a7064c19c1a9819ebdbd1faaab1a8ec92344438aaf4``), - to produce an output (**ciphertext**) which can be "decrypted" back - into the original plaintext by someone else who has the key, but - which is incomprehensible and computationally infeasible to decrypt - for anyone who does not have the key. -- **Public key encryption**: a special kind of encryption where there - is a process for generating two keys at the same time (typically - called a **private key** and a **public key**), such that documents - encrypted using one key can be decrypted with the other. Generally, - as suggested by the name, individuals publish their public keys and - keep their private keys to themselves. -- **Digital signature**: a digital signing algorithm is a process by - which a user can produce a short string of data called a "signature" - of a document using a private key such that anyone with the - corresponding public key, the signature and the document can verify - that (1) the document was "signed" by the owner of that particular - private key, and (2) the document was not changed after it was - signed. Note that this differs from traditional signatures where you - can scribble extra text onto a document after you sign it and there's - no way to tell the difference; in a digital signature any change to - the document will render the signature invalid. - -Blockchains -~~~~~~~~~~~ - -See also: https://bitcoin.org/en/vocabulary - -- **Address**: an address is essentially the representation of a public - key belonging to a particular user; for example, the address - associated with the private key given above is - ``cd2a3d9f938e13cd947ec05abc7fe734df8dd826``. Note that in practice, - the address is technically the hash of a public key, but for - simplicity it's better to ignore this distinction. -- **Transaction**: a transaction is a document authorizing some - particular action associated with the blockchain. In a currency, the - dominant transaction type is sending currency units or tokens to - someone else; in other systems actions like registering domain names, - making and fulfilling trade offers and entering into contracts are - also valid transaction types. -- **Block**: a block is a package of data that contains zero or more - transactions, the hash of the previous block ("parent"), and - optionally other data. The total set of blocks, with every block - except for the initial "genesis block" containing the hash of its - parent, is called the **blockchain** and contains the entire - transaction history of a network. Note that some blockchain-based - cryptocurrencies instead use the word "ledger" for a blockchain; the - two are roughly equivalent, although in systems that use the term - "ledger" each block generally contains a full copy of the current - state (eg. currency balances, partially fulfilled contracts, - registrations) of every account allowing users to discard outdated - historical data. -- **Account**: an account is the entry in a ledger, indexed by its - address, that contains the complete data about the state of that - account. In a currency system, this involves currency balances and - perhaps unfulfilled trade orders; in other cases more complex - relationships may be stored inside of accounts. -- **Proof of work**: one important property of a block in Bitcoin, - Ethereum and many other crypto-ledgers is that the hash of the block - must be smaller than some target value. The reason this is necessary - is that in a decentralized system anyone can produce blocks, so in - order to prevent the network from being flooded with blocks, and to - provide a way of measuring how much consensus there is behind a - particular version of the blockchain, it must in some way be hard to - produce a block. Because hashes are pseudorandom, finding a block - whose hash is less than - ``0000000100000000000000000000000000000000000000000000000000000000`` - takes an average of 4.3 billion attempts. In all such systems, the - target value self-adjusts so that on average one node in the network - finds a block every N minutes (eg. N = 10 for Bitcoin and 1 for - Ethereum). -- **Nonce**: a meaningless value in a block which can be adjusted in - order to try to satisfy the proof of work condition -- **Mining**: mining is the process of repeatedly aggregating - transactions, constructing a block and trying difference nonces until - a nonce is found that satisfies the proof of work condition. If a - miner gets lucky and produces a valid block, they are granted a - certain number of coins as a reward as well as all of the transaction - fees in the block, and all miners start trying to create a new block - containing the hash of the newly generated block as their parent. -- **Stale**: a stale is a block that is created when there is already - another block with the same parent out there; stales typically get - discarded and are wasted effort. -- **Fork**: a situation where two blocks are generated pointing to the - same block as their parent, and some portion of miners see one block - first and some see the other. This may lead to two blockchains - growing at the same time. Generally, it is mathematically - near-certain that a fork will resolve itself within four blocks as - miners on one chain will eventually get lucky and that chain will - grow longer and all miners switch to it; however, forks may last - longer if miners disagree on whether or not a particular block is - valid. -- **Double spend**: a deliberate fork, where a user with a large amount - of mining power sends a transaction to purchase some produce, then - after receiving the product creates another transaction sending the - same coins to themselves. The attacker then creates a block, at the - same level as the block containing the original transaction but - containing the second transaction instead, and starts mining on the - fork. If the attacker has more than 50% of all mining power, the - double spend is guaranteed to succeed eventually at any block depth. - Below 50%, there is some probability of success, but it is usually - only substantial at a depth up to about 2-5; for this reason, most - cryptocurrency exchanges, gambling sites and financial services wait - until six blocks have been produced ("six confirmations") before - accepting a payment. -- **SPV client** (or **light client**) - a client that downloads only a - small part of the blockchain, allowing users of low-power or - low-storage hardware like smartphones and laptops to maintain almost - the same guarantee of security by sometimes selectively downloading - small parts of the state without needing to spend megabytes of - bandwidth and gigabytes of storage on full blockchain validation and - maintennance. - -Ethereum Blockchain -~~~~~~~~~~~~~~~~~~~ - -See also: http://ethereum.org/ethereum.html - -- **Serialization**: the process of converting a data structure into a - sequence of bytes. Ethereum internally uses an encoding format called - recursive-length prefix encoding (RLP), described - `here `__ -- **Patricia tree** (or **trie**): a data structure which stores the - state of every account. The trie is built by starting from each - individual node, then splitting the nodes into groups of up to 16 and - hashing each group, then making hashes of hashes and so forth until - there is one final "root hash" for the entire trie. The trie has the - important properties that (1) there is exactly one possible trie and - therefore one possible root hash for each set of data, (2) it is very - easy to update, add or remove nodes in the trie and generate the new - root hash, (3) there is no way to modify any part of the tree without - changing the root hash, so if the root hash is included in a signed - document or a valid block the signature or proof of work secures the - entire tree, and (4) one can provide just the "branch" of a tree - going down to a particular node as cryptographic proof that that node - is indeed in the tree with that exact content. Patricia trees are - also used to store the internal storage of accounts as well as - transactions and uncles. See - `here `__ - for a more detailed description. -- **GHOST**: GHOST is a protocol by which blocks can contain a hash of - not just their parent, but also hashes for stales that are other - children of the parent's parent (called **uncles**). This ensures - that stales still contribute to blockchain security, and mitigates a - problem with fast blockchains that large miners have an advantage - because they hear about their own blocks immediately and so are less - likely to generate stales. -- **Uncle**: a child of a parent of a parent of a block that is not the - parent, or more generally a child of an ancestor that is not an - ancestor. If A is an uncle of B, B is a **nephew** of A. -- **Account nonce**: a transaction counter in each account. This - prevents replay attacks where a transaction sending eg. 20 coins from - A to B can be replayed by B over and over to continually drain A's - balance. -- **EVM code**: Ethereum virtual machine code, the programming language - in which accounts on the Ethereum blockchain can contain code. The - EVM code associated with an account is executed every time a message - is sent to that account, and has the ability to read/write storage - and itself send messages. -- **Message**: a sort of "virtual transaction" sent by EVM code from - one account to another. Note that "transactions" and "messages" in - Ethereum are different; a "transaction" in Ethereum parlance - specifically refers to a physical digitally signed piece of data that - goes in the blockchain, and every transaction triggers an associated - message, but messages can also be sent by EVM code, in which case - they are never represented in data anywhere. -- **Storage**: a key/value database contained in each account, where - keys and values are both 32-byte strings but can otherwise contain - anything. -- **Externally owned account**: an account controlled by a private key. - Externally owned accounts cannot contain EVM code. -- **Contract**: an account which contains, and is controlled by, EVM - code. Contracts cannot be controlled by private keys directly; unless - built into the EVM code, a contract has no owner once released. -- **Ether**: the primary internal cryptographic token of the Ethereum - network. Ether is used to pay transaction and computation fees for - Ethereum transactions. -- **Gas**: a measurement roughly equivalent to computational steps. - Every transaction is required to include a gas limit and a fee that - it is willing to pay per gas; miners have the choice of including the - transaction and collecting the fee or not. If the total number of gas - used by the computation spawned by the transaction, including the - original message and any sub-messages that may be triggered, is less - than or equal to the gas limit, then the transaction processes. If - the total gas exceeds the gas limit, then all changes are reverted, - except that the transaction is still valid and the fee can still be - collected by the miner. Every operation has a gas expenditure; for - most operations it is 1, although some expensive operations fave - expenditures up to 100 and a transaction itself has an expenditure of - 500. - -Non-blockchain -~~~~~~~~~~~~~~ - -- **EtherBrowser**: the upcoming primary client for Ethereum, which - will exist in the form of a web browser that can be used to access - both normal websites and applications built on top of the Ethereum - platform -- **Whisper**: an upcoming P2P messaging protocol that will be - integrated into the EtherBrowser -- **Swarm**: an upcoming P2P data storage protocol optimized for static - web hosting that will be integrated into the EtherBrowser -- **Solidity**, **LLL**, **Serpent** and **Mutan**: prorgamming - languages for writing contract code which can be compiled into EVM - code. Serpent can also be compiled into LLL. -- **PoC**: proof-of-concept, another name for a pre-launch release - -Surrounding concepts: applications and governance -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- **Decentralized application**: a program which is run by many people - which either uses or creates a decentralized network for some - specific purpose (eg. connecting buyers and sellers in some - marketplace, sharing files, online file storage, maintaining a - currency). Ethereum-based decentralized applications (also called - dapps, where the Đ is the Norse letter "eth") typically consist of an - HTML/Javascript webpage, and if viewed inside the EtherBrowser the - browser recognizes special Javascript APIs for sending transactions - to the blockchain, reading data from the blockchain and interacting - with Whisper and Swarm. A dapp typically also has a specific - associated contract on the blockchain, though dapps that facilitate - the creation of many contracts are quite possible. -- **Decentralized organization**: an organization that has no - centralized leadership, instead using a combination of formal - democratic voting processes and stigmergic self-organization as their - primary operating principles. A less impressive but sometimes - confused concept is a "geographically distributed organization", an - organization where people work far apart from each other and which - may even have no office at all; GDOs can still have formal - centralized leadership. -- **Theseus criterion**: a test for determining how decentralized an - organization is. The test is as follows: suppose the organization has - N people, and aliens try to pick K people in the organization at a - time (eg. once per week) and zap them out of existence, replacing - each group with K new people who know nothing about the organization. - For how high K can the organization function? Dictatorships fail at K - = 1 once the dictator is zapped away; the US government does slightly - better but would still be in serious trouble if all 638 members of - the Senate and Congress were to disappear, where as something like - Bitcoin or BitTorrent is resilient for extremely high K because new - agents can simply follow their economic incentives to fill in the - missing roles. A stricter test, the **Byzantine Theseus criterion**, - involves randomly substituting K users at a time with malicious - actors for some time before replacing them with new users. -- **Decentralized autonomous organization**: decentralized - organizations where the method of governance is in some fashion - "autonomous", ie. it's not controlled by some form of discussion - process or committee. -- **No common language criterion**: a test for determining how - autonomous an organization is. The test is as follows: suppose the N - people in the organization speak N different languages, with none in - common. Can the organization still function? -- **Delegative democracy** (or **liquid democracy**): a governance - mechanism for DOs and DAOs where everyone votes on everything by - default, but where individuals `can select specific - individuals `__ to - vote for them on specific issues. The idea is to generalize the - tradeoff between full direct democracy with every individual having - equal power and the expert opinion and quick decision making ability - provided by specific individuals, allowing people to defer to - friends, politicians, subject matter experts or anyone else to - exactly the extent that they want to. -- **Futarchy**: a governance mechanism `originally - proposed `__ by Robin Hanson for - managing political organizations, but which is actually extremely - applicable for DOs and DAOs: rule by prediction market. Essentially, - some easily measurable success metrics are chosen, and tokens are - released which will pay out some time in the future (eg. after 1 - year) depending on the values of those success metrics, with one such - token for each possible action to take. Each of these tokens are - traded against a corresponding dollar token, which pays out exactly - $1 if the corresponding measure is taken (if the corresponding - measure is not taken, both types of tokens pay $0, so the probability - of the action actually being taken does not affect the price). The - action that the market predicts will have the best results, as judged - by the token's high price on its market, is the action that will be - taken. This provides another, autonomous, mechanism for selecting for - and simultaneously rewarding expert opinion. - -Economics -~~~~~~~~~ - -- **Token system**: essentially, a fungible virtual good that can be - traded. More formally, a token system is a database mapping addresses - to numbers with the property that the primary allowed operation is a - transfer of N tokens from A to B, with the conditions that N is - non-negative, N is not greater than A's current balance, and a - document authorizing the transfer is digitally signed by A. Secondary - "issuance" and "consumption" operations may also exist, transaction - fees may also be collected, and simultaneous multi-transfers with - many parties may be possible. Typical use cases include currencies, - cryptographic tokens inside of networks, company shares and digital - gift cards. -- **Namespace**: a database mapping names to values. In the simplest - example anyone can register an entry if the name has not already been - taken (perhaps after paying some fee). If a name has been taken then - it can only be changed (if at all) by the account that made the - original registration (in many systems, ownership can also be - transferred). Namespaces can be used to store usernames, public keys, - internet domain names, token systems or other namespaces, and many - other applications. -- **Identity**: a set of cryptographically verifiable interactions that - have the property that they were all created by the same person -- **Unique identity**: a set of cryptographically verifiable - interactions that have the property that they were all created by the - same person, with the added constraint that one person cannot have - multiple unique identities -- **Incentive compatibility**: a protocol is incentive-compatible if - everyone is better off "following the rules" than attempting to - cheat, at least unless a very large number of people agree to cheat - together at the same time. -- **Basic income**: the idea of issuing some quantity of tokens to - every unique identity every period of time (eg. months), with the - ultimate intent being that people who do not wish to work or cannot - work can survive on this allowance alone. These tokens can simply be - crafted out of thin air, or they can come from some revenue stream - (eg. profit from some revenue-generating entity, or a government); in - order for the BI to be sufficient for a person to live on it alone, a - combination of revenue streams will likely have to be used. -- **Public good**: a service which provides a very small benefit to a - very large number of people, such that no individual has a large - effect on whether or not the good is produced and so no one has the - incentive to help pay for it. -- **Reputation**: the property of an identity that other entities - believe that identity to be either (1) competent at some specific - task, or (2) trustworthy in some context, ie. not likely to betray - others even if short-term profitable. -- **Web of trust**: the idea that if A highly rates B, and B highly - rates C, then A is likely to trust C. Complicated and powerful - mechanisms for determining the reliability of specific individuals in - specific concepts can theoretically be gathered from this principle. -- **Escrow**: if two low-reputation entities are engaged in commerce, - the payer may wish to leave the funds with a high-reputation third - party and instruct that party to send the funds to the payee only - when the product is delivered. This reduces the risk of the payer or - payee committing fraud. -- **Deposit**: digital property placed into a contract involving - another party such that if certain conditions are not satisfied that - property is automatically forfeited to the counterparty -- **Hostage**: digital property placed into a contract such that if - certain conditions are not satisfied that property is automatically - either destroyed or donated to charity or basic income funds, perhaps - with widely distributed benefit but necessarily with no significant - benefit to any specific individual. diff --git a/old-docs-for-reference/main-wiki.rst/HPOC_2015.rst b/old-docs-for-reference/main-wiki.rst/HPOC_2015.rst deleted file mode 100644 index e36367d..0000000 --- a/old-docs-for-reference/main-wiki.rst/HPOC_2015.rst +++ /dev/null @@ -1,333 +0,0 @@ -HPoC 2015 -~~~~~~~~~ - -Last year we released the "Hard Problems of Cryptocurrency" document, -detailing what we thought were some of the harder technical and economic -problems keeping cryptocurrency and cryptoeconomic technology from -mainstream viability. The list included issues such as scalability, more -efficient consensus algorithms, public goods incentivization, reputation -systems, among a number of other challenges. Over the past year, a large -portion of these problems have arguably been solved, or at least -research has been brought forward to the point where additional progress -is no longer a matter of zero-to-one fundamental breakthroughs, but -rather tweaking and empirical testing through real-world implementation. -At the same time, there are a substantial number of challenges that -still remain, although the problems here are substantially more specific -and less broadly reaching than previously. - -Meta-consensus -~~~~~~~~~~~~~~ - -In order to remain relevant in a rapidly evolving technological -landscape, software must update, and software that does not update has -no alternative but to slowly fade away and die as it is replaced by -superior technology. There is no reason why this principle should not -apply to decentralized crypto-protocols as well. However, the need to -make upgrades to decentralized crypto-systems leads to a natural -question: who controls the updating process? As of the time of this -writing, the Bitcoin community is going through the process of deciding -whether or not to increase the maximum block size from 1 MB to 20 MB, -and the lack of a deliberately instituted decision-making process has -lead to the situation where the de-facto decision-making process -essentially amounts to political debate among a small number of core -developers. - -Is there a way of building *intra-protocol meta-consensus* - that is, a -mechanism inside the protocol that facilitates agreement on upgrades to -the protocol, perhaps using some kind of consensus voting? Such a system -would have a number of benefits, including greater flexibility, less -reliance on political processes that end up being centralization risks, -and can arguably ensure a greater voice to all participants in the -protocol, not just those that are socially well-connected (see Jo -Freeman's `The Tyranny of -Structurelessness `__ for -more on this). - -Desirable properties of meta-consensus include: - -- Incentives to agree on beneficial protocol changes -- Some kind of guarantee that applications built under the old protocol - will remain maximally effective under the new protocol. Note that a - part of this will likely be some kind of object-oriented - encapsulation mechanisms in order to steer developers away from using - features which are highly protocol-specific -- Resistance against the mechanism being corrupted in some sense and - forced to lead to an undesirable protocol change -- The ability for users to automatically upgrade to a newly chosen - protocol without having to download a new client - -Existing work on this includes `Arthur Breitman's -Tezos `__, Bitshares' `delegated proof of -stake `__, and the -not-yet-released Ethereum 2.0 proposal. - -Public Goods Preference Revelation and Incentivization -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The other major problem in crypto-protocol development is the analogous -funding problem: how will protocol upgrades, and more generally -public-good ecosystem middleware, be paid for? In the initial phase of -development, the concept of "crowdsales" has proven to be absolutely -invaluable, providing millions of dollars of funding for efforts which -would have otherwise been relegated to being little more than volunteer -side projects. However, crowdsales by themselves have a fundamental -problem: they are front-loaded, creating heavy incentives for short-term -marketing but less so for long-term performance, and they are limited -one-time events from which the funds received eventually run out. And -even if the funds could somehow be managed so as not to run out, -crypto-protocol development would be permanently centralized in a single -organization. What would be ideal is, once again, some kind of -intra-protocol mechanism for incentivizing the development of public -goods. - -Public goods incentivization has a long and established literature, -including numerous -`results `__ -`from `__ -`mechanism `__ -`design `__ -and `assurance contract -theory `__ on the topic -of both how to fund the development of public goods and on the equally -important question of deciding which public goods are worth funding in -the first place. In a blockchain context, the funding problem is -somewhat easier than in a private-market context, because we have the -ability to "tax" all currency holders via inflation and taking the -excess of transaction fees minus consensus costs, but the preference -revelation problem is much harder; a human government can try to use -informal judgement to figure out which public goods are worth supporting -and which ones are not, but a blockchain literally cannot tell the -difference between a trustworthy development fund, an untrustworthy -development fund, a tobacco lobbying company, the "zero address" from -which coins can never be spent and a scammer. Hence, it must rely -entirely on some kind of mechanism design to elicit this information -from the community. - -The challenge here is applying these guarantees to a blockchain context. -Particular challenges include: - -- Being incentive-compatible even given the assumption that users can - securely and trustlessly bribe each other, eg. via contracts - (cooperative game theory can help here) -- Being incentive-compatible even given the assumption that the - attacker may have a superior ability to coordinate versus the - individual participants (cf. P + epsilon attacks; cooperative game - theory may be insufficient here as it generally assumes that - collections of users can either coordinate totally or not coordinate - at all) -- Avoiding Caplanian "rational irrationality" critiques, ie. providing - sufficiently large incentives for users to learn about which funds - are worth supporting and not simply immediately click on what looks - nicer - -The general model can be thought of as follows: - -- There exist N public goods, represented by addresses owned by funds - that promise to spend the money on particular public goods (eg. - development). Anyone can register an address in this set, perhaps - after paying some fee -- Users need to, using some mechanism, select how to split up funding - pool D between these goods (D may be a maximum size; the mechanism - may end up "burning" some of D) -- Attackers creating fake "public goods" that really just send money to - themselves can be seen simply as being public goods with a payoff - ratio of 1 that happens to be concentrated entirely in a single - player. The reason why attackers winning is socially bad is that - other "legitimate" public goods will have much higher payoff ratios -- If necessary, we can rely on the users having security deposits, eg. - being validators - -Coercion-proof Voting -~~~~~~~~~~~~~~~~~~~~~ - -Ari Juels in 2001 came up with a -`protocol `__ -for "coercion-resistant electronic elections" - a way of doing voting -online such that not only is it possible for users to vote without -revealing to others who they voted for, but it is in fact not possible -to prove to anyone else who you voted for *even if you wanted to* - -making it impossible to coerce or bribe people to vote. One possible -route to solving the preference revelation problem, as well as voting -games in general, is to implement this kind of scheme, making it much -harder to coordinate. It is by no means a complete solution, since a -user that controls two identities can still have those two identities -securely collude with each other, but combined with a wealth -deconcentration assumption it would make systems substantially more -robust. - -The challenge is, is it possible to implement some kind of -coercion-resistant electronic election into a decentralized public -blockchain context? The primary challenge here is the complete lack of -any specific parties that have private keys and can be trusted not to -collude with each other; the system would need to be completely public. - -Note: an alternative to making *cryptographically* coercion-resistant -electronic elections is making *cryptoeconomically* coercion-resistant -electronic elections: come up with some kind of mechanism such that if a -voter proves to another party any nonzero quantity of information about -who they voted for, that party can exploit them for an expected nonzero -return at their expense (if this exploitation can be made to be -*unprovable*, then even better, as it reduces the possibility of -effective circumvention through reputation). - -Anti-pre-revelation -~~~~~~~~~~~~~~~~~~~ - -There are many protocols such as -`Schellingcoin `__, -`Augur `__, N-of-N protocols in random number -generation, etc, that rely on some notion of users first -cryptographically "committing" to some value ``x``, eg. by submitting -``H(x)`` for some hash function, and then in a later stage "revealing" -the value for ``x`` that they submitted - with non-revelation or -incorrect revelation being punishable by security deposit loss. However, -many of these protocols only work effectively if users' answers during -the first phase are private; if users can collude to share information, -and particularly if they can *provably* share information, then the -mechanism's effectiveness decreases as collusion becomes easier. - -Suppose a commit-reveal protocol where all users must supply either 0 or -1, and they are "supposed to" randomly choose this value. In the first -step, each user must pick a (irrelevant) salt ``s``, and provide -``H([s, v])`` where ``v`` is either 0 or 1. In the second step, the user -must supply their values of ``s`` and ``v``, and have them be checked -against the commitment. The sum of all values ``v`` mod 2 is then taken -as a single bit of random output. Here, hypothetically all players can -talk to each other and provably coordinate on voting either 0 or 1. -However, we can design an anti-pre-revelation protocol as follows: any -party can choose to register a bet against any other party that they -will vote on some specific value with at last a 60% probability (ie. if -A bets that B will bet 0, then if B ends up providing ``v = 0`` then B -gets 2 units out of A's security deposit, and if B ends up providing -``v = 1`` then A gets 3 units out of B's security deposit). Hence, if -party ``P[i]`` reveals to party ``P[j]`` their ``v`` value, or even a -zero-knowledge proof of their ``v`` value with more than 60% -probability, they can be exploited (note that the 60% margin can be cut -down further to make *any nonzero revelation* costly by using `scoring -rule theory `__). - -A challenge is to either take this path and try to expand it into an -environment where the potential value space is much larger and -probabilities of voting may not be known a priori, or find some other -approach to make it cryptographically impossible or cryptoeconomically -expensive to reveal one's hidden value before one is supposed to. -Tailoring to specific applications (eg. linear Schellingcoin price -voting) is suboptimal but acceptable. A particular problem is the -existence of zero-knowledge proofs: one can use zk-SNARKs (or simply -plain ZKPs) in order to reveal any information about ``v`` and prove -that this information is correct by using the provided hash -``H([s, v])`` *without revealing anything about ``s``* or any -information about ``v`` that is undesired; hence, a solution should be -secure against *all* kinds of partial information revelation that may be -useful, and not simply revealing the exact value of ``v``. - -Random Number Generation -~~~~~~~~~~~~~~~~~~~~~~~~ - -A number of protocols, including consensus protocols, blockchain-based -lotteries, scalable sampling schemes, etc, require some kind of random -number generation in the protocol. Proof of work provides an answer -easily, because one cannot compute ahead of time what the result will -be, and once a result is found not revealing it carries a large -opportunity cost. However, proof of work is extremely expensive, -requiring constant expenditure equal to the security margin. - -An alternative is N-of-N commit-reveal, as exemplified in Tomlion's -RANDAO protocol, works as follows: - -1. ``n`` players ``P[1] ... P[n]`` with security deposits of size ``D`` - in the protocol choose random values ``V[1] ... V[n]`` with - ``0 <= v[i] < 2**256``, and ``P[i]`` submits ``H(V[i])`` during round - one. -2. In round two, every player who submitting a value ``H(V[i])`` must - submit ``V[i]``. -3. If all players submit their value correctly, then - ``(V[1] + ... + V[n]) % 2**256`` is taken as a random seed, and all - players are rewarded with ``D * i`` where ``i`` is an interest rate - (eg. 0.0001 per period). -4. If not all players submitted their value correctly, then all players - who participated get ``D * i``, all players who did not participate - lose their entire deposit and are kicked out, and the remaining - players repeat the game until eventually all N players cooperate and - reveal their values. - -If you are the last player to participate, then you can manipulate the -value at a very high cost, and even then only by replacing it with a -random value next time around (ie. one can avoid unfavorable values, but -one cannot target favorable values or even choose between two known -values). However, the mechanism has the limitations that (i) it relies -on a non-collusion assumption, (ii) the randomness that it provides is -not nearly as fast as proof of work randomness, making it useless for -some specific intra-block applications where proof of work shines, and -(iii) it can lead to honest players losing large amounts of money from a -network attack. Mitigating problem (iii) necessarily involves -exacerbating problem (ii), and vice versa. - -The open-ended challenge is to come up with a mechanism inside of a -cryptoeconomic context which provides random numbers as output with -maximally relaxed security assumptions and maximal robustness and -resilience to attackers - ideally, a mechanism with the same properties -as proof of work but without (or with only a negligible fraction of) its -cost. - -Anti-censorship -~~~~~~~~~~~~~~~ - -Public blockchains particularly have a strong need to be -censorship-resistant, ie. to be able to get transactions into the chain -even if powerful parties do not want them included. This is important -not just for controversial Wikileaks-style applications; even ordinary -financial applications, commit-reveal protocols, etc, could have their -security threatened if there was a way of effectively preventing -"challenge" messages from entering the blockchain. - -If the set of participants willing to collude to censor is smaller than -33%, then the problem is fairly trivial. If the set is greater than 33%, -however, then we know that those participants have the power to shut -down the network, albeit at very high cost to themselves. Hence, the -problem becomes somewhat different: how do we make it impossible for -colluding censors to censor specific transactions *without censoring -everything else as well*? - -One possible route to take is some kind of commit-reveal protocol, where -users submit a hash of a transaction plus proof that the transaction is -available, and then the transaction sender is somehow bound to include -the transaction itself once it is revealed (ie. blocks that do not -include the transaction will be invalid). However, this has the problem -that (i) proof of availability is very hard to implement, and (ii) -colluding censors can simply require the submission of a transaction -alongside its proof. In general, any protocol will likely be vulnerable -to "colluding censors can simply require a zero-knowledge proof of X", -but the challenge is making such a requirement maximally inconvenient -for all parties to implement. - -Privacy -~~~~~~~ - -Blockchains are often hailed as an alternative to centralized networks -that rely on trusting specific parties. However, one of the major areas -in which people actually do strongly distrust centralized parties in -real life is in the area of privacy, and blockchain protocols by -themsleves are even more public than centralized systems. Hence, -blockchain-based solutions to privacy will likely need to go a bit -beyond simply creating a decentralized database and being done with it; -effort must be made into creating protocols for maximally broad -categories of applications (eg. payments, financial contracts, identity -and reputation info publication) that combine blockchain-based data -publication with protocols that preserve individual privacy, and allow -individuals maximum freedom in what facts about themselves to expose to -what parties. - -Sub-problems of this problem include: - -- Fully anonymous currency (for existing work see Zerocash; Zerocash's - largest current flaw is arguably the long 90s transaction signing - period arising from its usage of zkSNARKs) -- A privacy-preserving reputation system that allows users to create - "zero-knowledge reputation certificates" proving that they have some - reputation score according to the target's desired metric but - revealing minimal other personal information -- A financial contract system that allows users to hide the code and - contents of their contracts to a maximal possible extent -- A maximally privacy-preserving decentralized internet-of-things - platform diff --git a/old-docs-for-reference/main-wiki.rst/Home.rst b/old-docs-for-reference/main-wiki.rst/Home.rst deleted file mode 100644 index d873a0f..0000000 --- a/old-docs-for-reference/main-wiki.rst/Home.rst +++ /dev/null @@ -1,66 +0,0 @@ -Welcome to the Ethereum Wiki -============================ - -This is the community-maintained wiki covering all sorts of information -on the next-generation peer-to-peer technology platform built by ÐΞV -including **Ethereum**, *the generalized blockchain for smart contract -development*, and **Whisper**, *the private low-level datagram -communication platform*. - -Users signed in with GitHub can edit and add pages using the -`browser `__ -or -`locally `__. - -Status ------- - -Frontier -~~~~~~~~ - -Version 1.0 of Ethereum aka Frontier was released on July 30th 2015! -Development continues towards the versions named Homestead, Metropolis -and Serenity (v1.1). Frontier is aimed at exchangers and -`miners `__. Homestead is -aiming for `Ðapps -developers `__, -while Metropolis is aiming for end users with the release of the Mist -browser. Serenity is meant to move from consensus through -`Proof-of-Work `__ to -`Proof-of-Stake `__. - -Getting started ---------------- - -To get the basic concepts of Ethereum visit the Ethereum homepage over -at `http://ethereum.org `__. If you want to get a -deeper understanding, start by read the -`whitepaper `__ and -the `design -rationale `__. -For a more formal review, read the `yellow -paper `__. See the `development -tutorial `__ -for quick start to developing smart contracts. - -Don't get lost --------------- - -Check the `Glossary `__ -and our `FAQ `__. There are -separate wikis for information relevant to the -`C++ `__ and -`Go `__ implementations -(Python and Javascript coming soon), - -Downloads ---------- - -Bleeding edge code can be cloned from the develop branch of their git -repositories: - https://github.com/ethereum/go-ethereum (Go) - -https://github.com/ethereum/webthree-umbrella (C++) - -https://github.com/ethereum/pyethapp (Python) - -To see the state of the latest Ethereum builds, see the `Buildbot -instance `__ for Go and Python and the -`Jenkins instance `__ for C++. diff --git a/old-docs-for-reference/main-wiki.rst/ICAP-Inter-exchange-Client-Address-Protocol.rst b/old-docs-for-reference/main-wiki.rst/ICAP-Inter-exchange-Client-Address-Protocol.rst deleted file mode 100644 index d2388ec..0000000 --- a/old-docs-for-reference/main-wiki.rst/ICAP-Inter-exchange-Client-Address-Protocol.rst +++ /dev/null @@ -1,198 +0,0 @@ -Transferring funds between third-party accounts, especially those of -exchanges, places considerable burden on the user and is error prone, -due to the way in which deposits are identified to the client account. -This problem was tackled by the existing banking industry through having -a common code known as *IBAN*. This code amalgamated the institution and -client account along with a error-detection mechanism practically -eliminating trivial errors and providing considerable convenience for -the user. Unfortunately, this is a heavily regulated and centralised -service accessible only to large, well-established institutions. The -present protocol, ICAP, may be viewed as a decentralised version of it -suitable for any institutions containing funds on the Ethereum system. - -IBAN -~~~~ - -For a good overview of the IBAN system, please see `Wikipedia's IBAN -article `__. -An IBAN code consists of up to 34 case insensitive alpha-numeric -characters. It contains three pieces of information: - -- The country code; a top-level identifier for the context of the - following (ISO 3166-1 alpha-2); -- The error-detection code; uses the *mod-97-10* checksumming protocol - (ISO/IEC 7064:2003); -- The basic bank account number (BBAN); an identifier of the - institution, branch and client account, whose composition is - dependent on the aforementioned country. - -For the UK, the BBAN is composed of: - -- Institution identifier, 4-character alphabetical, e.g. ``MIDL`` - (ironically) represents HSBC bank. -- Sort-code (branch identifier within the institution), a 6-digit - decimal number, e.g. ``402702`` would be the Lancaster branch of - HSBC. -- Account number (client identifier within the branch), an 8-digit - decimal number. - -Proposed Design -=============== - -Introduce a new IBAN country code: *XE*, formulated as the Ethereum *E* -prefixed with the "extended" *X*, as used in non-jurisdictional -currencies (e.g. XRP, XCP). - -There will be three BBAN possibilities for this code; *direct*, *basic* -and *indirect*. - -Direct -^^^^^^ - -The BBAN for this code when direct will be 30 characters and will -comprise one field: - -- Account identifier, 30 characters alphanumeric (< 155-bit). This will - be interpreted as a big-endian encoded base-36 integer representing - the least significant bits of a 160-bit Ethereum address. As such, - these Ethereum addresses will generally begin with a zero byte. - -e.g. XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS corresponds to the address -``00c5496aee77c1ba1f0854206a26dda82a81d6d8``. - -Basic -^^^^^ - -The same as the direct encoding, except that the code is 31 characters -(making it non-compliant for IBAN) and composes the same, single, field: - -- Account identifier, 31 characters alphanumeric (< 161-bit). This will - be interpreted as a big-endian encoded base-36 integer representing a - 160-bit Ethereum address. - -Indirect -^^^^^^^^ - -The BBAN for this code when indirect will be 16 characters and will -comprise three fields: - -- Asset identifier, 3-character alphanumeric (< 16-bit); -- Institution identifier, 4-character alphanumeric (< 21-bit); -- Institution client identifier, 9-character alphanumeric (< 47-bit); - -Including the four initial characters, this leads to a final -client-account address length of 20 characters, of the form: - -:: - - XE81ETHXREGGAVOFYORK - -Split into: - -- ``XE`` The country code for Ethereum; -- ``66`` The checksum; -- ``ETH`` The asset identifier within the client account - in this - case, "ETH" is the only valid asset identifier, since Ethereum's base - registry contract supports only this asset; -- ``XREG`` The institution code for the account - in this case, - Ethereum's base registry contract; -- ``GAVOFYORK`` The client identifier within the institution - in this - case, a direct payment with no additional data to whatever primary - address is associated with the name "GAVOFYORK" in Ethereum's base - registry contract; - -Notes ------ - -Institution codes beginning with ``X`` are reserved for system use. - -Other forms ------------ - -URI -~~~ - -General URIs can be formed though the URI scheme name ``iban``, followed -by the colon character ``:``, followed by the 20-character alphanumeric -identifier, thus for the example above, we would use: - -:: - - iban:XE81ETHXREGGAVOFYORK - -QR Code -~~~~~~~ - -A QR code may be generated directly from the URI using standard QR -encodings. For example, the example above ``iban:XE81ETHXREGGAVOFYORK`` -would have the corresponding QR code: - -.. figure:: http://opensecrecy.com/qr-XE81ETHXREGGAVOFYORK.gif - :alt: QR code for iban:XE81ETHXREGGAVOFYORK - - QR code for iban:XE81ETHXREGGAVOFYORK - -Transaction Semantics -===================== - -The mechanism for indirect asset transfer over three routing protocols -are specified, all of which are specific to the Ethereum domain -(country-code of ``XE``). One is for currency transfers directly to an -included address ("direct"), another is for clients with the system -address found through a Registry-lookup system of the client-ID, denoted -by asset class ``ETH``, whereas the last is for transfers to an -intermediary with associated data to specify client, denoted by asset -class ``XET`` (the latter two are "indirect"). - -Direct ------- - -If the IBAN code is 34 characters, it is a direct address; a direct -transfer is made to the address which, when base-36 encoded gives -exactly the data segment (the last 30 characters) of the IBAN code. - -Indirect ETH Asset: Simple transfers ------------------------------------- - -Within the ETH asset code of Ethereum's country-code (XE), i.e. as long -as the code begins with ``XE**ETH`` (where ``**`` is the valid -checksum), then we can define the required transaction to be the deposit -address given by a call to the *registry contract* denoted by the -institution code. For institutions not beginning with ``X``, this -corresponds to the primary address associated with the *Ethereum -standard name*: - -[institution code] ``/`` [client identifier] - -The *Ethereum standard name* is simply the normal hierarchical lookup -mechanism, as specified in the Ethereum standard interfaces document. - -We define a *registry contract* as a contract fulfilling the Registry -interface as specified in the Ethereum standard interfaces document. - -**TODO**: JS code for specifying the transfer. - -Indirect XET Asset: Institution transfers ------------------------------------------ - -For the ``XET`` asset code within the Ethereum country code (i.e. while -the code begins XE\*\*XET), then we can derive the transaction that must -be made through a lookup to the Ethereum ``iban`` registry contract. For -a given institution, this contract specifies two values: the deposit -call signature hash and the institution's Ethereum address. - -At present, only a single such deposit call is defined, which is: - -:: - - function deposit(uint64 clientAccount) - -whose signature hash is ``0x13765838``. The transaction to transfer the -assets should be formed as an ether-laden call to the institution's -Ethereum address using the ``deposit`` method as specified above, with -the client account determined through the value of the big-endian, -base-36 interpretation of the alpha-numeric *Institution client -identifier*, literally using the value of the characters ``0`` to ``9``, -then evaluating 'A' (or 'a') as 10, 'B' (or 'b') as 11 and so forth. - -**TODO**: JS code for specifying the transfer. diff --git a/old-docs-for-reference/main-wiki.rst/IPv6.rst b/old-docs-for-reference/main-wiki.rst/IPv6.rst deleted file mode 100644 index a3ba69b..0000000 --- a/old-docs-for-reference/main-wiki.rst/IPv6.rst +++ /dev/null @@ -1,23 +0,0 @@ -Goals -~~~~~ - -Allow IPv6 to be used over the ethereum peer network - -Basic Design -~~~~~~~~~~~~ - -Allow IP addresses to be specified either as a 4-byte array (IPv4) or a -16-byte array (IPv6). - -Needed Changes -~~~~~~~~~~~~~~ - -**Peers** [``0x05``, [``ip1``: ``B_4`` OR ``B_16``, ``port1``: ``P``, -``id1``: ``B_64``], [``ip2``: ``B_4`` OR ``B_16``, ``port2``: ``P``, -``id2``: ``B_64``], ... ] Specifies a number of known peers. \* ``ip`` -is either a 4-byte array 'ABCD' that should be interpreted as the IPv4 -address A.B.C.D or a 8-byte array 'ABCDEFGHIJKLMNOP' that should be -interpreted as the IPv6 address AB:CD:EF:GH:IJ:KL:MN:OP. \* ``port`` is -a 2-byte array that should be interpreted as a 16-bit big-endian -integer. \* ``id`` is the 512-bit hash that acts as the unique -identifier of the node. diff --git a/old-docs-for-reference/main-wiki.rst/JSON-RPC-Error-Codes-Improvement-Proposal.rst b/old-docs-for-reference/main-wiki.rst/JSON-RPC-Error-Codes-Improvement-Proposal.rst deleted file mode 100644 index 0fed2d9..0000000 --- a/old-docs-for-reference/main-wiki.rst/JSON-RPC-Error-Codes-Improvement-Proposal.rst +++ /dev/null @@ -1,176 +0,0 @@ -To help developers add proper error handling in the dapp side, we need -to implement custom error codes for the returned JSON RPC errors. - -JSON RPC Standard errors ------------------------- - -+-----------+----------------------------+----------------+ -| Code | Possible Return message | Description | -+===========+============================+================+ -| -32700 | Parse error | Invalid JSON | -| | | was received | -| | | by the server. | -| | | An error | -| | | occurred on | -| | | the server | -| | | while parsing | -| | | the JSON text. | -+-----------+----------------------------+----------------+ -| -32600 | Invalid Request | The JSON sent | -| | | is not a valid | -| | | Request | -| | | object. | -+-----------+----------------------------+----------------+ -| -32601 | Method not found | The method | -| | | does not exist | -| | | / is not | -| | | available. | -+-----------+----------------------------+----------------+ -| -32602 | Invalid params | Invalid method | -| | | parameter(s). | -+-----------+----------------------------+----------------+ -| -32603 | Internal error | Internal | -| | | JSON-RPC | -| | | error. | -+-----------+----------------------------+----------------+ -| -32000 to | ``Server error``. Reserved | -| -32099 | for implementation-defined | -| | server-errors. | -+-----------+----------------------------+----------------+ - -Custom error codes: -------------------- - -+-----------+----------------------------+----------------+ -| Code | Possible Return message | Description | -+===========+============================+================+ -| 1 | Unauthorized | Should be used | -| | | when some | -| | | action is not | -| | | authorized, | -| | | e.g. sending | -| | | from a locked | -| | | account. | -+-----------+----------------------------+----------------+ -| 2 | Action not allowed | Should be used | -| | | when some | -| | | action is not | -| | | allowed, e.g. | -| | | preventing an | -| | | action, while | -| | | another | -| | | depending | -| | | action is | -| | | processing on, | -| | | like sending | -| | | again when a | -| | | confirmation | -| | | popup is shown | -| | | to the user | -| | | (?). | -+-----------+----------------------------+----------------+ -| 3 | Execution error | Will contain a | -| | | subset of | -| | | custom errors | -| | | in the data | -| | | field. See | -| | | below. | -+-----------+----------------------------+----------------+ - -Custom error fields -~~~~~~~~~~~~~~~~~~~ - -Custom error ``3`` can contain custom error(s) to further explain what -went wrong. They will be contained in the ``data`` field of the RPC -error message as follows: - -.. code:: js - - { - code: 3, - message: 'Execution error', - data: [{ - code: 102, - message: 'Innsufficient gas', - reason: 'GAS' - }, - { - code: 103, - message: 'Gas limit exceeded', - reason: 'GAS' - }] - } - -+-----------+-----------------+----------------------------+----------------+ -| Code | Reson values | Possible Return message | Description | -+===========+=================+============================+================+ -| 100 | ? | X doesn't exist | Should be used | -| | | | when something | -| | | | which should | -| | | | be there is | -| | | | not found. | -| | | | (Doesn't apply | -| | | | for not found | -| | | | transactions | -| | | | or blocks. | -| | | | They return a | -| | | | success with | -| | | | value | -| | | | ``null``) | -+-----------+-----------------+----------------------------+----------------+ -| 101 | ``ETHER`` ? | Requires X | Should be used | -| | | | for actions | -| | | | which require | -| | | | somethin else, | -| | | | e.g. gas or a | -| | | | value. | -+-----------+-----------------+----------------------------+----------------+ -| 102 | ``GAS``, | X to low | Should be used | -| | ``ETHER`` | | when a to low | -| | | | value of | -| | | | something was | -| | | | given, e.g. an | -| | | | to low gas | -| | | | amount. | -+-----------+-----------------+----------------------------+----------------+ -| 103 | ``GAS`` | X limit exceeded | Should be used | -| | | | when a limit | -| | | | is exceeded, | -| | | | e.g. for the | -| | | | gas limit in a | -| | | | block. | -+-----------+-----------------+----------------------------+----------------+ -| 104 | ``CODE`` ? | Rejected | Should be used | -| | | | when an action | -| | | | was rejected, | -| | | | e.g. because | -| | | | of its content | -| | | | (to long | -| | | | contract code, | -| | | | containing | -| | | | wrong | -| | | | characters ?, | -| | | | should differ | -| | | | from | -| | | | ``-32602`` - | -| | | | Invalid | -| | | | params). | -+-----------+-----------------+----------------------------+----------------+ - -Possible future error codes? ----------------------------- - -+-----------+----------------------------+----------------+ -| Code | Possible Return message | Description | -+===========+============================+================+ -| 105 | Timeout | Should be used | -| | | when an action | -| | | timedout. | -+-----------+----------------------------+----------------+ -| 106 | Conflict | Should be used | -| | | when an action | -| | | conflicts with | -| | | another | -| | | (ongoing?) | -| | | action. | -+-----------+----------------------------+----------------+ diff --git a/old-docs-for-reference/main-wiki.rst/JSON-RPC.rst b/old-docs-for-reference/main-wiki.rst/JSON-RPC.rst deleted file mode 100644 index 458cbd8..0000000 --- a/old-docs-for-reference/main-wiki.rst/JSON-RPC.rst +++ /dev/null @@ -1,2865 +0,0 @@ -JSON RPC API -============ - -`JSON `__ is a lightweight data-interchange format. It -can represent numbers, strings, ordered sequences of values, and -collections of name/value pairs. - -`JSON-RPC `__ is a stateless, -light-weight remote procedure call (RPC) protocol. Primarily this -specification defines several data structures and the rules around their -processing. It is transport agnostic in that the concepts can be used -within the same process, over sockets, over HTTP, or in many various -message passing environments. It uses JSON (`RFC -4627 `__) as data format. - -JavaScript API --------------- - -To talk to an Ethereum node from inside a JavaScript application use the -`web3.js `__ library, which gives -an convenient interface for the RPC methods. See the `JavaScript -API `__ for more. - -JSON-RPC Endpoint ------------------ - -Default JSON-RPC endpoints: - -:: - - C++: http://localhost:8545 - Go: http://localhost:8545 - Py: http://localhost:4000 - -Go -~~ - -You can start the HTTP JSON-RPC with the ``--rpc`` flag - -.. code:: bash - - geth --rpc - -change the default port (8545) and listing address (localhost) with: - -.. code:: bash - - geth --rpc --rpcaddr --rpcport - -If accessing the RPC from a browser, CORS will need to be enabled with -the appropriate domain set. Otherwise, JavaScript calls are limit by the -same-origin policy and requests will fail: - -.. code:: bash - - geth --rpc --rpccorsdomain "http://localhost:3000" - -The JSON RPC can also be started from the `geth -console `__ -using the ``admin.startRPC(addr, port)`` command. - -C++ -~~~ - -You can start it by running ``eth`` application with ``-j`` option: - -.. code:: bash - - ./eth -j - -You can also specify JSON-RPC port (default is 8545): - -.. code:: bash - - ./eth -j --json-rpc-port 8079 - -Python -~~~~~~ - -In python the JSONRPC server is currently started by default and listens -on ``127.0.0.1:4000`` - -You can change the port and listen address by giving a config option. - -``pyethapp -c jsonrpc.listen_port=4002 -c jsonrpc.listen_host=127.0.0.2 run`` - -JSON-RPC support ----------------- - -+------------------+----------------+---------------+---------------+ -| | cpp-ethereum | go-ethereum | py-ethereum | -+==================+================+===============+===============+ -| JSON-RPC 1.0 | ✓ | | | -+------------------+----------------+---------------+---------------+ -| JSON-RPC 2.0 | ✓ | ✓ | ✓ | -+------------------+----------------+---------------+---------------+ -| Batch requests | ✓ | ✓ | ✓ | -+------------------+----------------+---------------+---------------+ -| HTTP | ✓ | ✓ | ✓ | -+------------------+----------------+---------------+---------------+ - -Output HEX values ------------------ - -At present there are two key datatypes that are passed over JSON: -unformatted byte arrays and quantities. Both are passed with a hex -encoding, however with different requirements to formatting: - -When encoding **QUANTITIES** (integers, numbers): encode as hex, prefix -with "0x", the most compact representation (slight exception: zero -should be represented as "0x0"). Examples: - 0x41 (65 in decimal) - -0x400 (1024 in decimal) - WRONG: 0x (should always have at least one -digit - zero is "0x0") - WRONG: 0x0400 (no leading zeroes allowed) - -WRONG: ff (must be prefixed 0x) - -When encoding **UNFORMATTED DATA** (byte arrays, account addresses, -hashes, bytecode arrays): encode as hex, prefix with "0x", two hex -digits per byte. Examples: - 0x41 (size 1, "A") - 0x004200 (size 3, -":raw-latex:`\0`B:raw-latex:`\0`") - 0x (size 0, "") - WRONG: 0xf0f0f -(must be even number of digits) - WRONG: 004200 (must be prefixed 0x) - -Currently `cpp-ethereum `__ -and `go-ethereum `__ provides -JSON-RPC communication only over http. - -The default block parameter ---------------------------- - -The following methods have a extra default block parameter: - -- `eth\_getBalance <#eth_getbalance>`__ -- `eth\_getCode <#eth_getcode>`__ -- `eth\_getTransactionCount <#eth_gettransactioncount>`__ -- `eth\_getStorageAt <#eth_getstorageat>`__ -- `eth\_call <#eth_call>`__ - -When requests are made that act on the state of Ethereum, the last -default block parameter determines the height of the block. - -The following options are possible for the defaultBlock parameter: - -- ``HEX String`` - an integer block number -- ``String "earliest"`` for the earliest/genesis block -- ``String "latest"`` - for the latest mined block -- ``String "pending"`` - for the pending state/transactions - -JSON-RPC methods ----------------- - -- `web3\_clientVersion <#web3_clientversion>`__ -- `web3\_sha3 <#web3_sha3>`__ -- `net\_version <#net_version>`__ -- `net\_peerCount <#net_peercount>`__ -- `net\_listening <#net_listening>`__ -- `eth\_protocolVersion <#eth_protocolversion>`__ -- `eth\_syncing <#eth_syncing>`__ -- `eth\_coinbase <#eth_coinbase>`__ -- `eth\_mining <#eth_mining>`__ -- `eth\_hashrate <#eth_hashrate>`__ -- `eth\_gasPrice <#eth_gasprice>`__ -- `eth\_accounts <#eth_accounts>`__ -- `eth\_blockNumber <#eth_blocknumber>`__ -- `eth\_getBalance <#eth_getbalance>`__ -- `eth\_getStorageAt <#eth_getstorageat>`__ -- `eth\_getTransactionCount <#eth_gettransactioncount>`__ -- `eth\_getBlockTransactionCountByHash <#eth_getblocktransactioncountbyhash>`__ -- `eth\_getBlockTransactionCountByNumber <#eth_getblocktransactioncountbynumber>`__ -- `eth\_getUncleCountByBlockHash <#eth_getunclecountbyblockhash>`__ -- `eth\_getUncleCountByBlockNumber <#eth_getunclecountbyblocknumber>`__ -- `eth\_getCode <#eth_getcode>`__ -- `eth\_sign <#eth_sign>`__ -- `eth\_sendTransaction <#eth_sendtransaction>`__ -- `eth\_sendRawTransaction <#eth_sendrawtransaction>`__ -- `eth\_call <#eth_call>`__ -- `eth\_estimateGas <#eth_estimategas>`__ -- `eth\_getBlockByHash <#eth_getblockbyhash>`__ -- `eth\_getBlockByNumber <#eth_getblockbynumber>`__ -- `eth\_getTransactionByHash <#eth_gettransactionbyhash>`__ -- `eth\_getTransactionByBlockHashAndIndex <#eth_gettransactionbyblockhashandindex>`__ -- `eth\_getTransactionByBlockNumberAndIndex <#eth_gettransactionbyblocknumberandindex>`__ -- `eth\_getTransactionReceipt <#eth_gettransactionreceipt>`__ -- `eth\_getUncleByBlockHashAndIndex <#eth_getunclebyblockhashandindex>`__ -- `eth\_getUncleByBlockNumberAndIndex <#eth_getunclebyblocknumberandindex>`__ -- `eth\_getCompilers <#eth_getcompilers>`__ -- `eth\_compileLLL <#eth_compilelll>`__ -- `eth\_compileSolidity <#eth_compilesolidity>`__ -- `eth\_compileSerpent <#eth_compileserpent>`__ -- `eth\_newFilter <#eth_newfilter>`__ -- `eth\_newBlockFilter <#eth_newblockfilter>`__ -- `eth\_newPendingTransactionFilter <#eth_newpendingtransactionfilter>`__ -- `eth\_uninstallFilter <#eth_uninstallfilter>`__ -- `eth\_getFilterChanges <#eth_getfilterchanges>`__ -- `eth\_getFilterLogs <#eth_getfilterlogs>`__ -- `eth\_getLogs <#eth_getlogs>`__ -- `eth\_getWork <#eth_getwork>`__ -- `eth\_submitWork <#eth_submitwork>`__ -- `eth\_submitHashrate <#eth_submithashrate>`__ -- `db\_putString <#db_putstring>`__ -- `db\_getString <#db_getstring>`__ -- `db\_putHex <#db_puthex>`__ -- `db\_getHex <#db_gethex>`__ -- `shh\_post <#shh_post>`__ -- `shh\_version <#shh_version>`__ -- `shh\_newIdentity <#shh_newidentity>`__ -- `shh\_hasIdentity <#shh_hasidentity>`__ -- `shh\_newGroup <#shh_newgroup>`__ -- `shh\_addToGroup <#shh_addtogroup>`__ -- `shh\_newFilter <#shh_newfilter>`__ -- `shh\_uninstallFilter <#shh_uninstallfilter>`__ -- `shh\_getFilterChanges <#shh_getfilterchanges>`__ -- `shh\_getMessages <#shh_getmessages>`__ - -JSON RPC API Reference ----------------------- - --------------- - -web3\_clientVersion -^^^^^^^^^^^^^^^^^^^ - -Returns the current client version. - -Parameters -'''''''''' - -none - -Returns -''''''' - -``String`` - The current client version - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":67}' - - // Result - { - "id":67, - "jsonrpc":"2.0", - "result": "Mist/v0.9.3/darwin/go1.4.1" - } - --------------- - -web3\_sha3 -^^^^^^^^^^ - -Returns Keccak-256 (*not* the standardized SHA3-256) of the given data. - -Parameters -'''''''''' - -1. ``String`` - the data to convert into a SHA3 hash - -.. code:: js - - params: [ - '0x68656c6c6f20776f726c64' - ] - -Returns -''''''' - -``DATA`` - The SHA3 result of the given string. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"web3_sha3","params":["0x68656c6c6f20776f726c64"],"id":64}' - - // Result - { - "id":64, - "jsonrpc": "2.0", - "result": "0x47173285a8d7341e5e972fc677286384f802f8ef42a5ec5f03bbfa254cb01fad" - } - --------------- - -net\_version -^^^^^^^^^^^^ - -Returns the current network protocol version. - -Parameters -'''''''''' - -none - -Returns -''''''' - -``String`` - The current network protocol version - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"net_version","params":[],"id":67}' - - // Result - { - "id":67, - "jsonrpc": "2.0", - "result": "59" - } - --------------- - -net\_listening -^^^^^^^^^^^^^^ - -Returns ``true`` if client is actively listening for network -connections. - -Parameters -'''''''''' - -none - -Returns -''''''' - -``Boolean`` - ``true`` when listening, otherwise ``false``. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":67}' - - // Result - { - "id":67, - "jsonrpc":"2.0", - "result":true - } - --------------- - -net\_peerCount -^^^^^^^^^^^^^^ - -Returns number of peers currenly connected to the client. - -Parameters -'''''''''' - -none - -Returns -''''''' - -``QUANTITY`` - integer of the number of connected peers. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":74}' - - // Result - { - "id":74, - "jsonrpc": "2.0", - "result": "0x2" // 2 - } - --------------- - -eth\_protocolVersion -^^^^^^^^^^^^^^^^^^^^ - -Returns the current Ethereum protocol version. - -Parameters -'''''''''' - -none - -Returns -''''''' - -``String`` - The current Ethereum protocol version - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_protocolVersion","params":[],"id":67}' - - // Result - { - "id":67, - "jsonrpc": "2.0", - "result": "54" - } - --------------- - -eth\_syncing -^^^^^^^^^^^^ - -Returns an object object with data about the sync status or FALSE. - -Parameters -'''''''''' - -none - -Returns -''''''' - -``Object|Boolean``, An object with sync status data or ``FALSE``, when -not syncing: - ``startingBlock``: ``QUANTITY`` - The block at which the -import started (will only be reset, after the sync reached his head) - -``currentBlock``: ``QUANTITY`` - The current block, same as -eth\_blockNumber - ``highestBlock``: ``QUANTITY`` - The estimated -highest block - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": { - startingBlock: '0x384', - currentBlock: '0x386', - highestBlock: '0x454' - } - } - // Or when not syncing - { - "id":1, - "jsonrpc": "2.0", - "result": false - } - --------------- - -eth\_coinbase -^^^^^^^^^^^^^ - -Returns the client coinbase address. - -Parameters -'''''''''' - -none - -Returns -''''''' - -``DATA``, 20 bytes - the current coinbase address. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_coinbase","params":[],"id":64}' - - // Result - { - "id":64, - "jsonrpc": "2.0", - "result": "0x407d73d8a49eeb85d32cf465507dd71d507100c1" - } - --------------- - -eth\_mining -^^^^^^^^^^^ - -Returns ``true`` if client is actively mining new blocks. - -Parameters -'''''''''' - -none - -Returns -''''''' - -``Boolean`` - returns ``true`` of the client is mining, otherwise -``false``. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_mining","params":[],"id":71}' - - // Result - { - "id":71, - "jsonrpc": "2.0", - "result": true - } - --------------- - -eth\_hashrate -^^^^^^^^^^^^^ - -Returns the number of hashes per second that the node is mining with. - -Parameters -'''''''''' - -none - -Returns -''''''' - -``QUANTITY`` - number of hashes per second. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_hashrate","params":[],"id":71}' - - // Result - { - "id":71, - "jsonrpc": "2.0", - "result": "0x38a" - } - --------------- - -eth\_gasPrice -^^^^^^^^^^^^^ - -Returns the current price per gas in wei. - -Parameters -'''''''''' - -none - -Returns -''''''' - -``QUANTITY`` - integer of the current gas price in wei. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":73}' - - // Result - { - "id":73, - "jsonrpc": "2.0", - "result": "0x09184e72a000" // 10000000000000 - } - --------------- - -eth\_accounts -^^^^^^^^^^^^^ - -Returns a list of addresses owned by client. - -Parameters -'''''''''' - -none - -Returns -''''''' - -``Array of DATA``, 20 Bytes - addresses owned by the client. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":1}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": ["0x407d73d8a49eeb85d32cf465507dd71d507100c1"] - } - --------------- - -eth\_blockNumber -^^^^^^^^^^^^^^^^ - -Returns the number of most recent block. - -Parameters -'''''''''' - -none - -Returns -''''''' - -``QUANTITY`` - integer of the current block number the client is on. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":83}' - - // Result - { - "id":83, - "jsonrpc": "2.0", - "result": "0x4b7" // 1207 - } - --------------- - -eth\_getBalance -^^^^^^^^^^^^^^^ - -Returns the balance of the account of given address. - -Parameters -'''''''''' - -1. ``DATA``, 20 Bytes - address to check for balance. -2. ``QUANTITY|TAG`` - integer block number, or the string ``"latest"``, - ``"earliest"`` or ``"pending"``, see the `default block - parameter <#the-default-block-parameter>`__ - -.. code:: js - - params: [ - '0x407d73d8a49eeb85d32cf465507dd71d507100c1', - 'latest' - ] - -Returns -''''''' - -``QUANTITY`` - integer of the current balance in wei. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0x407d73d8a49eeb85d32cf465507dd71d507100c1", "latest"],"id":1}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": "0x0234c8a3397aab58" // 158972490234375000 - } - --------------- - -eth\_getStorageAt -^^^^^^^^^^^^^^^^^ - -Returns the value from a storage position at a given address. - -Parameters -'''''''''' - -1. ``DATA``, 20 Bytes - address of the storage. -2. ``QUANTITY`` - integer of the position in the storage. -3. ``QUANTITY|TAG`` - integer block number, or the string ``"latest"``, - ``"earliest"`` or ``"pending"``, see the `default block - parameter <#the-default-block-parameter>`__ - -.. code:: js - - params: [ - '0x407d73d8a49eeb85d32cf465507dd71d507100c1', - '0x0', // storage position at 0 - '0x2' // state at block number 2 - ] - -Returns -''''''' - -``DATA`` - the value at this storage position. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getStorageAt","params":["0x407d73d8a49eeb85d32cf465507dd71d507100c1", "0x0", "0x2"],"id":1}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": "0x03" - } - --------------- - -eth\_getTransactionCount -^^^^^^^^^^^^^^^^^^^^^^^^ - -Returns the number of transactions *sent* from an address. - -Parameters -'''''''''' - -1. ``DATA``, 20 Bytes - address. -2. ``QUANTITY|TAG`` - integer block number, or the string ``"latest"``, - ``"earliest"`` or ``"pending"``, see the `default block - parameter <#the-default-block-parameter>`__ - -.. code:: js - - params: [ - '0x407d73d8a49eeb85d32cf465507dd71d507100c1', - 'latest' // state at the latest block - ] - -Returns -''''''' - -``QUANTITY`` - integer of the number of transactions send from this -address. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionCount","params":["0x407d73d8a49eeb85d32cf465507dd71d507100c1","latest"],"id":1}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": "0x1" // 1 - } - --------------- - -eth\_getBlockTransactionCountByHash -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Returns the number of transactions in a block from a block matching the -given block hash. - -Parameters -'''''''''' - -1. ``DATA``, 32 Bytes - hash of a block - -.. code:: js - - params: [ - '0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238' - ] - -Returns -''''''' - -``QUANTITY`` - integer of the number of transactions in this block. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockTransactionCountByHash","params":["0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"],"id":1}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": "0xb" // 11 - } - --------------- - -eth\_getBlockTransactionCountByNumber -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Returns the number of transactions in a block from a block matching the -given block number. - -Parameters -'''''''''' - -1. ``QUANTITY|TAG`` - integer of a block number, or the string - ``"earliest"``, ``"latest"`` or ``"pending"``, as in the `default - block parameter <#the-default-block-parameter>`__. - -.. code:: js - - params: [ - '0xe8', // 232 - ] - -Returns -''''''' - -``QUANTITY`` - integer of the number of transactions in this block. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockTransactionCountByNumber","params":["0xe8"],"id":1}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": "0xa" // 10 - } - --------------- - -eth\_getUncleCountByBlockHash -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Returns the number of uncles in a block from a block matching the given -block hash. - -Parameters -'''''''''' - -1. ``DATA``, 32 Bytes - hash of a block - -.. code:: js - - params: [ - '0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238' - ] - -Returns -''''''' - -``QUANTITY`` - integer of the number of uncles in this block. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getUncleCountByBlockHash","params":["0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"],"id"Block:1}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": "0x1" // 1 - } - --------------- - -eth\_getUncleCountByBlockNumber -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Returns the number of uncles in a block from a block matching the given -block number. - -Parameters -'''''''''' - -1. ``QUANTITY`` - integer of a block number, or the string "latest", - "earliest" or "pending", see the `default block - parameter <#the-default-block-parameter>`__ - -.. code:: js - - params: [ - '0xe8', // 232 - ] - -Returns -''''''' - -``QUANTITY`` - integer of the number of uncles in this block. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getUncleCountByBlockNumber","params":["0xe8"],"id":1}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": "0x1" // 1 - } - --------------- - -eth\_getCode -^^^^^^^^^^^^ - -Returns code at a given address. - -Parameters -'''''''''' - -1. ``DATA``, 20 Bytes - address -2. ``QUANTITY|TAG`` - integer block number, or the string ``"latest"``, - ``"earliest"`` or ``"pending"``, see the `default block - parameter <#the-default-block-parameter>`__ - -.. code:: js - - params: [ - '0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b', - '0x2' // 2 - ] - -Returns -''''''' - -``DATA`` - the code from the given address. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getCode","params":["0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b", "0x2"],"id":1}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": "0x600160008035811a818181146012578301005b601b6001356025565b8060005260206000f25b600060078202905091905056" - } - --------------- - -eth\_sign -^^^^^^^^^ - -Signs data with a given address. - -**Note** the address to sign must be unlocked. - -Parameters -'''''''''' - -1. ``DATA``, 20 Bytes - address -2. ``DATA``, Data to sign - -Returns -''''''' - -``DATA``: Signed data - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_sign","params":["0xd1ade25ccd3d550a7eb532ac759cac7be09c2719", "Schoolbus"],"id":1}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": "0x2ac19db245478a06032e69cdbd2b54e648b78431d0a47bd1fbab18f79f820ba407466e37adbe9e84541cab97ab7d290f4a64a5825c876d22109f3bf813254e8601" - } - --------------- - -eth\_sendTransaction -^^^^^^^^^^^^^^^^^^^^ - -Creates new message call transaction or a contract creation, if the data -field contains code. - -Parameters -'''''''''' - -1. ``Object`` - The transaction object - -- ``from``: ``DATA``, 20 Bytes - The address the transaction is send - from. -- ``to``: ``DATA``, 20 Bytes - (optional when creating new contract) - The address the transaction is directed to. -- ``gas``: ``QUANTITY`` - (optional, default: 90000) Integer of the gas - provided for the transaction execution. It will return unused gas. -- ``gasPrice``: ``QUANTITY`` - (optional, default: To-Be-Determined) - Integer of the gasPrice used for each paid gas -- ``value``: ``QUANTITY`` - (optional) Integer of the value send with - this transaction -- ``data``: ``DATA`` - The compiled code of a contract OR the hash of - the invoked method signature and encoded parameters. For details see - `Ethereum Contract - ABI `__ -- ``nonce``: ``QUANTITY`` - (optional) Integer of a nonce. This allows - to overwrite your own pending transactions that use the same nonce. - -.. code:: js - - params: [{ - "from": "0xb60e8dd61c5d32be8058bb8eb970870f07233155", - "to": "0xd46e8dd67c5d32be8058bb8eb970870f072445675", - "gas": "0x76c0", // 30400, - "gasPrice": "0x9184e72a000", // 10000000000000 - "value": "0x9184e72a", // 2441406250 - "data": "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675" - }] - -Returns -''''''' - -``DATA``, 32 Bytes - the transaction hash, or the zero hash if the -transaction is not yet available. - -Use `eth\_getTransactionReceipt <#eth_gettransactionreceipt>`__ to get -the contract address, after the transaction was mined, when you created -a contract. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_sendTransaction","params":[{see above}],"id":1}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" - } - --------------- - -eth\_sendRawTransaction -^^^^^^^^^^^^^^^^^^^^^^^ - -Creates new message call transaction or a contract creation for signed -transactions. - -Parameters -'''''''''' - -1. ``DATA``, The signed transaction data. - -.. code:: js - - params: ["0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675"] - -Returns -''''''' - -``DATA``, 32 Bytes - the transaction hash, or the zero hash if the -transaction is not yet available. - -Use `eth\_getTransactionReceipt <#eth_gettransactionreceipt>`__ to get -the contract address, after the transaction was mined, when you created -a contract. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":[{see above}],"id":1}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" - } - --------------- - -eth\_call -^^^^^^^^^ - -Executes a new message call immediately without creating a transaction -on the block chain. - -Parameters -'''''''''' - -1. ``Object`` - The transaction call object - -- ``from``: ``DATA``, 20 Bytes - (optional) The address the transaction - is send from. -- ``to``: ``DATA``, 20 Bytes - The address the transaction is directed - to. -- ``gas``: ``QUANTITY`` - (optional) Integer of the gas provided for - the transaction execution. eth\_call consumes zero gas, but this - parameter may be needed by some executions. -- ``gasPrice``: ``QUANTITY`` - (optional) Integer of the gasPrice used - for each paid gas -- ``value``: ``QUANTITY`` - (optional) Integer of the value send with - this transaction -- ``data``: ``DATA`` - (optional) Hash of the method signature and - encoded parameters. For details see `Ethereum Contract - ABI `__ - -2. ``QUANTITY|TAG`` - integer block number, or the string ``"latest"``, - ``"earliest"`` or ``"pending"``, see the `default block - parameter <#the-default-block-parameter>`__ - -Returns -''''''' - -``DATA`` - the return value of executed contract. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_call","params":[{see above}],"id":1}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": "0x0" - } - --------------- - -eth\_estimateGas -^^^^^^^^^^^^^^^^ - -Makes a call or transaction, which won't be added to the blockchain and -returns the used gas, which can be used for estimating the used gas. - -Parameters -'''''''''' - -See `eth\_call <#eth_call>`__ parameters, expect that all properties are -optional. - -Returns -''''''' - -``QUANTITY`` - the amount of gas used. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_estimateGas","params":[{see above}],"id":1}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": "0x5208" // 21000 - } - --------------- - -eth\_getBlockByHash -^^^^^^^^^^^^^^^^^^^ - -Returns information about a block by hash. - -Parameters -'''''''''' - -1. ``DATA``, 32 Bytes - Hash of a block. -2. ``Boolean`` - If ``true`` it returns the full transaction objects, if - ``false`` only the hashes of the transactions. - -.. code:: js - - params: [ - '0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331', - true - ] - -Returns -''''''' - -``Object`` - A block object, or ``null`` when no block was found: - -- ``number``: ``QUANTITY`` - the block number. ``null`` when its - pending block. -- ``hash``: ``DATA``, 32 Bytes - hash of the block. ``null`` when its - pending block. -- ``parentHash``: ``DATA``, 32 Bytes - hash of the parent block. -- ``nonce``: ``DATA``, 8 Bytes - hash of the generated proof-of-work. - ``null`` when its pending block. -- ``sha3Uncles``: ``DATA``, 32 Bytes - SHA3 of the uncles data in the - block. -- ``logsBloom``: ``DATA``, 256 Bytes - the bloom filter for the logs of - the block. ``null`` when its pending block. -- ``transactionsRoot``: ``DATA``, 32 Bytes - the root of the - transaction trie of the block. -- ``stateRoot``: ``DATA``, 32 Bytes - the root of the final state trie - of the block. -- ``receiptsRoot``: ``DATA``, 32 Bytes - the root of the receipts trie - of the block. -- ``miner``: ``DATA``, 20 Bytes - the address of the beneficiary to - whom the mining rewards were given. -- ``difficulty``: ``QUANTITY`` - integer of the difficulty for this - block. -- ``totalDifficulty``: ``QUANTITY`` - integer of the total difficulty - of the chain until this block. -- ``extraData``: ``DATA`` - the "extra data" field of this block. -- ``size``: ``QUANTITY`` - integer the size of this block in bytes. -- ``gasLimit``: ``QUANTITY`` - the maximum gas allowed in this block. -- ``gasUsed``: ``QUANTITY`` - the total used gas by all transactions in - this block. -- ``timestamp``: ``QUANTITY`` - the unix timestamp for when the block - was collated. -- ``transactions``: ``Array`` - Array of transaction objects, or 32 - Bytes transaction hashes depending on the last given parameter. -- ``uncles``: ``Array`` - Array of uncle hashes. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockByHash","params":["0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331", true],"id":1}' - - // Result - { - "id":1, - "jsonrpc":"2.0", - "result": { - "number": "0x1b4", // 436 - "hash": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331", - "parentHash": "0x9646252be9520f6e71339a8df9c55e4d7619deeb018d2a3f2d21fc165dde5eb5", - "nonce": "0xe04d296d2460cfb8472af2c5fd05b5a214109c25688d3704aed5484f9a7792f2", - "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347", - "logsBloom": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331", - "transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", - "stateRoot": "0xd5855eb08b3387c0af375e9cdb6acfc05eb8f519e419b874b6ff2ffda7ed1dff", - "miner": "0x4e65fda2159562a496f9f3522f89122a3088497a", - "difficulty": "0x027f07", // 163591 - "totalDifficulty": "0x027f07", // 163591 - "extraData": "0x0000000000000000000000000000000000000000000000000000000000000000", - "size": "0x027f07", // 163591 - "gasLimit": "0x9f759", // 653145 - "minGasPrice": "0x9f759", // 653145 - "gasUsed": "0x9f759", // 653145 - "timestamp": "0x54e34e8e" // 1424182926 - "transactions": [{...},{ ... }] - "uncles": ["0x1606e5...", "0xd5145a9..."] - } - } - --------------- - -eth\_getBlockByNumber -^^^^^^^^^^^^^^^^^^^^^ - -Returns information about a block by block number. - -Parameters -'''''''''' - -1. ``QUANTITY|TAG`` - integer of a block number, or the string - ``"earliest"``, ``"latest"`` or ``"pending"``, as in the `default - block parameter <#the-default-block-parameter>`__. -2. ``Boolean`` - If ``true`` it returns the full transaction objects, if - ``false`` only the hashes of the transactions. - -.. code:: js - - params: [ - '0x1b4', // 436 - true - ] - -Returns -''''''' - -See `eth\_getBlockByHash <#eth_getblockbyhash>`__ - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["0x1b4", true],"id":1}' - -Result see `eth\_getBlockByHash <#eth_getblockbyhash>`__ - --------------- - -eth\_getTransactionByHash -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Returns the information about a transaction requested by transaction -hash. - -Parameters -'''''''''' - -1. ``DATA``, 32 Bytes - hash of a transaction - -.. code:: js - - params: [ - "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238" - ] - -Returns -''''''' - -``Object`` - A transaction object, or ``null`` when no transaction was -found: - -- ``hash``: ``DATA``, 32 Bytes - hash of the transaction. -- ``nonce``: ``QUANTITY`` - the number of transactions made by the - sender prior to this one. -- ``blockHash``: ``DATA``, 32 Bytes - hash of the block where this - transaction was in. ``null`` when its pending. -- ``blockNumber``: ``QUANTITY`` - block number where this transaction - was in. ``null`` when its pending. -- ``transactionIndex``: ``QUANTITY`` - integer of the transactions - index position in the block. ``null`` when its pending. -- ``from``: ``DATA``, 20 Bytes - address of the sender. -- ``to``: ``DATA``, 20 Bytes - address of the receiver. ``null`` when - its a contract creation transaction. -- ``value``: ``QUANTITY`` - value transferred in Wei. -- ``gasPrice``: ``QUANTITY`` - gas price provided by the sender in Wei. -- ``gas``: ``QUANTITY`` - gas provided by the sender. -- ``input``: ``DATA`` - the data send along with the transaction. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionByHash","params":["0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"],"id":1}' - - // Result - { - "id":1, - "jsonrpc":"2.0", - "result": { - "hash":"0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b", - "nonce":"0x", - "blockHash": "0xbeab0aa2411b7ab17f30a99d3cb9c6ef2fc5426d6ad6fd9e2a26a6aed1d1055b", - "blockNumber": "0x15df", // 5599 - "transactionIndex": "0x1", // 1 - "from":"0x407d73d8a49eeb85d32cf465507dd71d507100c1", - "to":"0x85h43d8a49eeb85d32cf465507dd71d507100c1", - "value":"0x7f110" // 520464 - "gas": "0x7f110" // 520464 - "gasPrice":"0x09184e72a000", - "input":"0x603880600c6000396000f300603880600c6000396000f3603880600c6000396000f360", - } - } - --------------- - -eth\_getTransactionByBlockHashAndIndex -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Returns information about a transaction by block hash and transaction -index position. - -Parameters -'''''''''' - -1. ``DATA``, 32 Bytes - hash of a block. -2. ``QUANTITY`` - integer of the transaction index position. - -.. code:: js - - params: [ - '0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331', - '0x0' // 0 - ] - -Returns -''''''' - -See `eth\_getBlockByHash <#eth_gettransactionbyhash>`__ - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionByBlockHashAndIndex","params":[0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b, "0x0"],"id":1}' - -Result see `eth\_getTransactionByHash <#eth_gettransactionbyhash>`__ - --------------- - -eth\_getTransactionByBlockNumberAndIndex -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Returns information about a transaction by block number and transaction -index position. - -Parameters -'''''''''' - -1. ``QUANTITY|TAG`` - a block number, or the string ``"earliest"``, - ``"latest"`` or ``"pending"``, as in the `default block - parameter <#the-default-block-parameter>`__. -2. ``QUANTITY`` - the transaction index position. - -.. code:: js - - params: [ - '0x29c', // 668 - '0x0' // 0 - ] - -Returns -''''''' - -See `eth\_getBlockByHash <#eth_gettransactionbyhash>`__ - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionByBlockNumberAndIndex","params":["0x29c", "0x0"],"id":1}' - -Result see `eth\_getTransactionByHash <#eth_gettransactionbyhash>`__ - --------------- - -eth\_getTransactionReceipt -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Returns the receipt of a transaction by transaction hash. - -**Note** That the receipt is not available for pending transactions. - -Parameters -'''''''''' - -1. ``DATA``, 32 Bytes - hash of a transaction - -.. code:: js - - params: [ - '0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238' - ] - -Returns -''''''' - -``Object`` - A transaction receipt object, or ``null`` when no receipt -was found: - -- ``transactionHash``: ``DATA``, 32 Bytes - hash of the transaction. -- ``transactionIndex``: ``QUANTITY`` - integer of the transactions - index position in the block. -- ``blockHash``: ``DATA``, 32 Bytes - hash of the block where this - transaction was in. -- ``blockNumber``: ``QUANTITY`` - block number where this transaction - was in. -- ``cumulativeGasUsed``: ``QUANTITY`` - The total amount of gas used - when this transaction was executed in the block. -- ``gasUsed``: ``QUANTITY`` - The amount of gas used by this specific - transaction alone. -- ``contractAddress``: ``DATA``, 20 Bytes - The contract address - created, if the transaction was a contract creation, otherwise - ``null``. -- ``logs``: ``Array`` - Array of log objects, which this transaction - generated. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"],"id":1}' - - // Result - { - "id":1, - "jsonrpc":"2.0", - "result": { - transactionHash: '0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238', - transactionIndex: '0x1', // 1 - blockNumber: '0xb', // 11 - blockHash: '0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b', - cumulativeGasUsed: '0x33bc', // 13244 - gasUsed: '0x4dc', // 1244 - contractAddress: '0xb60e8dd61c5d32be8058bb8eb970870f07233155' // or null, if none was created - logs: [{ - // logs as returned by getFilterLogs, etc. - }, ...] - } - } - --------------- - -eth\_getUncleByBlockHashAndIndex -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Returns information about a uncle of a block by hash and uncle index -position. - -Parameters -'''''''''' - -1. ``DATA``, 32 Bytes - hash a block. -2. ``QUANTITY`` - the uncle's index position. - -.. code:: js - - params: [ - '0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b', - '0x0' // 0 - ] - -Returns -''''''' - -See `eth\_getBlockByHash <#eth_getblockbyhash>`__ - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getUncleByBlockHashAndIndex","params":["0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b", "0x0"],"id":1}' - -Result see `eth\_getBlockByHash <#eth_getblockbyhash>`__ - -**Note**: An uncle doesn't contain individual transactions. - --------------- - -eth\_getUncleByBlockNumberAndIndex -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Returns information about a uncle of a block by number and uncle index -position. - -Parameters -'''''''''' - -1. ``QUANTITY|TAG`` - a block number, or the string ``"earliest"``, - ``"latest"`` or ``"pending"``, as in the `default block - parameter <#the-default-block-parameter>`__. -2. ``QUANTITY`` - the uncle's index position. - -.. code:: js - - params: [ - '0x29c', // 668 - '0x0' // 0 - ] - -Returns -''''''' - -See `eth\_getBlockByHash <#eth_getblockbyhash>`__ - -**Note**: An uncle doesn't contain individual transactions. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getUncleByBlockNumberAndIndex","params":["0x29c", "0x0"],"id":1}' - -Result see `eth\_getBlockByHash <#eth_getblockbyhash>`__ - --------------- - -eth\_getCompilers -^^^^^^^^^^^^^^^^^ - -Returns a list of available compilers in the client. - -Parameters -'''''''''' - -none - -Returns -''''''' - -``Array`` - Array of available compilers. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getCompilers","params":[],"id":1}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": ["solidity", "lll", "serpent"] - } - --------------- - -eth\_compileSolidity -^^^^^^^^^^^^^^^^^^^^ - -Returns compiled solidity code. - -Parameters -'''''''''' - -1. ``String`` - The source code. - -.. code:: js - - params: [ - "contract test { function multiply(uint a) returns(uint d) { return a * 7; } }", - ] - -Returns -''''''' - -``DATA`` - The compiled source code. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_compileSolidity","params":["contract test { function multiply(uint a) returns(uint d) { return a * 7; } }"],"id":1}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": { - "code": "0x605880600c6000396000f3006000357c010000000000000000000000000000000000000000000000000000000090048063c6888fa114602e57005b603d6004803590602001506047565b8060005260206000f35b60006007820290506053565b91905056", - "info": { - "source": "contract test {\n function multiply(uint a) constant returns(uint d) {\n return a * 7;\n }\n}\n", - "language": "Solidity", - "languageVersion": "0", - "compilerVersion": "0.9.19", - "abiDefinition": [ - { - "constant": true, - "inputs": [ - { - "name": "a", - "type": "uint256" - } - ], - "name": "multiply", - "outputs": [ - { - "name": "d", - "type": "uint256" - } - ], - "type": "function" - } - ], - "userDoc": { - "methods": {} - }, - "developerDoc": { - "methods": {} - } - } - - } - --------------- - -eth\_compileLLL -^^^^^^^^^^^^^^^ - -Returns compiled LLL code. - -Parameters -'''''''''' - -1. ``String`` - The source code. - -.. code:: js - - params: [ - "(returnlll (suicide (caller)))", - ] - -Returns -''''''' - -``DATA`` - The compiled source code. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_compileSolidity","params":["(returnlll (suicide (caller)))"],"id":1}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": "0x603880600c6000396000f3006001600060e060020a600035048063c6888fa114601857005b6021600435602b565b8060005260206000f35b600081600702905091905056" // the compiled source code - } - --------------- - -eth\_compileSerpent -^^^^^^^^^^^^^^^^^^^ - -Returns compiled serpent code. - -Parameters -'''''''''' - -1. ``String`` - The source code. - -.. code:: js - - params: [ - "/* some serpent */", - ] - -Returns -''''''' - -``DATA`` - The compiled source code. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_compileSerpent","params":["/* some serpent */"],"id":1}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": "0x603880600c6000396000f3006001600060e060020a600035048063c6888fa114601857005b6021600435602b565b8060005260206000f35b600081600702905091905056" // the compiled source code - } - --------------- - -eth\_newFilter -^^^^^^^^^^^^^^ - -Creates a filter object, based on filter options, to notify when the -state changes (logs). To check if the state has changed, call -`eth\_getFilterChanges <#eth_getfilterchanges>`__. - -A note on specifying topic filters: -''''''''''''''''''''''''''''''''''' - -Topics are order-dependent. A transaction with a log with topics [A, B] -will be matched by the following topic filters: \* ``[]`` "anything" \* -``[A]`` "A in first position (and anything after)" \* ``[null, B]`` -"anything in first position AND B in second position (and anything -after)" \* ``[A, B]`` "A in first position AND B in second position (and -anything after)" \* ``[[A, B], [A, B]]`` "(A OR B) in first position AND -(A OR B) in second position (and anything after)" - -Parameters -'''''''''' - -1. ``Object`` - The filter options: - -- ``fromBlock``: ``QUANTITY|TAG`` - (optional, default: ``"latest"``) - Integer block number, or ``"latest"`` for the last mined block or - ``"pending"``, ``"earliest"`` for not yet mined transactions. -- ``toBlock``: ``QUANTITY|TAG`` - (optional, default: ``"latest"``) - Integer block number, or ``"latest"`` for the last mined block or - ``"pending"``, ``"earliest"`` for not yet mined transactions. -- ``address``: ``DATA|Array``, 20 Bytes - (optional) Contract address - or a list of addresses from which logs should originate. -- ``topics``: ``Array of DATA``, - (optional) Array of 32 Bytes - ``DATA`` topics. Topics are order-dependent. Each topic can also be - an array of DATA with "or" options. - -.. code:: js - - params: [{ - "fromBlock": "0x1", - "toBlock": "0x2", - "address": "0x8888f1f195afa192cfee860698584c030f4c9db1", - "topics": ["0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b", null, [0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b, 0x000000000000000000000000aff3454fce5edbc8cca8697c15331677e6ebccc]] - }] - -Returns -''''''' - -``QUANTITY`` - A filter id. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newFilter","params":[{"topics":["0x12341234"]}],"id":73}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": "0x1" // 1 - } - --------------- - -eth\_newBlockFilter -^^^^^^^^^^^^^^^^^^^ - -Creates a filter in the node, to notify when a new block arrives. To -check if the state has changed, call -`eth\_getFilterChanges <#eth_getfilterchanges>`__. - -Parameters -'''''''''' - -None - -Returns -''''''' - -``QUANTITY`` - A filter id. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newBlockFilter","params":[],"id":73}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": "0x1" // 1 - } - --------------- - -eth\_newPendingTransactionFilter -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Creates a filter in the node, to notify when new pending transactions -arrive. To check if the state has changed, call -`eth\_getFilterChanges <#eth_getfilterchanges>`__. - -Parameters -'''''''''' - -None - -Returns -''''''' - -``QUANTITY`` - A filter id. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newPendingTransactionFilter","params":[],"id":73}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": "0x1" // 1 - } - --------------- - -eth\_uninstallFilter -^^^^^^^^^^^^^^^^^^^^ - -Uninstalls a filter with given id. Should always be called when watch is -no longer needed. Additonally Filters timeout when they aren't requested -with `eth\_getFilterChanges <#eth_getfilterchanges>`__ for a period of -time. - -Parameters -'''''''''' - -1. ``QUANTITY`` - The filter id. - -.. code:: js - - params: [ - "0xb" // 11 - ] - -Returns -''''''' - -``Boolean`` - ``true`` if the filter was successfully uninstalled, -otherwise ``false``. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_uninstallFilter","params":["0xb"],"id":73}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": true - } - --------------- - -eth\_getFilterChanges -^^^^^^^^^^^^^^^^^^^^^ - -Polling method for a filter, which returns an array of logs which -occurred since last poll. - -Parameters -'''''''''' - -1. ``QUANTITY`` - the filter id. - -.. code:: js - - params: [ - "0x16" // 22 - ] - -Returns -''''''' - -``Array`` - Array of log objects, or an empty array if nothing has -changed since last poll. - -- For filters created with ``eth_newBlockFilter`` the return are block - hashes (``DATA``, 32 Bytes), e.g. ``["0x3454645634534..."]``. -- For filters created with ``eth_newPendingTransactionFilter`` the - return are transaction hashes (``DATA``, 32 Bytes), e.g. - ``["0x6345343454645..."]``. -- For filters created with ``eth_newFilter`` logs are objects with - following params: - -- ``type``: ``TAG`` - ``pending`` when the log is pending. ``mined`` if - log is already mined. -- ``logIndex``: ``QUANTITY`` - integer of the log index position in the - block. ``null`` when its pending log. -- ``transactionIndex``: ``QUANTITY`` - integer of the transactions - index position log was created from. ``null`` when its pending log. -- ``transactionHash``: ``DATA``, 32 Bytes - hash of the transactions - this log was created from. ``null`` when its pending log. -- ``blockHash``: ``DATA``, 32 Bytes - hash of the block where this log - was in. ``null`` when its pending. ``null`` when its pending log. -- ``blockNumber``: ``QUANTITY`` - the block number where this log was - in. ``null`` when its pending. ``null`` when its pending log. -- ``address``: ``DATA``, 20 Bytes - address from which this log - originated. -- ``data``: ``DATA`` - contains one or more 32 Bytes non-indexed - arguments of the log. -- ``topics``: ``Array of DATA`` - Array of 0 to 4 32 Bytes ``DATA`` of - indexed log arguments. (In *solidity*: The first topic is the *hash* - of the signature of the event (e.g. - ``Deposit(address,bytes32,uint256)``), except you declared the event - with the ``anonymous`` specifier.) - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getFilterChanges","params":["0x16"],"id":73}' - - // Result - { - "id":1, - "jsonrpc":"2.0", - "result": [{ - "logIndex": "0x1", // 1 - "blockNumber":"0x1b4" // 436 - "blockHash": "0x8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcfdf829c5a142f1fccd7d", - "transactionHash": "0xdf829c5a142f1fccd7d8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcf", - "transactionIndex": "0x0", // 0 - "address": "0x16c5785ac562ff41e2dcfdf829c5a142f1fccd7d", - "data":"0x0000000000000000000000000000000000000000000000000000000000000000", - "topics": ["0x59ebeb90bc63057b6515673c3ecf9438e5058bca0f92585014eced636878c9a5"] - },{ - ... - }] - } - --------------- - -eth\_getFilterLogs -^^^^^^^^^^^^^^^^^^ - -Returns an array of all logs matching filter with given id. - -Parameters -'''''''''' - -1. ``QUANTITY`` - The filter id. - -.. code:: js - - params: [ - "0x16" // 22 - ] - -Returns -''''''' - -See `eth\_getFilterChanges <#eth_getfilterchanges>`__ - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getFilterLogs","params":["0x16"],"id":74}' - -Result see `eth\_getFilterChanges <#eth_getfilterchanges>`__ - --------------- - -eth\_getLogs -^^^^^^^^^^^^ - -Returns an array of all logs matching a given filter object. - -Parameters -'''''''''' - -1. ``Object`` - the filter object, see `eth\_newFilter - parameters <#eth_newfilter>`__. - -.. code:: js - - params: [{ - "topics": ["0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b"] - }] - -Returns -''''''' - -See `eth\_getFilterChanges <#eth_getfilterchanges>`__ - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"topics":["0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b"]}],"id":74}' - -Result see `eth\_getFilterChanges <#eth_getfilterchanges>`__ - --------------- - -eth\_getWork -^^^^^^^^^^^^ - -Returns the hash of the current block, the seedHash, and the boundary -condition to be met ("target"). - -Parameters -'''''''''' - -none - -Returns -''''''' - -``Array`` - Array with the following properties: 1. ``DATA``, 32 Bytes - -current block header pow-hash 2. ``DATA``, 32 Bytes - the seed hash used -for the DAG. 3. ``DATA``, 32 Bytes - the boundary condition ("target"), -2^256 / difficulty. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getWork","params":[],"id":73}' - - // Result - { - "id":1, - "jsonrpc":"2.0", - "result": [ - "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", - "0x5EED00000000000000000000000000005EED0000000000000000000000000000", - "0xd1ff1c01710000000000000000000000d1ff1c01710000000000000000000000" - ] - } - --------------- - -eth\_submitWork -^^^^^^^^^^^^^^^ - -Used for submitting a proof-of-work solution. - -Parameters -'''''''''' - -1. ``DATA``, 8 Bytes - The nonce found (64 bits) -2. ``DATA``, 32 Bytes - The header's pow-hash (256 bits) -3. ``DATA``, 32 Bytes - The mix digest (256 bits) - -.. code:: js - - params: [ - "0x0000000000000001", - "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", - "0xD1FE5700000000000000000000000000D1FE5700000000000000000000000000" - ] - -Returns -''''''' - -``Boolean`` - returns ``true`` if the provided solution is valid, -otherwise ``false``. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0", "method":"eth_submitWork", "params":["0x0000000000000001", "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "0xD1GE5700000000000000000000000000D1GE5700000000000000000000000000"],"id":73}' - - // Result - { - "id":1, - "jsonrpc":"2.0", - "result": true - } - --------------- - -eth\_submitHashrate -^^^^^^^^^^^^^^^^^^^ - -Used for submitting mining hashrate. - -Parameters -'''''''''' - -1. ``Hashrate``, a hexadecimal string representation (32 bytes) of the - hash rate -2. ``ID``, String - A random hexadecimal(32 bytes) ID identifying the - client - -.. code:: js - - params: [ - "0x0000000000000000000000000000000000000000000000000000000000500000", - "0x59daa26581d0acd1fce254fb7e85952f4c09d0915afd33d3886cd914bc7d283c" - ] - -Returns -''''''' - -``Boolean`` - returns ``true`` if submitting went through succesfully -and ``false`` otherwise. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0", "method":"eth_submitHashrate", "params":["0x0000000000000000000000000000000000000000000000000000000000500000", "0x59daa26581d0acd1fce254fb7e85952f4c09d0915afd33d3886cd914bc7d283c"],"id":73}' - - // Result - { - "id":73, - "jsonrpc":"2.0", - "result": true - } - --------------- - -db\_putString -^^^^^^^^^^^^^ - -Stores a string in the local database. - -**Note** this function is deprecated and will be removed in the future. - -Parameters -'''''''''' - -1. ``String`` - Database name. -2. ``String`` - Key name. -3. ``String`` - String to store. - -.. code:: js - - params: [ - "testDB", - "myKey", - "myString" - ] - -Returns -''''''' - -``Boolean`` - returns ``true`` if the value was stored, otherwise -``false``. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"db_putString","params":["testDB","myKey","myString"],"id":73}' - - // Result - { - "id":1, - "jsonrpc":"2.0", - "result": true - } - --------------- - -db\_getString -^^^^^^^^^^^^^ - -Returns string from the local database. - -**Note** this function is deprecated and will be removed in the future. - -Parameters -'''''''''' - -1. ``String`` - Database name. -2. ``String`` - Key name. - -.. code:: js - - params: [ - "testDB", - "myKey", - ] - -Returns -''''''' - -``String`` - The previously stored string. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"db_getString","params":["testDB","myKey"],"id":73}' - - // Result - { - "id":1, - "jsonrpc":"2.0", - "result": "myString" - } - --------------- - -db\_putHex -^^^^^^^^^^ - -Stores binary data in the local database. - -**Note** this function is deprecated and will be removed in the future. - -Parameters -'''''''''' - -1. ``String`` - Database name. -2. ``String`` - Key name. -3. ``DATA`` - The data to store. - -.. code:: js - - params: [ - "testDB", - "myKey", - "0x68656c6c6f20776f726c64" - ] - -Returns -''''''' - -``Boolean`` - returns ``true`` if the value was stored, otherwise -``false``. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"db_putHex","params":["testDB","myKey","0x68656c6c6f20776f726c64"],"id":73}' - - // Result - { - "id":1, - "jsonrpc":"2.0", - "result": true - } - --------------- - -db\_getHex -^^^^^^^^^^ - -Returns binary data from the local database. - -**Note** this function is deprecated and will be removed in the future. - -Parameters -'''''''''' - -1. ``String`` - Database name. -2. ``String`` - Key name. - -.. code:: js - - params: [ - "testDB", - "myKey", - ] - -Returns -''''''' - -``DATA`` - The previously stored data. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"db_getHex","params":["testDB","myKey"],"id":73}' - - // Result - { - "id":1, - "jsonrpc":"2.0", - "result": "0x68656c6c6f20776f726c64" - } - --------------- - -shh\_version -^^^^^^^^^^^^ - -Returns the current whisper protocol version. - -Parameters -'''''''''' - -none - -Returns -''''''' - -``String`` - The current whisper protocol version - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"shh_version","params":[],"id":67}' - - // Result - { - "id":67, - "jsonrpc": "2.0", - "result": "2" - } - --------------- - -shh\_post -^^^^^^^^^ - -Sends a whisper message. - -Parameters -'''''''''' - -1. ``Object`` - The whisper post object: - -- ``from``: ``DATA``, 60 Bytes - (optional) The identity of the sender. -- ``to``: ``DATA``, 60 Bytes - (optional) The identity of the receiver. - When present whisper will encrypt the message so that only the - receiver can decrypt it. -- ``topics``: ``Array of DATA`` - Array of ``DATA`` topics, for the - receiver to identify messages. -- ``payload``: ``DATA`` - The payload of the message. -- ``priority``: ``QUANTITY`` - The integer of the priority in a rang - from ... (?). -- ``ttl``: ``QUANTITY`` - integer of the time to live in seconds. - -.. code:: js - - params: [{ - from: "0x04f96a5e25610293e42a73908e93ccc8c4d4dc0edcfa9fa872f50cb214e08ebf61a03e245533f97284d442460f2998cd41858798ddfd4d661997d3940272b717b1", - to: "0x3e245533f97284d442460f2998cd41858798ddf04f96a5e25610293e42a73908e93ccc8c4d4dc0edcfa9fa872f50cb214e08ebf61a0d4d661997d3940272b717b1", - topics: ["0x776869737065722d636861742d636c69656e74", "0x4d5a695276454c39425154466b61693532"], - payload: "0x7b2274797065223a226d6", - priority: "0x64", - ttl: "0x64", - }] - -Returns -''''''' - -``Boolean`` - returns ``true`` if the message was send, otherwise -``false``. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"shh_post","params":[{"from":"0xc931d93e97ab07fe42d923478ba2465f2..","topics": ["0x68656c6c6f20776f726c64"],"payload":"0x68656c6c6f20776f726c64","ttl":0x64,"priority":0x64}],"id":73}' - - // Result - { - "id":1, - "jsonrpc":"2.0", - "result": true - } - --------------- - -shh\_newIdentity -^^^^^^^^^^^^^^^^ - -Creates new whisper identity in the client. - -Parameters -'''''''''' - -none - -Returns -''''''' - -``DATA``, 60 Bytes - the address of the new identiy. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"shh_newIdentity","params":[],"id":73}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": "0xc931d93e97ab07fe42d923478ba2465f283f440fd6cabea4dd7a2c807108f651b7135d1d6ca9007d5b68aa497e4619ac10aa3b27726e1863c1fd9b570d99bbaf" - } - --------------- - -shh\_hasIdentity -^^^^^^^^^^^^^^^^ - -Checks if the client hold the private keys for a given identity. - -Parameters -'''''''''' - -1. ``DATA``, 60 Bytes - The identity address to check. - -.. code:: js - - params: [ - "0x04f96a5e25610293e42a73908e93ccc8c4d4dc0edcfa9fa872f50cb214e08ebf61a03e245533f97284d442460f2998cd41858798ddfd4d661997d3940272b717b1" - ] - -Returns -''''''' - -``Boolean`` - returns ``true`` if the client holds the privatekey for -that identity, otherwise ``false``. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"shh_hasIdentity","params":["0x04f96a5e25610293e42a73908e93ccc8c4d4dc0edcfa9fa872f50cb214e08ebf61a03e245533f97284d442460f2998cd41858798ddfd4d661997d3940272b717b1"],"id":73}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": true - } - --------------- - -shh\_newGroup -^^^^^^^^^^^^^ - -(?) - -Parameters -'''''''''' - -none - -Returns -''''''' - -``DATA``, 60 Bytes - the address of the new group. (?) - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"shh_newIdentity","params":[],"id":73}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": "0xc65f283f440fd6cabea4dd7a2c807108f651b7135d1d6ca90931d93e97ab07fe42d923478ba2407d5b68aa497e4619ac10aa3b27726e1863c1fd9b570d99bbaf" - } - --------------- - -shh\_addToGroup -^^^^^^^^^^^^^^^ - -(?) - -Parameters -'''''''''' - -1. ``DATA``, 60 Bytes - The identity address to add to a group (?). - -.. code:: js - - params: [ - "0x04f96a5e25610293e42a73908e93ccc8c4d4dc0edcfa9fa872f50cb214e08ebf61a03e245533f97284d442460f2998cd41858798ddfd4d661997d3940272b717b1" - ] - -Returns -''''''' - -``Boolean`` - returns ``true`` if the identity was successfully added to -the group, otherwise ``false`` (?). - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"shh_hasIdentity","params":["0x04f96a5e25610293e42a73908e93ccc8c4d4dc0edcfa9fa872f50cb214e08ebf61a03e245533f97284d442460f2998cd41858798ddfd4d661997d3940272b717b1"],"id":73}' - - // Result - { - "id":1, - "jsonrpc": "2.0", - "result": true - } - --------------- - -shh\_newFilter -^^^^^^^^^^^^^^ - -Creates filter to notify, when client receives whisper message matching -the filter options. - -Parameters -'''''''''' - -1. ``Object`` - The filter options: - -- ``to``: ``DATA``, 60 Bytes - (optional) Identity of the receiver. - *When present it will try to decrypt any incoming message if the - client holds the private key to this identity.* -- ``topics``: ``Array of DATA`` - Array of ``DATA`` topics which the - incoming message's topics should match. You can use the following - combinations: - - - ``[A, B] = A && B`` - - ``[A, [B, C]] = A && (B || C)`` - - ``[null, A, B] = ANYTHING && A && B`` ``null`` works as a wildcard - -.. code:: js - - params: [{ - "topics": ['0x12341234bf4b564f'], - "to": "0x04f96a5e25610293e42a73908e93ccc8c4d4dc0edcfa9fa872f50cb214e08ebf61a03e245533f97284d442460f2998cd41858798ddfd4d661997d3940272b717b1" - }] - -Returns -''''''' - -``QUANTITY`` - The newly created filter. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"shh_newFilter","params":[{"topics": ['0x12341234bf4b564f'],"to": "0x2341234bf4b2341234bf4b564f..."}],"id":73}' - - // Result - { - "id":1, - "jsonrpc":"2.0", - "result": "0x7" // 7 - } - --------------- - -shh\_uninstallFilter -^^^^^^^^^^^^^^^^^^^^ - -Uninstalls a filter with given id. Should always be called when watch is -no longer needed. Additonally Filters timeout when they aren't requested -with `shh\_getFilterChanges <#shh_getfilterchanges>`__ for a period of -time. - -Parameters -'''''''''' - -1. ``QUANTITY`` - The filter id. - -.. code:: js - - params: [ - "0x7" // 7 - ] - -Returns -''''''' - -``Boolean`` - ``true`` if the filter was successfully uninstalled, -otherwise ``false``. - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"shh_uninstallFilter","params":["0x7"],"id":73}' - - // Result - { - "id":1, - "jsonrpc":"2.0", - "result": true - } - --------------- - -shh\_getFilterChanges -^^^^^^^^^^^^^^^^^^^^^ - -Polling method for whisper filters. Returns new messages since the last -call of this method. - -**Note** calling the `shh\_getMessages <#shh_getmessages>`__ method, -will reset the buffer for this method, so that you won't receive -duplicate messages. - -Parameters -'''''''''' - -1. ``QUANTITY`` - The filter id. - -.. code:: js - - params: [ - "0x7" // 7 - ] - -Returns -''''''' - -``Array`` - Array of messages received since last poll: - -- ``hash``: ``DATA``, 32 Bytes (?) - The hash of the message. -- ``from``: ``DATA``, 60 Bytes - The sender of the message, if a sender - was specified. -- ``to``: ``DATA``, 60 Bytes - The receiver of the message, if a - receiver was specified. -- ``expiry``: ``QUANTITY`` - Integer of the time in seconds when this - message should expire (?). -- ``ttl``: ``QUANTITY`` - Integer of the time the message should float - in the system in seconds (?). -- ``sent``: ``QUANTITY`` - Integer of the unix timestamp when the - message was sent. -- ``topics``: ``Array of DATA`` - Array of ``DATA`` topics the message - contained. -- ``payload``: ``DATA`` - The payload of the message. -- ``workProved``: ``QUANTITY`` - Integer of the work this message - required before it was send (?). - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"shh_getFilterChanges","params":["0x7"],"id":73}' - - // Result - { - "id":1, - "jsonrpc":"2.0", - "result": [{ - "hash": "0x33eb2da77bf3527e28f8bf493650b1879b08c4f2a362beae4ba2f71bafcd91f9", - "from": "0x3ec052fc33..", - "to": "0x87gdf76g8d7fgdfg...", - "expiry": "0x54caa50a", // 1422566666 - "sent": "0x54ca9ea2", // 1422565026 - "ttl": "0x64" // 100 - "topics": ["0x6578616d"], - "payload": "0x7b2274797065223a226d657373616765222c2263686...", - "workProved": "0x0" - }] - } - --------------- - -shh\_getMessages -^^^^^^^^^^^^^^^^ - -Get all messages matching a filter. Unlike ``shh_getFilterChanges`` this -returns all messages. - -Parameters -'''''''''' - -1. ``QUANTITY`` - The filter id. - -.. code:: js - - params: [ - "0x7" // 7 - ] - -Returns -''''''' - -See `shh\_getFilterChanges <#shh_getfilterchanges>`__ - -Example -''''''' - -.. code:: js - - // Request - curl -X POST --data '{"jsonrpc":"2.0","method":"shh_getMessages","params":["0x7"],"id":73}' - -Result see `shh\_getFilterChanges <#shh_getfilterchanges>`__ diff --git a/old-docs-for-reference/main-wiki.rst/JavaScript-API.rst b/old-docs-for-reference/main-wiki.rst/JavaScript-API.rst deleted file mode 100644 index b115251..0000000 --- a/old-docs-for-reference/main-wiki.rst/JavaScript-API.rst +++ /dev/null @@ -1,3037 +0,0 @@ -Web3 JavaScript Ðapp API -======================== - -To make your Ðapp work on Ethereum, you can use the ``web3`` object -provided by the `web3.js -library `__. Under the hood it -communicates to a local node through `RPC -calls `__. web3.js works -with any Ethereum node, which exposes an RPC layer. - -``web3`` contains the ``eth`` object - ``web3.eth`` (for specifically -Ethereum blockchain interactions) and the ``shh`` object - ``web3.shh`` -(for Whisper interaction). Over time we'll introduce other objects for -each of the other web3 protocols. Working `examples can be found -here `__. - -If you want to look at some more sophisticated examples using web3.js -check out these `useful Ðapp -patterns `__. - -Getting Started ---------------- - -- `Adding web3 <#adding-web3>`__ -- `Using Callbacks <#using-callbacks>`__ -- `Batch requests <#batch-requests>`__ -- `A note on big numbers in - web3.js <#a-note-on-big-numbers-in-web3js>`__ -- `-> API Reference <#web3js-api-reference>`__ - -Adding web3 -~~~~~~~~~~~ - -First you need to get web3.js into your project. This can be done using -the following methods: - -- npm: ``$ npm install web3`` -- bower: ``$ bower install web3`` -- meteor: ``$meteor add ethereum:web3`` -- vanilla: link the ``dist./web3.min.js`` - -The you need to create a web3 instance, setting a provider. To make sure -you don't overwrite the already set provider when in mist, check first -if the web3 is available: - -.. code:: js - - if(typeof web3 !== 'undefined') - web3 = new Web3(web3.currentProvider); - else - // set the provider you want from Web3.providers - web3 = new Web3(new Web3.providers.HttpProvider("http://localhost:8545")); - -After that you can use the `API `__ of the -``web3`` object. - -Using callbacks -~~~~~~~~~~~~~~~ - -As this API is designed to work with a local RPC node, all its functions -use synchronous HTTP requests by default. - -If you want to make an asynchronous request, you can pass an optional -callback as the last parameter to most functions. All callbacks are -using an `error first -callback `__ -style: - -.. code:: js - - web3.eth.getBlock(48, function(error, result){ - if(!error) - console.log(result) - else - console.error(error); - }) - -Batch requests -~~~~~~~~~~~~~~ - -Batch requests allow queuing up requests and processing them at once. - -**Note** Batch requests are not faster! In fact making many requests at -once will in some cases be faster, as requests are processed -asynchronous. Batch requests are mainly useful to ensure the serial -processing of requests. - -.. code:: js - - var batch = web3.createBatch(); - batch.add(web3.eth.getBalance.request('0x0000000000000000000000000000000000000000', 'latest', callback)); - batch.add(web3.eth.contract(abi).at(address).balance.request(address, callback2)); - batch.execute(); - -A note on big numbers in web3.js -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You will always get a BigNumber object for number values as JavaScript -is not able to handle big numbers correctly. Look at the following -examples: - -.. code:: js - - "101010100324325345346456456456456456456" - // "101010100324325345346456456456456456456" - 101010100324325345346456456456456456456 - // 1.0101010032432535e+38 - -web3.js depends on the `BigNumber -Library `__ and adds it -automatically. - -.. code:: js - - var balance = new BigNumber('131242344353464564564574574567456'); - // or var balance = web3.eth.getBalance(someAddress); - - balance.plus(21).toString(10); // toString(10) converts it to a number string - // "131242344353464564564574574567477" - -The next example wouldn't work as we have more than 20 floating points, -therefore it is recommended to keep you balance always in *wei* and only -transform it to other units when presenting to the user: - -.. code:: js - - var balance = new BigNumber('13124.234435346456466666457455567456'); - - balance.plus(21).toString(10); // toString(10) converts it to a number string, but can only show max 20 floating points - // "13145.23443534645646666646" // you number would be cut after the 20 floating point - -Web3.js API Reference ---------------------- - -- `web3 <#web3>`__ -- `version <#web3versionapi>`__ - - - `api <#web3versionapi>`__ - - `node <#web3versionnode>`__ - - `network <#web3versionnetwork>`__ - - `ethereum <#web3versionethereum>`__ - - `whisper <#web3versionwhisper>`__ - -- `isConnected() <#web3isconnected>`__ -- `setProvider(provider) <#web3setprovider>`__ -- `currentProvider <#web3currentprovider>`__ -- `reset() <#web3reset>`__ -- `sha3(string, options) <#web3sha3>`__ -- `toHex(stringOrNumber) <#web3tohex>`__ -- `toAscii(hexString) <#web3toascii>`__ -- `fromAscii(textString, [padding]) <#web3fromascii>`__ -- `toDecimal(hexString) <#web3todecimal>`__ -- `fromDecimal(number) <#web3fromdecimal>`__ -- `fromWei(numberStringOrBigNumber, unit) <#web3fromwei>`__ -- `toWei(numberStringOrBigNumber, unit) <#web3towei>`__ -- `toBigNumber(numberOrHexString) <#web3tobignumber>`__ -- `isAddress(hexString) <#web3isAddress>`__ -- `net <#web3net>`__ - - - `listening/getListening <#web3netlistening>`__ - - `peerCount/getPeerCount <#web3ethpeercount>`__ - -- `eth <#web3eth>`__ - - - `defaultAccount <#web3ethdefaultaccount>`__ - - `defaultBlock <#web3ethdefaultblock>`__ - - `syncing/getSyncing <#web3ethsyncing>`__ - - `isSyncing <#web3ethissyncing>`__ - - `coinbase/getCoinbase <#web3ethcoinbase>`__ - - `hashrate/getHashrate <#web3ethhashrate>`__ - - `gasPrice/getGasPrice <#web3ethgasprice>`__ - - `accounts/getAccounts <#web3ethaccounts>`__ - - `mining/getMining <#web3ethmining>`__ - - `blockNumber/getBlockNumber <#web3ethblocknumber>`__ - - `register(hexString) <#web3ethregister>`__ (Not implemented yet) - - `unRegister(hexString) <#web3ethunregister>`__ (Not implemented - yet) - - `getBalance(address) <#web3ethgetbalance>`__ - - `getStorageAt(address, position) <#web3ethgetstorageat>`__ - - `getCode(address) <#web3ethgetcode>`__ - - `getBlock(hash/number) <#web3ethgetblock>`__ - - `getBlockTransactionCount(hash/number) <#web3ethgetblocktransactioncount>`__ - - `getUncle(hash/number) <#web3ethgetuncle>`__ - - `getBlockUncleCount(hash/number) <#web3ethgetblockunclecount>`__ - - `getTransaction(hash) <#web3ethgettransaction>`__ - - `getTransactionFromBlock(hashOrNumber, - indexNumber) <#web3ethgettransactionfromblock>`__ - - `getTransactionReceipt(hash) <#web3ethgettransactionreceipt>`__ - - `getTransactionCount(address) <#web3ethgettransactioncount>`__ - - `sendTransaction(object) <#web3ethsendtransaction>`__ - - `call(object) <#web3ethcall>`__ - - `estimateGas(object) <#web3ethestimategas>`__ - - `filter(array (, options) ) <#web3ethfilter>`__ - - - `watch(callback) <#web3ethfilter>`__ - - `stopWatching(callback) <#web3ethfilter>`__ - - `get() <#web3ethfilter>`__ - - - `contract(abiArray) <#web3ethcontract>`__ - - `contract.myMethod() <#contract-methods>`__ - - `contract.myEvent() <#contract-events>`__ - - `contract.allEvents() <#contract-allevents>`__ - - `getCompilers() <#web3ethgetcompilers>`__ - - `compile.lll(string) <#web3ethcompilelll>`__ - - `compile.solidity(string) <#web3ethcompilesolidity>`__ - - `compile.serpent(string) <#web3ethcompileserpent>`__ - - `namereg <#web3ethnamereg>`__ - - `sendIBANTransaction <#web3ethsendibantransaction>`__ - - `iban <#web3ethiban>`__ - - `fromAddress <#web3ethibanfromaddress>`__ - - `fromBban <#web3ethibanfrombban>`__ - - `createIndirect <#web3ethibancreateindirect>`__ - - `isValid <#web3ethibanisvalid>`__ - - `isDirect <#web3ethibanisdirect>`__ - - `isIndirect <#web3ethibanisindirect>`__ - - `checksum <#web3ethibanchecksum>`__ - - `institution <#web3ethibaninstitution>`__ - - `client <#web3ethibanclient>`__ - - `address <#web3ethibanaddress>`__ - - `toString <#web3ethibantostring>`__ - -- `db <#web3db>`__ - - - `putString(name, key, value) <#web3dbputstring>`__ - - `getString(name, key) <#web3dbgetstring>`__ - - `putHex(name, key, value) <#web3dbputhex>`__ - - `getHex(name, key) <#web3dbgethex>`__ - -- `shh <#web3shh>`__ - - - `post(postObject) <#web3shhpost>`__ - - `newIdentity() <#web3shhnewidentity>`__ - - `hasIdentity(hexString) <#web3shhhaveidentity>`__ - - `newGroup(\_id, \_who) <#web3shhnewgroup>`__ - - `addToGroup(\_id, \_who) <#web3shhaddtogroup>`__ - - `filter(object/string) <#web3shhfilter>`__ - - `watch(callback) <#web3shhfilter>`__ - - `stopWatching(callback) <#web3shhfilter>`__ - - `get(callback) <#web3shhfilter>`__ - -Usage -~~~~~ - -web3 -^^^^ - -The ``web3`` object provides all methods. - -Example -''''''' - -.. code:: js - - var Web3 = require('web3'); - // create an instance of web3 using the HTTP provider. - // NOTE in mist web3 is already available, so check first if its available before instantiating - var web3 = new Web3(new Web3.providers.HttpProvider("http://localhost:8545")); - --------------- - -web3.version.api -^^^^^^^^^^^^^^^^ - -.. code:: js - - web3.version.api - -Returns -''''''' - -``String`` - The Ethereum JS API version. - -Example -''''''' - -.. code:: js - - var version = web3.version.api; - console.log(version); // "0.2.0" - --------------- - -web3.version.node -^^^^^^^^^^^^^^^^^ - -:: - - web3.version.node - // or async - web3.version.getClient(callback(error, result){ ... }) - -Returns -''''''' - -``String`` - The client/node version. - -Example -''''''' - -.. code:: js - - var version = web3.version.node; - console.log(version); // "Mist/v0.9.3/darwin/go1.4.1" - --------------- - -web3.version.network -^^^^^^^^^^^^^^^^^^^^ - -:: - - web3.version.network - // or async - web3.version.getNetwork(callback(error, result){ ... }) - -Returns -''''''' - -``String`` - The network protocol version. - -Example -''''''' - -.. code:: js - - var version = web3.version.network; - console.log(version); // 54 - --------------- - -web3.version.ethereum -^^^^^^^^^^^^^^^^^^^^^ - -:: - - web3.version.ethereum - // or async - web3.version.getEthereum(callback(error, result){ ... }) - -Returns -''''''' - -``String`` - The Ethereum protocol version. - -Example -''''''' - -.. code:: js - - var version = web3.version.ethereum; - console.log(version); // 60 - --------------- - -web3.version.whisper -^^^^^^^^^^^^^^^^^^^^ - -:: - - web3.version.whisper - // or async - web3.version.getWhisper(callback(error, result){ ... }) - -Returns -''''''' - -``String`` - The whisper protocol version. - -Example -''''''' - -.. code:: js - - var version = web3.version.whisper; - console.log(version); // 20 - --------------- - -web3.isConnected -^^^^^^^^^^^^^^^^ - -:: - - web3.isConnected() - -Should be called to check if a connection to a node exists - -Parameters -'''''''''' - -none - -Returns -''''''' - -``Boolean`` - -Example -''''''' - -.. code:: js - - if(!web3.isConnected()) { - - // show some dialog to ask the user to start a node - - } else { - - // start web3 filters, calls, etc - - } - --------------- - -web3.setProvider -^^^^^^^^^^^^^^^^ - -:: - - web3.setProvider(provider) - -Should be called to set provider. - -Parameters -'''''''''' - -none - -Returns -''''''' - -``undefined`` - -Example -''''''' - -.. code:: js - - web3.setProvider(new web3.providers.HttpProvider('http://localhost:8545')); // 8080 for cpp/AZ, 8545 for go/mist - --------------- - -web3.currentProvider -^^^^^^^^^^^^^^^^^^^^ - -:: - - web3.currentProvider - -Will contain the current provider, if one is set. This can be used to -check if mist etc. set already a provider. - -Returns -''''''' - -``Object`` - The provider set or ``null``; - -Example -''''''' - -.. code:: js - - // Check if mist etc. already set a provider - if(!web3.currentProvider) - web3.setProvider(new web3.providers.HttpProvider("http://localhost:8545")); - --------------- - -web3.reset -^^^^^^^^^^ - -:: - - web3.reset(keepIsSyncing) - -Should be called to reset state of web3. Resets everything except -manager. Uninstalls all filters. Stops polling. - -Parameters -'''''''''' - -1. ``Boolean`` - If ``true`` it will uninstall all filters, but will - keep the `web3.eth.isSyncing() <#web3ethissyncing>`__ polls - -Returns -''''''' - -``undefined`` - -Example -''''''' - -.. code:: js - - web3.reset(); - --------------- - -web3.sha3 -^^^^^^^^^ - -:: - - web3.sha3(string, options) - -Parameters -'''''''''' - -1. ``String`` - The string to hash using the Keccak-256 SHA3 algorithm -2. ``Object`` - Set ``encoding`` to ``hex`` if the string to hash is - encoded in hex. A leading ``0x`` will be automatically ignored. - -Returns -''''''' - -``String`` - The Keccak-256 SHA3 of the given data. - -Example -''''''' - -.. code:: js - - var hash = web3.sha3("Some ASCII string to be hashed"); - console.log(hash); // "b21dbc7a5eb6042d91f8f584af266f1a512ac89520f43562c6c1e37eab6eb0c4" - - var hashOfHash = web3.sha3(hash, {encoding: 'hex'}); - console.log(hashOfHash); // "951b5476a2c80d7ee31877385456aa8a3351cd0e9a80b24ee16372705e3dec86" - --------------- - -web3.toHex -^^^^^^^^^^ - -:: - - web3.toHex(mixed); - -Converts any value into HEX. - -Parameters -'''''''''' - -1. ``String|Number|Object|Array|BigNumber`` - The value to parse to HEX. - If its an object or array it will be ``JSON.stringify`` first. If its - a BigNumber it will make it the HEX value of a number. - -Returns -''''''' - -``String`` - The hex string of ``mixed``. - -Example -''''''' - -.. code:: js - - var str = web3.toHex({test: 'test'}); - console.log(str); // '0x7b2274657374223a2274657374227d' - --------------- - -web3.toAscii -^^^^^^^^^^^^ - -:: - - web3.toAscii(hexString); - -Converts a HEX string into a ASCII string. - -Parameters -'''''''''' - -1. ``String`` - A HEX string to be converted to ascii. - -Returns -''''''' - -``String`` - An ASCII string made from the given ``hexString``. - -Example -''''''' - -.. code:: js - - var str = web3.toAscii("0x657468657265756d000000000000000000000000000000000000000000000000"); - console.log(str); // "ethereum" - --------------- - -web3.fromAscii -^^^^^^^^^^^^^^ - -:: - - web3.fromAscii(string [, padding]); - -Converts any ASCII string to a HEX string. - -Parameters -'''''''''' - -1. ``String`` - An ASCII string to be converted to HEX. -2. ``Number`` - The number of bytes the returned HEX string should have. - -Returns -''''''' - -``String`` - The converted HEX string. - -Example -''''''' - -.. code:: js - - var str = web3.fromAscii('ethereum'); - console.log(str); // "0x657468657265756d" - - var str2 = web3.fromAscii('ethereum', 32); - console.log(str2); // "0x657468657265756d000000000000000000000000000000000000000000000000" - --------------- - -web3.toDecimal -^^^^^^^^^^^^^^ - -:: - - web3.toDecimal(hexString); - -Converts a HEX string to its number representation. - -Parameters -'''''''''' - -1. ``String`` - An HEX string to be converted to a number. - -Returns -''''''' - -``Number`` - The number representing the data ``hexString``. - -Example -''''''' - -.. code:: js - - var number = web3.toDecimal('0x15'); - console.log(number); // 21 - --------------- - -web3.fromDecimal -^^^^^^^^^^^^^^^^ - -:: - - web3.fromDecimal(number); - -Converts a number or number string to its HEX representation. - -Parameters -'''''''''' - -1. ``Number|String`` - A number to be converted to a HEX string. - -Returns -''''''' - -``String`` - The HEX string representing of the given ``number``. - -Example -''''''' - -.. code:: js - - var value = web3.fromDecimal('21'); - console.log(value); // "0x15" - --------------- - -web3.fromWei -^^^^^^^^^^^^ - -:: - - web3.fromWei(number, unit) - -Converts a number of wei into the following Ethereum units: - -- ``kwei``/``ada`` -- ``mwei``/``babbage`` -- ``gwei``/``shannon`` -- ``szabo`` -- ``finney`` -- ``ether`` -- ``kether``/``grand``/``einstein`` -- ``mether`` -- ``gether`` -- ``tether`` - -Parameters -'''''''''' - -1. ``Number|String|BigNumber`` - A number or BigNumber instance. -2. ``String`` - One of the above ether units. - -Returns -''''''' - -``String|BigNumber`` - Either a number string, or a BigNumber instance, -depending on the given ``number`` parameter. - -Example -''''''' - -.. code:: js - - var value = web3.fromWei('21000000000000', 'finney'); - console.log(value); // "0.021" - --------------- - -web3.toWei -^^^^^^^^^^ - -:: - - web3.toWei(number, unit) - -Converts an Ethereum unit into wei. Possible units are: - -- ``kwei``/``ada`` -- ``mwei``/``babbage`` -- ``gwei``/``shannon`` -- ``szabo`` -- ``finney`` -- ``ether`` -- ``kether``/``grand``/``einstein`` -- ``mether`` -- ``gether`` -- ``tether`` - -Parameters -'''''''''' - -1. ``Number|String|BigNumber`` - A number or BigNumber instance. -2. ``String`` - One of the above ether units. - -Returns -''''''' - -``String|BigNumber`` - Either a number string, or a BigNumber instance, -depending on the given ``number`` parameter. - -Example -''''''' - -.. code:: js - - var value = web3.toWei('1', 'ether'); - console.log(value); // "1000000000000000000" - --------------- - -web3.toBigNumber -^^^^^^^^^^^^^^^^ - -:: - - web3.toBigNumber(numberOrHexString); - -Converts a given number into a BigNumber instance. - -See the `note on BigNumber <#a-note-on-big-numbers-in-javascript>`__. - -Parameters -'''''''''' - -1. ``Number|String`` - A number, number string or HEX string of a - number. - -Returns -''''''' - -``BigNumber`` - A BigNumber instance representing the given value. - -Example -''''''' - -.. code:: js - - var value = web3.toBigNumber('200000000000000000000001'); - console.log(value); // instanceOf BigNumber - console.log(value.toNumber()); // 2.0000000000000002e+23 - console.log(value.toString(10)); // '200000000000000000000001' - --------------- - -web3.net -~~~~~~~~ - -web3.net.listening -^^^^^^^^^^^^^^^^^^ - -:: - - web3.net.listening - // or async - web3.net.getListening(callback(error, result){ ... }) - -This property is read only and says whether the node is actively -listening for network connections or not. - -Returns -''''''' - -``Boolean`` - ``true`` if the client is actively listening for network -connections, otherwise ``false``. - -Example -''''''' - -.. code:: js - - var listening = web3.net.listening; - console.log(listening); // true of false - --------------- - -web3.net.peerCount -^^^^^^^^^^^^^^^^^^ - -:: - - web3.net.peerCount - // or async - web3.net.getPeerCount(callback(error, result){ ... }) - -This property is read only and returns the number of connected peers. - -Returns -''''''' - -``Number`` - The number of peers currently connected to the client. - -Example -''''''' - -.. code:: js - - var peerCount = web3.net.peerCount; - console.log(peerCount); // 4 - --------------- - -web3.eth -~~~~~~~~ - -Contains the Ethereum blockchain related methods. - -Example -''''''' - -.. code:: js - - var eth = web3.eth; - --------------- - -web3.eth.defaultAccount -^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.defaultAccount - -This default address is used for the following methods (optionally you -can overwrite it by specifying the ``from`` property): - -- `web3.eth.sendTransaction() <#web3ethsendtransaction>`__ -- `web3.eth.call() <#web3ethcall>`__ - -Values -'''''' - -``String``, 20 Bytes - Any address you own, or where you have the -private key for. - -*Default is* ``undefined``. - -Returns -''''''' - -``String``, 20 Bytes - The currently set default address. - -Example -''''''' - -.. code:: js - - var defaultAccount = web3.eth.defaultAccount; - console.log(defaultAccount); // '' - - // set the default block - web3.eth.defaultAccount = '0x8888f1f195afa192cfee860698584c030f4c9db1'; - --------------- - -web3.eth.defaultBlock -^^^^^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.defaultBlock - -This default block is used for the following methods (optionally you can -override it by passing the defaultBlock parameter): - -- `web3.eth.getBalance() <#web3ethgetbalance>`__ -- `web3.eth.getCode() <#web3ethgetcode>`__ -- `web3.eth.getTransactionCount() <#web3ethgettransactioncount>`__ -- `web3.eth.getStorageAt() <#web3ethgetstorageat>`__ -- `web3.eth.call() <#web3ethcall>`__ -- `web3.eth.estimateGas() <#web3ethestimategas>`__ - -Values -'''''' - -Default block parameters can be one of the following: - -- ``Number`` - a block number -- ``String`` - ``"earliest"``, the genisis block -- ``String`` - ``"latest"``, the latest block (current head of the - blockchain) -- ``String`` - ``"pending"``, the currently mined block (including - pending transactions) - -*Default is* ``latest`` - -Returns -''''''' - -``Number|String`` - The default block number to use when querying a -state. - -Example -''''''' - -.. code:: js - - var defaultBlock = web3.eth.defaultBlock; - console.log(defaultBlock); // 'latest' - - // set the default block - web3.eth.defaultBlock = 231; - --------------- - -web3.eth.syncing -^^^^^^^^^^^^^^^^ - -:: - - web3.eth.syncing - // or async - web3.eth.getSyncing(callback(error, result){ ... }) - -This property is read only and returns the either a sync object, when -the node is syncing or ``false``. - -Returns -''''''' - -``Object|Boolean`` - A sync object as follows, when the node is -currently syncing or ``false``: - ``startingBlock``: ``Number`` - The -block number where the sync started. - ``currentBlock``: ``Number`` - -The block number where at which block the node currently synced to -already. - ``highestBlock``: ``Number`` - The estimated block number to -sync to. - -Example -''''''' - -.. code:: js - - var sync = web3.eth.syncing; - console.log(sync); - /* - { - startingBlock: 300, - currentBlock: 312, - highestBlock: 512 - } - */ - --------------- - -web3.eth.isSyncing -^^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.isSyncing(callback); - -This convenience function calls the ``callback`` everytime a sync -starts, updates and stops. - -Returns -''''''' - -``Object`` - a isSyncing object with the following methods: - -- ``syncing.addCallback()``: Adds another callback, which will be - called when the node starts or stops syncing. -- ``syncing.stopWatching()``: Stops the syncing callbacks. - -Callback return value -''''''''''''''''''''' - -- ``Boolean`` - The callback will be fired with ``true`` when the - syncing starts and with ``false`` when it stopped. -- ``Object`` - While syncing it will return the syncing object: -- ``startingBlock``: ``Number`` - The block number where the sync - started. -- ``currentBlock``: ``Number`` - The block number where at which block - the node currently synced to already. -- ``highestBlock``: ``Number`` - The estimated block number to sync to. - -Example -''''''' - -.. code:: js - - web3.eth.isSyncing(function(error, sync){ - if(!error) { - // stop all app activity - if(sync === true) { - // we use `true`, so it stops all filters, but not the web3.eth.syncing polling - web3.reset(true); - - // show sync info - } else if(sync) { - console.log(sync.currentBlock); - - // re-gain app operation - } else { - // run your app init function... - } - } - }); - --------------- - -web3.eth.coinbase -^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.coinbase - // or async - web3.eth.getCoinbase(callback(error, result){ ... }) - -This property is read only and returns the coinbase address were the -mining rewards go to. - -Returns -''''''' - -``String`` - The coinbase address of the client. - -Example -''''''' - -.. code:: js - - var coinbase = web3.eth.coinbase; - console.log(coinbase); // "0x407d73d8a49eeb85d32cf465507dd71d507100c1" - --------------- - -web3.eth.mining -^^^^^^^^^^^^^^^ - -:: - - web3.eth.mining - // or async - web3.eth.getMining(callback(error, result){ ... }) - -This property is read only and says whether the node is mining or not. - -Returns -''''''' - -``Boolean`` - ``true`` if the client is mining, otherwise ``false``. - -Example -''''''' - -.. code:: js - - var mining = web3.eth.mining; - console.log(mining); // true or false - --------------- - -web3.eth.hashrate -^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.hashrate - // or async - web3.eth.getHashrate(callback(error, result){ ... }) - -This property is read only and returns the number of hashes per second -that the node is mining with. - -Returns -''''''' - -``Number`` - number of hashes per second. - -Example -''''''' - -.. code:: js - - var hashrate = web3.eth.hashrate; - console.log(hashrate); // 493736 - --------------- - -web3.eth.gasPrice -^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.gasPrice - // or async - web3.eth.getGasPrice(callback(error, result){ ... }) - -This property is read only and returns the current gas price. The gas -price is determined by the x latest blocks median gas price. - -Returns -''''''' - -``BigNumber`` - A BigNumber instance of the current gas price in wei. - -See the `note on BigNumber <#a-note-on-big-numbers-in-javascript>`__. - -Example -''''''' - -.. code:: js - - var gasPrice = web3.eth.gasPrice; - console.log(gasPrice.toString(10)); // "10000000000000" - --------------- - -web3.eth.accounts -^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.accounts - // or async - web3.eth.getAccounts(callback(error, result){ ... }) - -This property is read only and returns a list of accounts the node -controls. - -Returns -''''''' - -``Array`` - An array of addresses controlled by client. - -Example -''''''' - -.. code:: js - - var accounts = web3.eth.accounts; - console.log(accounts); // ["0x407d73d8a49eeb85d32cf465507dd71d507100c1"] - --------------- - -web3.eth.blockNumber -^^^^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.blockNumber - // or async - web3.eth.getBlockNumber(callback(error, result){ ... }) - -This property is read only and returns the current block number. - -Returns -''''''' - -``Number`` - The number of the most recent block. - -Example -''''''' - -.. code:: js - - var number = web3.eth.blockNumber; - console.log(number); // 2744 - --------------- - -web3.eth.register -^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.register(addressHexString [, callback]) - -(Not Implemented yet) Registers the given address to be included in -``web3.eth.accounts``. This allows non-private-key owned accounts to be -associated as an owned account (e.g., contract wallets). - -Parameters -'''''''''' - -1. ``String`` - The address to register -2. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Returns -''''''' - -? - -Example -''''''' - -.. code:: js - - web3.eth.register("0x407d73d8a49eeb85d32cf465507dd71d507100ca") - --------------- - -web3.eth.unRegister -^^^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.unRegister(addressHexString [, callback]) - -(Not Implemented yet) Unregisters a given address. - -Parameters -'''''''''' - -1. ``String`` - The address to unregister. -2. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Returns -''''''' - -? - -Example -''''''' - -.. code:: js - - web3.eth.unregister("0x407d73d8a49eeb85d32cf465507dd71d507100ca") - --------------- - -web3.eth.getBalance -^^^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.getBalance(addressHexString [, defaultBlock] [, callback]) - -Get the balance of an address at a given block. - -Parameters -'''''''''' - -1. ``String`` - The address to get the balance of. -2. ``Number|String`` - (optional) If you pass this parameter it will not - use the default block set with - `web3.eth.defaultBlock <#web3ethdefaultblock>`__. -3. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Returns -''''''' - -``String`` - A BigNumber instance of the current balance for the given -address in wei. - -See the `note on BigNumber <#a-note-on-big-numbers-in-javascript>`__. - -Example -''''''' - -.. code:: js - - var balance = web3.eth.getBalance("0x407d73d8a49eeb85d32cf465507dd71d507100c1"); - console.log(balance); // instanceof BigNumber - console.log(balance.toString(10)); // '1000000000000' - console.log(balance.toNumber()); // 1000000000000 - --------------- - -web3.eth.getStorageAt -^^^^^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.getStorageAt(addressHexString, position [, defaultBlock] [, callback]) - -Get the storage at a specific position of an address. - -Parameters -'''''''''' - -1. ``String`` - The address to get the storage from. -2. ``Number`` - The index position of the storage. -3. ``Number|String`` - (optional) If you pass this parameter it will not - use the default block set with - `web3.eth.defaultBlock <#web3ethdefaultblock>`__. -4. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Returns -''''''' - -``String`` - The value in storage at the given position. - -Example -''''''' - -.. code:: js - - var state = web3.eth.getStorageAt("0x407d73d8a49eeb85d32cf465507dd71d507100c1", 0); - console.log(state); // "0x03" - --------------- - -web3.eth.getCode -^^^^^^^^^^^^^^^^ - -:: - - web3.eth.getCode(addressHexString [, defaultBlock] [, callback]) - -Get the code at a specific address. - -Parameters -'''''''''' - -1. ``String`` - The address to get the code from. -2. ``Number|String`` - (optional) If you pass this parameter it will not - use the default block set with - `web3.eth.defaultBlock <#web3ethdefaultblock>`__. -3. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Returns -''''''' - -``String`` - The data at given address ``addressHexString``. - -Example -''''''' - -.. code:: js - - var code = web3.eth.getCode("0xd5677cf67b5aa051bb40496e68ad359eb97cfbf8"); - console.log(code); // "0x600160008035811a818181146012578301005b601b6001356025565b8060005260206000f25b600060078202905091905056" - --------------- - -web3.eth.getBlock -^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.getBlock(blockHashOrBlockNumber [, returnTransactionObjects] [, callback]) - -Returns a block matching the block number or block hash. - -Parameters -'''''''''' - -1. ``String|Number`` - The block number or hash. Or the string - ``"earliest"``, ``"latest"`` or ``"pending"`` as in the `default - block parameter <#web3ethdefaultblock>`__. -2. ``Boolean`` - (optional, default ``false``) If ``true``, the returned - block will contain all transactions as objects, if ``false`` it will - only contains the transaction hashes. -3. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Returns -''''''' - -``Object`` - The block object: - -- ``number``: ``Number`` - the block number. ``null`` when its pending - block. -- ``hash``: ``String``, 32 Bytes - hash of the block. ``null`` when its - pending block. -- ``parentHash``: ``String``, 32 Bytes - hash of the parent block. -- ``nonce``: ``String``, 8 Bytes - hash of the generated proof-of-work. - ``null`` when its pending block. -- ``sha3Uncles``: ``String``, 32 Bytes - SHA3 of the uncles data in the - block. -- ``logsBloom``: ``String``, 256 Bytes - the bloom filter for the logs - of the block. ``null`` when its pending block. -- ``transactionsRoot``: ``String``, 32 Bytes - the root of the - transaction trie of the block -- ``stateRoot``: ``String``, 32 Bytes - the root of the final state - trie of the block. -- ``miner``: ``String``, 20 Bytes - the address of the beneficiary to - whom the mining rewards were given. -- ``difficulty``: ``BigNumber`` - integer of the difficulty for this - block. -- ``totalDifficulty``: ``BigNumber`` - integer of the total difficulty - of the chain until this block. -- ``extraData``: ``String`` - the "extra data" field of this block. -- ``size``: ``Number`` - integer the size of this block in bytes. -- ``gasLimit``: ``Number`` - the maximum gas allowed in this block. -- ``gasUsed``: ``Number`` - the total used gas by all transactions in - this block. -- ``timestamp``: ``Number`` - the unix timestamp for when the block was - collated. -- ``transactions``: ``Array`` - Array of transaction objects, or 32 - Bytes transaction hashes depending on the last given parameter. -- ``uncles``: ``Array`` - Array of uncle hashes. - -Example -''''''' - -.. code:: js - - var info = web3.eth.getBlock(3150); - console.log(info); - /* - { - "number": 3, - "hash": "0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46", - "parentHash": "0x2302e1c0b972d00932deb5dab9eb2982f570597d9d42504c05d9c2147eaf9c88", - "nonce": "0xfb6e1a62d119228b", - "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347", - "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", - "transactionsRoot": "0x3a1b03875115b79539e5bd33fb00d8f7b7cd61929d5a3c574f507b8acf415bee", - "stateRoot": "0xf1133199d44695dfa8fd1bcfe424d82854b5cebef75bddd7e40ea94cda515bcb", - "miner": "0x8888f1f195afa192cfee860698584c030f4c9db1", - "difficulty": BigNumber, - "totalDifficulty": BigNumber, - "size": 616, - "extraData": "0x", - "gasLimit": 3141592, - "gasUsed": 21662, - "timestamp": 1429287689, - "transactions": [ - "0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b" - ], - "uncles": [] - } - */ - --------------- - -web3.eth.getBlockTransactionCount -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.getBlockTransactionCount(hashStringOrBlockNumber [, callback]) - -Returns the number of transaction in a given block. - -Parameters -'''''''''' - -1. ``String|Number`` - The block number or hash. Or the string - ``"earliest"``, ``"latest"`` or ``"pending"`` as in the `default - block parameter <#web3ethdefaultblock>`__. -2. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Returns -''''''' - -``Number`` - The number of transactions in the given block. - -Example -''''''' - -.. code:: js - - var number = web3.eth.getBlockTransactionCount("0x407d73d8a49eeb85d32cf465507dd71d507100c1"); - console.log(number); // 1 - --------------- - -web3.eth.getUncle -^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.getUncle(blockHashStringOrNumber, uncleNumber [, returnTransactionObjects] [, callback]) - -Returns a blocks uncle by a given uncle index position. - -Parameters -'''''''''' - -1. ``String|Number`` - The block number or hash. Or the string - ``"earliest"``, ``"latest"`` or ``"pending"`` as in the `default - block parameter <#web3ethdefaultblock>`__. -2. ``Number`` - The index position of the uncle. -3. ``Boolean`` - (optional, default ``false``) If ``true``, the returned - block will contain all transactions as objects, if ``false`` it will - only contains the transaction hashes. -4. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Returns -''''''' - -``Object`` - the returned uncle. For a return value see -`web3.eth.getBlock() <#web3ethgetblock>`__. - -**Note**: An uncle doesn't contain individual transactions. - -Example -''''''' - -.. code:: js - - var uncle = web3.eth.getUncle(500, 0); - console.log(uncle); // see web3.eth.getBlock - --------------- - -web3.eth.getTransaction -''''''''''''''''''''''' - -:: - - web3.eth.getTransaction(transactionHash [, callback]) - -Returns a transaction matching the given transaction hash. - -Parameters -'''''''''' - -1. ``String`` - The transaction hash. -2. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Returns -''''''' - -``Object`` - A transaction object its hash ``transactionHash``: - -- ``hash``: ``String``, 32 Bytes - hash of the transaction. -- ``nonce``: ``Number`` - the number of transactions made by the sender - prior to this one. -- ``blockHash``: ``String``, 32 Bytes - hash of the block where this - transaction was in. ``null`` when its pending. -- ``blockNumber``: ``Number`` - block number where this transaction was - in. ``null`` when its pending. -- ``transactionIndex``: ``Number`` - integer of the transactions index - position in the block. ``null`` when its pending. -- ``from``: ``String``, 20 Bytes - address of the sender. -- ``to``: ``String``, 20 Bytes - address of the receiver. ``null`` when - its a contract creation transaction. -- ``value``: ``BigNumber`` - value transferred in Wei. -- ``gasPrice``: ``BigNumber`` - gas price provided by the sender in - Wei. -- ``gas``: ``Number`` - gas provided by the sender. -- ``input``: ``String`` - the data sent along with the transaction. - -Example -''''''' - -.. code:: js - - var blockNumber = 668; - var indexOfTransaction = 0 - - var transaction = web3.eth.getTransaction(blockNumber, indexOfTransaction); - console.log(transaction); - /* - { - "hash": "0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b", - "nonce": 2, - "blockHash": "0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46", - "blockNumber": 3, - "transactionIndex": 0, - "from": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b", - "to": "0x6295ee1b4f6dd65047762f924ecd367c17eabf8f", - "value": BigNumber, - "gas": 314159, - "gasPrice": BigNumber, - "input": "0x57cb2fc4" - } - */ - --------------- - -web3.eth.getTransactionFromBlock -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - getTransactionFromBlock(hashStringOrNumber, indexNumber [, callback]) - -Returns a transaction based on a block hash or number and the -transactions index position. - -Parameters -'''''''''' - -1. ``String`` - A block number or hash. Or the string ``"earliest"``, - ``"latest"`` or ``"pending"`` as in the `default block - parameter <#web3ethdefaultblock>`__. -2. ``Number`` - The transactions index position. -3. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Returns -''''''' - -``Object`` - A transaction object, see -`web3.eth.getTransaction <#web3ethgettransaction>`__: - -Example -''''''' - -.. code:: js - - var transaction = web3.eth.getTransactionFromBlock('0x4534534534', 2); - console.log(transaction); // see web3.eth.getTransaction - --------------- - -web3.eth.getTransactionReceipt -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.getTransactionReceipt(hashString [, callback]) - -Returns the receipt of a transaction by transaction hash. - -**Note** That the receipt is not available for pending transactions. - -Parameters -'''''''''' - -1. ``String`` - The transaction hash. -2. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Returns -''''''' - -``Object`` - A transaction receipt object, or ``null`` when no receipt -was found: - -- ``blockHash``: ``String``, 32 Bytes - hash of the block where this - transaction was in. -- ``blockNumber``: ``Number`` - block number where this transaction was - in. -- ``transactionHash``: ``String``, 32 Bytes - hash of the transaction. -- ``transactionIndex``: ``Number`` - integer of the transactions index - position in the block. -- ``from``: ``String``, 20 Bytes - address of the sender. -- ``to``: ``String``, 20 Bytes - address of the receiver. ``null`` when - its a contract creation transaction. -- ``cumulativeGasUsed``: ``Number`` - The total amount of gas used when - this transaction was executed in the block. -- ``gasUsed``: ``Number`` - The amount of gas used by this specific - transaction alone. -- ``contractAddress``: ``String`` - 20 Bytes - The contract address - created, if the transaction was a contract creation, otherwise - ``null``. -- ``logs``: ``Array`` - Array of log objects, which this transaction - generated. - -Example -''''''' - -.. code:: js - - var receipt = web3.eth.getTransactionReceipt('0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b'); - console.log(receipt); - { - "transactionHash": "0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b", - "transactionIndex": 0, - "blockHash": "0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46", - "blockNumber": 3, - "contractAddress": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b", - "cumulativeGasUsed": 314159, - "gasUsed": 30234, - "logs": [{ - // logs as returned by getFilterLogs, etc. - }, ...] - } - --------------- - -web3.eth.getTransactionCount -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.getTransactionCount(addressHexString [, defaultBlock] [, callback]) - -Get the numbers of transactions sent from this address. - -Parameters -'''''''''' - -1. ``String`` - The address to get the numbers of transactions from. -2. ``Number|String`` - (optional) If you pass this parameter it will not - use the default block set with - `web3.eth.defaultBlock <#web3ethdefaultblock>`__. -3. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Returns -''''''' - -``Number`` - The number of transactions sent from the given address. - -Example -''''''' - -.. code:: js - - var number = web3.eth.getTransactionCount("0x407d73d8a49eeb85d32cf465507dd71d507100c1"); - console.log(number); // 1 - --------------- - -web3.eth.sendTransaction -^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.sendTransaction(transactionObject [, callback]) - -Sends a transaction to the network. - -Parameters -'''''''''' - -1. ``Object`` - The transaction object to send: - -- ``from``: ``String`` - The address for the sending account. Uses the - `web3.eth.defaultAccount <#web3ethdefaultaccount>`__ property, if not - specified. -- ``to``: ``String`` - (optional) The destination address of the - message, left undefined for a contract-creation transaction. -- ``value``: ``Number|String|BigNumber`` - (optional) The value - transferred for the transaction in Wei, also the endowment if it's a - contract-creation transaction. -- ``gas``: ``Number|String|BigNumber`` - (optional, default: - To-Be-Determined) The amount of gas to use for the transaction - (unused gas is refunded). -- ``gasPrice``: ``Number|String|BigNumber`` - (optional, default: - To-Be-Determined) The price of gas for this transaction in wei, - defaults to the mean network gas price. -- ``data``: ``String`` - (optional) Either a `byte - string `__ - containing the associated data of the message, or in the case of a - contract-creation transaction, the initialisation code. -- ``nonce``: ``Number`` - (optional) Integer of a nonce. This allows to - overwrite your own pending transactions that use the same nonce. - -2. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Returns -''''''' - -``String`` - The 32 Bytes transaction hash as HEX string. - -If the transaction was a contract creation use -`web3.eth.getTransactionReceipt() <#web3gettransactionreceipt>`__ to get -the contract address, after the transaction was mined. - -Example -''''''' - -.. code:: js - - - // compiled solidity source code using https://chriseth.github.io/cpp-ethereum/ - var code = "603d80600c6000396000f3007c01000000000000000000000000000000000000000000000000000000006000350463c6888fa18114602d57005b600760043502 - 8060005260206000f3"; - - web3.eth.sendTransaction({data: code}, function(err, address) { - if (!err) - console.log(address); // "0x7f9fade1c0d57a7af66ab4ead7c2eb7b11a91385" - }); - --------------- - -web3.eth.call -^^^^^^^^^^^^^ - -:: - - web3.eth.call(callObject [, defaultBlock] [, callback]) - -Executes a message call transaction, which is directly executed in the -VM of the node, but never mined into the blockchain. - -Parameters -'''''''''' - -1. ``Object`` - A transaction object see - `web3.eth.sendTransaction <#web3ethsendtransaction>`__, with the - difference that for calls the ``from`` property is optional as well. -2. ``Number|String`` - (optional) If you pass this parameter it will not - use the default block set with - `web3.eth.defaultBlock <#web3ethdefaultblock>`__. -3. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Returns -''''''' - -``String`` - The returned data of the call, e.g. a codes functions -return value. - -Example -''''''' - -.. code:: js - - var result = web3.eth.call({ - to: "0xc4abd0339eb8d57087278718986382264244252f", - data: "0xc6888fa10000000000000000000000000000000000000000000000000000000000000003" - }); - console.log(result); // "0x0000000000000000000000000000000000000000000000000000000000000015" - --------------- - -web3.eth.estimateGas -^^^^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.estimateGas(callObject [, defaultBlock] [, callback]) - -Executes a message call or transaction, which is directly executed in -the VM of the node, but never mined into the blockchain and returns the -amount of the gas used. - -Parameters -'''''''''' - -See `web3.eth.sendTransaction <#web3ethsendtransaction>`__, expect that -all properties are optional. - -Returns -''''''' - -``Number`` - the used gas for the simulated call/transaction. - -Example -''''''' - -.. code:: js - - var result = web3.eth.estimateGas({ - to: "0xc4abd0339eb8d57087278718986382264244252f", - data: "0xc6888fa10000000000000000000000000000000000000000000000000000000000000003" - }); - console.log(result); // "0x0000000000000000000000000000000000000000000000000000000000000015" - --------------- - -web3.eth.filter -^^^^^^^^^^^^^^^ - -.. code:: js - - // can be 'latest' or 'pending' - var filter = web3.eth.filter(filterString); - // OR object are log filter options - var filter = web3.eth.filter(options); - - // watch for changes - filter.watch(function(error, result){ - if (!error) - console.log(result); - }); - - // Additionally you can start watching right away, by passing a callback: - web3.eth.filter(options, function(error, result){ - if (!error) - console.log(result); - }); - -Parameters -'''''''''' - -1. ``String|Object`` - The string ``"latest"`` or ``"pending"`` to watch - for changes in the latest block or pending transactions respectively. - Or a filter options object as follows: - -- ``fromBlock``: ``Number|String`` - The number of the earliest block - (``latest`` may be given to mean the most recent and ``pending`` - currently mining, block). By default ``latest``. -- ``toBlock``: ``Number|String`` - The number of the latest block - (``latest`` may be given to mean the most recent and ``pending`` - currently mining, block). By default ``latest``. -- ``address``: ``String`` - An address or a list of addresses to only - get logs from particular account(s). -- ``topics``: ``Array of Strings`` - An array of values which must each - appear in the log entries. The order is important, if you want to - leave topics out use ``null``, e.g. ``[null, '0x00...']``. You can - also pass another array for each topic with options for that topic - e.g. ``[null, ['option1', 'option2']]`` - -Returns -''''''' - -``Object`` - A filter object with the following methods: - -- ``filter.get(callback)``: Returns all of the log entries that fit the - filter. -- ``filter.watch(callback)``: Watches for state changes that fit the - filter and calls the callback. See `this note <#using-callbacks>`__ - for details. -- ``filter.stopWatching()``: Stops the watch and uninstalls the filter - in the node. Should always be called once it is done. - -Watch callback return value -''''''''''''''''''''''''''' - -- ``String`` - When using the ``"latest"`` parameter, it returns the - block hash of the last incoming block. -- ``String`` - When using the ``"pending"`` parameter, it returns a - transaction hash of the last add pending transaction. -- ``Object`` - When using manual filter options, it returns a log - object as follows: - - - ``logIndex``: ``Number`` - integer of the log index position in - the block. ``null`` when its pending log. - - ``transactionIndex``: ``Number`` - integer of the transactions - index position log was created from. ``null`` when its pending - log. - - ``transactionHash``: ``String``, 32 Bytes - hash of the - transactions this log was created from. ``null`` when its pending - log. - - ``blockHash``: ``String``, 32 Bytes - hash of the block where this - log was in. ``null`` when its pending. ``null`` when its pending - log. - - ``blockNumber``: ``Number`` - the block number where this log was - in. ``null`` when its pending. ``null`` when its pending log. - - ``address``: ``String``, 32 Bytes - address from which this log - originated. - - ``data``: ``String`` - contains one or more 32 Bytes non-indexed - arguments of the log. - - ``topics``: ``Array of Strings`` - Array of 0 to 4 32 Bytes - ``DATA`` of indexed log arguments. (In *solidity*: The first topic - is the *hash* of the signature of the event (e.g. - ``Deposit(address,bytes32,uint256)``), except you declared the - event with the ``anonymous`` specifier.) - -**Note** For event filter return values see `Contract -Events <#contract-events>`__ - -Example -''''''' - -.. code:: js - - var filter = web3.eth.filter('pending'); - - filter.watch(function (error, log) { - console.log(log); // {"address":"0x0000000000000000000000000000000000000000", "data":"0x0000000000000000000000000000000000000000000000000000000000000000", ...} - }); - - // get all past logs again. - var myResults = filter.get(function(error, logs){ ... }); - - ... - - // stops and uninstalls the filter - filter.stopWatching(); - --------------- - -web3.eth.contract -^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.contract(abiArray) - -Creates a contract object for a solidity contract, which can be used to -initiate contracts on an address. You can read more about events -`here `__. - -Parameters -'''''''''' - -1. ``Array`` - ABI array with descriptions of functions and events of - the contract. - -Returns -''''''' - -``Object`` - A contract object, which can be initiated as follows: - -.. code:: js - - var MyContract = web3.eth.contract(abiArray); - - // instantiate by address - var contractInstance = MyContract.at([address]); - - // deploy new contract - var contractInstance = MyContract.new([contructorParam1] [, contructorParam2], {data: '0x12345...', from: myAccount, gas: 1000000}); - - // Get the data to deploy the contract manually - var contractData = MyContract.new.getData([contructorParam1] [, contructorParam2], {data: '0x12345...'}); - // contractData = '0x12345643213456000000000023434234' - -And then you can either initiate an existing contract on an address, or -deploy the contract using the compiled byte code: - -.. code:: js - - // Instantiate from an existing address: - var myContractInstance = MyContract.at(myContractAddress); - - - // Or deploy a new contract: - - // Deploy the contract asyncronous: - var myContractReturned = MyContract.new(param1, param2, { - data: myContractCode, - gas: 300000, - from: mySenderAddress}, function(err, myContract){ - if(!err) { - // NOTE: The callback will fire twice! - // Once the contract has the transactionHash property set and once its deployed on an address. - - // e.g. check tx hash on the first call (transaction send) - if(!myContract.address) { - console.log(myContract.transactionHash) // The hash of the transaction, which deploys the contract - - // check address on the second call (contract deployed) - } else { - console.log(myContract.address) // the contract address - } - - // Note that the returned "myContractReturned" === "myContract", - // so the returned "myContractReturned" object will also get the address set. - } - }); - - // Deploy contract syncronous: The address will be added as soon as the contract is mined. - // Additionally you can watch the transaction by using the "transactionHash" property - var myContractInstance = MyContract.new(param1, param2, {data: myContractCode, gas: 300000, from: mySenderAddress}); - myContractInstance.transactionHash // The hash of the transaction, which created the contract - myContractInstance.address // undefined at start, but will be auto-filled later - -**Note** When you deploy a new contract, you should check for the next -12 blocks or so if the contract code is still at the address (using -`web3.eth.getCode() <#web3ethgetcode>`__), to make sure a fork didn't -change that. - -Example -''''''' - -.. code:: js - - // contract abi - var abi = [{ - name: 'myConstantMethod', - type: 'function', - constant: true, - inputs: [{ name: 'a', type: 'string' }], - outputs: [{name: 'd', type: 'string' }] - }, { - name: 'myStateChangingMethod', - type: 'function', - constant: false, - inputs: [{ name: 'a', type: 'string' }, { name: 'b', type: 'int' }], - outputs: [] - }, { - name: 'myEvent', - type: 'event', - inputs: [{name: 'a', type: 'int', indexed: true},{name: 'b', type: 'bool', indexed: false] - }]; - - // creation of contract object - var MyContract = web3.eth.contract(abi); - - // initiate contract for an address - var myContractInstance = MyContract.at('0xc4abd0339eb8d57087278718986382264244252f'); - - // call constant function - var result = myContractInstance.myConstantMethod('myParam'); - console.log(result) // '0x25434534534' - - // send a transaction to a function - myContractInstance.myStateChangingMethod('someParam1', 23, {value: 200, gas: 2000}); - - // short hand style - web3.eth.contract(abi).at(address).myAwesomeMethod(...); - - // create filter - var filter = myContractInstance.myEvent({a: 5}, function (error, result) { - if (!error) - console.log(result); - /* - { - address: '0x8718986382264244252fc4abd0339eb8d5708727', - topics: "0x12345678901234567890123456789012", "0x0000000000000000000000000000000000000000000000000000000000000005", - data: "0x0000000000000000000000000000000000000000000000000000000000000001", - ... - } - */ - }); - --------------- - -Contract Methods -^^^^^^^^^^^^^^^^ - -.. code:: js - - // Automatically determines the use of call or sendTransaction based on the method type - myContractInstance.myMethod(param1 [, param2, ...] [, transactionObject] [, callback]); - - // Explicitly calling this method - myContractInstance.myMethod.call(param1 [, param2, ...] [, transactionObject] [, callback]); - - // Explicitly sending a transaction to this method - myContractInstance.myMethod.sendTransaction(param1 [, param2, ...] [, transactionObject] [, callback]); - - // Explicitly sending a transaction to this method - myContractInstance.myMethod.sendTransaction(param1 [, param2, ...] [, transactionObject] [, callback]); - - // Get the call data, so you can call the contract through some other means - var myCallData = myContractInstance.myMethod.getData(param1 [, param2, ...]); - // myCallData = '0x45ff3ff6000000000004545345345345..' - -The contract object exposes the contracts methods, which can be called -using parameters and a transaction object. - -Parameters -'''''''''' - -- ``String|Number`` - (optional) Zero or more parameters of the - function. -- ``Object`` - (optional) The (previous) last parameter can be a - transaction object, see - `web3.eth.sendTransaction <#web3ethsendtransaction>`__ parameter 1 - for more. -- ``Function`` - (optional) If you pass a callback as the last - parameter the HTTP request is made asynchronous. See `this - note <#using-callbacks>`__ for details. - -Returns -''''''' - -``String`` - If its a call the result data, if its a send transaction a -created contract address, or the transaction hash, see -`web3.eth.sendTransaction <#web3ethsendtransaction>`__ for details. - -Example -''''''' - -.. code:: js - - // creation of contract object - var MyContract = web3.eth.contract(abi); - - // initiate contract for an address - var myContractInstance = MyContract.at('0x78e97bcc5b5dd9ed228fed7a4887c0d7287344a9'); - - var result = myContractInstance.myConstantMethod('myParam'); - console.log(result) // '0x25434534534' - - myContractInstance.myStateChangingMethod('someParam1', 23, {value: 200, gas: 2000}, function(err, result){ ... }); - --------------- - -Contract Events -^^^^^^^^^^^^^^^ - -.. code:: js - - var event = myContractInstance.MyEvent({valueA: 23} [, additionalFilterObject]) - - // watch for changes - event.watch(function(error, result){ - if (!error) - console.log(result); - }); - - // Or pass a callback to start watching immediately - var event = myContractInstance.MyEvent([{valueA: 23}] [, additionalFilterObject] , function(error, result){ - if (!error) - console.log(result); - }); - -You can use events like `filters <#web3ethfilter>`__ and they have the -same methods, but you pass different objects to create the event filter. - -Parameters -'''''''''' - -1. ``Object`` - Indexed return values you want to filter the logs by, - e.g. ``{'valueA': 1, 'valueB': [myFirstAddress, mySecondAddress]}``. - By default all filter values are set to ``null``. It means, that they - will match any event of given type sent from this contract. -2. ``Object`` - Additional filter options, see - `filters <#web3ethfilter>`__ parameter 1 for more. By default - filterObject has field 'address' set to address of the contract. Also - first topic is the signature of event. -3. ``Function`` - (optional) If you pass a callback as the last - parameter it will immediately start watching and you don't need to - call ``myEvent.watch(function(){})``. See `this - note <#using-callbacks>`__ for details. - -Callback return -''''''''''''''' - -``Object`` - An event object as follows: - -- ``args``: ``Object`` - The arguments coming from the event. -- ``event``: ``String`` - The event name. -- ``logIndex``: ``Number`` - integer of the log index position in the - block. -- ``transactionIndex``: ``Number`` - integer of the transactions index - position log was created from. -- ``transactionHash``: ``String``, 32 Bytes - hash of the transactions - this log was created from. -- ``address``: ``String``, 32 Bytes - address from which this log - originated. -- ``blockHash``: ``String``, 32 Bytes - hash of the block where this - log was in. ``null`` when its pending. -- ``blockNumber``: ``Number`` - the block number where this log was in. - ``null`` when its pending. - -Example -''''''' - -.. code:: js - - var MyContract = web3.eth.contract(abi); - var myContractInstance = MyContract.at('0x78e97bcc5b5dd9ed228fed7a4887c0d7287344a9'); - - // watch for an event with {some: 'args'} - var myEvent = myContractInstance.MyEvent({some: 'args'}, {fromBlock: 0, toBlock: 'latest'}); - myEvent.watch(function(error, result){ - ... - }); - - // would get all past logs again. - var myResults = myEvent.get(function(error, logs){ ... }); - - ... - - // would stop and uninstall the filter - myEvent.stopWatching(); - --------------- - -Contract allEvents -^^^^^^^^^^^^^^^^^^ - -.. code:: js - - var events = myContractInstance.allEvents([additionalFilterObject]); - - // watch for changes - events.watch(function(error, event){ - if (!error) - console.log(event); - }); - - // Or pass a callback to start watching immediately - var events = myContractInstance.allEvents([additionalFilterObject,] function(error, log){ - if (!error) - console.log(log); - }); - -Will call the callback for all events which are created by this -contract. - -Parameters -'''''''''' - -1. ``Object`` - Additional filter options, see - `filters <#web3ethfilter>`__ parameter 1 for more. By default - filterObject has field 'address' set to address of the contract. Also - first topic is the signature of event. -2. ``Function`` - (optional) If you pass a callback as the last - parameter it will immediately start watching and you don't need to - call ``myEvent.watch(function(){})``. See `this - note <#using-callbacks>`__ for details. - -Callback return -''''''''''''''' - -``Object`` - See `Contract Events <#contract-events>`__ for more. - -Example -''''''' - -.. code:: js - - var MyContract = web3.eth.contract(abi); - var myContractInstance = MyContract.at('0x78e97bcc5b5dd9ed228fed7a4887c0d7287344a9'); - - // watch for an event with {some: 'args'} - var events = myContractInstance.allEvents({fromBlock: 0, toBlock: 'latest'}); - events.watch(function(error, result){ - ... - }); - - // would get all past logs again. - events.get(function(error, logs){ ... }); - - ... - - // would stop and uninstall the filter - myEvent.stopWatching(); - --------------- - -web3.eth.getCompilers -^^^^^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.getCompilers([callback]) - -Gets a list of available compilers. - -Parameters -'''''''''' - -1. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Returns -''''''' - -``Array`` - An array of strings of available compilers. - -Example -''''''' - -.. code:: js - - var number = web3.eth.getCompilers(); - console.log(number); // ["lll", "solidity", "serpent"] - --------------- - -web3.eth.compile.solidity -^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.compile.solidity(sourceString [, callback]) - -Compiles solidity source code. - -Parameters -'''''''''' - -1. ``String`` - The solidity source code. -2. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Returns -''''''' - -``Object`` - Contract and compiler info. - -Example -''''''' - -.. code:: js - - var source = "" + - "contract test {\n" + - " function multiply(uint a) returns(uint d) {\n" + - " return a * 7;\n" + - " }\n" + - "}\n"; - var compiled = web3.eth.compile.solidity(source); - console.log(compiled); - // { - "test": { - "code": "0x605280600c6000396000f3006000357c010000000000000000000000000000000000000000000000000000000090048063c6888fa114602e57005b60376004356041565b8060005260206000f35b6000600782029050604d565b91905056", - "info": { - "source": "contract test {\n\tfunction multiply(uint a) returns(uint d) {\n\t\treturn a * 7;\n\t}\n}\n", - "language": "Solidity", - "languageVersion": "0", - "compilerVersion": "0.8.2", - "abiDefinition": [ - { - "constant": false, - "inputs": [ - { - "name": "a", - "type": "uint256" - } - ], - "name": "multiply", - "outputs": [ - { - "name": "d", - "type": "uint256" - } - ], - "type": "function" - } - ], - "userDoc": { - "methods": {} - }, - "developerDoc": { - "methods": {} - } - } - } - } - --------------- - -web3.eth.compile.lll -^^^^^^^^^^^^^^^^^^^^ - -:: - - web3. eth.compile.lll(sourceString [, callback]) - -Compiles LLL source code. - -Parameters -'''''''''' - -1. ``String`` - The LLL source code. -2. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Returns -''''''' - -``String`` - The compiled LLL code as HEX string. - -Example -''''''' - -.. code:: js - - var source = "..."; - - var code = web3.eth.compile.lll(source); - console.log(code); // "0x603880600c6000396000f3006001600060e060020a600035048063c6888fa114601857005b6021600435602b565b8060005260206000f35b600081600702905091905056" - --------------- - -web3.eth.compile.serpent -^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - web3.eth.compile.serpent(sourceString [, callback]) - -Compiles serpent source code. - -Parameters -'''''''''' - -1. ``String`` - The serpent source code. -2. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Returns -''''''' - -``String`` - The compiled serpent code as HEX string. - -.. code:: js - - var source = "..."; - - var code = web3.eth.compile.serpent(source); - console.log(code); // "0x603880600c6000396000f3006001600060e060020a600035048063c6888fa114601857005b6021600435602b565b8060005260206000f35b600081600702905091905056" - --------------- - -web3.eth.namereg -^^^^^^^^^^^^^^^^ - -:: - - web3.eth.namereg - -Returns GlobalRegistrar object. - -Usage -''''' - -see -`namereg `__ -example - --------------- - -web3.db -~~~~~~~ - -web3.db.putString -^^^^^^^^^^^^^^^^^ - -:: - - web3.db.putString(db, key, value) - -This method should be called, when we want to store a string in the -local leveldb database. - -Parameters -'''''''''' - -1. ``String`` - The database to store to. -2. ``String`` - The name of the store. -3. ``String`` - The string value to store. - -Returns -''''''' - -``Boolean`` - ``true`` if successfull, otherwise ``false``. - -Example -''''''' - -param is db name, second is the key, and third is the string value. - -.. code:: js - - web3.db.putString('testDB', 'key', 'myString') // true - --------------- - -web3.db.getString -^^^^^^^^^^^^^^^^^ - -:: - - web3.db.getString(db, key) - -This method should be called, when we want to get string from the local -leveldb database. - -Parameters -'''''''''' - -1. ``String`` - The database string name to retrieve from. -2. ``String`` - The name of the store. - -Returns -''''''' - -``String`` - The stored value. - -Example -''''''' - -param is db name and second is the key of string value. - -.. code:: js - - var value = web3.db.getString('testDB', 'key'); - console.log(value); // "myString" - --------------- - -web3.db.putHex -^^^^^^^^^^^^^^ - -:: - - web3.db.putHex(db, key, value) - -This method should be called, when we want to store binary data in HEX -form in the local leveldb database. - -Parameters -'''''''''' - -1. ``String`` - The database to store to. -2. ``String`` - The name of the store. -3. ``String`` - The HEX string to store. - -Returns -''''''' - -``Boolean`` - ``true`` if successfull, otherwise ``false``. - -Example -''''''' - -.. code:: js - - web3.db.putHex('testDB', 'key', '0x4f554b443'); // true - --------------- - -web3.db.getHex -^^^^^^^^^^^^^^ - -:: - - web3.db.getHex(db, key) - -This method should be called, when we want to get a binary data in HEX -form from the local leveldb database. - -Parameters -'''''''''' - -1. ``String`` - The database to store to. -2. ``String`` - The name of the store. - -Returns -''''''' - -``String`` - The stored HEX value. - -Example -''''''' - -param is db name and second is the key of value. - -.. code:: js - - var value = web3.db.getHex('testDB', 'key'); - console.log(value); // "0x4f554b443" - --------------- - -web3.shh -~~~~~~~~ - -`Whisper -Overview `__ - -Example -''''''' - -.. code:: js - - var shh = web3.shh; - --------------- - -web3.shh.post -^^^^^^^^^^^^^ - -web3.shh.post(object [, callback]) - -This method should be called, when we want to post whisper message to -the network. - -Parameters -'''''''''' - -1. ``Object`` - The post object: - -- ``from``: ``String``, 60 Bytes HEX - (optional) The identity of the - sender. -- ``to``: ``String``, 60 Bytes HEX - (optional) The identity of the - receiver. When present whisper will encrypt the message so that only - the receiver can decrypt it. -- ``topics``: ``Array of Strings`` - Array of topics ``Strings``, for - the receiver to identify messages. -- ``payload``: ``String|Number|Object`` - The payload of the message. - Will be autoconverted to a HEX string before. -- ``priority``: ``Number`` - The integer of the priority in a rang from - ... (?). -- ``ttl``: ``Number`` - integer of the time to live in seconds. - -2. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Returns -''''''' - -``Boolean`` - returns ``true`` if the message was send, otherwise -``false``. - -Example -''''''' - -.. code:: js - - var identity = web3.shh.newIdentity(); - var topic = 'example'; - var payload = 'hello whisper world!'; - - var message = { - from: identity, - topics: [topic], - payload: payload, - ttl: 100, - workToProve: 100 // or priority TODO - }; - - web3.shh.post(message); - --------------- - -web3.shh.newIdentity -^^^^^^^^^^^^^^^^^^^^ - -:: - - web3.shh.newIdentity([callback]) - -Should be called to create new identity. - -Parameters -'''''''''' - -1. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Returns -''''''' - -``String`` - A new identity HEX string. - -Example -''''''' - -.. code:: js - - var identity = web3.shh.newIdentity(); - console.log(identity); // "0xc931d93e97ab07fe42d923478ba2465f283f440fd6cabea4dd7a2c807108f651b7135d1d6ca9007d5b68aa497e4619ac10aa3b27726e1863c1fd9b570d99bbaf" - --------------- - -web3.shh.hasIdentity -^^^^^^^^^^^^^^^^^^^^ - -:: - - web3.shh.hasIdentity(identity, [callback]) - -Should be called, if we want to check if user has given identity. - -Parameters -'''''''''' - -1. ``String`` - The identity to check. -2. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Returns -''''''' - -``Boolean`` - returns ``true`` if the identity exists, otherwise -``false``. - -Example -''''''' - -.. code:: js - - var identity = web3.shh.newIdentity(); - var result = web3.shh.hasIdentity(identity); - console.log(result); // true - - var result2 = web3.shh.hasIdentity(identity + "0"); - console.log(result2); // false - --------------- - -web3.shh.newGroup -^^^^^^^^^^^^^^^^^ - -Example -''''''' - -.. code:: js - - // TODO: not implemented yet - --------------- - -web3.shh.addToGroup -^^^^^^^^^^^^^^^^^^^ - -Example -''''''' - -.. code:: js - - // TODO: not implemented yet - --------------- - -web3.shh.filter -^^^^^^^^^^^^^^^ - -.. code:: js - - var filter = web3.shh.filter(options) - - // watch for changes - filter.watch(function(error, result){ - if (!error) - console.log(result); - }); - -Watch for incoming whisper messages. - -Parameters -'''''''''' - -1. ``Object`` - The filter options: - -- ``topics``: ``Array of Strings`` - Filters messages by this topic(s). - You can use the following combinations: - - - ``['topic1', 'topic2'] == 'topic1' && 'topic2'`` - - ``['topic1', ['topic2', 'topic3']] == 'topic1' && ('topic2' || 'topic3')`` - - ``[null, 'topic1', 'topic2'] == ANYTHING && 'topic1' && 'topic2'`` - -> ``null`` works as a wildcard - -- ``to``: Filter by identity of receiver of the message. If provided - and the node has this identity, it will decrypt incoming encrypted - messages. - -2. ``Function`` - (optional) If you pass a callback the HTTP request is - made asynchronous. See `this note <#using-callbacks>`__ for details. - -Callback return -''''''''''''''' - -``Object`` - The incoming message: - -- ``from``: ``String``, 60 Bytes - The sender of the message, if a - sender was specified. -- ``to``: ``String``, 60 Bytes - The receiver of the message, if a - receiver was specified. -- ``expiry``: ``Number`` - Integer of the time in seconds when this - message should expire (?). -- ``ttl``: ``Number`` - Integer of the time the message should float in - the system in seconds (?). -- ``sent``: ``Number`` - Integer of the unix timestamp when the message - was sent. -- ``topics``: ``Array of String`` - Array of ``String`` topics the - message contained. -- ``payload``: ``String`` - The payload of the message. -- ``workProved``: ``Number`` - Integer of the work this message - required before it was send (?). - --------------- - -web3.eth.sendIBANTransaction -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code:: js - - var txHash = web3.eth.sendIBANTransaction('0x00c5496aee77c1ba1f0854206a26dda82a81d6d8', 'XE81ETHXREGGAVOFYORK', 0x100); - -Sends IBAN transaction from user account to destination IBAN address. - -Parameters -'''''''''' - -- ``string`` - address from which we want to send transaction -- ``string`` - IBAN address to which we want to send transaction -- ``value`` - value that we want to send in IBAN transaction - --------------- - -web3.eth.iban -^^^^^^^^^^^^^ - -.. code:: js - - var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); - --------------- - -web3.eth.iban.fromAddress -^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code:: js - - var i = web3.eth.iban.fromAddress('0x00c5496aee77c1ba1f0854206a26dda82a81d6d8'); - console.log(i.toString()); // 'XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS - --------------- - -web3.eth.iban.fromBban -^^^^^^^^^^^^^^^^^^^^^^ - -.. code:: js - - var i = web3.eth.iban.fromBban('ETHXREGGAVOFYORK'); - console.log(i.toString()); // "XE81ETHXREGGAVOFYORK" - --------------- - -web3.eth.iban.createIndirect -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code:: js - - var i = web3.eth.iban.createIndirect({ - institution: "XREG", - identifier: "GAVOFYORK" - }); - console.log(i.toString()); // "XE81ETHXREGGAVOFYORK" - --------------- - -web3.eth.iban.isValid -^^^^^^^^^^^^^^^^^^^^^ - -.. code:: js - - var valid = web3.eth.iban.isValid("XE81ETHXREGGAVOFYORK"); - console.log(valid); // true - - var valid2 = web3.eth.iban.isValid("XE82ETHXREGGAVOFYORK"); - console.log(valid2); // false, cause checksum is incorrect - - var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); - var valid3 = i.isValid(); - console.log(valid3); // true - --------------- - -web3.eth.iban.isDirect -^^^^^^^^^^^^^^^^^^^^^^ - -.. code:: js - - var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); - var direct = i.isDirect(); - console.log(direct); // false - --------------- - -web3.eth.iban.isIndirect -^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code:: js - - var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); - var indirect = i.isIndirect(); - console.log(indirect); // true - --------------- - -web3.eth.iban.checksum -^^^^^^^^^^^^^^^^^^^^^^ - -.. code:: js - - var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); - var checksum = i.checksum(); - console.log(checksum); // "81" - --------------- - -web3.eth.iban.institution -^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code:: js - - var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); - var institution = i.institution(); - console.log(institution); // 'XREG' - --------------- - -web3.eth.iban.client -^^^^^^^^^^^^^^^^^^^^ - -.. code:: js - - var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); - var client = i.client(); - console.log(client); // 'GAVOFYORK' - --------------- - -web3.eth.iban.address -^^^^^^^^^^^^^^^^^^^^^ - -.. code:: js - - var i = new web3.eth.iban('XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS'); - var address = i.address(); - console.log(address); // '00c5496aee77c1ba1f0854206a26dda82a81d6d8' - --------------- - -web3.eth.iban.toString -^^^^^^^^^^^^^^^^^^^^^^ - -.. code:: js - - var i = new web3.eth.iban('XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS'); - console.log(i.toString()); // 'XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS' diff --git a/old-docs-for-reference/main-wiki.rst/Kademlia-Peer-Selection.rst b/old-docs-for-reference/main-wiki.rst/Kademlia-Peer-Selection.rst deleted file mode 100644 index e11462a..0000000 --- a/old-docs-for-reference/main-wiki.rst/Kademlia-Peer-Selection.rst +++ /dev/null @@ -1,101 +0,0 @@ -Peer addresses -============== - -Nodes in the P2P network are identified by 256-bit cryptographic hashes -of the nodes' public keys. - -The distance between two addresses is the MSB first numerical value of -their XOR. - -Peer table format -================= - -The peer table consists of rows, initially only one, at most 255 -(typically much less). Each row contains at most *k* peers (data -structures containing information about said peer such as their peer -address, network address, a timestamp, signature by the peer and -possibly various other meta-data), where *k* is a parameter (not -necessarily global) with typical values betwen 5 and 20. - -This parameter, *k*, determines the redundancy of the network: the peer -selection algorithm described in this page aims to maintain exactly *k* -peers in each row. If several different protocols requiring routing are -used on the network, each protocol *p* can specify its own redundancy -requirement *k*\ \ *p*\ , in which case the corresponding *k*\ \ *p*\ -number of peers supporting that protocol are maintained. Participants -must specify what protocols they support. - -Row numbering starts with 0. Each row number *i* contains peers whose -address matches the first *i* bits of this node's address. The *i*\ +1st -bit of the address must differ from this nodes address in all rows -except the last one. - -As a matter of implementation, it might be worth internally representing -all 255 rows from the outset (requiring that the *i*\ +1st bit be -different from our node in all rows); but then considering all of the -rows at the end as if they were one row. That is, we look at non empty -rows at the end and treat the elements in them as if they belonged to -row *i* where *i* is the lowest index such that the total number of all -elements in row *i* and in all higher rows, together is at most *k*. - -Note: there is a difference here to the original Kedemlia paper -http://pdos.csail.mit.edu/~petar/papers/maymounkov-kademlia-lncs.pdf The -rows with a high *i* for us here are the rows with a low *i* in the -paper. For us, high *i* means high number of bits agreeing, for them -high *i* mean high xor distance. - -Adding a new peer -================= - -A peer is added to the row to which it belongs according to the length -of address prefix in common with this node. If that would increase the -length of the row in question beyond *k*, the **worst** peer (according -to some, not necessarily global, peer quality metric) is dropped from -the row, except if it is the last row, in which case a new row *i* + 1 -is added and the elements in the old last row are split between the two -rows according to the bit at the corresponding position. Note: If we -followed the implementation suggestion in the previous section, then we -do not need to make an exception for the last row, nor do we have to -worry about splitting the last row on the implementation level. - -One sufficient condition for adding a peer is a signed "*add\_me*" -message containing the sender's peer address and network address, the -addressee's peer address and a recent timestamp. - -Lookup -====== - -A lookup request contains a peer address (which might or might not be -valid, it does not matter). The response is the peer list from the full -row corresponding to the requested address (information about at most -*k* peers, or *k*\ \ *p*\ peers for the protocol *p* in use). - -For brevity, it might be worth treating *add\_me* requests for nodes -that are not already in the peer table as self-lookups and respond -accordingly. - -The new peers are added to the peer table after which the ones in the -row corresponding to the address being searched are sent the lookup -request recursively, until no peers are returned that are closer to the -searched address. - -Joining the network -=================== - -Requires only one bootstrap peer, to which the new node sends an -*add\_me* message and subsequently adds every node from the response to -its own peer table. - -Thereafter, it performs a lookup of a synthetic random address from the -address range corresponding to rows with indices that are smaller than -the row in which the bootstrap node ended up. - -Backwards compatibility mode and DoS safety -=========================================== - -Nodes can still safely dump their full peer table and accept connections -from naive nodes. Overwriting the entire peer table of a node requires -significant computational effort even with relatively low *k*. DoS -attacks against non-naive nodes (as described in this page) require -generating addresses with corresponding key pairs for each row, -requiring quite a bit of hashing power. diff --git a/old-docs-for-reference/main-wiki.rst/Licensing.rst b/old-docs-for-reference/main-wiki.rst/Licensing.rst deleted file mode 100644 index 564b991..0000000 --- a/old-docs-for-reference/main-wiki.rst/Licensing.rst +++ /dev/null @@ -1,67 +0,0 @@ -Overview - -The Ethereum Foundation ensures three principles concerning the funds it -uses to develop Ethereum: - -- it is both open source software and Free software after the - definition of the Free Software Foundation (so-called FOSS); -- no special treatment is given to any single entity concerning the - copyright of the software, the Foundation included; -- source-code will not be distributed ahead of binaries. - -However, this is not where the story ends; there are many different -licenses available that conform to these rules. After considerable -discussion, both internal and external together with The Ethereum -software collection is distributed under several licenses, partly to -reflect the different thinking of the minds behind different pieces of -software and partly to reflect the need to adapt to real-world issues -and opportunities and lay out a strategy to provide the best possible -future for the Ethereum community. - -The Core -~~~~~~~~ - -The core of Ethereum includes the consensus engine, the networking code -and any supporting libraries. For C++, this includes libethereum, -libp2p, libdevcore, libdevcrypto, libethcore, libevm and libevmface. - -The core of Ethereum will be released under the most liberal of -licenses. This reflects our desire to have Ethereum used in as many -diverse environments as possible, even those which, for various reasons -can require modifications or augmentations to the software which cannot -be released to the public. - -In this way, while we have not arrived at a final license, we expect to -select one of the MIT license, the MPL license or the LGPL license. If -the latter is chosen, it will come with an amendment allowing it to be -linked to be statically linked to software for which source code is not -available. - -In this way, the core of Ethereum, be it C++ or Go, will be available -for use in any commercial environment, closed or open source. - -The Applications -~~~~~~~~~~~~~~~~ - -The applications of Ethereum, including the Solidity compiler -(libsolidity, solc), AlethZero and Mix will be distributed under the GNU -General Public License. This is to reflect the fact that these pieces of -software tend to not, by nature, need to be amalgamated or augmented -into a larger, closed-source, whole. There is however, much to be gained -through many different members of the Ethereum-community being -incentivised to develop on and build out such software. - -In this way we hope our initial version of Solidity and Mix lay down the -foundation for others to build upon and improve in the true -Free/open-source software manner. - -The Middleware -~~~~~~~~~~~~~~ - -The middleware of Ethereum, including the Javascript-based ethereum.js, -the webthree libraries and eth (the command line client) will be -distributed under an Affero license, likely the LGPL variant of it. We -wish to allow free development of technologies by allowing linking to -arbitrary software, but again would like to incentivise feeding of -back-end integration work back into the community, especially regarding -the interoperability with legacy systems. diff --git a/old-docs-for-reference/main-wiki.rst/Light-client-protocol.rst b/old-docs-for-reference/main-wiki.rst/Light-client-protocol.rst deleted file mode 100644 index c353334..0000000 --- a/old-docs-for-reference/main-wiki.rst/Light-client-protocol.rst +++ /dev/null @@ -1,140 +0,0 @@ -The purpose of the light client protocol is to allow users in -low-capacity environments (embedded smart property environments, -smartphones, browser extensions, some desktops, etc) to maintain a -high-security assurance about the current state of some particular part -of the Ethereum state or verify the execution of a transaction. Although -full security is only possible for a full node, the light client -protocol allows light nodes processing about 1KB of data per 2 minutes -to receive data from the network about the parts of the state that are -of concern to them, and be sure that the data is correct provided that -the majority of miners are correctly following the protocol, and perhaps -even only provided that at least one honest verifying full node exists. - -Background: Patricia Merkle Trees -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -All substantial quantities of data in Ethereum are stored in a data -structure known as the `Patricia Merkle -tree `__, -a tree structure where each node in the tree is the hash of its -children. Each set of key/value pairs maps to a unique root hash, and -only a small subset of nodes is needed to prove that a particular -key/value combination is in the tree corresponding to a particular root -hash. - -.. figure:: http://vitalik.ca/files/spv.png - :alt: - -The size complexity of a Merkle proof scales linearly with the height of -a tree; because each child in a tree has a particular number of children -(in our case, up to 17), this means that the size complexity of a Merkle -proof is logarithmic in the quantity of data stored. This means that, -even if the entire state tree is a few gigabytes in size, if a node -receives a state root from a trusted source that node has the ability to -know with full certainty the validity of any information with the tree -by only downloading a few kilobytes of data in a proof. - -An SPV proof of a node in a Patricia tree simply consists of the -complete subset of tree nodes that were processed in order to access it -(or, more specifically, the tree nodes that needed to be looked up in a -reverse-hash-lookup database). In a simple implementation of a Patricia -tree, retrieving the value associated with a particular key requires -descending the hash tree, constantly looking up nodes in the database by -their hashes, until you eventually reach the final leaf node; a simple -algorithm for producing an SPV proof is to simply run this naive -algorithm, and record all of the database lookups that were made. SPV -verification consists of running the naive lookup algorithm but pointing -it to a custom database populated only with the nodes in the SPV proof; -if there is a "node not found" error, then the proof is invalid. - -Principles ----------- - -In Ethereum, a light client can be viewed as a client that downloads -block headers by default, and verifies only a small portion of what -needs to be verified, using a distributed hash table as a database for -trie nodes in place of its local hard drive. For a "partially light -client", which processes everything but is constrained by hard drive -space and so stores almost nothing, swapping out a database read with a -DHT get request is by itself sufficient to meet the requirements. -Indeed, all "full clients" except for archive nodes (intended to be run -by businesses, block explorers, etc) will eventually be set up as -"partially light clients" with respect to all history older than a few -thousand blocks. However, what we are also interested in supporting is -*fully* light clients, which never even process most transactions. -Formally, we can say that *all* measures of a full light client are -bounded by a sublinear function of the number of transactions in a block -- in most cases, the protocols below work for a bound of O(log(n)), -though one particular mechanism works only for ~O(sqrt(n)). - -Some use cases for a fully light client, and how the light client meets -those use cases, include: - -- A light client wants to know the state of an account (nonce, balance, - code or storage index) at a particular time. The light client can - simply recursively download trie nodes from the state root until it - gets to the desired value. -- A light client wants to check that a transaction was confirmed. The - light client can simply ask the network for the index and block - number of that transaction, and recursively download transaction trie - nodes to check for availability. -- Light clients want to collectively validate a block. Each light - client ``C[i]`` chooses one transaction index ``i`` with transaction - ``T[i]`` (with corresponding receipt ``R[i]``) and does the - following: - - - Initiate the state with state root ``R[i-1].medstate`` and - ``R[i-1].gas_used`` (if ``i = 0`` use the parent endstate and 0 - ``gas_used``) - - Process transaction ``T[i]`` - - Check that the resulting state root is ``R[i].medstate`` and the - gas\_used is ``R[i].gas_used`` - - Check that the set of logs and bloom produced matches - ``R[i].logs`` and ``R[i].logbloom`` - - Checks that the bloom is a subset of the block header-level bloom - (this detects block header-level blooms with false negatives); - then pick a few random indices of the block header-level bloom - where that bloom contains a 1 and ask other nodes for a - transaction-level bloom that contains a 1 at that index, rejecting - the block if no response is given (this detects block header-level - blooms with false positives) - -- Light clients want to "watch" for events that are logged. The - protocol here is the following: - - - A light client gets all block headers, checks for block headers - that contain bloom filters that match one of a desired list of - addresses or topics that the light client is interested in - - Upon finding a potentially matching block header, the light client - downloads all transaction receipts, checks them for transactions - whose bloom filters match - - Upon finding a potentially matching transaction, the light client - checks its actual log RLP, and sees if it actually matches - -The first three light client protocols require a logarithmic amount of -data access and computation; the fourth requires ~O(sqrt(N)) since bloom -filters are only a two-level structure, although this can be improved to -O(log(N)) if the light client is willing to rely on multiple providers -to point to "interesting" transaction indices and decommission providers -if they are revealed to have missed a transaction. The first protocol is -useful to simply check up on state, and the second in consumer-merchant -scenarios to check that a transaction was validated. The third protocol -allows Ethereum light clients to collectively validate blocks with a -very low degree of trust. In Bitcoin, for example, a miner can create a -block that gives the miner an excessive amount of transaction fees, and -there would be no way for light nodes to detect this themselves, or upon -seeing an honest full node detect it verify a proof of invalidity. In -Ethereum, if a block is invalid, it must contain an invalid state -transition at some index, and so a light client that happens to be -verifying that index can see that something is wrong, either because the -proof step does not check out, or because data is unavailable, and that -client can then raise the alarm. - -The fourth protocol is useful in cases where a dapp wants to keep track -of some kind of events that need to be efficiently verifiable, but which -do not need to be part of the permanent state; an example is a -decentralized exchange logging trades or a wallet logging transactions -(note that the light client protocol will need to be augmented with -header-level coinbase and uncle checks for this to work fully with -mining accounts). In Bitcoin terminology, ``LOG`` can be viewed as a -pure "proof of publication" opcode. diff --git a/old-docs-for-reference/main-wiki.rst/Middleware-and-Dapp-Project-Ideas.rst b/old-docs-for-reference/main-wiki.rst/Middleware-and-Dapp-Project-Ideas.rst deleted file mode 100644 index a4cda8d..0000000 --- a/old-docs-for-reference/main-wiki.rst/Middleware-and-Dapp-Project-Ideas.rst +++ /dev/null @@ -1,279 +0,0 @@ -This page describes some ideas that I (Vitalik) have that I would like -to see implemented, but do not have time for myself. If anyone wants -advice on how to implement them feel free to ping me at any time, or -just start yourself. - -Data Feed -~~~~~~~~~ - -The core idea behind a data feed is simple: a data feed is a contract -with an administrator that maintains a key-value store, where the keys -represent what data is stored (eg. "BTC/USD") and the values represent -the value that the administrator believes the variable currently is in -the real world (eg. 235). A simple data feed contract can be found `in -the standardized contract APIs -repository `__; -it has a ``set`` function which allows its administrator to set the -value for a particular key, and a ``get`` function which allows anyone -to get the value for a particular key; that particular contract also -allows the administrator to set a fee in ether. - -Regarding fee setting, note that you should not set the fee too high as -otherwise it's possible at medium cost to create a "caching passthrough -contract": essentially, the smart contract equivalent of piracy, and -there's no way to prevent that without compromising the flexibility that -makes Ethereum Ethereum; a fee of around 1-10 finney should be fair and -work well if you do wish to charge. - -The way that you would implement the server side code is simple. In -pseudocode, you can implement it as a separate daemon that accesses an -api: - -:: - - keys = [("BTC/USD", "http://my_exchange.com/api/BTCUSD?password=12345"), - ("CHF/USD", "http://my_exchange.com/api/CHFUSD?password=12345"), - ("temperature:Seattle", "http://my_weather_network.com/api/temperature/Seattle?password=12346"), - ... ] - for key, url in keys: - try: - value = json.loads(open(url))["value"] - ethereum.send_transaction(ethereum.get_nonce(ethereum.my_address), ethereum.get_gasprice(), - 200000, MY_DATAFEED_CONTRACT, 0, MY_DATAFEED_ABI.encode('set', [key, value]) - except: - pass - -(Note: the above is pseudocode; not all of the above methods are -available in pyethereum quite yet). - -If you control: - -- An exchange or other website that has access to price feed or index - data -- A weather network -- A site that lists results of real-life events -- A service that KYCs people and assigns them unique identity tokens -- Any other data repository - -Then the Ethereum ecosystem will benefit from you publishing a data feed -contract on the Ethereum blockchain. - -A closely related idea is an **HTTP getter passthrough contract**. -Essentially, the contract would have one method, ``get(string)``, that -would take a URL as an argument, and simply log the URL alongside the -address that asked for the get. A server daemon would make a curl -request to the URL, and call the ``passthroughCallback(string)`` method -of the sender address with the output. Note that multiple daemons -running in this form could be called in multisig fashion if desired. - -Web of trust -~~~~~~~~~~~~ - -Reputation and credit scores are potentially a very powerful economic -lubricant in modern society, allowing us to easily tell reliable from -unreliable parties, and are even more important in a decentralized world -where centralized curation is unavailable and many classes of regulation -become more difficult to enforce. The question of "can this user be -trusted?" is approximated with a simple and easy-to-understand number. - -Currently, such systems are actively being looked into and adopted by -private companies particularly in the "sharing economy": - -.. raw:: html - -
- -|image0| - -.. raw:: html - -
- -And even governments: - -.. raw:: html - -
- -|image1| - -.. raw:: html - -
- -However, if we want to create a globally accessible system, centralized -credit scores are arguably insufficient: not everyone in the world will -be willing to trust a particular entity to provide accurate and fair -credit scores, particularly in international cases where there are large -political differences. Hence, while centralized credit scores may work -in particular closed environments, in an international trade context it -would be more ideal to have a global framework that allows specialized -scoring agencies to exist, but which allows recipients to choose which -ones they "listen" to, and even combine their scores. - -A highly effective solution to this problem, which has existed in -academia and the public for over a decade, uses the "web of trust" -route: essentially, instead of trying to achieve a single universal -score for everyone, provide a way for each person to score anyone else -from their own point of view. This is accomplished through the trust -transitivity heuristic: if A trusts B, and B trusts C, then to some -degree that's cause for A to trust C. In some ways, centralized credit -scores are a special case of this: everyone trusts the central agency -(in theory), the central agency assigns people trust ratings, and so -that's how much everyone is induced to trust everyone else. However, the -decentralized approach is more general, and ideally allows us to take -into account *all* "chains of trust" between two people, and not just -the ones that flow through a particular centralized gateway. - -.. figure:: http://vitalik.ca/files/wot_centralized_and_decentralized.png?1 - :alt: - -One example of an algorithm that does this well is the `Advogato trust -metric `__, a trust score -scheme based on -`max-flow `__. - -A useful project would be to create an implementation of such a system -on Ethereum, and create a dapp by which anyone can register an identity, -and register trust scores for other identities. Then, create a -decentralized cloud computing service by which anyone can query "provide -a proof, consisting of a list of trust paths, showing the Advogato trust -score from A to B" and anyone can reply in exchange for a micropayment -(or perhaps create a server that does it for free, and convince a -charity to subsidize it); if user A wants to know "what is B's trust -score", they can make this query, receive the result, verify the proof, -and then display it. - -This system could then be used by many other dapps on Ethereum, -including financial contract using price feeds and arbitration. - -Financial Derivatives Market -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Essentially, a polished, working dapp that allows users to make options -on any Ethereum asset, and derivatives (eg. CFDs) on any Ethereum price -feed. This should support "multisig price feeds": choosing multiple data -feed contract addresses that support a particular ticker symbol, and -taking the median of them, so as to remove reliance on any single party. - -Supported actions should ideally include: - -- Entering into CFDs with other parties on any price index, settling in - any standards-compatible currency or asset (though perhaps start with - ETH) -- Options between any two assets (though perhaps start with - asset<->ETH) -- Plain old regular asset exchange -- An order book for all of the above - -RANDAO -~~~~~~ - -Essentially, -`this `__. -Set it up as a decentralized service which any lottery or other -randomness-based game can use; also, build a "full node software" -package/plugin which facilitates participating in the RANDAO by -providing random numbers. - -Interface with national ID -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Create a system, relying on trusting no one other than the original -issuer, by which users with electronic identities (eg. Estonian digital -ID, other electronic passports, crypto KYC schemes, etc) can prove to -the Ethereum blockchain that they have that particular ID. Note that -this can be plugged into the WoT by, eg, creating a contract which -trusts everyone who has an Estonian digital ID with score 1. - -Zero knowledge proofs -~~~~~~~~~~~~~~~~~~~~~ - -Create multiple compatible implementations of a ZK-SNARK protocol. - -Ultrahard KDFs for brainwallets -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A decentralized paid cloud computing service for brainwallet -computations, combined with a client-side solution, in order to -implement my proposal for ultra-secure brainwallets using -blind-outsourceable ultrahard KDFs: -https://blog.ethereum.org/2014/10/23/information-theoretic-account-secure-brainwallets/ - -Estonia ID integration -~~~~~~~~~~~~~~~~~~~~~~ - -Create a system which integrates the Estonian digital ID system into -Ethereum; essentially, create a registry where someone can link their -address to a particular Estonian digital ID by signing a transaction -with their ID. The registry should cryptographically verify that the -signature is valid and that it matches a particular ID, and should then -store a mapping, eg. ``address -> (first name, last name, number)`` - -Some developer resources that can help with this include: - -- http://eid.eesti.ee/index.php/Authenticating\_in\_web\_applications -- https://e-estonia.com/e-residents/for-developers/ -- https://sk.ee/en/services/testcard/ -- http://id.ee/index.php?id=30469 - -Security Deposit-backed Conditional Hashcash -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The key piece of technology that later spawned the advent of blockchains -starting with Bitcoin, proof of work, was originally devised for quite a -different application: email spam prevention. In order to send an email -that would be viewed by recipients' email interfaces, users would need -to complete a certain amount of computational work on their computers -that could quickly be verified. This would impose a small cost in -electricity and CPU power to sending an email (say, $0.01) that would in -theory be no problem for ordinary messages, but would be so expensive as -to make spam no longer worth it. In practice, this idea never succeeded, -in large part because people did not want to pay for their email and -because it would only lead to spammers paying more in order to send more -well-crafted emails to fewer parties, which would be more likely to -receive attention because users think that they already passed the proof -of work filter. - -Here, I propose a proof of stake twist on the algorithm that would solve -this problem. The key insight is that instead of making the sender -*always* pay the cost, we make the cost a security deposit, and the -recipient has the right, only if they wish, to destroy the security -deposit at no benefit to themselves (in an actual implementation, -"destroy" will hopefully mean something like "donate to protocol -developers"). Ordinary "useful" messages would get through unscathed, -and spam would be punished in proportion to the percentage of people -that find it scammy. The conditional nature of the protocol can -theoretically allow the deposits to be increased much higher than the -cost of proof of work; deposits of $1 or even higher are quite -reasonable. - -There are two possible extensions to this idea: - -1. Use techniques similar to `anti-pre-revelation - games `__ - (or possibly other techniques) to allow users to destroy other users' - security deposits (either probabilistically or fully) without the - victim knowing who did it. This allows the mechanism to be used more - effectively in intra-organizational and social situations, so that - you can punish people for being annoying without extra-protocol - repercussions. Aside from information-theoretic strategies, there may - be routes to doing this using Chaumian blinding schemes, - cryptographic accumulators and/or zk-SNARK proofs; the goal to target - would be in a scenario with one sender and N recipients, with the - sender having a deposit of $NX, giving each recipient the right to - destroy $X exactly once without revealing which one of the N they - are; the main challenge is the sender gleaning this information by - simulating the process of each single recipient destroying their - deposit and seeing which one(s) fail, and so private information on - the recipients' part and perhaps even an interactive protocol is - required. -2. Have different levels of deposits, where higher levels of deposits - can be used to signal more importance/urgency in the interface; at - the highest levels, one could imagine a deposit of $500 leading to - one's phone ringing maximally loudly whereas a deposit of $0.1 would - only lead to an email appearing next time one opens one's mailbox. - -.. |image0| image:: http://www.kellydessaint.com/wp-content/uploads/2014/08/lyft_ratings3.jpg -.. |image1| image:: https://www.privateinternetaccess.com/blog/wp-content/uploads/2015/10/SesameCredit.jpg - :target: https://www.privateinternetaccess.com/blog/2015/10/in-china-your-credit-score-is-now-affected-by-your-political-opinions-and-your-friends-political-opinions/ diff --git a/old-docs-for-reference/main-wiki.rst/Mining.rst b/old-docs-for-reference/main-wiki.rst/Mining.rst deleted file mode 100644 index 824e429..0000000 --- a/old-docs-for-reference/main-wiki.rst/Mining.rst +++ /dev/null @@ -1,168 +0,0 @@ -Introduction -============ - -The word mining originates in the context of the gold analogy for crypto -currencies. Gold or precious metals are scarce, so are digital tokens, -and the only way to increase the total volume is through mining it. This -is appropriate to the extent that in Ethereum too, the only mode of -issuance post launch is via the mining. Unlike these examples however, -mining is also the way to secure the network by creating, verifying, -publishing and propagating blocks in the blockchain. - -- Mining Ether = Securing the network = verify computation - -So what is mining anyway? -------------------------- - -Ethereum Frontier like all blockchain technologies uses an -incentive-driven model of security. Consensus is based on choosing the -block with the highest total difficulty. Miners produce blocks which the -others check for validity. Among other well-formedness criteria, a block -is only valid if it contains **proof of work** (PoW) of a given -**difficulty**. Note that in Ethereum 1.1, this is likely gonna be -replaced by a **proof of stake** model. - -[The proof of work algorithm used is called -`Ethash `__ (a modified -version of -`Dagger-Hashimoto `__ -involves finding a nonce input to the algorithm so that the result is -below a certain threshold depending on the difficulty. The point in PoW -algorithms is that there is no better strategy to find such a nonce than -enumerating the possibilities while verification of a solution is -trivial and cheap. If outputs have a uniform distribution, then we can -guarantee that on average the time needed to find a nonce depends on the -difficulty threshold, making it possible to control the time of finding -a new block just by manipulating difficulty. - -The difficulty dynamically adjusts so that on average one block is -produced by the entire network every 12 seconds (ie., 12 s block time). -This heartbeat basically punctuates the synchronisation of system state -and guarantees that maintaining a fork (to allow double spend) or -rewriting history is impossible unless the attacker possesses more than -half of the network mining power (so called 51% attack). - -Any node participating in the network can be a miner and their expected -revenue from mining will be directly proportional to their (relative) -mining power or **hashrate**, ie., number of nonces tried per second -normalised by the total hashrate of the network. - -Ethash PoW is memory hard, making it basically ASIC resistant. This -basically means that calculating the PoW requires choosing subsets of a -fixed resource dependent on the nonce and block header. This resource (a -few gigabyte size data) is called a **DAG**. The -`DAG `__ is totally -different every 30000 blocks (a 100 hour window, called an **epoch**) -and takes a while to generate. Since the DAG only depends on block -height, it can be pregenerated but if its not, the client need to wait -the end of this process to produce a block. Until clients actually -precache dags ahead of time the network may experience a massive block -delay on each epoch transition. Note that the DAG does not need to be -generated for verifying the PoW essentially allowing for verification -with both low CPU and small memory. - -As a special case, when you start up your node from scratch, mining will -only start once the DAG is built for the current epoch. - -Mining Rewards --------------- - -Note that mining 'real' Ether will start with the Frontier release. On -the Olympics testnet, the `Frontier -pre-release `__, the ether -mined have no value (but see `Olympic -rewards `__). - -The successful PoW miner of the winning block receives: \* A **static -block reward** for the 'winning' block, consisting of exactly 5.0 Ether -\* All of the gas expended within the block, that is, all the gas -consumed by the execution of all the transactions in the block submitted -by the winning miner is compensated for by the senders. The gascost -incurred is credited to the miner's account as part of the consensus -protocoll. Over time, it's expected these will dwarf the static block -reward. - An extra reward for including Uncles as part of the block, in -the form of an extra 1/32 per Uncle included - -Uncles are stale blocks, ie with parent that are ancestors (max 6 blocks -back) of the including block. Valid uncles are rewarded in order to -neutralise the effect of network lag on the dispersion of mining -rewards, thereby increasing security. Uncles included in a block formed -by the successful PoW miner receive 7/8 of the static block reward = -4.375 ether A maximum of 2 uncles allowed per block. - -Ethash DAG ----------- - -Ethash uses a **DAG** (directed acyclic graph) for the proof of work -algorithm, this is generated for each **epoch**, i.e every 30000 blocks -(100 hours). The DAG takes a long time to generate. If clients only -generate it on demand, you may see a long wait at each epoch transition -before the first block of the new epoch is found. However, the DAG only -depends on block number, so it CAN and SHOULD be calculated in advance -to avoid long wait at each epoch transition. ``geth`` implements -automatic DAG generation and maintains two DAGS at a time for smooth -epoch transitions. Automatic DAG generation is turned on and off when -mining is controlled from the console. It is also turned on by default -if ``geth`` is launched with the ``--mine`` option. Note that clients -share a DAG resource, so if you are running multiple instances of any -client, make sure automatic dag generation is switched on in at most one -client. - -To generate the DAG for an arbitrary epoch: - -:: - - geth makedag - -For instance ``geth makedag 360000 ~/.ethash``. Note that ethash uses -``~/.ethash`` (Mac/Linux) or ``~/AppData/Ethash`` (Windows) for the DAG -so that it can shared between clients. - -The Algorithm -============= - -Our algorithm, `Ethash `__ -(previously known as Dagger-Hashimoto), is based around the provision of -a large, transient, randomly generated dataset which forms a DAG (the -Dagger-part), and attempting to solve a particular constraint on it, -partly determined through a block's header-hash. - -It is designed to hash a fast verifiability time within a slow CPU-only -environment, yet provide vast speed-ups for mining when provided with a -large amount of memory with high-bandwidth. The large memory -requirements mean that large-scale miners get comparatively little -super-linear benefit. The high bandwidth requirement means that a -speed-up from piling on many super-fast processing units sharing the -same memory gives little benefit over a single unit. - -Formal Requirements -------------------- - -TODO: Content from formal requirements doc. - -Design Decisions Taken ----------------------- - -TODO: Content from design decisions doc. - -Infrastructure Overview ------------------------ - -Mining will be accomplished in one of two ways: either on CPU (and -possibly the GPU, to be confirmed) with the Mist client or on the GPU -though a combination of the Ethereum daemon and -`sgminer `__. - -An sgminer module for Ethash is expected to be released at some point -during, but not necessarily before the Frontier Genesis. - -JSON-RPC --------- - -Communication between the external mining application and the Ethereum -daemon for work provision and submission happens through the JSON-RPC -API. Two RPC functions are provided; ``eth_getWork`` and -``eth_submitWork``. - -These are formally documented on the `JSON-RPC -API `__ wiki article. diff --git a/old-docs-for-reference/main-wiki.rst/Mix-Features.rst b/old-docs-for-reference/main-wiki.rst/Mix-Features.rst deleted file mode 100644 index d707a96..0000000 --- a/old-docs-for-reference/main-wiki.rst/Mix-Features.rst +++ /dev/null @@ -1,219 +0,0 @@ -**OUTDATED** *This document can contain outdated information.* - -Block Mining -============ - -Hit ``File``->``New Project``. - -Type contract: - -.. code:: javascript - - contract Test { - } - -Hit ``File``->``Save``. - -Hit ``Deploy``->``Deploy 'Default'`` to deploy contract. - -Then for index.html: - -.. code:: html - - - - - - - number: - - - - -Hit ``File``->``Save``. - -In the HTML view, you'll see: - -:: - - number: 1 - -Hit ``Deploy``->``Mine``. - -The HTML view will update to: - -:: - - number: 2 - -Parameters in Contract Constructor -================================== - -Write a Contract containing parameters in the constructor: - -.. code:: javascript - - contract Test { - uint mem; - Test(uint _a, uint _b) { mem = _a; } - get() returns (uint) - { - return mem; - } - } - -Press ``F7`` => ``Edit State`` The transaction named 'Constructor' -should appear in the transaction lists. - -Press ``Edit`` (on ``Constructor``) This modal dialog should allow users -to fill in input parameters (\_a and \_b). - -Press ``+`` to add a new transaction. Select the function ``get`` and -save. - -Press ``F5`` (or run the current editing state if this is not the -default state). - -Verify that the return value of ``get`` is displayed and is this is the -good one => in the transaction log (column ``returned``). - -Deploy to Network -================= - -This feature allows users to deploy the current project as a dapp in the -main blockchain. This will deploy contracts and register front end -resources. - -The deployment process includes two steps: - **The Deployment of -contracts**: This step will deploy contracts in the main blockchain and -package front end resources of the current project. After this operation -the package (package.dapp) will be available inside the deployment -directory. - -- **The Registration of front end resources**: To render the dapp, the - Ethereum browser (Mist or AlethZero) needs to access this package. - This step will register the URL where the resources are stored. - -To Deploy your dapp, Please follow these instructions: - -Click on ``Deploy``, ``Deploy to Network``. This modal dialog displays -two parts, We will focus on the first part (Deployment) for now: - -| **The Deployment of contracts** - 4 Buttons: ``Help`` to access to the - WikiPage, ``Open Package Folder`` to open the deployment directory - (this button is only enable is the package is built), - ``Copy Base64 conversion to ClipBoard`` to copy the Base64 value of - the built package (this button is only enable is the package is - built), ``Exit`` to close this modal dialog. -| - ``Root Registrar address`` is the address of the root registrar - contract (used to link the dapp with resources. - - ``Account used to deploy`` allows users to select the Ethereum account - to use to deploy. - ``Amount of gas to use..`` is the amount of gas - that the deployment process will use to deploy contracts. - - ``Ethereum Application URL`` is the address that users should use in - Mist (or AlethZero) to access to the dapp. in italic, you can check - the formatted dapp URL (which will be used by the Ethereum browser) - (ex: eth/user1/app1). - ``Web Application Resources URL`` is the URL - where the front resources (html/js/...) will be stored. - 1 button to - start the deployment process (The checkbox ``Deploy Contract(s)`` is - disabled and checked if this is the first time the contract is - deployed. If not you can choose to repackage the resources without - redeploying the contract by unchecking this option). - -Click on ``Deploy contract(s) and Package resources files`` (last -button) and the deployment is executed. Then many options/actions will -be enabled: - ``Open Package Folder``, -``Copy Base64 conversion to ClipBoard``, ``Deploy Contract(s)`` - All -inputs associated with the second step. - -**Host your web application** - -There are many places where to host front end resources, you just need -to find a web server. One other way (and very easy way) could be to use -the pastebin.com service: - Follow the first deployment step to deploy -contract(s). - The ``Copy Base64 conversion to ClipBoard`` icon will be -enable (on top of the modal dialog), click on this icon to copy the -Base64 content into the clipboard. - Go to pastebin.com and paste the -content into the ``New Paste`` input. Then click on -``Submit'. - Go through the Captcha. - Copy the address targeted by the link``\ Raw\ ``(on the top of the page). - Use this address in the``\ Web -Application Resources URL\` field. - -**Registration of front end resources** - ``URL Hint contract address`` -is the address of the contract which is used to store the URL where the -resources are. - ``Web Application Resources URL`` is the URL from where -the Ethereum browser will retrieve resources. - -Click on ``Register hosted Web Application`` and Mix will register the -front end resources on the Ethereum network. - -Users can now use Mist or AlethZero to access to the dapp, using the -Ethereum URL (ex: eth/user1/app1). - -Account Management -================== - -When a new state is created, it is possible to add new accounts which -can be used to send transaction. It is not possible to delete an account -if this one is used by a transaction. - -By default, one account is created, this account will be used to deploy -standards contract like ``Config`` and ``NameReg`` but can also be used -in other transactions. - -For each created account users have to specify a balance. When users -start to debugging, the state will be initialized with all the -configured accounts/balances. - -When a transaction is edited, users can select which account to set as -the sender. - -Logs Window -=========== - -Clicking on the header status pane will open a pane which displays all -logs generated by Mix. There are 3 log levels: info, warning, error. -Those logs comes from different part of Mix: - ``JavaScript`` displays -logs coming from the Web preview, it shows error messages generated by -the JavaScript engine and messages generated by the command -``console.log('...')``. - ``Run`` displays logs coming from the -execution of transactions. - ``State`` displays logs coming from -directly from the state (State alteration, New block added). - -``Compilation`` displays logs generated by an error when Mix is trying -to compile contracts. - -On the header are several actions: - Clear the content of this window. - -Copy the content to the Clipboard. - Select which log type to display (4 -buttons). - Use the text input to filter displayed logs. - -Auto-completion for solidity source -=================================== - -Auto-completion in Mix is based on the code mirror plugins show-hint.js -and anyword-hint.js (Not semantic) It displays: - Solidity token -(currency, keywords, stdContract, Time, Types). - Contract Name. - -Functions Name. - Words that are in the nearby code. - -Error messages -============== - -When running a bunch of transactions, several error might happen. One of -the common error is that the current account does not have enough ether -to execute a transaction. Users should be aware of that and the status -panel should display the amount of gas needed, and the current amount of -ether that the user has given for this transaction. Other important -error messages will be displayed here. - -Highlight secondary error locations -=================================== - -If the current compilation error has secondary errors locations Mix -shows those secondary errors. In each secondary errors Mix shows where -(document) the primary error is. diff --git a/old-docs-for-reference/main-wiki.rst/Mix-The-DApp-IDE.rst b/old-docs-for-reference/main-wiki.rst/Mix-The-DApp-IDE.rst deleted file mode 100644 index 05d2fb2..0000000 --- a/old-docs-for-reference/main-wiki.rst/Mix-The-DApp-IDE.rst +++ /dev/null @@ -1,275 +0,0 @@ -Welcome to Mix IDE! -=================== - -This guide provides a very simple and quick introduction to the Mix IDE -workflow by walking you through the creation of a simple dapp. Once you -are done with this tutorial, you will have a general knowledge of how to -create and run applications in the IDE. - -Note that the software is in still in proof-of-concept state. Things are -changing rapidly and this tutorial might not be up to date. If that is -the case `please open an -issue `__ or `edit the -wiki `__. - -Getting started. ----------------- - -This tutorial assumes you have `C++ Ethereum -installed `__. If this is -the case, then Mix is already installed. - -Creating a new project ----------------------- - -Let's create a simple dapp that will allow user to store and query -personal movie ratings. - -In the IDE, choose ``File > New Project``. Enter the project name -"MovieRatings" and a path for the project file. To the left there is a -project items list with two items added by default: Sample and -index.html. Contract contains -`Solidity `__ -contract code, and index.html is for the front-end. You can add new -contract files to the project using file menu. All files will be copied -to the project directory. By default a sample contract is created. - -Select Sample and enter the text for the rating contract: - -.. code:: js - - contract Rating { - function setRating(bytes32 _key, uint256 _value) { - ratings[_key] = _value; - } - mapping (bytes32 => uint256) public ratings; - } - -Check `Solidity -tutorial `__ -for solidity reference. - -Now select ``index.html`` and enter the following html code: - -.. code:: html - - - - - - - -

Ratings

-
- Store: - - - -
-
- Query: - -
-
- - - -Note that Mix exposes the following objects into the global window -context: \* -```web3`` `__ -- Ethereum JavaScript API - -- ``contracts`` - A collection of contract objects. A key to the - collection is the contract name. A value is an object with the - following properties: -- ``contract`` - Contract object instance (created as in - ``web3.eth.contract``) -- ``address`` - Contract address from the last deployed state (see - below) -- ``interface`` - Contract ABI - -Check the `JavaScript API -Reference `__ for -further information. - -Select ``File > Save`` to save project files. You should see the web -preview in the web preview pane. - -Setting up scenario -------------------- - -Now we need to configure a scenario for debugging. Mix has its own -blockchain that is reset on each debugging session. Scenarios are used -to get the blockchain to a point where it is possible to make -transactions and calls to a contract. A scenario is defined by a -sequence of transactions that create dapp and all dependencies on the -blockchain and set up dapp initial storage. - -If the scenario panel on the right side is not open, open it by pressing -``F7`` or selecting ``Windows > Show right view`` from the menu. A -default scenario is already created (which contains the transaction -which deploy the Sample contract). We don't need this anymore. Click on -the green checkbox on the left side of the transaction. This will delete -the transaction on the next rebuild. The rebuild button is blinking it -means that the scenario needs to be rebuilt in order to apply changes. -Click on it. - -At this point we have a clean blockchain. Click on the icon "add -Transaction..." which is represented by a flying blue plane. Be sure to -have selected "Create Contract" and that the contract "Rating" is -selected. Apply changes. The contract is now deployed and you can use it -from the web preview. Let's create a new transaction. Click an "add -Transaction..." then select "Transact with Contract". The deployed -contract "Rating - O" should be selected, this is the one which has been -previously deployed. You want now to call the function "setRating". -Select the function and give some parameters (for instance Titanic for -the first parameter and an integer for the second). Apply changes. - -Now let's test out contract. Type "Titanic" in the web preview query -input and you should see the result returned. Enter a name and a rating -in store fields and click ``Save`` to add a new rating. Note that all -transactions and calls made to the contract during state deployment and -debugging session are recorded into the scenario panel to the right (you -can hide calls by unselecting the option "Scenario > Display calls" in -the mix menu). Now it is possible to debug a transaction. Expand one -transaction (by clicking on the arrow on the right side) and on "Debug -Transaction". - -Debugging ---------- - -Mix currently supports assembly level contract code debugging. Source -level debugging is a work in progress. - -Assembly level debugging -~~~~~~~~~~~~~~~~~~~~~~~~ - -Double-click a ``setRating`` transaction in the transaction log to debug -it. The VM assembly code is loaded into the assembly view and the -execution slider is reset to a first position. You can navigate the -execution using the slider and/or step buttons. At any execution point -the following information is available: - -- VM stack. -- Call stack - Grows when contract is calling into another contract. - Double click a stack frame to view the machine state in that frame -- Storage - Storage data associated with the contract -- Memory - Machine memory allocated up to this execution point -- Call data - Transaction or call parameters - -See the `Ethereum Yellow Paper `__ for VM -instruction description. - -Deployment to network ---------------------- - -This feature allows users to deploy the current project as a dapp in the -main blockchain. This will deploy contracts and register frontend -resources. - -The deployment process includes three steps: - -- **Deploy contract**: This step will deploy contracts in the main - blockchain. - -- **Package dapp**: This step is used to package and upload frontend - resources. - -- **Register**: To render the dapp, the Ethereum browser (Mist or - AlethZero) needs to access this package. This step will register the - URL where the resources are stored. - -To Deploy your dapp, Please follow these instructions: - -Click on ``Deploy``, ``Deploy to Network``. This modal dialog displays -three parts (see above): - -- **Deploy contract** - -- *Select Scenario* - -"Ethereum node URL" is the location where a node is running, there must -be a node running in order to initiate deployment. - -"Pick Scenario to deploy" is a mandatory step. Mix will execute -transactions that are in the selected scenario (all transactions except -transactions that are not related to contract creation or contract -call). Mix will display all the transactions in the panel below with all -associated input parameters. - -"Gas Used": depending on the selected scenario, Mix will display the -total gas used. - -- *Deploy Scenario* - -"Deployment account" allow selecting the account that Mix will use to -execute transactions. - -"Gas Price" shows the default gas price of the network. You can also -specify a different value. - -"Deployment cost": depending on the value of the gas price that you want -to use and the selected scenario. this will display the amount ether -that the deployment need. - -"Deployed Contract": before any deployment this part is empty. This will -be filled once the deployment is finished by all contract addresses that -have been created. - -"Verifications". This will shows the number of verifications (number of -blocks generated on top of the last block which contains the last -deployed transactions). Mix keep track of all the transactions. If one -is missing (unvalidated) it will be displayed in this panel. - -- **Package dapp** - -- *Generate local package* - -The action "Generate Package" will create the package.dapp in the -specified folder - -"Local package Url" the content of this field can be pasted directly in -AlethZero in order to use the dapp before uploading it. - -- *Upload and share package* - -This step has to be done outside of Mix. package.dapp file has to be -hosted by a server in order to be available by all users. - -"Copy Base64" will copy the base64 value of the package to the -clipboard. - -"Host in pastebin.com" will open pastebin.com in a browser (you can then -host your package as base64). - -- **Package dapp** - -"Root Registrar address" is the account address of the root registrar -contract - -"Http URL" is the url where resources are hosted (pastebin.com or -similar) - -"Ethereum URL" is the url that users will use in AlethZero or Mist to -access your dapp. - -"Formatted Ethereum URL" is the url that users will use in AlethZero or -Mist to access your dapp. - -"Gas Price" shows the default gas price of the network. You can also -specify a different value. - -"Registration Cost" will display the amount of ether you need to -register your dapp url. diff --git a/old-docs-for-reference/main-wiki.rst/Mix-improvement-proposal.rst b/old-docs-for-reference/main-wiki.rst/Mix-improvement-proposal.rst deleted file mode 100644 index d0b1cb1..0000000 --- a/old-docs-for-reference/main-wiki.rst/Mix-improvement-proposal.rst +++ /dev/null @@ -1,42 +0,0 @@ -how it currently looks, its working well for very simple scripts, but -its hard to impossible to use for any advanced javascript application, -using require.js, common.js, bower, npm, angualr.js, ember, canjs, -meteor or any more advanced js framework. As the current deploy method -forces you to do things in a simplistic way (linking ethereum.js, -contracts files and add the contract variable) - -This also makes it hard to test your application as the deploy process -is the one, which uploads the contracts as well and nobody want to -deploy its app and contracts without being able to thoroughly test them -on the main/test net beforehand. - -Additionally not all dapps use one or more contracts, but might want to -deploy contracts on the fly (like the wallet dapp) and need a simple way -to get the compiled contract code. - -So here a re my suggestions: - -- Deploy should only deploy the app files (with the possibility to - choose a to-deploy-folder), and can include the automated name reg - stuff as well - -- contracts should be deployed by right clicking them -> deploy - contract, which then asks where to deploy (testnet, mainnet) and - gives back the ABI and address (maybe in a - ``myContract-deployed.js``) - -- contracts should also be compiled with right click -> compile - contract, giving the compiled HEX string and ABI in an - ``myContract-compiled.js`` (or just use one ``myContract-mix.js``) - -- the files in the sidebar should show the folder structure and not - sort by type, as any advanced js application needs more than just an - index.html and js file. (folders are good ;) - -- the deployable file should be zip, not rlp so people can unpack it - easily and discover the content which will be deployed. This also - allows to understand it and write separate bundle scripts for them. - **(But, might anyway become obsolete with swarm)** - -I think this improvements, will allow for greater flexibility without -compromising the use of mix. diff --git a/old-docs-for-reference/main-wiki.rst/Morden.rst b/old-docs-for-reference/main-wiki.rst/Morden.rst deleted file mode 100644 index a6a997b..0000000 --- a/old-docs-for-reference/main-wiki.rst/Morden.rst +++ /dev/null @@ -1,90 +0,0 @@ -Morden is the first Ethereum alternative testnet. It is expected to -continue throughout the Frontier and Homestead era. - -Usage -~~~~~ - -TurboEthereum (C++) -^^^^^^^^^^^^^^^^^^^ - -This is supported natively on 0.9.93 and above. Pass the ``--morden`` -argument in when starting any of the clients. e.g.: - -:: - - > eth --morden - -Or, for AlethZero - -:: - - > alethzero --morden - -PyEthApp (Python client) -^^^^^^^^^^^^^^^^^^^^^^^^ - -PyEthApp supports the morden network from v1.0.5 onwards: - -:: - - > pyethapp --profile morden run - -geth (Go client) -^^^^^^^^^^^^^^^^ - -:: - - > geth --testnet - -Details -~~~~~~~ - -- Network Identity: **2** -- All parameters same as Frontier except: -- genesis.json (given below); -- Initial Account Nonce (``IAN``) is 2^20 (instead of 0 in all previous - networks). - - - All accounts in the state trie have nonce >= ``IAN``. - - Whenever an account is inserted into the state trie it is - initialised with nonce = ``IAN``. - -- Genesis block hash: - ``0cd786a2425d16f152c658316c423e6ce1181e15c3295826d7c9904cba9ce303`` -- Genesis state root: - ``f3f4696bbf3b3b07775128eb7a3763279a394e382130f27c21e70233e04946a9`` - -Seed Nodes -~~~~~~~~~~ - -- ``enode://e58d5e26b3b630496ec640f2530f3e7fa8a8c7dfe79d9e9c4aac80e3730132b869c852d3125204ab35bb1b1951f6f2d40996c1034fd8c5a69b383ee337f02ddc@92.51.165.126:30303`` - -genesis.json -~~~~~~~~~~~~ - -.. code:: json - - { - "nonce": "0x00006d6f7264656e", - "difficulty": "0x20000", - "mixhash": "0x00000000000000000000000000000000000000647572616c65787365646c6578", - "coinbase": "0x0000000000000000000000000000000000000000", - "timestamp": "0x00", - "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000", - "extraData": "0x", - "gasLimit": "0x2FEFD8", - "alloc": { - "0000000000000000000000000000000000000001": { "balance": "1" }, - "0000000000000000000000000000000000000002": { "balance": "1" }, - "0000000000000000000000000000000000000003": { "balance": "1" }, - "0000000000000000000000000000000000000004": { "balance": "1" }, - "102e61f5d8f9bc71d0ad4a084df4e65e05ce0e1c": { "balance": "1606938044258990275541962092341162602522202993782792835301376" } - } - } - -Getting Ether -~~~~~~~~~~~~~ - -One way to get Ether is by using the `Ethereum wei -faucet `__. Just type in your -account address and enjoy some free ether. diff --git a/old-docs-for-reference/main-wiki.rst/NatSpec-Determination.rst b/old-docs-for-reference/main-wiki.rst/NatSpec-Determination.rst deleted file mode 100644 index 8e0e495..0000000 --- a/old-docs-for-reference/main-wiki.rst/NatSpec-Determination.rst +++ /dev/null @@ -1,34 +0,0 @@ -Publishing and finding the [NatSpec] -(https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format) -documentation for a contract is an important part of the Ethereum -system. There are two pieces to this puzzle: the first is for a given -client to be able to determine, given a call to a contract, what a -**trustworthy** NatSpec documentation hash for the contract is; the -second is to find the actual NatSpec documentation body given its -content hash. - -Trusted Content Determination -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The former, trusted content determination, will ultimately be -accomplished through a sophisticated reputation system. In the meantime, -we (the Ethereum foundation) will maintain our own curated repository of -trusted NatSpec documentation hashes in a contract. The contract is -trivial, just providing a mapping from contract code hash to NatSpec -JSON file hash. It can be found -`here `__. -We, alone, will retain the key updating and adding entries to this -contract. - -This contract will have a specific address on the PoC-9 & Frontier -testnet, probably referenced from the Ethereum services contract. - -Content Publishing and Distribution -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The latter, content publishing and distribution, will ultimately be -accomplished through the "Swarm" subsystem or IPFS. Until then, we will -piggy back on the existing workaround for content-based publication and -distribution; the `URL -Hint `__ -system. diff --git a/old-docs-for-reference/main-wiki.rst/Natspec-Example.rst b/old-docs-for-reference/main-wiki.rst/Natspec-Example.rst deleted file mode 100644 index a4bb5e7..0000000 --- a/old-docs-for-reference/main-wiki.rst/Natspec-Example.rst +++ /dev/null @@ -1,75 +0,0 @@ -Introduction -============ - -This is intended as an example of proof of concept of the natspec -evaluation in Alethzero, the CPP client and as a showcase of the -functionality of Natspec comments. - -Steps -===== - -Create the natspec documentation --------------------------------- - -Open up alethzero client and type in the following contract that we will -use as an example - -:: - - contract test { - /// @notice Will multiply `a` by 7. - function multiply(uint a) returns(uint d) { - return a * 7; - } - } - -.. figure:: images/natspec1.png - :alt: Creating natspec in AZ - - Creating natspec in AZ - -Then press the ``Execute`` button in order to generate the contract -creation transaction. We can do that from the JSON Api too but we are -using AlethZero in order to create the natspec documentation from the -contract. Pressing the execute button will create a local database entry -(LevelDB) of a mapping of the contract's hash to the natspec -documentation. - -This is just a temporary solution to showcase the functionality of -natspec. The idea is for people to be able to retrieve natspec -documentations of contracts from a trusted authority which most users -can trust. - -Open up the example contract ----------------------------- - -|Opening up example contract| We will be using the JSON Api to try and -perform the only transaction that our example contract has defined in -its interface. Open up Alethzero's internal browser and type in the -following path to get to our example -``/path/to/cpp-ethereum/libjsqrc/ethereumjs/example/natspec_contract.html``. - -You should see a page similar to below. Press the button to start the -example. |Starting natspec example| ## Performing the transaction - -This is the interface our *application* has for the contract. Using the -textbox we can provide the input to the transaction and then execute it. - -Authentication --------------- - -At this final stage is where natspec actually comes into place. Each and -every transaction has an authentication stage. The natspec documentation -is what is provided to the user in order to notify him of the -transaction and query whether or not to go ahead with it. -|Authenticating natspec| - -As you can see from the picture below even if a contract's transaction -does not have any specific documentation we will still get a generic -popup message asking us whether or not we want to authenticate the -transaction. |Authenticating unknown transaction| - -.. |Opening up example contract| image:: images/natspec2.png -.. |Starting natspec example| image:: images/natspec3.png -.. |Authenticating natspec| image:: images/natspec4.png -.. |Authenticating unknown transaction| image:: images/natspec5.png diff --git a/old-docs-for-reference/main-wiki.rst/Network-Status.rst b/old-docs-for-reference/main-wiki.rst/Network-Status.rst deleted file mode 100644 index 586863b..0000000 --- a/old-docs-for-reference/main-wiki.rst/Network-Status.rst +++ /dev/null @@ -1,126 +0,0 @@ -Network Status Monitoring -========================= - -The `Ethereum (centralised) network status -monitor `__ (known sometimes as "eth-netstats") is -a web-based application to monitor the health of the testnet/mainnet -through a group of nodes. - -Listing -------- - -To list your node, you must install the client-side information relay, a -node module. Instructions given here work on Ubuntu (Mac OS X follow -same instructions, but sudo may be unnecessary). Other platforms vary -(please make sure that nodejs-legacy is also installed, otherwise some -modules might fail). - -Clone the git repo, then install pm2: - -:: - - git clone https://github.com/cubedro/eth-net-intelligence-api - cd eth-net-intelligence-api - npm install - sudo npm install -g pm2 - -Then edit the ``app.json`` file in it to configure for your node: - -- alter the value to the right of ``LISTENING_PORT`` to the Ethereum - listening port (default: 30303) -- alter the value to the right of ``INSTANCE_NAME`` to whatever you - wish to name your node; -- alter the value to the right of ``CONTACT_DETAILS`` if you wish to - share your contact details -- alter the value to the right of ``RPC_PORT`` to the rpc port for your - node (by default 8545 for both cpp and go); -- and alter the value to the right of ``WS_SECRET`` to the secret - (you'll have to get this off `the official skype - channel `__). - -Finally run the process with: - -:: - - pm2 start app.json - -Several commands are available: - -- ``pm2 list`` to display the process status; -- ``pm2 logs`` to display logs; -- ``pm2 gracefulReload node-app`` for a soft reload; -- ``pm2 stop node-app`` to stop the app; -- ``pm2 kill`` to kill the daemon. - -Updating -~~~~~~~~ - -In order to update you have to do the following: - ``git pull`` to pull -the latest version - ``sudo npm update`` to update the dependencies - -``pm2 gracefulReload node-app`` to reload the client - --------------- - -Auto-installation on a fresh Ubuntu install -------------------------------------------- - -Fetch and run the build shell. This will install everything you need: -latest Ethereum - CLI from develop branch (you can choose between eth or -geth), node.js, npm & pm2. - -.. code:: bash - - bash <(curl https://raw.githubusercontent.com/cubedro/eth-net-intelligence-api/master/bin/build.sh) - -Configuration -~~~~~~~~~~~~~ - -Configure the app modifying -`app.json `__. -Note that you have to modify the backup ``app.json`` (to allow you to -set your env vars without being rewritten when updating). - -.. code:: js - - "env": - { - "NODE_ENV" : "production", // tell the client we're in production environment - "RPC_HOST" : "localhost", // eth JSON-RPC host the default is 8545 - "RPC_PORT" : "8545", // eth JSON-RPC port - "LISTENING_PORT" : "30303", // eth listening port (only used for display) - "INSTANCE_NAME" : "", // whatever you wish to name your node - "CONTACT_DETAILS" : "", // add your contact details here if you wish (email/skype) - "WS_SERVER" : "wss://rpc.ethstats.net", // path to eth-netstats WebSockets api server - "WS_SECRET" : "", // WebSockets api server secret used for login - } - -Run -~~~ - -Run it using pm2: - -.. code:: bash - - cd ~/bin - pm2 start processes.json - -Ethereum (eth or geth) must be running with rpc enabled. - -:: - - geth --rpc - -the default port (if one is not specified) for rpc under geth is 8545 - -Updating -~~~~~~~~ - -To update the API client use the following command: - -.. code:: bash - - ~/bin/www/bin/update.sh - -It will stop the current netstats client processes, automatically detect -your Ethereum implementation and version, update it to the latest -develop build, update netstats client and reload the processes. diff --git a/old-docs-for-reference/main-wiki.rst/Node-discovery-protocol.rst b/old-docs-for-reference/main-wiki.rst/Node-discovery-protocol.rst deleted file mode 100644 index 289ce73..0000000 --- a/old-docs-for-reference/main-wiki.rst/Node-discovery-protocol.rst +++ /dev/null @@ -1,13 +0,0 @@ -In a nutshell: \* Aimed at discovering *RLPx nodes* to connect to \* -UDP-based RPC protocol -(`kademlia `__-like) \* Defines -4 packet types: *ping*, *pong*, *findnode* and *neighbors* - -See details at either: \* -`devp2p `__ repository's `node -discovery -protocol `__ -page \* `go-ethereum `__ -repository's `node discovery -protocol `__ -page diff --git a/old-docs-for-reference/main-wiki.rst/Open-positions-&-Schemes.rst b/old-docs-for-reference/main-wiki.rst/Open-positions-&-Schemes.rst deleted file mode 100644 index 6f85f88..0000000 --- a/old-docs-for-reference/main-wiki.rst/Open-positions-&-Schemes.rst +++ /dev/null @@ -1,78 +0,0 @@ -Full-time Roles -~~~~~~~~~~~~~~~ - -Ethereum has a number of full-time employee roles open. For the Berlin -team (concentrating mostly around the C++-based implementation and -development tools) you'll be based in Kreuzberg, Berlin in our central -office/hub/café location, for the Amsterdam team (concentrating mostly -around the Go-based implementation and the consumer software) you'll -work remotely for now. Roles include security, optimisation, networking -and helping make reality our advanced integrated blockchain development -environment. We are presently particularly interested in expanding our -team for the latter; if you have good knowledge of the Qt5 platform -including QtQuick & QML, then please get in touch with -``jobs@ethdev.com``. - -For more information on full time positions, see ``TODO: Aeron``. - -Hub-Invitation Scheme -~~~~~~~~~~~~~~~~~~~~~ - -If you have been working on an Ethereum/ÐΞV-related project, we would -love to hear from you. In addition to helping wherever we can with fixes -and advice, for promising non-profit, open-source projects where -considerable effort has clearly been invested we would like to invite -you to collaborate more closely at one of our holons/hubs. At present -there are two operational hubs: - -- **ÐΞV Berlin** in Kreuzberg (Berlin), Germany; -- **ÐΞV Amsterdam** near Museum Plein, Netherlands; -- **Ethereum Suisse** in Zug (near Zurich), Switzerland. - -Such an invitation will include travel costs, a small stipend for food -costs during the time and shared accommodation. You will have full -access to the hub resources during your stay and be free to work and -relax around other members of the local ÐΞV & Ethereum communities. - -Projects that are especially interesting to us are: - alternative -implementations of the protocol in esoteric languages; - legacy-system -(web back-end, but perhaps other frameworks/environments, too) -integrations; - education and adoption tools; - Ðapps & contracts that -do something novel; - Ðapps & contracts that do something well. - -If you believe you have such a project and would like to come visit us -for a while, let us know at ``visitus@ethdev.com``! - -Sponsoring Scheme -~~~~~~~~~~~~~~~~~ - -Additionally, for interesting projects, we would like to extend -financial support in the form of a small bursary. We consider all such -projects, as with the Hub Invitation Scheme. Bursary amounts vary from -the $1000s to the $10,000s, depending on the size, scope and outlook of -the project. - -If you believe you have such a project let us know at -``bursary@ethdev.com``, with a proposal for where you would like to take -the project and estimates of any expenses that might be involved in -taking it forward. - -FAQ -~~~ - -Q. I want to make a client in language XYZ. I haven't started yet but -was hoping you'd pay me a full developer's salary to do it. Can I have a -job? - -A. No. Our resources do not extend so far. We wish you luck with your -endeavour and if you get far would certainly invite you to our -collaborative environment in the above scheme. - -Q. I have an idea for a contract/Ðapp/integration/... Could I get some -money to fund its development? - -A. Ethereum/ÐΞV is not an accelerator, incubator or investment -operation. We only wish to lend a hand (financial and otherwise) to -those already engrossed in their project. As such our assistance schemes -are open only to those whose already have an established project that is -Ethereum-centric. diff --git a/old-docs-for-reference/main-wiki.rst/Parallel-Block-Downloads.rst b/old-docs-for-reference/main-wiki.rst/Parallel-Block-Downloads.rst deleted file mode 100644 index 7e6798b..0000000 --- a/old-docs-for-reference/main-wiki.rst/Parallel-Block-Downloads.rst +++ /dev/null @@ -1,47 +0,0 @@ -New network protocol & strategy. - -Goals -~~~~~ - -- Achieve parallel downloads of chain -- Introduce framework that can form basis of Swarm -- Minimise unnecessary block transfers - -Basic Overview -~~~~~~~~~~~~~~ - -- Two peers connect & say Hello. Hello includes the TD & hash of their - best block. -- The client with the worst TD asks peer for full chain of just block - hashes. -- Chain of hashes is stored in space shared by all peer connections, - and used as a "work pool". -- While there are hashes in the chain of hashes that we don't have in - our chain: -- Ask for N blocks from our peer using the hashes. Mark them as on - their way so we don't get them from another peer. - -Required Changes -~~~~~~~~~~~~~~~~ - -Network protocol: 33 - -Additional parameters to Hello: - ``TD``: Total Difficulty of the best -chain. Integer. - ``BestHash``: The hash of the best (i.e. highest TD) -known block. - ``GenesisHash``: The hash of the Genesis block. - -Additional Message types: - ``0x17``: ``GetBlockHashes`` [ ``hash`` : -``B_32``, ``maxBlocks``: ``P`` ]: Requests a ``BlockHashes`` message of -at most ``maxBlocks`` entries, of block hashes from the blockchain, -starting at the parent of block ``hash``. Does not *require* the peer to -give ``maxBlocks`` hashes - they could give somewhat fewer. - -``0x18``:``BlockHashes`` [ ``hash_0``: ``B_32``, ``hash_1``: ``B_32``, -.... ]: Gives a series of hashes of blocks (each the child of the next). -This implies that the blocks are ordered from youngest to oldest. - -``0x19``:``GetBlocks`` [ ``hash_0``: ``B_32``, ``hash_1``: ``B_32``, -.... ]: Requests a ``Blocks`` message detailing a number of blocks to be -sent, each referred to by a hash. Note: Don't expect that the peer -necessarily give you all these blocks in a single message - you might -have to re-request them. - -Remove Message types: - ``GetChain`` - ``NotInChain`` diff --git a/old-docs-for-reference/main-wiki.rst/Patricia-Tree.rst b/old-docs-for-reference/main-wiki.rst/Patricia-Tree.rst deleted file mode 100644 index 61fcf6f..0000000 --- a/old-docs-for-reference/main-wiki.rst/Patricia-Tree.rst +++ /dev/null @@ -1,238 +0,0 @@ -Merkle Patricia Tree Specification -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Merkle Patricia trees provide a cryptographically authenticated data -structure that can be used to store all (key, value) bindings, although -for the scope of this paper we are restricting keys and values to -strings (to remove this restriction, just use any serialization format -for other data types). They are fully deterministic, meaning that a -Patricia tree with the same (key,value) bindings is guaranteed to be -exactly the same down to the last byte and therefore have the same root -hash, provide the holy grail of O(log(n)) efficiency for inserts, -lookups and deletes, and are much easier to understand and code than -more complex comparison-based alternatives like red-black trees. - -Preamble: Basic Radix Trees -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In a basic radix tree, every node looks as follows: - -:: - - [ value, i0, i1 ... in] - -Where i0 ... in represent the symbols of the alphabet (often binary or -hex). value is the terminal value at the node, and the values in the i0 -... in slots are either NULL or pointers to (in our case, hashes of) -other nodes. This forms a basic (key, value) store; for example, if you -are interested in the value that is currently mapped to dog in the tree, -you would first convert dog into the alphabet (giving 646f67 if we're -using hex), and then descend down the tree following that path until at -the end of the path you read the value. That is, you would first look up -the root hash in a key/value store to get the root node, then look up -node 6 of the root node to get the node one level down, then look up -node 4 of that, then look up node 6 of that, and so on, until, once you -followed the path root -> 6 -> 4 -> 6 -> f -> 6 -> 7, you look up the -value of the node that you have and return the result. - -The update and delete operations for radix trees are simple, and can be -defined roughly as follows: - -:: - - def update(node,key,value): - if key == '': - curnode = db.get(node) if node else [ NULL ] * 17 - newnode = curnode.copy() - newnode['value'] = value - else: - curnode = db.get(node) if node else [ NULL ] * 17 - newnode = curnode.copy() - newindex = update(curnode[key[0]],key[1:],value) - newnode[key[0]] = newindex - db.put(hash(newnode),newnode) - return hash(newnode) - - def delete(node,key): - if key == '' or node is NULL: - return NULL - else: - curnode = db.get(node) - newnode = curnode.copy() - newindex = delete(curnode[key[0]],key[1:]) - newnode[key[0]] = newindex - if len(filter(x -> x is not NULL, newnode)) == 0: - return NULL - else: - db.put(hash(newnode),newnode) - return hash(newnode) - -The "Merkle" part of the radix tree arises in the fact that a -deterministic cryptographic hash of a node is used as the pointer to the -node, rather than some 32-bit or 64-bit memory location as might happen -in a more traditional tree implemented in C. This provides a form of -cryptographic authentication to the data structrure; if the root hash of -a given trie is publicly known, then anyone can provide a proof that the -trie has a given value at a specific key by providing the nodes going up -each step of the way. it is impossible for an attacker to provide a -proof of a (key, value) pair that does not exist since the root hash is -ultimately based on all hashes below it, so any modification would -change the root hash. - -However, radix trees have one major limitation: their inefficiency. If -you want to store just one (key,value) binding where the key is a few -hundred characters long, you will need over a kilobyte of extra space to -store one level per character, and each lookup or delete will take -hundreds of steps. The Patricia tree introduced here solves this issue. - -Specification: Compact encoding of hex sequence with optional terminator -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The traditional compact way of encoding a hex string is to convert it -into binary - that is, a string like 0f1248 would become three bytes -[15, 18, 72] (or in string representation -:raw-latex:`\x`0f:raw-latex:`\x`18H). However, this approach has one -slight problem: what if the length of the hex string is odd? In that -case, there is no way to distinguish between, say, 0f1248 and f1248. -Additionally, our application in the Merkle Patricia tree requires the -additional feature that a hex string can also have a special "terminator -symbol" at the end (denoted by the 'T'). A terminator symbol can occur -only once, and only at the end. An alternative way of thinking about -this to not think of there being a terminator symbol, but instead treat -bit specifying the existence of the terminator symbol as a bit -specifying that the given node encodes a final node, where the value is -an actual value, rather than the hash of yet another node. - -To solve both of these issues, we force the first nibble of the final -bytestream to encode two flags, specifying oddness of length (ignoring -the 'T' symbol) and terminator status; these are placed, respectively, -into the two lowest significant bits of the first nibble. In the case of -an even-length hex string, we must introduce a second nibble (of value -zero) to ensure the hex-string is even in length and thus is -representable by a whole number of bytes. Thus we construct the -following encoding: - -:: - - def compact_encode(hexarray): - term = 1 if hexarray[-1] == 16 else 0 - if term: hexarray = hexarray[:-1] - oddlen = len(hexarray) % 2 - flags = 2 * term + oddlen - if oddlen: - hexarray = [flags] + hexarray - else: - hexarray = [flags] + [0] + hexarray - // hexarray now has an even length whose first nibble is the flags. - o = '' - for i in range(0,len(hexarray),2): - o += chr(16 * hexarray[i] + hexarray[i+1]) - return o - -Examples: - -:: - - > [ 1, 2, 3, 4, 5 ] - '\x11\x23\x45' ( Here in python, '\x11#E' because of its displaying unicodes. ) - > [ 0, 1, 2, 3, 4, 5 ] - '\x00\x01\x23\x45' - > [ 0, 15, 1, 12, 11, 8, T ] - '\x20\x0f\x1c\xb8' - > [ 15, 1, 12, 11, 8, T ] - '\x3f\x1c\xb8' - -Main specification: Merkle Patricia Tree -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Merkle Patricia trees solve the inefficiency issue by adding some extra -complexity to the data structure. A node in a Merkle Patricia tree is -one of the following: - -1. NULL (represented as the empty string) -2. A two-item array ``[ key, v ]`` (aka kv node) -3. A 17-item array ``[ v0 ... v15, vt ]`` (aka diverge node) - -The idea is that in the event that there is a long path of nodes each -with only one element, we shortcut the descent by setting up a kv node -``[ key, value ]``, where the key gives the hexadecimal path to descend, -in the compact encoding described above, and the value is just the hash -of the node like in the standard radix tree. Also, we add another -conceptual change: internal nodes can no longer have values, only leaves -with no children of their own can; however, since to be fully generic we -want the key/value store to be able to store keys like 'dog' and 'doge' -at the same time, we simply add a terminator symbol (16) to the alphabet -so there is never a value "en-route" to another value. - -For a kv node, a two-item array ``[ key, v ]``, ``v`` can be a value or -a node. \* When ``v`` is a value, key must be the result of compact -encoding a nibbles list **with** terminator. \* When ``v`` is a node, -key must be the result of compact encoding a nibbles list **without** -terminator. - -For a diverge node, a 17-item array ``[ v0 ... v15, vt ]``, each item in -v0...v15 should always be a node or blank, and vt should always be a -value or blank. So to store a value in one item of v0...v15, we should -instead store a kv node, where k is the result of compact encoding an -empty nibbles list **with** terminator. - -Here is the extended code for getting a node in the Merkle Patricia -tree: - -:: - - def get_helper(node,key): - if key == []: return node - if node = '': return '' - curnode = rlp.decode(node if len(node) < 32 else db.get(node)) - if len(curnode) == 2: - (k2, v2) = curnode - k2 = compact_decode(k2) - if k2 == key[:len(k2)]: - return get(v2, key[len(k2):]) - else: - return '' - elif len(curnode) == 17: - return get_helper(curnode[key[0]],key[1:]) - - def get(node,key): - key2 = [] - for i in range(len(key)): - key2.push(int(ord(key) / 16)) - key2.push(ord(key) % 16) - key2.push(16) - return get_helper(node,key2) - -Example: suppose we had a tree containing the pairs ('dog', 'puppy'), -('horse', 'stallion'), ('do', 'verb'), ('doge', 'coin'). First, we -convert the keys over to hex format: - -:: - - [ 6, 4, 6, 15, 16 ] : 'verb' - [ 6, 4, 6, 15, 6, 7, 16 ] : 'puppy' - [ 6, 4, 6, 15, 6, 7, 6, 5, 16 ] : 'coin' - [ 6, 8, 6, 15, 7, 2, 7, 3, 6, 5, 16 ] : 'stallion' - -Now, we build the tree: - -:: - - ROOT: [ '\x16', A ] - A: [ '', '', '', '', B, '', '', '', C, '', '', '', '', '', '', '', '' ] - B: [ '\x00\x6f', D ] - D: [ '', '', '', '', '', '', E, '', '', '', '', '', '', '', '', '', 'verb' ] - E: [ '\x17', F ] - F: [ '', '', '', '', '', '', G, '', '', '', '', '', '', '', '', '', 'puppy' ] - G: [ '\x35', 'coin' ] - C: [ '\x20\x6f\x72\x73\x65', 'stallion' ] - -Where a node is referenced inside a node, what is included is -H(rlp.encode(x)) where H(x) = sha3(x) if len(x) >= 32 else x and -rlp.encode is the -`RLP `__ -encoding function. Note that when updating a trie, you will need to -store the key/value pair (sha3(x), x) in a persistent lookup table when -you create a node with length >= 32, but if the node is shorter than -that then you do not need to store anything when length < 32 for the -obvious reason that the function f(x) = x is reversible. diff --git a/old-docs-for-reference/main-wiki.rst/Poll-for-token-proposal-EIP-20.rst b/old-docs-for-reference/main-wiki.rst/Poll-for-token-proposal-EIP-20.rst deleted file mode 100644 index 9145df2..0000000 --- a/old-docs-for-reference/main-wiki.rst/Poll-for-token-proposal-EIP-20.rst +++ /dev/null @@ -1,22 +0,0 @@ -Poll for https://github.com/ethereum/EIPs/issues/20 - -github username \| IN \| OUT \| NextEIP\*? \| Comments -----------------\|----------------\|---------------\|-----------------------------------\|--------- -example \| Set1, identifier \| decimals, approve, unapprove, allowance -\| YES \| christianlundkvist\| Set1 \| decimals \| YES \| nmushegian \| -Set1 \| decimals \| YES \| joeykrug \| Set1, identifier \| ? \| ? \| -koeppelmann \| Set1, identifier \| ? \| ? \| Georgi87 \| Set1, -identifier \| decimals \| Yes \| niran \| Set1 \| decimals \| YES?\| -ethers \| Set1, identifier \| decimals \| YES \| simondlr \| Set1 \| -decimals \| YES \| frozeman \| Set1, decimals \| \| NO \| alexvandesande -\| Set1, decimals \| \| \| caktux \| Set1, decimals \| \| \| firecar96 -\| Set1 \| decimals, identifier \| YES \| - -- Set1 = balanceOf, transfer, transferFrom, totalSupply, approve, - unapprove, allowance -- "identifier" = - https://github.com/ethereum/EIPs/issues/20#issuecomment-158436720 and - the discussion -- NextEIP means should the OUT items be in separate EIP/s or be in - EIP20 itself but marked Optional. YES means separate EIP/s, NO means - keep in EIP20 and mark it Optional. diff --git a/old-docs-for-reference/main-wiki.rst/Problems.rst b/old-docs-for-reference/main-wiki.rst/Problems.rst deleted file mode 100644 index 78f0406..0000000 --- a/old-docs-for-reference/main-wiki.rst/Problems.rst +++ /dev/null @@ -1,1386 +0,0 @@ -The science of cryptography, which has existed to some degree for -millennia but in a formal and systematized form for less than fifty -years, can be most simply defined as the study of communication in an -adversarial environment. In a similar vein, we can define -cryptoeconomics as a field that goes one step further: the study of -economic interaction in an adversarial environment. To distinguish -itself from traditional economics, which certainly studies both economic -interaction and adversaries, cryptoeconomics generally focuses on -interactions that take place over network protocols. Particular domains -of cryptoeconomics include: - -- Online trust and reputation systems -- Cryptographic tokens / cryptocurrencies, and more generally digital - assets -- Self-executing "smart" contracts -- Consensus algorithms -- Anti-spam and anti-sybil attack algorithms -- Incentivized marketplaces for computational resources -- Decentralized systems for social welfare / mutual aid / basic income -- Decentralized governance (for both for-profit and non-profit - entities) - -The increasing prominence of cryptoeconomics in the last five years is -to a large extent the result of the growth of cryptocurrencies and -digital tokens, and brings a new, and interesting, dimension to -cryptography. While before cryptography was, by and large, a purely -computational and information-theoretic science, with strong guarantees -built on security assumptions that are close to absolute, once money -enters the picture the perfect world of mathematics must interact with a -much more messy reality of human social structures, economic incentives, -partial guarantees and known vulnerabilities that can only be mitigated, -and not outright removed. While a cryptographer is used to assumptions -of the form "this algorithm is guaranteed to be unbreakable provided -that these underlying math problems remain hard", the world of -cryptoeconomics must contend with fuzzy empirical factors such as the -difficulty of collusion attacks, the relative quantity of altruistic, -profit-seeking and anti-altruistic parties, the level of concentration -of different kinds of resources, and in some cases even sociocultural -circumstances. - -In traditional applied cryptography, security assumptions tend to look -something like this: - -1. No one can do more than 279 computational steps -2. Factoring is hard (ie. superpolynomial) -3. Taking nth roots modulo composites is hard -4. The elliptic curve discrete logarithm problem cannot be solved faster - than in 2n/2 time - -In cryptoeconomics, on the other hand, the basic security assumptions -that we depend on are, alongside the cryptographic assumptions, roughly -the following: - -1. No set of individuals that control more than 25% of all computational - resources is capable of colluding -2. No set of individuals that control more than 25% of all money is - capable of colluding -3. The amount of computation of a certain proof of work function that - can be accomplished with a given amount of money is not superlinear - beyond a point which is reasonably low -4. There exist a non-negligible number of altruists and a non-negligible - number of crazies or political opponents of the system, and the - majority of users can be reasonably modeled as being close to - economically rational -5. The number of users of a system is large, and users can appear or - disappear at any time, although at least some users are persistent -6. Censorship is impossible, and any two nodes can send messages to each - other relatively quickly. -7. It is trivial to generate a very large number of IP addresses, and - one can purchase an unlimited amount of network bandwidth -8. Many users are anonymous, so negative reputations and debts are close - to unenforceable - -There will also be additional security assumptions specific to certain -problems. Thus, quite often it will not even be possible to definitively -say that a certain protocol is secure or insecure or that a certain -problem has been solved. Rather, it will be necessary to create -solutions that are optimized for particular empirical and social -realities, and continue further and further optimizing them over time. - -Technology ----------- - -The decentralized consensus technology used in Bitcoin is impressive to -a very large extent because of its simplicity. A 30-year-old problem in -computer science was solved via a mechanism which is simple to -implement, and so simple to understand that even some semi-technical -teenagers can describe the entirety of how it works. However, at the -same time the technology in its current form is very limited. The -scalability in Bitcoin is very crude; the fact that every full node -needs to process every transaction is a large roadblock to the future -success of the platform, and a factor preventing its effective use in -micropayments (arguably the one place where it is the most useful). -Timestamping is flawed, and proof-of-computation algorithms are very -limited in the types of computation that they can support. The fact that -the original solution was so "easy", however, suggests that there is -still a large opportunity to improve, and there are a number of -directions in which improvement could be directed. - -1. Blockchain Scalability -~~~~~~~~~~~~~~~~~~~~~~~~~ - -One of the largest problems facing the cryptocurrency space today is the -issue of scalability. It is an often repeated claim that, while -mainstream payment networks process something like 2000 transactions per -second, in its current form the Bitcoin network can only process seven. -On a fundamental level, this is not strictly true; simply by changing -the block size limit parameter, Bitcoin can easily be made to support 70 -or even 7000 transactions per second. However, if Bitcoin does get to -that scale, we run into a problem: it becomes impossible for the average -user to run a full node, and full nodes become relegated only to that -small collection of businesses that can afford the resources. Because -mining only requires the block header, even miners can (and in practice -most do) mine without downloading the blockchain. - -The main concern with this is trust: if there are only a few entities -capable of running full nodes, then those entities can conspire and -agree to give themselves a large number of additional bitcoins, and -there would be no way for other users to see for themselves that a block -is invalid without processing an entire block themselves. Although such -a fraud may potentially be discovered after the fact, power dynamics may -create a situation where the default action is to simply go along with -the fraudulent chain (and authorities can create a climate of fear to -support such an action) and there is a coordination problem in switching -back. Thus, at the extreme, Bitcoin with 7000 transactions per second -has security properties that are essentially similar to a centralized -system like Paypal, whereas what we want is a system that handles 7000 -TPS with the same levels of decentralization that cryptocurrency -originally promised to offer. - -Ideally, a blockchain design should exist that works, and has similar -security properties to Bitcoin with regard to 51% attacks, that -functions even if no single node processes more than ``1/n`` of all -transactions where ``n`` can be scaled up to be as high as necessary, -although perhaps at the cost of linearly or quadratically growing -secondary inefficiencies and convergence concerns. This would allow the -blockchain architecture to process an arbitrarily high number of TPS but -at the same time retain the same level of decentralization that Satoshi -envisioned. - -**Problem**: create a blockchain design that maintains Bitcoin-like -security guarantees, but where the maximum size of the most powerful -node that needs to exist for the network to keep functioning is -substantially sublinear in the number of transactions. - -**Additional Assumptions and Requirements**: - -- There exist a large number of miners in the network -- Miners may be using specialized hardware or unspecialized hardware. - Specialized hardware should be assumed to be more powerful than - unspecialized hardware by a large (eg. 10000) constant factor at - specific tasks. -- Ordinary users will be using unspecialized hardware -- Ideally, after some number of blocks (perhaps logarithmic in the - total size of the network) every transaction should require 51% of - network hashpower to reverse. However, solutions where transactions - can pay very small fees for a lower "level" of security are - acceptable, though one should take care to avoid situations where an - attacker can profit by performing one attack to reverse very many - small transactions at the same time -- Ideally, the solution should work for and maintain as many properties - as possible of a generalized account-based blockchain (eg. Ethereum), - though solutions specific to currency, domain registrations or other - specialized use caes are acceptable - -2. Timestamping -~~~~~~~~~~~~~~~ - -An important property that Bitcoin needs to keep is that there should be -roughly one block generated every ten minutes; if a block is generated -every day, the payment system becomes too slow, and if a block is -generated every second there are serious centralization and network -efficiency concerns that would make the consensus system essentially -nonviable even assuming the absence of any attackers. To ensure this, -the Bitcoin network adjusts difficulty so that if blocks are produced -too quickly it becomes harder to mine a new block, and if blocks are -produced too slowly it becomes easier. - -However, this solution requires an important ingredient: the blockchain -must be aware of time. In order to solve this problem, Bitcoin requires -miners to submit a timestamp in each block, and nodes reject a block if -the block's timestamp is either (i) behind the median timestamp of the -previous eleven blocks, or (ii) more than 2 hours into the future, from -the point of view of the node's own internal clock. This algorithm is -good enough for Bitcoin, because time serves only the very limited -function of regulating the block creation rate over the long term, but -there are potential vulnerabilities in this approach, issues which may -compound in blockchains where time plays a more important role. - -**Problem**: create a distributed incentive-compatible system, whether -it is an overlay on top of a blockchain or its own blockchain, which -maintains the current time to high accuracy. - -**Additional Assumptions and Requirements** - -- All legitimate users have clocks in a normal distribution around some - "real" time with standard deviation 20 seconds. -- No two nodes are more than 20 seconds apart in terms of the amount of - time it takes for a message originating from one node to reach any - other node. -- The solution is allowed to rely on an existing concept of "N nodes"; - this would in practice be enforced with proof-of-stake or non-sybil - tokens (see #9). -- The system should continuously provide a time which is within 120s - (or less if possible) of the internal clock of >99% of honestly - participating nodes. Note that this also implies that the system - should be self-consistent to within about 190s. -- The system should exist without relying on any kind of proof-of-work. -- External systems may end up relying on this system; hence, it should - remain secure against attackers controlling < 25% of nodes regardless - of incentives. - -3. Arbitrary Proof of Computation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Perhaps the holy grail of the study zero-knowledge proofs is the concept -of an arbitrary proof of computation: given a program P with input I, -the challenge is to create a zero-knowledge proof that you ran P with -input I and received output O, such that the proof can be verified -quickly (ie. in polylogarithmic or ideally constant time) even if the -original computation took a very large number of steps to complete. In -an ideal setup, the proof would even hide the value of I, just proving -that you ran P with some output with result O, and if I needs to be made -public it can be embedded into the program. Such a primitive, if -possible, would have massive implications for cryptocurrency: - -1. The blockchain scalability problem would be much easier to solve. - Instead of miners publishing blocks containing a list of - transactions, they would be publishing a proof that they ran the - blockchain state updater with some list of transactions and produced - a certain output; thus, instead of transactions needing to be - verified by every node in the network, they could be processed by one - miner and then every other miner and user could quickly verify the - proof of computation and if the proof turns out correct they would - accept the new state. This is not a complete solution, because there - would still be a need to transmit data, but the problem would be much - easier with this powerful building block. -2. The blockchain privacy problem would be much easier to solve. The - blockchain scalability solution above would hide the details behind - individual transactions; it would only reveal the fact that all of - them are legitimate, so transactions would be hidden from everyone - but the sender and the receiver. -3. It would become computationally viable to use a Turing-complete - consensus network as a generic distributed cloud computing system; if - you have any computation you wanted done, you would be able to - publish the program for miners and miners would be able to run the - program for you and deliver the result alongside a proof of its - validity. - -There is a large amount of existing research on this topic, including a -protocol known as "SCIP" (Succinct Computational Integrity and Privacy) -that is already working in test environments, although with the -limitation that a trusted third party is required to initially set up -the keys; use of this prior work by both its original developers and -others is encouraged. - -**Problem**: create programs ``POC_PROVE(P,I) -> (O,Q)`` and -``POC_VERIFY(P,O,Q) -> { 0, 1 }`` such that ``POC_PROVE`` runs program -``P`` on input ``I`` and returns the program output ``O`` and a -proof-of-computation ``Q`` and ``POC_VERIFY`` takes ``P``, ``O`` and -``Q`` and outputs whether or not ``Q`` and ``O`` were legitimately -produced by the ``POC_PROVE`` algorithm using ``P``. - -**Requirements And Additional Assumptions** - -- The runtime of ``POC_PROVE`` should be in ``O(n*polylog(n))`` where - ``n`` is the number of steps required to run the program. -- The runtime of ``POC_VERIFY`` should be either constant or - logarithmic in the number of steps, and at most linear in the maximum - memory usage of the program. -- The protocol should require no trusted third parties. If TTPs are - required, the protocol should include a mechanism for simulating one - efficiently using secure multiparty computation. - -4. Code Obfuscation -~~~~~~~~~~~~~~~~~~~ - -For many years now we have known how to encrypt data. Simple, robust and -well-tested algorithms exist for both symmetric key encryption, where -the same key is needed to encrypt and decrypt, and public key -encryption, where the encryption key and decryption key are different -and one cannot be derived from the other. However, there is another kind -of encryption that can potentially be very useful, but for which we -currently have no viable algorithm: the encryption of programs. The holy -grail is to create an obfuscator ``O``, such that given any program P -the obfuscator can produce a second program ``O(P) = Q`` such that ``P`` -and ``Q`` return the same output if given the same input and, -importantly, ``Q`` reveals no information whatsoever about the internals -of ``P``. One can hide inside of ``Q`` a password, a secret encryption -key, or one can simply use ``Q`` to hide the proprietary workings of the -algorithm itself. - -In 2007, it was proven that perfect "black box" encryption is -impossible; essentially, the argument is that there is a difference -between having black-box access to a program and having the code to that -program, no matter how obfuscated, and one can construct certain classes -of programs that resist obfuscation. However, there is also a weaker -notion of obfuscation, known as indistinguishability obfuscation, that -appears to be quite possible. The definition of an indistinguishability -obfuscator ``O`` is that if you take two equivalent (ie. same inputs -> -same outputs) programs ``A`` and ``B`` and calculate ``O(A) = P`` and -``O(B) = Q``, then there is no computationally feasible way for an -outsider without access to ``A`` or ``B`` to tell whether ``P`` came -from ``A`` or ``B``. - -This type of obfuscation may seem more limited, but it is nevertheless -sufficient for many applications. For a heuristic argument why, consider -two programs ``F`` and ``G`` where ``F`` internally contains and simply -prints out that 32-byte string which is the hash of "12345", whereas G -actually computes the hash of "12345" and prints it out. By the -indistinguishability obfuscation definition, there is no computationally -feasible way to tell ``O(F)`` from ``O(G)`` apart. Hence, if one can -feasibly recover "12345" from ``O(G)``, then for ``O(G)`` and ``O(F)`` -to be indistinguishable one would also need to be able to feasibly -recover "12345" from ``O(F)`` - a feat which essentially entails -breaking the preimage resistance of a cryptographic hash function. - -Recently, a discovery was made by Craig Gentry, Amit Sahai et al on an -algorithm which uses a construction known as "multilinear jugsaw -puzzles" in order to accomplish this. Their algorithm, described here, -claims to satisfy the indistinguishability obfuscation property, -although at a high cost: the algorithm requires the use of fully -homomorphic encryption, a highly inefficient construction that incurs -roughly a one-billion-fold computational overhead. - -If this construction can be made better, the potential benefits are -massive. The most interesting possibility in the world of cryptocurrency -is the idea of an on-blockchain contract containing private information. -This basically allows for the scripting properties of Turing-complete -blockchain technologies, such as Ethereum, to be exported into any other -financial or non-financial system on the internet; for example, one can -imagine an Ethereum contract which contains a user's online banking -password, and if certain conditions of the contract are satisfied the -contract would initiate an HTTPS session with the bank, using some node -as an intermediary, and log into the bank account with the user's -password and make a specified withdrawal. Because the contract would be -obfuscated, there would be no way for the intermediary node, or any -other player in the blockchain, to modify the request in-transit or -determine the user's password. The same trick can be done with any other -website, or much more easily with a "dumb" blockchain such as Bitcoin. - -**Problem**: create a reasonably efficient indistinguishability -obfuscation algorithm. - -**Additional Assumptions and Requirements** - -- Successful attacks must have an expected runtime above 2^80 -- The algorithm should be sufficiently fast that a standard ECDSA - signature or an AES encryption should be feasible within 108 - computational steps (more specifically, 108 gas in the Ethereum VM) - -5. Hash-Based Cryptography -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -One of the looming threats on the horizon to cryptocurrency, and -cryptography in general, is the issue of quantum computers. Currently, -the problem does not seem too severe; all quantum computers are either -"adiabatic quantum computers", effective at only an extremely limited -set of problems and perhaps not even better than classical computers at -all, or machines with a very small number of qubits not capable of -factoring numbers higher than 35. In the future, however, quantum -computers may become much more powerful, and the recent revelations -around the activities of government agencies such as the NSA have -sparked fears, however unlikely, that the US military may control a -quantum computer already. With this in mind, the movement toward -quantum-proof cryptography has become a somewhat higher priority. - -To date, all quantum-proof schemes fall into one of two categories. -First, there are algorithms involving lattice-based constructions, -relying on the hardness of the problem of finding a linear combination -of vectors whose sum is much shorter than the length of any individual -member. These algorithms appear to be powerful, and relatively -efficient, but many distrust them because they rely on complicated -mathematical objects and relatively unproven assumptions. However, there -is also another class of algorithms that are quantum-proof: hash-based -algorithms. One example of this is the classic Lamport signature: create -a Merkle tree of 164 nodes (a figure chosen specifically to match 160 -bits of security), publish the root, and then have the signature of a -document be the combined Merkle tree proof of a subset of 82 nodes -pseudorandomly chosen based on the hash of the document. This signature -is one-time, and bulky (~3000 bytes), but fulfils the purpose. - -The question is, can we do better? There is an approach known as hash -ladders, allowing the size of a signature to be brought down to 420 -bytes, and one can use Merkle trees on another level to increase the -number of signatures possible, although at the cost of adding 100-300 -bytes to the signature. However, even still these approaches are -imperfect, and if hash-based cryptography is to be competitive the -properties of the algorithms will need to be substantially improved in -order to have nicer properties. - -**Problem**: create a signature algorithm relying on no security -assumption but the random oracle property of hashes that maintains 160 -bits of security against classical computers (ie. 80 vs. quantum due to -Grover's algorithm) with optimal size and other properties. - -**Requirements And Additional Assumptions** - -- The computational effort of producing a signature should be less than - 224 computational steps, assuming a hash takes 28 steps (a reasonable - assumption due to hardware optimizations and in the future hashing - ASICs built into chips) -- The size of a signature should be as small as possible -- The size of a public key should be as small as possible -- The signature algorithm should be scalable to add any number of uses, - although likely at the cost of adding a constant number of bytes per - signature for every 2x increase in the maximum number of uses, and if - possible the setup time should be sublinear in the number of uses. - -Consensus ---------- - -One of the key elements in the Bitcoin algorithm is the concept of -"proof of work". In any Byzantine-fault-tolerant system, the security -level is often defined as the minimum percentage of hostile nodes - for -example, in the context of secret sharing, the Berlekamp-Welch algorithm -with 2x redundancy is guaranteed to provide the correct output assuming -that the total number of hostile nodes does not exceed 25% of the -network, and in the context of Bitcoin mining the requirement is that -the size of the set of honest nodes exceeds the size of any individual -hostile coalition. However, all of these security guarantees have one -important qualification: there must be some way to define what an -individual node is. Before Bitcoin, most fault-tolerant algorithms had -high computational complexity and assumed that the size of the network -would be small, and so each node would be run by a known individual or -organization and so it is possible to count each node individually. - -With Bitcoin, however, nodes are numerous, mostly anonymous, and can -enter or leave the system at any time. Unless one puts in careful -thought, such a system would quickly run into what is known as a Sybil -attack, where a hostile attacks simply creates five times as many nodes -as the rest of the network combined, whether by running them all on the -same machine or rented virtual private server or on a botnet, and uses -this supermajority to subvert the network. In order to prevent this kind -of attack, the only known solution is to use a resource-based counting -mechanism. For this purpose, Bitcoin uses a scheme known as -proof-of-work, which consists of solving problems that are difficult to -solve, but easy to verify. The weight of a node in the consensus is -based on the number of problem solutions that the node presents, and the -Bitcoin system rewards nodes that present such solutions ("miners") with -new bitcoins and transaction fees. - -Bitcoin's proof of work algorithm is a simple design known as Hashcash, -invented by Adam Back in 1995. The hashcash function works as follows: - -:: - - def hashcash_produce(data, difficulty): - nonce = random.randrange(2**256) - while sha256(data + str(nonce)) > 2**256 / difficulty: - nonce += 1 - return nonce - - def hashcash_verify(data, nonce, difficulty): - return sha256(data + str(nonce)) <= 2**256 / difficulty - -Note that in the actual Bitcoin protocol nonces are limited to 32 bits; -at higher difficulty levels, one is required to also manipulate -transaction data in the block as a sort of "extranonce". - -Originally, the intent behind the Bitcoin design was very egalitarian in -nature. Every individual would mine on their own desktop computer, -producing a highly decentralized network without any point of control -and a distribution mechanism that spread the initial supply a BTC across -a wide number of users. And for the first 18 months of Bitcoin's -existence, the system worked. In the summer of 2010, however, developers -released a Bitcoin miner that took advantage of the massive -parallelization offered by the graphics processing unit (GPU) of -powerful computers, mining about 10-50 times more efficiently than CPUs. -In 2013, specialization took a further turn, with the introduction of -devices called "application-specific integrated circuits" - chips -designed in silicon with the sole purpose of Bitcoin mining in mind, -providing another 10-50x rise in efficiency. CPU and GPU mining are now -completely unprofitable, and the only way to mine is to either start a -multimillion-dollar ASIC manufacturing company or purchase an ASIC from -one that already exists. - -Another related issue is mining pool centralization. Theoretically, the -legitimate function of a mining pool is simple: instead of mining on -their own and receiving a small chance of earning the block reward of 25 -BTC, miners mine for a pool, and the pool sends them a proportionate -constant payout (eg. 0.002 BTC per block). There are centralized mining -pools, but there are also P2P pools which serve the same function. -However, P2P pools require miners to validate the entire blockchain, -something which general-purpose computers can easily do but ASICs are -not capable of; as a result, ASIC miners nearly all opt for centralized -mining pools. The result of these trends is grim. Right now, nearly 25% -of all new ASIC hashpower is produced in a single factory in Shenzhen, -and nearly 50% of the network is controlled by a single mining pool. - -The second problem is easy to alleviate; one simply creates a mining -algorithm that forces every mining node to store the entire blockchain. -The first problem, that of mining centralization, is much harder. There -is the possibility that the problem will solve itself over time, and as -the Bitcoin mining industry grows it will naturally become more -decentralized as room emerges for more firms to participate. However, -that is an empirical claim that may or may not come to pass, and we need -to be prepared for the eventuality that it does not. Furthermore, the -wasted energy and computation costs of proof of work as they stand today -may prove to be entirely avoidable, and it is worth looking to see if -that aspect of consensus algorithms can be alleviated. - -6. ASIC-Resistant Proof of Work -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -One approach at solving the problem is creating a proof-of-work -algorithm based on a type of computation that is very difficult to -specialize. One specific ideas involves creating a hash function that is -"memory-hard", making it much more difficult to create an ASIC that -achieves massive gains through parallelization. This idea is simple, but -fundamentally limited - if a function is memory-hard to compute, it is -also generally memory-hard to verify. Additionally, there may be ways to -specialize hardware for an algorithm that have nothing to do with -hyperparallelizing it. Another approach involves randomly generating new -mining functions per block, trying to make specialization gains -impossible because the ASIC ideally suited for performing arbitrary -computations is by definition simply a CPU. There may also be other -strategies aside from these two. - -Ultimately, perfect ASIC resistance is impossible; there are always -portions of circuits that are going to be unused by any specific -algorithm and that can be trimmed to cut costs in a specialized device. -However, what we are looking for is not perfect ASIC resistance but -rather economic ASIC resistance. Economic ASIC resistance can be defined -as follows. First of all, we note that in a non-specialized environment -mining returns are sublinear - everyone owns one computer, say with N -units of unused computational power, so up to N units of mining cost -only the additional electricity cost, whereas mining beyond N units -costs both electricity and hardware. If the cost of mining with -specialized hardware, including the cost of research and development, is -higher per unit hashpower than the cost of those first N units of mining -per user then one can call an algorithm economically ASIC resistant. - -For a more in-depth discussion on ASIC-resistant hardware, see -https://blog.ethereum.org/2014/06/19/mining/ - -**Problem**: Create two functions, ``PoWProduce(data,diff) -> nonce`` -and ``PoWVerify(data,nonce,diff) -> { 0, 1 }``, to serve as alternatives -to Hashcash such that it is economically unattractive to produce an ASIC -for ``PoWProduce`` - -**Additional Assumptions And Requirements**: - -- ``PoWProduce`` must have expected runtime linear in ``diff`` -- ``PoWVerify`` must have runtime at most polylogarithmic in ``diff`` -- Running ``PoWProduce`` should be the most efficient, or very close to - the most efficient, way to produce values that return ``1`` when - checked with ``PoWVerify`` (ie. no software optimization) -- ``PoWProduce`` must not be superlinear in computational power or - time; that is to say, the expected number of successful - ``PoWProduce`` computations for a node with ``N`` dollars worth of - hardware after ``t`` seconds should be bounded by ``kNt`` for some - ``k``. Furthermore, the linearity should kick in quickly; ie. $1000 - worth of mining hardware should function with over 90% efficiency. -- It should be shown with reasonably rigorous technological and - economic analysis that the algorithm is economically ASIC resistant. - -7. Useful Proof of Work -~~~~~~~~~~~~~~~~~~~~~~~ - -Another related economic issue, often pointed out by detractors of -Bitcoin, is that the proof of work done in the Bitcoin network is -essentially wasted effort. Miners spend 24 hours a day cranking out -SHA256 (or in more advanced implementations Scrypt) computations with -the hopes of producing a block that has a very low hash value, and -ultimately all of this work has no value to society. Traditional -centralized networks, like Paypal and the credit card network, manage to -get by without performing any proof of work computations at all, whereas -in the Bitcoin ecosystem about a million US dollars of electricity and -manufacturing effort is essentially wasted every day to prop up the -network. - -One way of solving the problem that many have proposed is making the -proof of work function something which is simultaneously useful; a -common candidate is something like Folding@home, an existing program -where users can download software onto their computers to simulate -protein folding and provide researchers with a large supply of data to -help them cure diseases. The problem is, however, that Folding@home is -not "easy to verify"; verifying the someone did a Folding@home -computation correctly, and did not cut corners to maximize their -rounds-per-second at the cost of making the result useless in actual -research, takes as long as doing the computation oneself. If either an -efficiently verifiable proof-of-computation for Folding@home can be -produced, or if we can find some other useful computation which is easy -to verify, then cryptocurrency mining could actually become a huge boon -to society, not only removing the objection that Bitcoin wastes -"energy", but even being socially beneficial by providing a public good. - -Note that there is one major concern with this approach that has been -identified: if the useful PoW is implemented incorrectly, it can -potentially reduce the cost of an attack on the network. If the useful -PoW is useful in such a way that it is sometimes economically viable for -certain very large entities to perform the computation even without the -currency incentive, then those entities have an incentive to launch -attacks against the network at no cost, since they would be performing -the computations anyway. One simple, though crude and imperfect, way of -addressing this problem is to make the PoW a half-and-half mix between -useful and useless, making the cost of an attack at least 50% of what it -would be in a useless-PoW environemnt. In practice, the overhead of -making PoW verifiable may well introduce over 2x inefficiency -unintentionally. Another economic solution is to make the computation a -"pure" public good such that no individual entity derives a significant -benefit from it. Proposed solutions to this problem should include a -rigorous analysis of this issue. - -**Problem**: Create two functions, ``PoWProduce(data,diff) -> nonce`` -and ``PoWVerify(data,nonce,diff) -> { 0, 1 }``, to serve as alternatives -to Hashcash such that the outputs of ``PoWProduce`` are independently -useful. - -**Requirements** - -- ``PoWProduce`` must have expected runtime linear in ``diff`` -- ``PoWVerify`` must have expected runtime at most polylogarithmic in - ``diff`` -- Running ``PoWProduce`` should be the most efficient way to produce - values that return ``1`` when checked with ``PoWVerify`` -- ``PoWProduce`` must not be superlinear in computational power or - time; that is to say, the expected number of successful - ``PoWProduce`` computations for a node with ``N`` dollars worth of - hardware after ``t`` seconds should be bounded by ``kNt`` for some - ``k``. Furthermore, the linearity should kick in quickly; ie. $1000 - worth of mining hardware should function with over 90% efficiency. -- ``PoWProduce`` must produce a public good, such that the total value - to everyone of the public good produced is greater than the cost of - all resources invested into the mining process. -- The system must be able to exist without a trusted third party, but - it is reasonable to allow a trusted third party to serve as a data - source for useful computations. If the trusted third party acts - maliciously in any way, the public good may be negated but the - blockchain mining should not be compromised. - -8. Proof of Stake -~~~~~~~~~~~~~~~~~ - -Another approach to solving the mining centralization problem is to -abolish mining entirely, and move to some other mechanism for counting -the weight of each node in the consensus. The most popular alternative -under discussion to date is "proof of stake" - that is to say, instead -of treating the consensus model as "one unit of CPU power, one vote" it -becomes "one currency unit, one vote". - -A very simple proof of stake algorithm requires the miner mining the -block to sign it with the private key to the address holding their -coins, where the block is valid if -``sha256(PREVHASH + ADDRESS + TIMESTAMP) <= 2^256 * BALANCE / DIFFICULTY`` -where ``PREVHASH`` is the hash of the previous block, ``ADDRESS`` is the -signer's address with balance ``BALANCE``, ``TIMESTAMP`` is the current -Unix time in seconds and ``DIFFICULTY`` is an adjustable parameter to -regulate the frequency of successful signatures. At first glance, this -algorithm has the basic required properties: every miner has some random -chance per second of succeeding, and if your address has twice as much -money in it then you have double the chance of success. - -However, this algorithm has one important flaw: there is "nothing at -stake". In the event of a fork, whether the fork is accidental or a -malicious attempt to rewrite history and reverse a transaction, the -optimal strategy for any miner is to mine on every chain, so that the -miner gets their reward no matter which fork wins. Thus, assuming a -large number of economically interested miners, an attacker may be able -to send a transaction in exchange for some digital good (usually another -cryptocurrency), receive the good, then start a fork of the blockchain -from one block behind the transaction and send the money to themselves -instead, and even with 1% of the total stake the attacker's fork would -win because everyone else is mining on both. - -Another problem to keep in mind is the issue of so-called "long-range -attacks" - attacks where the miner attempts to start a fork not five or -ten blocks behind the head of the main chain, as happens normally, but -hundreds of thousands of blocks back. If an algorithm is designed -incorrectly, it may be possible for an attacker to start from that far -back, and then mine billions of blocks into the future (since no proof -of work is required), and new users would not be able to tell that the -blockchain with billions of blocks more is illegitimate. This can -generally be solved with timestamping, but special corner cases do tend -to appear in overcomplicated designs. - -The Slasher algorithm, described -`here `__ -and implemented by Zack Hess as a proof-of-concept -`here `__, represents my own -attempt at fixing the nothing-at-stake problem. The core idea is that -(1) the miners for each block are determined ahead of time, so in the -event of a fork a miner will either have an opportunity to mine a given -block on all chains or no chains, and (2) if a miner is caught signing -two distinct blocks with the same block number they can be deprived of -their reward. The algorithm is viable and effective, but it suffers from -two flaws of unknown significance. First, if all of the miners for a -given block learn each other's identities beforehand, they can meet up -and collude to shut down the network. Second, the nothing-at-stake -problem remaing for attacks going back more than 3000 blocks, although -this is a smaller issue because such attacks would be very obvious and -can automatically trigger warnings. - -For a more in-depth discussion on proof of stake, see -https://blog.ethereum.org/2014/07/05/stake/ - -**Problem**: create a proof-of-stake algorithm that solves the -nothing-at-stake problem and long-range attack problems, without -introducing new collusion risks that require less than 25% of -stakeholders to succeed. - -**Additional Requirements And Assumptions** - -- The expected return from mining should be bounded by ``k`` times the - miner's stake for some ``k``, and assuming $1 billion total - participating stake a stake of $1000 should be able to reach 90% of - this maximum efficiency. -- The algorithm should be fully incentive-compatible, addressing the - double-voting issue defined above and the collusion issue defined - above at both short and long range. - -9. Proof of Storage -~~~~~~~~~~~~~~~~~~~ - -A third approach to the problem is to use a scarce computational -resource other than computational power or currency. In this regard, the -two main alternatives that have been proposed are storage and bandwidth. -There is no way in principle to provide an after-the-fact cryptographic -proof that bandwidth was given or used, so proof of bandwidth should -most accurately be considered a subset of social proof, discussed in -later problems, but proof of storage is something that certainly can be -done computationally. An advantage of proof-of-storage is that it is -completely ASIC-resistant; the kind of storage that we have in hard -drives is already close to optimal. - -The most simple algorithm for proving that you own a file with ``N`` -blocks is to build a Merkle tree out of it, publish the root, and every -``k`` blocks publish a Merkle tree proof of the ``i``\ th block where -``i`` is the previous block hash mod ``N``. However, this algorithm is -limited because it is only a simple building block, not a complete -solution. In order to turn this into a currency, one would need to -determine which files are being stored, who stores whose files, to what -extent and how the system should enforce redundancy, and if the files -come from the users themselves how to prevent compression optimizations -and long-range attacks. - -Currently, the latest work in this area are two projects called -Permacoin and Torcoin, which solve some of the problems in proof of -storage with two insights. First, users should not be able to choose -which files they store. Instead, files should be randomly selected based -on their public key and users should be required to store ALL of the -work assigned or else face a zero reward. This idea, provided in the -context of proof of bandwidth in the case of Torcoin, prevents attacks -involving users only storing their own data. Second, a Lamport-like -signature algorithm can be used that requires users to have their -private key and store their file locally; as a result; uploading all of -one's files to the cloud is no longer a viable strategy. This, to some -degree, forces redundancy. - -However, the problem with Permacoin is that it leaves unclear what files -should be stored; cryptocurrency issuance can theoretically pay for -billions of dollars of work per year, but there is no single static -archive whose storage is worth billions. Ideally, the system would allow -for new files to be added, and perhaps even allow users to upload their -own files, but without introducing new vulnerabilities. - -**Problem**: create a currency that uses proof-of-storage as its -consensus and distribution algorithm. - -**Additional Assumptions And Requirements** - -- The currency must be future-proof, being able to expand the amount of - data stored over time; the system should not eventually fall into - some failure state if hard disk space continues to get cheaper and - more efficient. -- The currency should ideally be maximally useful. At the least, the - currency should allow people to upload their own files and have them - stored, providing an uploading network with minimal cryptographic - overhead, although ideally the currency should select for files that - are public goods, providing net total value to society in excess of - the number of currency units issued. -- The expected return from mining should be at most slightly - superlinear, ie. it must be bounded by ``ks/(1-s)`` for some ``k``, - where ``s`` is the miner's share of the total network, although - perfect linearity is ideal. -- The system should be maximally resistant against mining pool - centralization as a result of any small degree of superlinearity. -- The system should be secure against nothing-at-stake and long-range - attacks. -- The system should be secure against attacker involving users - uploading specially formatted files or storing their own data. - -Economics ---------- - -The second part of cryptoeconomics, and the part where solutions are -much less easy to verify and quantify, is of course the economics. -Cryptocurrencies are not just cryptographic systems, they are also -economic systems, and both kinds of security need to be taken into -account. Sometimes, cryptographic security may even be slightly -compromised in favor of an economic approach - if a signature algorithm -takes more effort to crack than one could gain from cracking it, that is -often a reasonable substitute for true security. At the same time, -economic problems are also much more difficult to define. One cannot -usually definitively know whether or not a problem has been solved -without extensive experimentation, and the result will often depend on -cultural factors or the other organizational and social structures used -by the individuals involved. However, if the economic problems can be -solved, the solutions may often have reach far beyond just -cryptocurrency. - -10. Stable-value cryptoassets -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -One of the main problems with Bitcoin is the issue of price volatility. -The value of a bitcoin often experiences very large fluctuations, rising -or falling by as much as 25% in a single day and 3x in a month. The main -economic reason behind this is that the supply of bitcoins is fixed, so -its price is directly proportional to demand (and therefore, by -efficient market hypothesis, the expected discounted future demand), and -demand is very unpredictable. It is not known if Bitcoin will be simply -a niche payment method for transcations requiring a high degree of -privacy, a replacement for Western Union, a mainstream consumer payment -system or the reserve currency of the world, and the expected value of a -bitcoin differs over a thousandfold between these various levels of -adoption. Furthermore, the utility of the Bitcoin protocol is heavily -dependent on the movements of the Bitcoin price (ie. people are -interested in Bitcoin more if the price is going up), creating a -positive feedback loop, which has arguably been responsible for both -Bitcoin's great meteoric rises and its many-month-long periods of rapid -decline. - -To solve this problem, there are generally two paths that can be taken. -The first is to have the network somehow detect its current level of -economic usage, and have a supply function that automatically increases -supply when usage increases. This reduces uncertainty; even though the -expected future level of adoption of the protocol may have a variance of -10-100x, the circumstance where adoption increases 100x will also have -100x more supply and so the value of the currency will remain the same. -There is a problem that if usage decreases there is no way to remove -units from circulation, but even still the lack of upward uncertainty -should reduce upward volatility, and downward volatility would also -naturally reduce because it is no longer bad news for the value of the -currency when an opportunity for increased usage is suddenly removed. -Furthermore, in the long term the economy can be expected to grow, so -the zero-supply-growth floor may not even ever be reached in practice. - -The problem is that measuring an economy in a secure way is a difficult -problem. The most obvious metric that the system has access to is mining -difficulty, but mining difficulty also goes up with Moore's law and in -the short term with ASIC development, and there is no known way to -estimate the impact of Moore's law alone and so the currency cannot know -if its difficulty increased by 10x due to better hardware, a larger user -volume or a combination of both. Other metrics, such as transaction -count, are potentially gameable by entities that want the supply to -change in a particular direction (generally, holders want a lower -supply, miners want a higher supply). - -Another approach is to attempt to create a currency which tracks a -specific asset, using some kind of incentive-compatible scheme likely -based on the game-theoretic concept of Schelling points, to feed price -information about the asset into the system in a decentralized way. This -could then be combined with a supply function mechanism as above, or it -can be incorporated into a zero-total-supply currency system which uses -debts collateralized with other cryptographic assets to offset its -positive supply and thus gain the ability to grow and shrink with -changes to usage in either direction. The problem here is constructing -the scheme in such a way that there is no incentive for entities to feed -in false price information in order to increase or decrease the supply -of the asset in their favor. - -**Problem**: construct a cryptographic asset with a stable price. - -**Requirements** - -- The expected root-mean-square daily change in the logarithm of the - price of the asset should be less than 25% of that of Bitcoin under - similar conditions. Ideally, the asset should be guaranteed to almost - always maintain a value within 10% of an arbitrary cryptographic or - real-world asset for which price information is easily accessible -- The expectation analysis should take into account black swan risks - (ie. systems where the variance is 0% 99% of the time but 10x in a - day the other 1% of the time are unacceptable) -- The solution must come with a model, including parameters such as - short-term-consumption purchases, medium-term purchases, speculative - purchases, positive and negative media, adoption and regulatory - events, irrational actors and actors with political motives, show - that their model well fits the history of Bitcoin and potentially - major altcoins without overfitting, and show that under the model the - other two requirements hold -- Zero-total-supply assets, ie. assets where each unit is balanced by a - collateralized debt of a unit, are allowed, although such systems - must include a robust margin-calling mechanism because it is assumed - that most users are anonymous and can therefore trivially run away - from debts - -11. Decentralized Public Goods Incentivization -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -One of the challenges in economic systems in general is the problem of -"public goods". For example, suppose that there is a scientific research -project which will cost $1 million to complete, and it is known that if -it is completed the resulting research will save one million people $5 -each. In total, the social benefit is clear: if everyone contributes $1, -then each individual person will see a benefit of $5 - $1 = $4 for $4 -million total. However, the problem is that from the point of view of -each individual person contributing does not make sense - whether or not -you contribute has close to zero bearing on whether enough money will be -collected, so everyone has the incentive to sit out and let everyone -else throw their money in, with the result that no one does. - -So far, most problems to public goods have involved centralization; some -large organization, whether a big company or a government, agrees to -offer some of its private services only to those individuals who -participate in paying for the public good. Often this is done -implicitly: for example, some of the money from each purchase of an iPad -goes toward research and development (some of which is a public good, -and some of which is an excludable "club good"). At other times, it's -more explicit, as in the case of taxation. In order for decentralized -economic systems (we'll refer to decentralized economic systems that -somehow rely on cryptography and/or cryptocurrency as "cryptoeconomic -systems") to be effective, ways of incentivizing production of public -goods relevant to that system are required. A few possible approaches -include: - -- **Assurance contracts** - the idea behind an assurance contract is - that ``N`` people may or may not put their funds into a pool, where - that pool pays to produce a public good if and only if at least $X in - total is contributed. Otherwise, the pool pays everyone back. If the - pool creator acts optimally, the tipping point will be right at the - top of the bell curve that is the probability distribution for how - much other people might contribute, meaning that the chance that one - user with their contribution of ``X/N`` will be pivotal should, by - central limit theorem, approach ``~1/sqrt(N)``, creating a - ``sqrt(N)``-sized amplifying effect on their donation. -- **Dominant assurance contracts** - a special type of assurance - contract, called a dominant assurance contract, involves an - entrepreneur that pays all contributors back slightly more than 100% - of what they put in if the fund fails to reach its target (and takes - profits if the fund succeeds); this provides an incentive for someone - to create optimally targeted assurance contracts. -- **Currency issuance** - a cryptoeconomic system can contain its own - currency or token system which is somehow necessary or useful in some - part of the system. These currency units can then either be generated - by the system and then sold or directly assigned to reward - contribution. This approach gets around the free-rider problem - because no one needs to pay the $1 explicitly; the value arises out - of the emergent value of the network which is does not cost people to - support. -- **Status goods issuance** - a status good can be defined as a good - that confers only relative benefit to its holder and not absolute - benefit to society; for example, you may stand out in the public if - you wear an expensive diamond necklace, but if everyone could - trivially obtain such a necklace the situation would be very similar - to a world with no diamond necklaces at all. A cryptoeconomic system - can release its own status goods, and then sell or award them. One - example of a status good is a "badge"; some online forums, for - example, show a special badge beside users that have contributed - funds to support the forum's development and maintenance. Another - important example of a status good is a namespace; for example, a - decentralized messaging protocol may be able to fund itself by - selling off all of the 1-4 letter usernames. -- **Recursive rewarding** - this is in some ways a mirror image of the - concept of "recursive punishment" that arguably underlies a large - number of social protocols. For example, consider the case of - tax-funded police forces. In natural circumstances, there often arise - opportunities to take actions which are beneficial to the - perpetrator, but ultimately harmful to society as a whole (eg. - theft). The most common solution to this problem is punishment - an - act which is harmful in itself, but which shifts the incentives so - that attacking is no longer beneficial to the perpetrator. However, - there is a problem: there is no incentive to participate in the - punishment process. This is solved by making punishment obligatory, - with non-participation (in modern society by paying taxes) itself - punishable by the same mechanism. Recursive rewarding is a mirror - image of this strategy: here, we reward a desirable action, and - people who partivipate in the rewarding mechanism (eg. by giving - reward recipients a discount in shops) are themselves to be rewarded. - -Many of these approached can arguably be done in concert, or even -simultaneously within one mechanism. - -**Problem**: come up with and implement methods for incentivizing public -goods production in a decentralized environment. - -**Additional Assumptions And Requirements** - -- A fully trustworthy oracle exists for determining whether or not a - certain public good task has been completed (in reality this is - false, but this is the domain of another problem) -- The agents involved can be a combination of individual humans, teams - of humans, AIs, simple software programs and decentralized - cryptographic entities -- A certain degree of cultural filtering or conditioning may be - required for the mechanism to work, but this should be as small as - possible -- No reliance on trusted parties or centralized parties should be - required. Where some kind of "supernode" role does exist, the - protocol should provide a way for anyone to participate in that - function with a mechanism for rewarding those who do it well -- The mechanism should ideally be able to handle both public goods - which everyone values and public goods which are only valued by a - small portion of the population (eg. the production of a freely - available book or video on a specific topic) - -12. Reputation systems -~~~~~~~~~~~~~~~~~~~~~~ - -A concept which can arguably be considered to be a mirror image of -currency is a reputation system. A reputation system serves three -functions. First of all, it provides a mechanism for filtering honest -people from dishonest people. Different people have different moral -preference profiles, and so individuals who cheat less in one context -are less likely to cheat in another context. Second, it provides an -incentive not to cheat. If an individual can be said to possess a -reputation of value ``R``, and he enters a business deal where he is -receiving payment ``V`` in exchange for a product with -cost-of-production ``C``, then as long as ``R > C`` the reputation -system removes the incentive to run away with the money because doing so -would sacrifice the reputation. Finally, reputation can be thought of as -a kind of point system that people value intrinsically, both in a -private context and as a status good in comparison with others. - -Money serves functions that are very similar. People who are willing to -spend more money on something tend to want it more, creating a filtering -function ensuring efficient resource consumption on the demand side. It -provides an incentive not to cheat by consuming and not producing, -because if you do so your remaining currency units and thus ability to -consume in the future will go down. And finally, it is also very much an -intrinsically valued point system; in fact, some argue that among very -wealthy individuals this function of money is dominant. - -However, there are also differences. First, money is an absolute score - -I have X units of currency C from the point of view of everyone in the -world - but reputation is a relative measure, depending on both the -owner of the reputation and the observer. I may have a high reputation -in North America, a near-zero reputation in Africa, and a negative -reputation among certain kinds of antitechnologist and ultranationalist -groups. Second, reputation is free to give; it does not cost me anything -to praise you, except potentially moral liability that I may incur if -you turn out to act immorally in some way. This is in contrast with -money, where adding X units to A means subtracting X units from B. - -However, up until very recently, reputation has been a very informal -concept, having no concept of score and instead relying entirely on -individual opinion. Because opinion is relatively easy to manipulate, -this means that reputation as a concept has been highly suboptimal in -its implementation, and has been quite vulnerable to informational and -psychological attacks. Some specific problems are: - -1. How do we know how what the value of someone's reputation with - someone else is after a particular number of interactions? A common - attack on informal reputation systems is the "long con" - act - honestly but passively and cheaply for a very long time, accumulate - trust, and then suddenly go all out and destructively capitalize on - one's reputation as much as possible. The initial dormant phase is - cheap for the attacker, but ends up resulting in the attacker - accumulating a disproportionately large amount of trust for the - community and thereby ultimately causing much more damange than good. - Overcompensate for this too much, however, and there ends up being no - opportunity to gain trust. -2. How do we incorporate secondary trust? In general, when ``A`` is - deciding whether or not to trust ``B``, ``A`` has not had any prior - dealings with ``B``, and therefore has no way of knowing whether or - not ``B`` is trustworthy. One approach is to just look at all ratings - for ``B``, but then we run into the issue of Sybil attacks: what if - ``B`` creates 50000 fake users, all of whom rate each other highly, - to give good ratings to him? To solve this problem, reputation - systems rely on a fallback known as a web of trust: find some chain - of people ``P[1] ... P[k]`` such that ``A`` trusts ``P[1]``, ``P[i]`` - trusts ``P[i+1]`` for all ``i``, and ``P[k]`` trusts ``B``. Under the - "six degrees of separation hypothesis", any two people in the world - except those completely disconnected from society have such a chain - of maximum length ``k = 5`` (so at most six hops total). However, the - question arises, if ``A`` has a certain rating for ``P[1]`` and - ``P[1]`` has a certain rating for ``B``, what should the reputation - system recommend to ``B``? -3. If a reputation system becomes more formalized, are there market - attacks that reduce its effectiveness to simply being just another - form of money? Specifically, how would a reputation system where - giving reputation is free handle users multiplying their reputation - with millions of "I praise you if you praise me" trades? Will such - trades need to be explicitly banned, punishable by loss of - reputation, or is there a better solution? -4. How do we deal with double use attacks? Specifically, suppose that - ``A`` has a reputation with value ``R = $1000``. Using this - reputation, ``A`` has a business dealing where ``P[1]`` trusts her - for $600. Then, she simultaneously engages in such a dealing with - ``P[2], P[3] ... P[10]``, each of whom individually believe that - ``A`` will not betray them since $600 < $1000, and then runs away - with $6000 taking the $1000 hit from the value of her reputation. How - do we prevent such fractional reserve-like scenarios? - -**Problem**: design a formalized reputation system, including a score -``rep(A,B) -> V`` where ``V`` is the reputation of ``B`` from the point -of view of ``A``, a mechanism for determining the probability that one -party can be trusted by another, and a mechanism for updating the -reputation given a record of a particular open or finalized interaction. - -Note that for the purpose of this use case we are targeting specifically -the "can I trust you" use case of reputation, and not the -social-incentivizing -"`whuffie `__"-esque -currency-like aspect. - -**Additional Assumptions and Requirements** - -- The system has access to a record of all finalized transactions - inside the system and all transactions in progress, although entities - are of course able to choose to make deals outside the system -- It is allowed to introduce mechanisms like charity donations, public - goods provision and sacrifices as a way of increasing one's - reputation. However, if non-monetary contributions are allowed, there - needs to be some mechanism for measuring their value -- For simplicity, we can assume that interactions between two people - are of the form "A pays, then B sends the product and A receives", - with no possibility for loss beyond the principal (eg. food - poisoning) or ambiguous quality. Ideally, however, the system should - account for such possibilities. -- The system should continue to be reasonably accurate whether the - parties involved are simple programs (eg. micropayment software - protocols), more complicated AIs, DAOs, individual humans or human - centralized or decentralized organizations -- If a mechanism is provided for determining the probability of a - successful interaction, a success metric for the system can be - defined as the sum over all transactions of - ``V * (S * log(p) - (1-S) * log(1-p))``, where ``S = 1`` if the - transaction succeeded and ``S = 0`` if there was a registered - complaint, ``p`` is the assigned probability and ``V`` is the value - of the transaction. The objective is to maximize this metric. - -Metrics -------- - -In the world of cryptoeconomics, in order for something to be rewarded -it must be measured. Some things are easy to measure; for example, just -by looking at the string "dog5356356" and its SHA256 hash, -``0000390f327fefc900...``, one can clearly see that around 216 SHA256 -computations were done to produce it. Other computational results that -cannot be verified so quickly can be easily measured competitively using -challenge-response protocols, where different parties are incentivized -to find errors in each other's proofs. Results to mathematical problems -are also usually easy to computationally verify. Other things, however, -cannot be verified just by looking them; in that case, in both the real -world and the cryptographic world, there is only one solution: social -proof. - -To some extent, proof of work consensus is itself a form of social -proof. Transaction A happened before transaction B because the majority -of users say it did, and there is an economic incentive to go with the -majority opinion (specifically, if you generate a block on the incorrect -chain, that block will get discarded and the miner will receive no -reward). Assuming that most participants act truthfully, the incentive -is to go along with the projected majority and tell the truth as well. -This insight can be extended into -`SchellingCoin `__, -a generalized data feed protocol, protocols for proof of bandwidth, and -anything else that can be quickly verified. The challenge is, however, -what if verification has a cost? What if it takes some effort to -determine whether or not a certain thing has happened, or what if the -information is in principle only available to a few people? If there is -too much gathering cost or secrecy, then centralization becomes -necessary; the question is, how high can we go? How much can we measure -without any social proof at all, and how much can we measure without a -centralized verifier? - -13. Proof of excellence -~~~~~~~~~~~~~~~~~~~~~~~ - -One interesting, and largely unexplored, solution to the problem of -distribution specifically (there are reasons why it cannot be so easily -used for mining) is using tasks that are socially useful but require -original human-driven creative effort and talent. For example, one can -come up with a "proof of proof" currency that rewards players for coming -up with mathematical proofs of certain theorems. There is no generic -algorithm, aside from brute force, for proving theorems, and yet proofs -of theorems are theoretically computationally easy to verify: one simply -needs to write every step of the proof in a formal language, allowing -the use of only one inference rule (eg. ``a + b = b + a`` or -``a * (b + c) = a * b + a * c`` but not ``a * (b + c) = a * c + b * a``) -between each step, and having a program verify the correctness of the -inferences at each step. - -For example, a proof of a common algebraic factorization problem appears -as follows: - -:: - - a^2 - b^2 - = a^2 - a*b + a*b - b^2 - = a*a - a*b + a*b - b^2 - = a*(a - b) + a*b - b^2 - = a*(a - b) + a*b - b*b - = a*(a - b) + b*a - b*b - = a*(a - b) + b*(a - b) - = (a + b)*(a - b) - -Each step of the proof can be verified using pattern matching -algorithms, but it is much harder for a computer to figure out that the -trick is to add and subtract ``a*b`` into the expression (technically, -in this case specialized algorithms can do it, but in more general cases -especially involving second-order logic it becomes intractable). Note -that for computers the proof must be written down in excruciating -detail; blockchain-based algorithms specifically heavily benefit from -simplicity. To alleviate this problem, compilers can likely be made that -can make small two and three-step inferences and expand shorter proofs -into more complete ones. - -Alternatives to proof-of-proof include proof-of-optimization, finding -optimal inputs to some function to maximize a particular output (eg. the -ability of a radio antenna to receive signals), algorithms involving -playing strategy games or multiplayer AI challenges (one can even -require users to submit programs to the blockchain that play against -each other), and solving a specific math problem at greater and greater -difficulty (eg. factoring). Note that because success in these problems -is very sporadic, and highly inegalitarian, one cannot use most of these -algorithms for consensus; rather, it makes sense to focus on -distribution. - -**Problem**: create a proof-of-excellence distribution mechanism that -rewards solving problems that are both dominated by human effort and -whose solutions provide some benefit to humanity. - -**Additional Assumptions and Requirements** - -- Given a well-justified extrapolation of the global levels of human - and computer competence at the underlying problem, over 75% of the - rewards from the system should be provided by human labor, although - software aids are allowed. -- The algorithm must ideally be future-proof; that is to say, it must - continue rewarding value production in the long term and should not - be an area that will eventually be "solved" completely. -- The distribution should be maximally egalitarian, though this is a - secondary concern. -- The system should be secure against front-running attacks, ie. if an - individual submits a solution, then it should not be practical for - even a moderately powerful attacker to look at the solution and then - resubmit his own transaction containing the same solution and thereby - steal the reward. - -14. Anti-Sybil systems -~~~~~~~~~~~~~~~~~~~~~~ - -A problem that is somewhat related to the issue of a reputation system -is the challenge of creating a "unique identity system" - a system for -generating tokens that prove that an identity is not part of a Sybil -attack. The naive form of anti-Sybil token is simple: a sacrifice or -proof of deposit. In a sacrifice setup, such identities simply cost $X, -and in a PoD system identities require a deposit of $Y in order to be -active, where perhaps the deposit can be taken away or destroyed under -certain circumstances. However, we would like to have a system that has -nicer and more egalitarian features than "one-dollar-one-vote"; -arguably, one-person-one-vote would be ideal. - -To date, we have seen two major strategies for trying to solve this -problem. One potential solution is to come up with a proof-of-work -algorithm which is dominated by human labor, and not computers. This is -not as difficult as it may seem; although computers get more and more -powerful every year, there are a number of problems that have remained -out of computers' reach for decades, and it may even be possible to -identify a class of problems that are the -artificial-intelligence-theoretic equivalent of "NP-complete" - problems -such that, if they can be solved, it with high probability implies that -AI can essentially replicate human activity in its entirety, in which -case we are essentially in a post-scarcity utopia and money and -incentivization may not even be necessary. These problems may be -non-interactive challenges like CAPTCHAs, although all existing CAPTCHAs -are far from adequate for the task, or they may be interactive strategy -games like Go. - -The second strategy is to use social proof, turning the muscle of -decentralized information gathering toward a simple problem: are these -two identities the same person? If they are not, then they receive two -anti-Sybil tokens, and if they are they receive one token. In general, -we can separately define two concepts of identity: voluntary identity -and involuntary identity. A voluntary identity can be seen as a cluster -of interactions which are in some fashion correlated with each other; -for example, a cryptographic identity consists of the set of -interactions signed by a particular public key. An involuntary identity -is a cluster of interactions which are correlated with each other, but -where the entity producing the interactions does not want the -correlations to be visible. A simple unique identity system would rely -on voluntary identities embedded in social networks, with the -understanding that creating separate identities with reputations is an -expensive task and so most people would not want to do it, but a more -advanced system may try to detect involuntary slipups like writing style -patterns or IP addresses. - -The question is, can we use these mechanisms, either separately or -together, and perhaps in combination with cryptoeconomic protocols and -sacrifices as a fallback in order to create an anti-Sybil system which -is highly egalitarian? We will accept that any scheme can be cracked at -some cost; however, what we want is for it to be much more efficient for -individuals to obtain *one* anti-Sybil token "the proper way" rather -than purchasing one off the grey/black market. The challenge is to push -the grey/black market cost as high as possible, as much as possible -without making the first token difficult. - -**Problem** - create a mechanism for distributing anti-Sybil tokens - -**Additional Assumptions and Requirements**: - -- Everyone is part of a social network with similar characteristics to - social networks now found in the real world, and social data can be - provably provided to cryptoeconomic systems (eg. blockchains, - Ethereum contracts) -- The cost of obtaining one anti-Sybil token for a human should be as - low as possible -- The cost of obtaining multiple anti-Sybil tokens for a human should - be as high as possible -- The cost of obtaining anti-Sybil tokens for an automated system - should be as high as possible (this is a more important criterion - than high cost for multi-obtainment for humans) -- The system should not create dependency on centralized parties (eg. - government passport offices) that have the power to cheat the system - -15. Decentralized contribution metrics -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Incentivizing the production of public goods is, unfortunately, not the -only problem that centralization solves. The other problem is -determining, first, which public goods are worth producing in the first -place and, second, determining to what extent a particular effort -actually accomplished the production of the public good. This challenge -deals with the latter issue. Although in the case of computational tasks -it's easy to come up with a proof of solution, for non-computational -tasks the situation is much more difficult. If a cryptoeconomic system -wants to incentivize users to build better graphical user interfaces to -its own system, how would it rate people's contributions? `Even more -problematically `__, -what about potentially quasi-adversarial tasks like incentivizing -updates to its own code? What about a DAO that funds healthcare, or -tries to incentivize adopting renewable energy? - -This is a subclass of the general "social proof" problem; here, the -particular challenge is that each individual datum in question is -something that very few people are interested in, and data gathering -costs are often high. Sometimes, there is not even a concept of a single -"correct" value with respect to the particular metric; in the case of -quality measurement for an interface, a solution like A/B testing may be -required. In adversarial cases, there may need to be an opportunity for -incentivized opponents to look at a solution and attempt to pick it -apart. - -**Problem**: come up with and implement a decentralized method for -determining whether or not a particular task was performed by a specific -person, and for estimating the quality of the work - -**Additional Assumptions and Requirements** - -- The agents involved can be a combination of individual humans, teams - of humans, AIs, simple software programs and other DAOs -- There is no cryptographically verifiable information about the - completion of any task; the system must rely entirely on some form of - social proof - -16. Decentralized success metrics -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Another, related, problem to the problem of decentralized contribution -metrics is the problem of decentralized success metrics. On the -macroscopic scale, how do we know if, and to what extent, an -organization has succeeded in accomplishing its objectives? In the case -of something like Bitcoin, there is a simple, but imperfect, answer: -success can be measured by the hashpower of the network. This setup is -reasonably effective, but is flawed in two ways: first, hashpower is an -imperfect proxy for price, because the development or nondevelopment of -ASICs may skew the results, and second, price is an imperfect proxy for -success, because the currency may have greater success as something with -a lower market capitalization if it is more used in other ways. In the -case of a DAO funding healthcare or anti-climate-change efforts, -however, no such heuristic exists at all. Once again, some concept of -social proof is the only option. - -Here, information gathering costs are low, and information is accessible -to everyone in the public, so a higher level of accuracy is possible, -hopefully even enough for financial contracts based off of the metric to -be possible. However, in order to maintain that higher level of -accuracy, and in the presence of such financial derivatives, new -problems arise. Can one moderately powerful entity manipulate the metric -for their own benefit? If information gathering costs do exist, is the -system vulnerable to falling into a centralized equilibrium, where -everyone is incentivized to simply follow along with the actions of some -specific party? - -**Problem**: come up with and implement a decentralized method for -measuring numerical real-world variables - -**Additional Assumptions and Requirements** - -- The agents involved can be a combination of individual humans, teams - of humans, AIs, simple software programs and other DAOs -- The system should be able to measure anything that humans can - currently reach a rough consensus on (eg. price of an asset, - temperature, global CO2 concentration diff --git a/old-docs-for-reference/main-wiki.rst/Proposal-Extend-GetBlockHashes-with-target-hash.rst b/old-docs-for-reference/main-wiki.rst/Proposal-Extend-GetBlockHashes-with-target-hash.rst deleted file mode 100644 index aff22ef..0000000 --- a/old-docs-for-reference/main-wiki.rst/Proposal-Extend-GetBlockHashes-with-target-hash.rst +++ /dev/null @@ -1,99 +0,0 @@ -Problem -======= - -The current protocol specification does not provide the means to -mitigate an infinite chain feeding attack. A malicious peer can make up -arbitrary blocks on the fly, and feed their hashes indefinitely to a -target, without ever linking to the existing chain. This will result in -an eventual memory exhaustion and crash. The root cause is that the -protocol provides no means to validate any blocks, without first pulling -the entire hash chain. - -Solution -======== - -Peers should be able to request hashes not only backwards towards the -genesis block, but forward too to some specific target hash. This would -allow the downloader to start pulling actual blocks and verify them -concurrently with fetching the hashes. If no peers (including the hash -provider) has the blocks to back up the hashes, the chain is rejected. - -This forward synchronization strategy requires the capacity to locate a -common ancestor block to our blockchain and that of a remote peer in -order to know the joining point from which to request the hashes. This -can be facilitated with the same mechanism by doing a binary search on -our blockchain, requesting 1xhashes from the remote (towards its -advertised head) side to see if it knows about it or not, honing in on -the common ancestor. - -Specification -============= - -1. Extend ``GetBlockHashes`` packet with an additional field: - - **GetBlockHashes** [``+0x03``: ``P``, ``srcHash``: ``B_32``, - ``targetHash``: ``B_32``, ``maxBlocks``: ``P``] - - - ``targetHash``: The endpoint in a remote blockchain towards which - to retrieve hashes - -2. Modify ``BlockHashes``'s returned hash order: - - - Adhere to that requested by ``GetBlockHashes``, opposed to the - current "hard coded" young -> old ordering - -The benefit of this proposal is that beside providing the means to do -forward syncing, it retains the capacity to implement the currently -specified reverse fetch behavior by passing the genesis block's hash to -``targetHash``. This way Ethereum implementations don't have to -immediately devise a new downloader strategy to cope with the update, -but can function as they are until ready to evolve. - -Supersedes -========== - -[[Proposal: BlockHashesFromNumbers]] - -The main issue the ``BlockHashesFromNumbers`` set out to resolve was the -slow download of hashes (which was stalling the synchronization), by -introducing parallel fetches based on height/block-number based hash -retrievals. It also inherently provided a mechanism to limit the number -of potentially invalid hashes downloaded to that of the current chain's -height. - -The current proposal however approaches the challenge from the opposite -direction. By downloading hashes towards the end of a chain - after the -first hash delivery - blocks can be immediately retrieved in parallel -(compared to which hash downloads are insignificant in size and hence -latency), so there is no need for the added complexity and potential -issues with parallelizing hash downloads. Additionally, by limiting the -number of pending hashes, we can also prevent any infinite chain -attacks. - -Given that the current proposal addresses all of the issues -``BlockHashesFromNumbers`` aimed to fix, while being much less invasive -(requires the addition of single packet field); is gracefully compatible -with previous protocol implementations (they can continue to function -without an algorithm update); and implementation wise is straightforward -and easy to reason about; we believe it is a superior proposal. - -Critique -~~~~~~~~ - -- Closer to the present protocol than ``BlockHashesFromNumbers``. -- Less general and expansive than ``BlockHashesFromNumbers``: it is - designed for a very particular strategy and is less likely to be - adaptable to future, unknown strategies. -- Does not support parallel hash-chain downloading alongside forward - hash-chain downloading (``BlockHashesFromNumbers`` supports both). -- Somewhat more complex in terms of semantics: -- The notion of a series of hash going from a source hash to a - destination hash is found nowhere else in the protocol or codebase. - Exchanging number to/from hash is already found in the API. -- Not immediately clear with edge cases (e.g. if from is genesis and to - is leaf, or if from doesn't exist in the chain but leaf does, or - vice-versa). ``BlockHashesFromNumbers`` is well-defined under all - circumstances. -- Somewhat more complex in terms of implementation; how to efficiently - determine the fork point or common ancestor? - ``BlockHashesFromNumbers`` would make it trivial with a binary chop. diff --git a/old-docs-for-reference/main-wiki.rst/Proposal-NewBlockHashes.rst b/old-docs-for-reference/main-wiki.rst/Proposal-NewBlockHashes.rst deleted file mode 100644 index 0b94334..0000000 --- a/old-docs-for-reference/main-wiki.rst/Proposal-NewBlockHashes.rst +++ /dev/null @@ -1,33 +0,0 @@ -Problem -======= - -Block propagation is slow. This is partly due to the problematic -strategy decision of either sending out a new block to all peers (costly -in terms of bandwidth, especially when considered at the network level -where most nodes will receive a block from most of their peers) or send -a new block to a randomly selected subset of peers (making worst-case -propagation times substantial). - -Solution -======== - -Much better would be a low-bandwidth full propagation of the hash. All -nodes would receive a hash for each new block from most of their peers -(peers who have demonstrated knowledge of the hash would not be -notified). However, the block itself would need only be transferred once -per node. - -Specification -============= - -Introduce a new packet: ``NewBlockHashes``, into the slot ``+0x01`` -(original taken by ``GetTransactions``, which is not defunct). - -**NewBlockHashes** [``+0x01``: ``P``, ``hash1``: ``B_32``, ``hash2``: -``B_32``, ``...``] Specify one or more new blocks which have appeared on -the network. Including hashes that the sending peer could reasonable be -considered to know that the receiving node is aware of is considered Bad -Form, and may reduce the reputation of the sending node. Including -hashes that the sending node later refuses to honour with a proceeding -``GetBlocks`` message is considered Bad Form, and may reduce the -reputation of the sending node. diff --git a/old-docs-for-reference/main-wiki.rst/Proposal-Reversion-Notification.rst b/old-docs-for-reference/main-wiki.rst/Proposal-Reversion-Notification.rst deleted file mode 100644 index 60b01c8..0000000 --- a/old-docs-for-reference/main-wiki.rst/Proposal-Reversion-Notification.rst +++ /dev/null @@ -1,118 +0,0 @@ -**JSONRPC** changes: --------------------- - -``eth_getFilterChanges``, ``eth_getFilterLogs`` both return additional -fields: "type" and "polarity" - -- ``type``: ``STRING`` - ``pending`` when the log is pending. ``mined`` - if log is already mined. -- ``polarity``:``BOOL`` - either ``true`` (the transaction pertaining - to this log was mined or arrived as pending compared to the previous - notification/notified block) or ``false`` (the transaction pertaining - to this log was reverted or was deleted compared to the previous - notification/notified block). - -.. code:: diff - - // Result - { - "id":1, - "jsonrpc":"2.0", - "result": [{ - "logIndex": "0x1", // 1 - "blockNumber":"0x1b4" // 436 - "blockHash": "0x8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcfdf829c5a142f1fccd7d", - "transactionHash": "0xdf829c5a142f1fccd7d8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcf", - "transactionIndex": "0x0", // 0 - "address": "0x16c5785ac562ff41e2dcfdf829c5a142f1fccd7d", - "data":"0x0000000000000000000000000000000000000000000000000000000000000000", - + "type":"mined", - + "polarity": true, - "topics": ["0x59ebeb90bc63057b6515673c3ecf9438e5058bca0f92585014eced636878c9a5"] - },{ - ... - }] - } - -- logs order - -logs should be returned in order, from earliest to latest. - -In case of fork, the order should be following: - -:: - - // - // ......1 - 2 - 3a - 4a - // ...............\- 3b - 4b - 5b - // - // getLogs({fromBlock: 4a, toBlock: 5b}) should return - // 4a, 3a, 3b, 4b, 5b - // - -**JSONRPC** new methods: ------------------------- - -- ``eth_newFilterEx`` (new version of ``eth_newFilter``) -- ``eth_getLogsEx`` (new version of ``eth_getLogs``) - -They expect 'fromBlock', 'toBlock' to be block hash instead of block -number. - -.. code:: diff - - params: [{ - - "fromBlock": "0x1", - + "fromBlock": "0x599438826541d3e8c29c167fa15b491d91b65e422f8b8a3da69eaa9a43c832e1", - - "toBlock": "0x2", - + "toBlock": "0x599438826541d3e8c29c167fa15b491d91b65e422f8b8a3da69eaa9a43c832e1", - "address": "0x8888f1f195afa192cfee860698584c030f4c9db1", - "topics": ["0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b"] - }] - -- ``eth_getFilterChangesEx`` (new version of ``eth_getFilterChanges``) -- ``eth_getFilterLogsEx`` (new version of ``eth_getFilterLogs``) - -``eth_getFilterChangesEx`` && ``eth_getFilterLogsEx`` have the same -input params as ``eth_getFilterChanges`` && ``eth_getFilterLogs``, but -different format of returned objects. - -:: - - // Result - { - "id":1, - "jsonrpc":"2.0", - "result": [{ - "blockNumber":"0x1b4" // 436 - "blockHash": "0x8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcfdf829c5a142f1fccd7d", - "type": "pending", - "polarity": true, - "logs": [{ - "logIndex": "0x1", // 1 - "transactionHash": "0xdf829c5a142f1fccd7d8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcf", - "transactionIndex": "0x0", // 0 - "address": "0x16c5785ac562ff41e2dcfdf829c5a142f1fccd7d", - "data":"0x0000000000000000000000000000000000000000000000000000000000000000", - "topics": ["0x59ebeb90bc63057b6515673c3ecf9438e5058bca0f92585014eced636878c9a5"] - },{ - ... - }], - },{ - ... - }] - } - -Comments: ---------- - -**Fabian**: I like it but i would change three things: - -1. ``polarity: true`` -> ``invalidated: true`` or ``invalid: true`` -2. get rid of the old filter and add ``eth_newFilterEx`` as - ``eth_newLogFilter``, to make it fit the other filter type names - (``eth_newBlockFilter``, ``etH_newPendingTransactionFilter``) -3. Don't return logs grouped by blocks, as i don't see an advantage - besides that it is harder to parse. (Logs don't really care in which - block they came, though we need to add the ``blockX`` properties for - reference) diff --git a/old-docs-for-reference/main-wiki.rst/Proposal-Transaction-Proxy-Hooks.rst b/old-docs-for-reference/main-wiki.rst/Proposal-Transaction-Proxy-Hooks.rst deleted file mode 100644 index b2d4cbb..0000000 --- a/old-docs-for-reference/main-wiki.rst/Proposal-Transaction-Proxy-Hooks.rst +++ /dev/null @@ -1,94 +0,0 @@ -Requirements ------------- - -Need an abstraction mechanism to allow dapps like the Wallet provide -their services in an integrated manner without compromising the -neutrality of the browser or placing undue burden on third-party dapp -developers to support them. - -Basic Design ------------- - -The ethereum.js interface may be utilised to allow the dapp client to -register itself as the transaction handler for each of a number of -accounts; in doing so it will provide an additional callback. - -This is done through one addition to the ethereum.js ``web3.eth`` -object, ``registerProxyTransactor``: - -:: - - var addresses = []; - // TODO: populate addresses - - function f(tx) { - // tx includes tx.from, tx.to, tx.data, tx.value, tx.gasPrice, tx.gas - // and is *exactly* the same as what was passed to eth.transact, but probably not in this - // JS environment. - // tx.from is guaranteed to be an element of addresses. - // TODO: do something - } - - web3.eth.registerProxyTransactor(addresses, f); - -That's the entire JS API. - -In terms of JSON-RPC, there must be an alteration to ``eth_accounts``: -rather than just including the accounts that we have the secret key for -(and that the user has accepted are valid for this dapp to use and know -about), all accounts passed as the first argument to -``registerProxyTransactor`` should also be contained (with the same -safeguards as per user acceptance). - -There are also two additional calls in the JSON-RPC; one for polling the -status of whether any transactions are waiting to be signed by our -callback that we registered as the second argument of -``registerProxyTransactor``, and one for letting the core know that our -ethereum.js object is capable of proxying transactions sent from the -addresses passed as the first argument of ``registerProxyTransactor``. - -The first is ``eth_registerAddressHandler``; it takes one argument which -is an array of addresses and returns an integer identifier. Any -otherwise unsignable transactions whose from address is included in this -array should be, at some time later, returned to this session as a -result of polling the RPC function ``eth_checkProxyTransactions``. - -``eth_checkProxyTransactions`` takes one argument - the previous integer -identifier and returns an array of transactions, each of the form that -are passed to ``web3.eth.transact``. - -Core -~~~~ - -Cores must maintain queues of proxy transactions together with sets of -addresses, one each per ethereum.js ``web3.eth`` object (identified -through the integer returned to ``eth_registerAddressHandler`` and -provided by ``eth_checkProxyTransactions``). These transactions are to -be returned to the session via ``eth_checkProxyTransactions``. They are -to be filled whenever an ``eth_transact`` is called (from any session) -with a ``from`` address that is contained in the corresponding set of -proxyable addresses. - -Notes -~~~~~ - -If it's called twice, all previous state associated with it is replaced. -If two ethereum.js ``web3.eth`` objects both try to handle the same -address, the first one wins and the second silently fails. - -NatSpec messages should be shown for all transactions, ideally only a -single ultimate user action required for any given high-level -transaction. E.g.: - -- Send 56 ether to ``Dave - 0x56789123`` from account - ``Gav's Bank Account - 0x12345678``. -- Wallet dapp handling account ``Gav's Bank Account - 0x12345678`` - requests authorisation to conduct the above through: Message from - ``Gav - 0x34343455`` to ``Gav's Bank Account - 0x12345678`` to: Send - 56 ether to ``Dave - 0x56789123``. - -The first NatSpec line just corresponds to the first bare and -impossible-to-sign transaction from a contract. The second is the actual -transaction that will be signed, stating that Gav (the account for which -we have a secret key), would sign a transaction instructing the wallet -to send the funds. diff --git a/old-docs-for-reference/main-wiki.rst/RLP.rst b/old-docs-for-reference/main-wiki.rst/RLP.rst deleted file mode 100644 index f07d984..0000000 --- a/old-docs-for-reference/main-wiki.rst/RLP.rst +++ /dev/null @@ -1,107 +0,0 @@ -The purpose of RLP (Recursive Length Prefix) is to encode arbitrarily -nested arrays of binary data, and RLP is the main encoding method used -to serialize objects in Ethereum. The only purpose of RLP is to encode -structure; encoding specific atomic data types (eg. strings, ints, -floats) is left up to higher-order protocols; in Ethereum integers must -be represented in big endian binary form with no leading zeroes (thus -making the integer value zero be equivalent to the empty byte array). - -If one wishes to use RLP to encode a dictionary, the two suggested -canonical forms are to either use ``[[k1,v1],[k2,v2]...]`` with keys in -lexicographic order or to use the higher-level `Patricia -Tree `__ encoding -as Ethereum does. - -Definition -~~~~~~~~~~ - -The RLP encoding function takes in an item. An item is defined as -follows: - -- A string (ie. byte array) is an item -- A list of items is an item - -For example, an empty string is an item, as is the string containing the -word "cat", a list containing any number of strings, as well as more -complex data structures like -``["cat",["puppy","cow"],"horse",[[]],"pig",[""],"sheep"]``. Note that -in the context of the rest of this article, "string" will be used as a -synonym for "a certain number of bytes of binary data"; no special -encodings are used and no knowledge about the content of the strings is -implied. - -RLP encoding is defined as follows: - -- For a single byte whose value is in the ``[0x00, 0x7f]`` range, that - byte is its own RLP encoding. -- Otherwise, if a string is 0-55 bytes long, the RLP encoding consists - of a single byte with value **0x80** plus the length of the string - followed by the string. The range of the first byte is thus - ``[0x80, 0xb7]``. -- If a string is more than 55 bytes long, the RLP encoding consists of - a single byte with value **0xb7** plus the length of the length of - the string in binary form, followed by the length of the string, - followed by the string. For example, a length-1024 string would be - encoded as ``\xb9\x04\x00`` followed by the string. The range of the - first byte is thus ``[0xb8, 0xbf]``. -- If the total payload of a list (i.e. the combined length of all its - items) is 0-55 bytes long, the RLP encoding consists of a single byte - with value **0xc0** plus the length of the list followed by the - concatenation of the RLP encodings of the items. The range of the - first byte is thus ``[0xc0, 0xf7]``. -- If the total payload of a list is more than 55 bytes long, the RLP - encoding consists of a single byte with value **0xf7** plus the - length of the length of the payload in binary form, followed by the - length of the payload, followed by the concatenation of the RLP - encodings of the items. The range of the first byte is thus - ``[0xf8, 0xff]``. - -In code, this is: - -.. code:: python - - def rlp_encode(input): - if isinstance(input,str): - if len(input) == 1 and chr(input) < 128: return input - else: return encode_length(len(input),128) + input - elif isinstance(input,list): - output = '' - for item in input: output += rlp_encode(item) - return encode_length(len(output),192) + output - - def encode_length(L,offset): - if L < 56: - return chr(L + offset) - elif L < 256**8: - BL = to_binary(L) - return chr(len(BL) + offset + 55) + BL - else: - raise Exception("input too long") - - def to_binary(x): - return '' if x == 0 else to_binary(int(x / 256)) + chr(x % 256) - -Examples -~~~~~~~~ - -The string "dog" = [ 0x83, 'd', 'o', 'g' ] - -The list [ "cat", "dog" ] = -``[ 0xc8, 0x83, 'c', 'a', 't', 0x83, 'd', 'o', 'g' ]`` - -The empty string ('null') = ``[ 0x80 ]`` - -The empty list = ``[ 0xc0 ]`` - -The encoded integer 15 (':raw-latex:`\x`0f') = ``[ 0x0f ]`` - -The encoded integer 1024 (':raw-latex:`\x`04:raw-latex:`\x`00') = -``[ 0x82, 0x04, 0x00 ]`` - -The `set theoretical -representation `__ -of two, -``[ [], [[]], [ [], [[]] ] ] = [ 0xc7, 0xc0, 0xc1, 0xc0, 0xc3, 0xc0, 0xc1, 0xc0 ]`` - -The string "Lorem ipsum dolor sit amet, consectetur adipisicing elit" = -``[ 0xb8, 0x38, 'L', 'o', 'r', 'e', 'm', ' ', ... , 'e', 'l', 'i', 't' ]`` diff --git a/old-docs-for-reference/main-wiki.rst/RPC-Testing.rst b/old-docs-for-reference/main-wiki.rst/RPC-Testing.rst deleted file mode 100644 index 72ee3f0..0000000 --- a/old-docs-for-reference/main-wiki.rst/RPC-Testing.rst +++ /dev/null @@ -1,12 +0,0 @@ -:: - - { - blockchain: [ - { - difficulty: 1024, - transactions: [ - ... - ] - }, - ] - } diff --git a/old-docs-for-reference/main-wiki.rst/Raspberry-Pi-instructions.rst b/old-docs-for-reference/main-wiki.rst/Raspberry-Pi-instructions.rst deleted file mode 100644 index 7b0e624..0000000 --- a/old-docs-for-reference/main-wiki.rst/Raspberry-Pi-instructions.rst +++ /dev/null @@ -1,174 +0,0 @@ -Get the "everything-is-ready" image for your Raspberry Pi 2 ------------------------------------------------------------ - -Download from: http://gav.ethdev.com/ArchLinuxEthereum12082015.img.zip -(07.01.2016: download still not available, Gavin Wood referred to -Christoph Jentzsch, waiting for response from @CJentzsch. It's 2.4 GB in -size, if you want to save bandwidth, go and build it yourself, see -instructions below) - -Unzip it and follow those guidelines to copy the image to your sd card: -https://www.raspberrypi.org/documentation/installation/installing-images/ - -Plugin the sd card, LAN connection and the power supply and lets start! - -In order to connect to your pi follow those instructions: -https://www.raspberrypi.org/documentation/remote-access/ssh - -Currently there are two users, ``root`` and ``pi``. The passwords are -``root`` and ``raspberry``, respectively. The first thing you should do -is change that. Otherwise everyone can see your IP in netstats and just -log into your Raspberry Pi. Log in and type ``passwd `` to update -the password for each user. - -Currently the go client (geth) and the cpp client (eth) are -preinstalled. You can find instruction on how to use them here: -https://github.com/ethereum/go-ethereum/wiki/Command-Line-Options and -here: -https://github.com/ethereum/cpp-ethereum/wiki/Using-Ethereum-CLI-Client. -But executing eth/geth with ``--help`` will give you more up-to-date -information on how to use them. Also eth-netstats is installed. You can -find instructions in how to use it here: -https://github.com/ethereum/wiki/wiki/Network-Status. It is used to -display your client on the centralized network server -(http://stats.ethdev.com/). In order to give your client a different -name, choose your favorite command line text editor and change the -``INSTANCE_NAME`` parameter in ``~/eth-net-intelligence-api/app.json`` -to whatever you like. - -For convenience there is ``startClientWithNetstat.sh`` -script (execute it with bash) which starts the client and registers it -on eth-netstats. (Note: Downloading the chain takes several hours up to -a day, during that time the Raspberry Pi is so busy that netstats -doesn't work properly, it may even crash. You may not see your client on -netstats until the download is complete. If you don't see you client -after one complete day, try a reboot and execute the script again.) - -For updating the clients you can just do -``bash updateClient.sh`` (this may take a while and may -not work, since it is pulling current develop. Dependencies have -changed). - -Resize your system to use large sd cards ----------------------------------------- - -The image is for a 8GB sd card. It allocates 2 GB as swap (needed for -compiling and mining :-) ). If your sd card is larger than 8GB, then -follow those instructions: - -As root execute - -:: - - fdisk /dev/mmcblk0 - -Delete the third partition: - -:: - - d - 3 - -Create a new primary partition and use default sizes prompted. This will -then create a partition that fills the disk. - -:: - - n - p - 3 - enter - enter - -Save and exit fdisk: - -:: - - w - -Now reboot (``reboot``). Once rebooted: - -:: - - resize2fs /dev/mmcblk0p3 - -That's it, now you are using all the disk space available. This has been -tested on the Raspberry Pi 2 only. - -Just get the binaries ---------------------- - -Alternativly, you can use the linux system of your choice and and get -the arm binaries here: \* -https://build.ethereum.org/builds/ARM%20Go%20develop%20branch/geth-ARM-latest.tar.bz2 -(go) \* -https://github.com/doublethinkco/webthree-umbrella-cross/releases/tag/crosseth-armhf-apt-2015-12-31 -(cpp-ethereum) - -Build it yourself ------------------ - -If you want to build all that yourself, you can do so following those -instructions: - -We start with a ArchLinux system with 2 GB swap. Instructions on how to -get there can be found here: -http://archlinuxarm.org/forum/viewtopic.php?f=60&t=8366 - -go-ethereum -~~~~~~~~~~~ - -`Installation instructions for -ARM `__ - -cpp-ethereum -~~~~~~~~~~~~ - -First we install all necessary libaries as described here -https://github.com/ethereum/cpp-ethereum/wiki/Building-on-ArchLinux (but -without the qt libs): - -These are the required packages from the official repositories: - -:: - - sudo pacman -Sy - sudo pacman -S base-devel cmake scons clang llvm boost leveldb crypto++ jsoncpp - -These are packages that you can get from the `AUR(Arch User -Repositories) `__. I would suggest using -`yaourt `__ or any other of -the `AUR helpers `__. - -:: - - yaourt -S argtable libjson-rpc-cpp - -Yaourt can be installed by doing this: - -:: - - curl -O https://aur.archlinux.org/packages/pa/package-query/package-query.tar.gz - tar -xvzf package-query.tar.gz - cd package-query - makepkg -si - - cd .. - curl -O https://aur.archlinux.org/packages/ya/yaourt/yaourt.tar.gz - tar -xvzf yaourt.tar.gz - cd yaourt - makepkg -si - -Building the client -^^^^^^^^^^^^^^^^^^^ - -The instructions for building the client from here and on are identical -with Ubuntu so the reader should refer to the `relevant -page `__. -but use ``cmake .. -DBUNDLE=minimal -DETHASHCL=0 -DEVMJIT=0`` instead. - -Resources: - -http://archlinuxarm.org/forum/viewtopic.php?f=60&t=8366 -http://archlinuxarm.org/forum/viewtopic.php?f=31&t=3119 -https://github.com/ethereum/cpp-ethereum/wiki/Building-on-ArchLinux diff --git a/old-docs-for-reference/main-wiki.rst/Registrar-ABI.rst b/old-docs-for-reference/main-wiki.rst/Registrar-ABI.rst deleted file mode 100644 index c21964d..0000000 --- a/old-docs-for-reference/main-wiki.rst/Registrar-ABI.rst +++ /dev/null @@ -1,59 +0,0 @@ -Registrar -~~~~~~~~~ - -Read-only interface that all registrars must implement - -Javascript -^^^^^^^^^^ - -:: - - var Registrar = web3.eth.contract([{"constant":true,"inputs":[{"name":"_owner","type":"address"}],"name":"name","outputs":[{"name":"o_name","type":"bytes32"}],"type":"function"},{"constant":true,"inputs":[{"name":"_name","type":"bytes32"}],"name":"owner","outputs":[{"name":"o_owner","type":"address"}],"type":"function"},{"constant":true,"inputs":[{"name":"_name","type":"bytes32"}],"name":"content","outputs":[{"name":"o_content","type":"bytes32"}],"type":"function"},{"constant":true,"inputs":[{"name":"_name","type":"bytes32"}],"name":"addr","outputs":[{"name":"o_address","type":"address"}],"type":"function"},{"constant":true,"inputs":[{"name":"_name","type":"bytes32"}],"name":"subRegistrar","outputs":[{"name":"o_subRegistrar","type":"address"}],"type":"function"},{"anonymous":false,"inputs":[{"indexed":true,"name":"name","type":"bytes32"}],"name":"Changed","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"name":"name","type":"bytes32"},{"indexed":true,"name":"addr","type":"address"}],"name":"PrimaryChanged","type":"event"}]); - -Solidity -^^^^^^^^ - -:: - - contract Registrar{function name(address _owner)constant returns(bytes32 o_name){}function owner(bytes32 _name)constant returns(address o_owner){}function content(bytes32 _name)constant returns(bytes32 o_content){}function addr(bytes32 _name)constant returns(address o_address){}function subRegistrar(bytes32 _name)constant returns(address o_subRegistrar){}} - -GlobalRegistrar -~~~~~~~~~~~~~~~ - -``GlobalRegistrar`` is the main name registration object. The global -registrar object on the PoC-9 testnet is at address -``0xc6d9d2cd449a754c494264e1809c50e34d64562b``. - -Javascript -^^^^^^^^^^ - -:: - - var GlobalRegistrar = web3.eth.contract([{"constant":true,"inputs":[{"name":"_owner","type":"address"}],"name":"name","outputs":[{"name":"o_name","type":"bytes32"}],"type":"function"},{"constant":true,"inputs":[{"name":"_name","type":"bytes32"}],"name":"owner","outputs":[{"name":"","type":"address"}],"type":"function"},{"constant":true,"inputs":[{"name":"_name","type":"bytes32"}],"name":"content","outputs":[{"name":"","type":"bytes32"}],"type":"function"},{"constant":true,"inputs":[{"name":"_name","type":"bytes32"}],"name":"addr","outputs":[{"name":"","type":"address"}],"type":"function"},{"constant":false,"inputs":[{"name":"_name","type":"bytes32"}],"name":"reserve","outputs":[],"type":"function"},{"constant":true,"inputs":[{"name":"_name","type":"bytes32"}],"name":"subRegistrar","outputs":[{"name":"o_subRegistrar","type":"address"}],"type":"function"},{"constant":false,"inputs":[{"name":"_name","type":"bytes32"},{"name":"_newOwner","type":"address"}],"name":"transfer","outputs":[],"type":"function"},{"constant":false,"inputs":[{"name":"_name","type":"bytes32"},{"name":"_registrar","type":"address"}],"name":"setSubRegistrar","outputs":[],"type":"function"},{"constant":false,"inputs":[],"name":"Registrar","outputs":[],"type":"function"},{"constant":false,"inputs":[{"name":"_name","type":"bytes32"},{"name":"_a","type":"address"},{"name":"_primary","type":"bool"}],"name":"setAddress","outputs":[],"type":"function"},{"constant":false,"inputs":[{"name":"_name","type":"bytes32"},{"name":"_content","type":"bytes32"}],"name":"setContent","outputs":[],"type":"function"},{"constant":false,"inputs":[{"name":"_name","type":"bytes32"}],"name":"disown","outputs":[],"type":"function"},{"constant":true,"inputs":[{"name":"_name","type":"bytes32"}],"name":"register","outputs":[{"name":"","type":"address"}],"type":"function"},{"anonymous":false,"inputs":[{"indexed":true,"name":"name","type":"bytes32"}],"name":"Changed","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"name":"name","type":"bytes32"},{"indexed":true,"name":"addr","type":"address"}],"name":"PrimaryChanged","type":"event"}]); - -Solidity -^^^^^^^^ - -:: - - contract GlobalRegistrar{function name(address _owner)constant returns(bytes32 o_name){}function owner(bytes32 _name)constant returns(address ){}function content(bytes32 _name)constant returns(bytes32 ){}function addr(bytes32 _name)constant returns(address ){}function reserve(bytes32 _name){}function subRegistrar(bytes32 _name)constant returns(address o_subRegistrar){}function transfer(bytes32 _name,address _newOwner){}function setSubRegistrar(bytes32 _name,address _registrar){}function Registrar(){}function setAddress(bytes32 _name,address _a,bool _primary){}function setContent(bytes32 _name,bytes32 _content){}function disown(bytes32 _name){}function register(bytes32 _name)constant returns(address ){}} - -OwnedRegistrar -~~~~~~~~~~~~~~ - -OwnedRegistrar fill the same interface as Registrar but allows a single -owner complete authority over its contents. - -Javascript -^^^^^^^^^^ - -:: - - var OwnedRegistrar = web3.eth.contract([{"constant":true,"inputs":[{"name":"_owner","type":"address"}],"name":"name","outputs":[{"name":"o_name","type":"bytes32"}],"type":"function"},{"constant":true,"inputs":[{"name":"_name","type":"bytes32"}],"name":"owner","outputs":[{"name":"o_owner","type":"address"}],"type":"function"},{"constant":true,"inputs":[{"name":"_name","type":"bytes32"}],"name":"getAddress","outputs":[{"name":"o_owner","type":"address"}],"type":"function"},{"constant":true,"inputs":[{"name":"_name","type":"bytes32"}],"name":"content","outputs":[{"name":"","type":"bytes32"}],"type":"function"},{"constant":true,"inputs":[{"name":"_name","type":"bytes32"}],"name":"addr","outputs":[{"name":"","type":"address"}],"type":"function"},{"constant":true,"inputs":[{"name":"_name","type":"bytes32"}],"name":"subRegistrar","outputs":[{"name":"","type":"address"}],"type":"function"},{"constant":true,"inputs":[{"name":"_owner","type":"address"}],"name":"getName","outputs":[{"name":"o_name","type":"bytes32"}],"type":"function"},{"constant":false,"inputs":[{"name":"_name","type":"bytes32"},{"name":"_registrar","type":"address"}],"name":"setSubRegistrar","outputs":[],"type":"function"},{"constant":true,"inputs":[{"name":"_name","type":"bytes32"}],"name":"record","outputs":[{"name":"o_primary","type":"address"},{"name":"o_subRegistrar","type":"address"},{"name":"o_content","type":"bytes32"}],"type":"function"},{"constant":false,"inputs":[{"name":"_name","type":"bytes32"},{"name":"_a","type":"address"},{"name":"_primary","type":"bool"}],"name":"setAddress","outputs":[],"type":"function"},{"constant":false,"inputs":[{"name":"_name","type":"bytes32"},{"name":"_content","type":"bytes32"}],"name":"setContent","outputs":[],"type":"function"},{"constant":false,"inputs":[{"name":"_name","type":"bytes32"}],"name":"disown","outputs":[],"type":"function"},{"anonymous":false,"inputs":[{"indexed":true,"name":"name","type":"bytes32"}],"name":"Changed","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"name":"name","type":"bytes32"},{"indexed":true,"name":"addr","type":"address"}],"name":"PrimaryChanged","type":"event"}]); - -Solidity -^^^^^^^^ - -:: - - contract OwnedRegistrar{function name(address _owner)constant returns(bytes32 o_name){}function owner(bytes32 _name)constant returns(address o_owner){}function getAddress(bytes32 _name)constant returns(address o_owner){}function content(bytes32 _name)constant returns(bytes32 ){}function addr(bytes32 _name)constant returns(address ){}function subRegistrar(bytes32 _name)constant returns(address ){}function getName(address _owner)constant returns(bytes32 o_name){}function setSubRegistrar(bytes32 _name,address _registrar){}function record(bytes32 _name)constant returns(address o_primary,address o_subRegistrar,bytes32 o_content){}function setAddress(bytes32 _name,address _a,bool _primary){}function setContent(bytes32 _name,bytes32 _content){}function disown(bytes32 _name){}} diff --git a/old-docs-for-reference/main-wiki.rst/Security-Categorization.rst b/old-docs-for-reference/main-wiki.rst/Security-Categorization.rst deleted file mode 100644 index cb12049..0000000 --- a/old-docs-for-reference/main-wiki.rst/Security-Categorization.rst +++ /dev/null @@ -1,195 +0,0 @@ -See also: https://github.com/ethereum/wiki/wiki/Design-Rationale, for -descriptions of potentially counterintuitive design decisions in -Ethereum. - -The purpose of this document is to attempt to create a taxonomy of key -security properties that we are targeting for the Ethereum protocol, -implementation and materials to have at launch time, as well as provide -supplementary information where needed for each one. - -Yellow Paper -~~~~~~~~~~~~ - -- Paper is free of typos and mathematical and grammatical errors -- The definitions in the paper are clear and unambiguous -- Pay particular attention to external dependencies, eg. the definition - of secp256k1 -- In places where the formal definition deviates drastically from all - commonly used intuitive definitions, clear explanations are provided - -Proof of Work -~~~~~~~~~~~~~ - -The working spec description of Dagger Hashimoto is available at -https://github.com/ethereum/wiki/wiki/Ethash - -The algorithm is intended to have the following key properties: - -- ASIC resistance (ie. lowest possible ASIC speedup coefficient) -- Light-client verifiability, in <1s on Python or Javascript on a - desktop or C++ on a Raspberry Pi - -And should not have any of the following flaws: - -- High centralization risk (ie. unboundedly superlinear return) -- Possibility of superior "complex" software implementations (eg. as in - SAT solving) -- Cheap evasion of memory hardness (due to light-client verifiability - considerations, a low-memory implementation must exist, but this - should not be a practical way of mining, and hybrid reduced-memory - implementations should also be uneconomical) -- Outright trivial attack (eg. the underlying function is actually - polytime invertible) -- Pool resistance -- If pools are going to happen, p2pools should be a viable option - -Block algorithm -~~~~~~~~~~~~~~~ - -A simulator of difficulty adjustment is available at -https://github.com/ethereum/economic-modeling/blob/master/diffadjust/blkdiff.py -. - -The modified GHOST algorithm is defined -`here `__. - -The following properties are desired: - -- The difficulty adjustment should update quickly to increasing or - decreasing hashpower and should not be maliciously gameable in any - sense. -- The 12 second block time + GHOST should not have perverse incentives - (ie. it should be optimal to mine on the head) -- The 12 second block time should not induce an excessively high orphan - rate and higher confirmation times than expected. -- Ethereum should remain reasonably light-client friendly, especially - for low-power IoT (patch solution if necessary: block skiplists, eg. - every block with number % n^k == 0 must refer to the block n^k blocks - ago, for say n = 4 and k = 0...3; this basically entails turning - prevhash into an array) -- Blockchain bloat: blocksize too big to incentivize new full nodes. - Will it be dynamically adjusted? If so, also rogue miners attack to - bloat the blockchain -- It should be expensive to generate incentives not to mine on the best - chain using baits inside of smart contracts - -Gas economics -~~~~~~~~~~~~~ - -- The floating gas limit should achieve the compatibility objectives - described in https://github.com/ethereum/wiki/wiki/White-Paper#fees -- There should not exist a way for a transaction to get itself executed - and spend large amounts of computational resources on many nodes - without paying for gas - - - The following is an example vulnerability: a miner can create a - transaction A that spends a very large amount of gas (eg. - ~gaslimit \* 0.99) running useless computation. That miner then - creates a transaction B with the same nonce that has no effect, - and tries to mine a block containing B. If a miner produces a - block containing B, it broadcasts A, forcing all other nodes on - the network to waste time processing A, even though A actually - getting accepted is nearly impossible since B is already published - in a block. - -- There should not be any kind of of perverse incentive in the way gas - costs work on the high level (eg. how gas is passed from parent to - child message, how gas is refunded, exception reversions, etc) -- Storage gas refund mechanism should not be exploitable -- The operation gas costs should match the cost of running the - operation at least complexity-theoretically (ie. there should be no - way of causing O(n^2) computational load with O(n) gas). - - - An n\*log(n) vulnerability against ``JUMP``\ s in the JIT VM is - known, but is deemed not sufficiently catastrophic to worry about - - An example prior vulnerability in PoC6 was that since - ``CALLDATACOPY`` always cost 1 gas, you could incur n^2 - computational load with n ``CALLDATACOPY`` instructions on n bytes - of memory (ie. O(n) gas) - - A good implementation of ``CALL`` and ``CREATE`` should never - actually copy memory to produce call data. Otherwise, it will be - vulnerable to a quadratic execution attack where a contract runs - CALL n times on n bytes of memory, causing n^2 computational load - on O(n) gas - - The return data of a ``CALL`` is not a source of a quadratic - execution vulnerability because the ``RETURN`` opcode expands - memory in each inner call, thereby costing ``n`` memory expansion - gas ``n`` times. - -- Expanding the amount of data stored in the state should cost at least - 5 gas per byte in all cases -- There should not exist some operations are much more expensive to - execute per unit gas than others, leading to a high "multiplicative - griefing factor". Note that this is not a primary concern for - security audits; we will perform profiles of each operation ourselves - later on in order to set gas costs optimally. - -VM -~~ - -- The VM implementation and the formal specifications (so called Yellow - Paper) should be equivalent. The VM implementation can be found at - https://github.com/ethereum/go-ethereum/tree/master/vm -- The VM should be resistant to the following attack scenarios: -- Transactions/messages whose execution will somehow escape the VM and - either reveal or modify memory or hard drive contents of the client's - machine -- Transactions/messages whose execution will cause a system crash -- Transactions/messages that could be processed differently by - different machines -- Transactions/messages that have a much higher execution time / gas - cost ratio than most others, opening the door to a denial-of-service - attack - -Wire protocol -~~~~~~~~~~~~~ - -The wire protocol is described here: -https://github.com/ethereum/wiki/wiki/%C3%90%CE%9EVp2p-Wire-Protocol - -The wire protocol should be secure against the following issues: - -- Node isolation against the block spread algorithm -- Single account transaction paralelism ratio due to nonce validation - in peers (vs DoS prevention) -- Sequences of wire messages that would lead to the recipient spending - a very large amount of time responding to them -- Sequences of wire messages that would lead to the recipient storing a - large amount of data -- Sequences of wire messages that would lead to the recipient storing - data that is specifically crafted to make data structures blow up - (eg. sending transactions with hashes in sequence in order to make - trees very very deep) -- Any third party software, e.g. leveldb would also fall under this - scrutiny - e.g. what kind of tree is leveldb? Is it vulnerable to - such DoS attacks? -- Messages that would fingerprint the target - -JS / RPC -~~~~~~~~ - -- Check that there are no exploits in the Javascript API, JSON-RPC API -- Define a security model for browser+js bindings. (-or give - nathan@leastauthority.com a link to an existing doc.) - -Libraries -~~~~~~~~~ - -- Leveldb -- Check for hidden limits in leveldb and other libraries that might - trigger inconsistent failures outside the VM, similar to - http://bitcoinmagazine.com/3668/bitcoin-network-shaken-by-blockchain-fork/ -- Crytopgraphic libraries -- secp256k1 with a Go bridge (https://github.com/obscuren/secp256k1-go) -- A fork of the official golang sha3 package - (https://github.com/obscuren/sha3) (Reason for using a sha3 fork is - because the official sha3 has switched to FIPS-202 which Ethereum - can't use because genesis addresses have been generated using an - earlier version of sha3) -- Official ripemd package (code.google.com/p/go.crypto/ripemd160) - -Non-Audit security-related product wishlist: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- How-to write secure contracts -- How-to write secure html+js front-ends diff --git a/old-docs-for-reference/main-wiki.rst/Security-Issue-Process.rst b/old-docs-for-reference/main-wiki.rst/Security-Issue-Process.rst deleted file mode 100644 index a31540c..0000000 --- a/old-docs-for-reference/main-wiki.rst/Security-Issue-Process.rst +++ /dev/null @@ -1,52 +0,0 @@ -Draft of steps that should be taken when finding a security issue in -Ethereum. Security issue is defined as a problem in scope of -`Security-Categorization `__. - -Partly inspired by `OWASP Risk -Rating `__ - -Documentation -~~~~~~~~~~~~~ - -- Add a entry describing the issue at (TODO: github link). -- Estimate likelihood, impact and complexity of fix. -- Affected software version(s). - -Estimate Likelihood -~~~~~~~~~~~~~~~~~~~ - -- How likely is it to be uncovered and exploited by an attacker? -- Ease of discovery? -- Ease of exploit? -- Likelihood of detection? - -Estimate Impact -~~~~~~~~~~~~~~~ - -- Blockchain consensus. Potential of blockchain fork? -- Financial damage. Loss of ether? -- Privacy. E.g. revealing who sent a tx or who owns an address. -- Availability. Can it impact availablity of node(s)? - -Technical description -~~~~~~~~~~~~~~~~~~~~~ - -- Protocol version. -- Client version(s). Single or multiple implementations? -- OS / external library version(s). -- Link to relevant source code. -- How to fix. -- How to test. - -Ownership / Responsibility -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- Who is assigned to fix the issue? -- Who will test / review a fix? -- Who takes responsibility for preparing new builds of client software? - -Disclosure -~~~~~~~~~~ - -- Who takes on to disclose the issue? -- Communication channels (mail lists, twitter, github). diff --git a/old-docs-for-reference/main-wiki.rst/Serenity_Wishlist.rst b/old-docs-for-reference/main-wiki.rst/Serenity_Wishlist.rst deleted file mode 100644 index 7493a1d..0000000 --- a/old-docs-for-reference/main-wiki.rst/Serenity_Wishlist.rst +++ /dev/null @@ -1,198 +0,0 @@ -This document outlines known flaws and missing features in Ethereum -Frontier and Homestead that are non-serious but inconvenient, and which -we decided to leave in in order to be able to launch in any reasonable -timeframe. We intend to thoroughly investigate solving all of these -issues for Serenity (aka. Ethereum 1.1). - -Big Issues -~~~~~~~~~~ - -1. Because every user must process every transaction (ie. the per-user - required quantity of storage is linear in the number of users or - level of usage), Ethereum is currently fundamentally unscalable, as - are all other blockchain technologies to date. We believe this to be - the single largest problem in blockchain development, and it will be - our primary focus for either Serenity or a version soon after. -2. Proof of work is an extremely expensive means of maintaining - consensus and produces substantial negative externalities due to - environmental issues and to a lesser degree principal-agent issues, - and its security guarantees are uncomfortably incomplete (eg. it is - vulnerable to `P + epsilon - attacks `__ - or even outright bribes of fairly low size). We plan to resolve this - via proof of stake, which resolves these issues via a combination of - proof of stake and subjective resolution-of-last-resort. A small - amount of proof of work may remain as an anti-DDoS measure. - -Trie -~~~~ - -In the process of designing Ethereum 1.0 we have done a thorough job of -optimizing the Ethereum virtual machine's computational power, but a -much less thorough job of optimizing the database. There exists the -possibility for substantial space savings, for both full nodes and light -clients, by reorganizing Merkle tree structures and accounts. One -example model for a more optimized state tree is the following: - -1. Assign account numbers sequentially, not via - ``address = sha3(pubkey) % 2**160``. This means that the set of - accounts is contiguous, allowing standard binary Merkle trees to be - used in place of Patricia trees, saving substantial space in state, - history and LOAD/SSTORE time due to the resulting tight-packing. -2. Where Patricia trees are required, switch from hex to binary (est. - 10-50% savings) -3. Where Patricia trees are required, note that currently a proof stores - redundant info by storing a hash of a tree node in one node and then - the other node separately. Create a special-purpose compression - algorithm, either LZV style or placing nodes into each other directly - when they refer to each other, to deduplicate (est. 35% savings). -4. Charge rent for accounts. This entails expanding accounts by adding a - ``last_accessed`` parameter, and then when an account is accessed we - update the parameter to the current block timestamp and - simultaneously subtract - ``rent * (block.timestamp - acct.last_accessed)`` from the account - balance, where ``rent`` is somehow dynamically adjusted. If the new - balance is below zero, then the account is destroyed and a large gas - refund is provided. We theorize that large miners and account holders - will want to create transactions that destroy accounts that are - lagging on rent in order to reduce storage bloat; alternatively we - can incentivize it with an additional security deposit. -5. Require transactions to include a timestamp, so that they can only be - valid in ``[timestamp, timestamp + 3600]``. This prevents replay - attacks in the special case that accounts go down to zero balance, - get deleted and then regain balance but with a nonce reset to zero. - -More expressive Merkle trees -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Certain kinds of mechanisms, to be developed on Ethereum, require a -richer set of data structures then just arrays, key/value maps, etc; the -most commonly asked-for one is a heap (or an equivalent data structure -that supports push/pop/top in logtime), highly useful in -front-runner-proof markets among other applications. Currently, -implementing a heap in Ethereum will lead to log^3(n) overhead, as we -have a tree (the heap) on top of a tree (the account storage Patricia -tree) on top of a tree (leveldb). Making a custom DB for the Patricia -tree will likely need to be done at some point anyway, and will remove -one level of overhead. However, the larger gain will come from the -ability to have a Merklized heap-like structure, essentially making the -heap operations native to the protocol. This reduces the total overhead -all the way to the optimum of log(n). - -See also: Andrew Miller's `Lambda -Auth `__, potentially useful as a -starting point for a generalized design. - -Events -~~~~~~ - -There should ideally be some mechanism by which one can create events -that trigger automatically at certain times in the future, without any -overlay protocols (as one simple application of this, consider a dice -game that depends on future block data as a source of randomness). For -this to work effectively, one must introduce an "event tree" into the -Ethereum state alongside the state tree, and add specialized opcodes for -creating events (events can be seen as one-way calls that get "frozen" -and then executed in the future). A mechanism for gas costs for events, -particularly recurring events, should be determined. - -Verification -~~~~~~~~~~~~ - -Currently, secp256k1 ECDSA + SHA3 exists as a privileged signature -verification algorithm in Ethereum. Ideally, since we are a generalized -platform, it would be nice to be able to support any signature -verification algorithm. A proposed design for this is: - -1. When a transaction is sent, it does not require a sender, only a - "destination" address. Gas price, start gas, value, and data are - still required. -2. The top-level message execution by default has a limit of 25000 gas, - and within that time must either exit with an error, or run an - ``ACCEPT`` opcode, paying for the full amount of gas from that - contract's account. If the message exits with an error before - ACCEPTing, the transaction is invalid. If it ACCEPTs, then it has the - full amount of gas to run any other computation, send sub-messages, - etc. The intent is for the first 25000 gas to be spent verifying a - signature placed inside of the transaction data, and exiting with an - error if the signature is invalid. - -Ideally, the initial limit would be large enough to support many kinds -of signatures, but still small enough to be DDoS-proof. An alternative -would be to require PoW on transactions, and scale the PoW difficulty -with a verification gas limit set in the transaction; ASIC-resistant PoW -can be used for this, though it would need to be carefully designed to -be more CPU-friendly rather than GPU-friendly as is the case for Ethash. - -Compression -~~~~~~~~~~~ - -Currently, wire and database compression is done with a fairly crude -algorithm that run-length-encodes zeroes but otherwise leaves data -unchanged. Substantial gains can probably be made by applying either a -pre-generated Huffman code or some separate compression algorithm such -as http://lloyd.github.io/easylzma/. - -Virtual machine -~~~~~~~~~~~~~~~ - -The Ethereum virtual machine has a number of suboptimalities at present, -and so there are plenty of features that can be added or impoved. -Particular possibilities include: - -1. The addition of opcodes specialized for 64-bit arithmetic, which can - be done on machines much more quickly. -2. The addition of ``MCOPY`` as an opcode and not a contract. -3. Replacement of DUP1...DUP16 and SWAP1...SWAP16 with ``DUP `` - (where ```` is stored similarly to pushdata). This allows for - unlimited depth in stack variables. -4. The addition of a ``DEPTH`` opcode to determine the current call - stack depth, useful or determining whether or not there is enough - stack space to make a particular sub-call with a compile-time-known - depth. -5. A more radical rearchitecture where the VM deals with 64-bit values - only, and long-arithmetic is done directly over memory slices. This - removes the 256-bit limit and allows easy crypto calculations at - arbitrary sizes. - -Sending funds -~~~~~~~~~~~~~ - -Currently, there is no way to send *all* of one's funds to a contract -from an externally owned account, unless one can exactly estimate the -amount of gas that will be consumed. This adds some inconvenience to the -process of emptying accounts. A possible solution is a "keep the change" -opcode, by which a contract can (i) absorb all remaining gas in a -message, (ii) claim ``gas * gasprice`` as ether for itself, and (iii) -have that gas NOT count toward the miner's revenue or the block's gas -limit. - -Currency Neutrality -~~~~~~~~~~~~~~~~~~~ - -Allow any currency to be used for purposes of security deposits, paying -rent, etc. One possible framework in which this could happen is as -follows: - -1. Create a base protocol-level concept of "currency". An eligible - currency should give the protocol the ability to print more units of - it and should support the standard send/receive/allow withdrawal - interface. -2. Have (and subsidize liquidity on LMSR-style?) an on-protocol - decentralized exchange to determine the price of each token relative - to each other token. -3. Anyone can set a security deposit of any size in any currency. The - protocol keeps track of a minimum security deposit in every currency - (adjusted to target some number of validators), and you cannot add a - deposit unless you provide at least this quantity. A deposit ceases - to be usable if it falls below 50% of the minimum. - -Alternatives include being more liberal with regard to the assets -involved, but using some kind of preference-revelation scheme to -determine the value of a maximally arbitrary asset (note: this is hard -when you do not have a single "favored currency" which you are assuming -will have higher liquidity than everything else). - -A third option is to have a demurrage-heavy (or otherwise ephemeral) -pseudo-currency, similar to gas, which is in some way assigned to -validators. diff --git a/old-docs-for-reference/main-wiki.rst/Serpent.rst b/old-docs-for-reference/main-wiki.rst/Serpent.rst deleted file mode 100644 index c4c6407..0000000 --- a/old-docs-for-reference/main-wiki.rst/Serpent.rst +++ /dev/null @@ -1,800 +0,0 @@ -Serpent is one of the high-level programming languages used to write -Ethereum contracts. The language, as suggested by its name, is designed -to be very similar to Python; it is intended to be maximally clean and -simple, combining many of the efficiency benefits of a low-level -language with ease-of-use in programming style, and at the same time -adding special domain-specific features for contract programming. The -latest version of the Serpent compiler, available `on -github `__, is written in C++, -allowing it to be easily included in any client. - -This tutorial assumes basic knowledge of how Ethereum works, including -the concept of blocks, transactions, contracts and messages and the fact -that contracts take a byte array as input and provide a byte array as -output. If you do not, then go -`here `__ -for a basic tutorial. - -This documentation is not complete and these examples may further help: - -https://github.com/AugurProject/augur-core/tree/master/tests/serpent\_tests - -https://github.com/ethereum/serpent/tree/develop/examples - -https://github.com/AugurProject/augur-core/tree/master/src - -https://github.com/ethereum/dapp-bin - -Differences Between Serpent and Python -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The important differences between Serpent and Python are: - -- Python numbers have potentially unlimited size, Serpent numbers wrap - around 2256. For example, in Serpent the expression ``3^(2^254)`` - suprisingly evaluates to 1, even though in reality the actual integer - is too large to be recorded in its entirety within the universe. -- Serpent has no decimals. -- Serpent has no list comprehensions (expressions like - ``[x**2 for x in my_list]``), dictionaries or most other advanced - features -- Serpent has no concept of first-class functions. Contracts do have - functions, and can call their own functions, but variables (except - storage) do not persist across calls. -- Serpent has a concept of persistent storage variables (see below) -- Serpent has an ``extern`` statement used to call functions from other - contracts (see below) - -Installation -~~~~~~~~~~~~ - -In order to install the Serpent python library and executable do: - -:: - - $ sudo pip install ethereum-serpent - -You can install pyethereum itself as well: - -:: - - $ sudo pip install ethereum - -If you want a library you can directly call from C++, instead do: - -:: - - $ git clone http://github.com/ethereum/serpent - $ cd serpent - $ make - $ sudo make install - -Tutorial -~~~~~~~~ - -Now, let's write our first contract. Paste the following into a file -called ``mul2.se``: - -:: - - def double(x): - return(x * 2) - -This contract is a simple two lines of code, and defines a function. -Functions can be called either by transactions or by other contracts, -and are the way that Serpent contracts provide an "interface" to other -contracts and to transactions; for example, a contract defining a -currency might have functions ``send(to, value)`` and -``check_balance(address)``. - -Additionally, the Pyethereum testing environment that we will be using -simply assumes that data input and output are in this format. - -Now, let's try actually compiling the code. Type: - -:: - - $ serpent compile mul2.se - 604380600b600039604e567c01000000000000000000000000000000000000000000000000000000006000350463eee9720681141560415760043560405260026040510260605260206060f35b505b6000f3 - -And there we go, that's the hexadecimal form of the code that you can -put into transactions. Or, if you want to see opcodes: - -:: - - $ serpent pretty_compile mul2.se - [PUSH1, 67, DUP1, PUSH1, 11, PUSH1, 0, CODECOPY, PUSH1, 78, JUMP, PUSH29, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, PUSH1, 0, CALLDATALOAD, DIV, PUSH4, 238, 233, 114, 6, DUP2, EQ, ISZERO, PUSH1, 65, JUMPI, PUSH1, 4, CALLDATALOAD, PUSH1, 64, MSTORE, PUSH1, 2, PUSH1, 64, MLOAD, MUL, PUSH1, 96, MSTORE, PUSH1, 32, PUSH1, 96, RETURN, JUMPDEST, POP, JUMPDEST, PUSH1, 0, RETURN] - -Alternatively, you can compile to LLL to get an intermediate -representation: - -:: - - $ serpent compile_to_lll mul2.se - (return 0 - (lll - (with '__funid - (div (calldataload 0) - 26959946667150639794667015087019630673637144422540572481103610249216 - ) - (unless (iszero (eq (get '__funid) 4008276486)) - (seq - (set 'x (calldataload 4)) - (seq - (set '_temp_521 (mul (get 'x) 2)) - (return (ref '_temp_521) 32) - ) - ) - ) - ) - 0 - ) - ) - -This shows you the machinery that is going on inside. As with most -contracts, the outermost layer of code exists only to copy the data of -the inner code during initialization and return it, since the code -returned during initialization is the code that will be executed every -time the contract is called; in the EVM you can see this with the -``CODECOPY`` opcode, and in LLL this corresponds to the ``lll`` -meta-operation. Inside of the LLL, we have a wrapper whose purpose it is -to grab the first four bytes of the contract data, (that's the -``(div (calldataload 0) 26959946667150639794667015087019630673637144422540572481103610249216)``; -we grab four bytes by grabbing the first 32 bytes and dividing it by -2^224) to get the function ID that is being called, and then inside of -that we have a series of functions (in this case only one function) that -checks the function ID provided against all function IDs supported by -the contract. If the function ID is 4008276486, then it sets a variable -``'x`` to the message data bytes 4-35 (that's ``(calldataload 4)``), -sets a temporary variable to equal to ``2 * x``, and returns the 32 byte -memory slice that contains that variable. - -The function ID is calculated by computing a hash based on the function -name and arguments and taking the first four bytes. In this case we have -a function named ``double`` with a single integer as an argument; on the -command line we can do: - -:: - - $ serpent get_prefix double i - 4008276486 - -Note that you can have multiple functions with the same name, if they -take different combinations of inputs. For instance, a hypothetical -function double that takes three integers as input (and, say, returns an -array consisting of 2x each one) would have a different prefix: - -:: - - $ serpent get_prefix double iii - 1142360101 - -The letter ``i`` is meant for integers, and for fixed-length (up to 32 -byte) strings (which are treated the same as integers in Serpent and -EVM). Use the letter ``s`` for variable-length string arguments, and -``a`` for arrays; more on these later. - -Now, what if you want to actually run the contract? That is where -`pyethereum `__ comes in. Open -up a Python console in the same directory, and run: - -:: - - >>> from ethereum import tester as t - >>> s = t.state() - >>> c = s.abi_contract('mul2.se') - >>> c.double(42) - 84 - -The second line initializes a new state (ie. a genesis block). The third -line creates a new contract, and creates an object in Python which -represents it. You can use ``c.address`` to access this contract's -address. The fourth line calls the contract with argument 42, and we see -84 predictably come out. - -Note that if you want to send a transaction to such a contract in the -testnet or livenet, you will need to package up the transaction data for -"call function double with an integer as an input with data 42". The -command line instruction for this is *deprecated*: - -.. raw:: html - - - -:: - - $ serpent encode_abi double i 42 - eee97206000000000000000000000000000000000000000000000000000000000000002a - -Example: Name Registry -~~~~~~~~~~~~~~~~~~~~~~ - -Having a multiply-by-two function on the blockchain is kind of boring. -So let's do something marginally more interesting: a name registry. The -main function will be a ``register(key, value)`` operation which checks -if a given key was already taken, and if is unoccupied then register it -with the desired value and return 1; if the key is already occupied -return 0. We will also add a second function to check the value -associated with a particular key. Let's try it out: - -:: - - def register(key, value): - # Key not yet claimed - if not self.storage[key]: - self.storage[key] = value - return(1) - else: - return(0) # Key already claimed - - def ask(key): - return(self.storage[key]) - -Here, we see a few parts in action. First, we have the ``key`` and -``value`` variables that the function takes as arguments. The second -line is a comment; it does not get compiled and only serves to remind -you what the code does. Then, we have a standard if/else clause, which -checks if ``self.storage[key]`` is zero (ie. unclaimed), and if it is -then it sets ``self.storage[key] = value`` and returns 1. Otherwise, it -returns zero. ``self.storage`` is also a pseudo-array, acting like an -array but without any particular memory location. - -Now, paste the code into ``namecoin.se``, if you wish try compiling it -to LLL, opcodes or EVM, and let's try it out in the pyethereum tester -environment: - -:: - - >>> from ethereum import tester as t - >>> s = t.state() - >>> c = s.abi_contract('namecoin.se') - >>> c.register(0x67656f726765, 45) - 1 - >>> c.register(0x67656f726765, 20) - 0 - >>> c.register(0x6861727279, 65) - 1 - >>> c.ask(0x6861727279) - 65 - -If we wanted to encode the transaction data for that first call, we -would do: - -.. raw:: html - - - -:: - - $ serpent encode_abi register ii 0x67656f726765 45 - d66d6c10000000000000000000000000000000000000000000000000000067656f726765000000000000000000000000000000000000000000000000000000000000002d - -Including files, and calling other contracts -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Once your projects become larger, you will not want to put everything -into the same file; things become particularly inconvenient when one -piece of code needs to create a contract. Fortunately, the process for -splitting code into multiple files is quite simple. Make the following -two files: - -mul2.se: - -:: - - def double(x): - return(x * 2) - -returnten.se: - -:: - - extern mul2.se: [double:[int256]:int256] - - MUL2 = create('mul2.se') - def returnten(): - return(MUL2.double(5)) - -And open Python: - -:: - - >>> from ethereum import tester as t - >>> s = t.state() - >>> c = s.abi_contract('returnten.se') - >>> c.returnten() - 10 - -Note that here we introduced several new features. Particularly: - -- The ``create`` command to create a contract using code from another - file -- The ``extern`` keyword to declare a class of contract for which we - know the names of the functions -- The interface for calling other contracts - -``create`` is self-explanatory; it creates a contract and returns the -address to the contract. - -The way ``extern`` works is that you declare a class of contract, in -this case ``mul2``, and then list in an array the names of the -functions, in this case just ``double``. To generate -``extern mul2.se: [double:[int256]:int256]`` use - -:: - - $ serpent mk_signature mul2.se - -From there, given any variable containing an address, you can do -``x.double(arg1)`` to call the address stored by that variable. The -arguments are the values provided to the function. If you provide too -few arguments, the rest are filled to zero, and if you provide too many -the extra ones are ignored. Function calling also has some other -optional arguments: - -- ``gas=12414`` - call the function with 12414 gas instead of the - default (all gas) -- ``value=10^19`` - send 10^19 wei (10 ether) along with the message -- ``data=x``, ``datasz=5`` - call the function with 5 values from the - array ``x``; note that this replaces other function arguments. - ``data`` without ``datasz`` is illegal -- ``outsz=7`` - by default, Serpent processes the output of a function - by taking the first 32 bytes and returning it as a value. However, if - ``outsz`` is used as here, the function will instead return an array - containing 7 values; if you type ``y = x.fun(arg1, outsz=7)`` then - you will be able to access the output via ``y[0]``, ``y[1]``, etc. - -Another similar operation to ``create`` is ``inset('filename')``, which -simply puts code into a particular place without adding a separate -contract. - -returnten.se - -:: - - inset('mul2.se') - - def returnten(): - return(self.double(5)) - -Storage data structures -~~~~~~~~~~~~~~~~~~~~~~~ - -In more complicated contracts, you will often want to store data -structures in storage to represent certain objects. For example, you -might have a decentralized exchange contract that stores the balances of -users in multiple currencies, as well as open bid and ask orders where -each order has a price and a quantity. For this, Serpent has a built-in -mechanism for defining your own structures. For example, in such a -decentralized exchange contract you might see: - -:: - - data user_balances[][] - data orders[](buys[](user, price, quantity), sells[](user, price, quantity)) - -Then, you might do something like: - -:: - - def fill_buy_order(currency, order_id): - # Available amount buyer is willing to buy - q = self.orders[currency].buys[order_id].quantity - # My balance in the currency - bal = self.user_balances[msg.sender][currency] - # The buyer - buyer = self.orders[currency].buys[order_id].user - if q > 0: - # The amount we can actually trade - amount = min(q, bal) - # Trade the currency against the base currency - self.user_balances[msg.sender][currency] -= amount - self.user_balances[buyer][currency] += amount - self.user_balances[msg.sender][0] += amount * self.orders[currency].buys[order_id].price - self.user_balances[buyer][0] -= amount * self.orders[currency].buys[order_id].price - # Reduce the remaining quantity on the order - self.orders[currency].buys[order_id].quantity -= amount - -Notice how we define the data structures at the top, and then use them -throughout the contract. These data structure gets and sets are -converted into storage accesses in the background, so the data -structures are persistent. - -The language for doing data structures is simple. First, we can do -simple variables: - -:: - - data blah - - x = self.blah - self.blah = x + 1 - -Then, we can do arrays, both finite and infinite: - -:: - - data blah[1243] - data blaz[] - - x = self.blah[505] - y = self.blaz[3**160] - self.blah[125] = x + y - -Note that finite arrays are always preferred, because it will cost less -gas to calculate the storage index associated with a finite array index -lookup. And we can do tuples, where each element of the tuple is itself -a valid data structure: - -:: - - data body(head(eyes[2], nose, mouth), arms[2], legs[2]) - - x = self.body.head.nose - y = self.body.arms[1] - -And we can do arrays of tuples: - -:: - - data bodies[100](head(eyes[2], nose, mouth), arms[2](fingers[5], elbow), legs[2]) - - x = self.bodies[45].head.eyes[1] - y = self.bodies[x].arms[1].fingers[3] - -Note that the following is unfortunately not legal: - -:: - - data body(head(eyes[2], nose, mouth), arms[2], legs[2]) - - x = self.body.head - y = x.eyes[0] - -Accesses have to descend fully in a single statement. To see how this -could be used in a simpler example, let's go back to our name registry, -and upgrade it so that when a user registers a key they become the owner -of that key, and the owner of a key has the ability to (1) transfer -ownership, and (2) change the value. We'll remove the return values here -for simplicity. - -:: - - data registry[](owner, value) - - def register(key): - # Key not yet claimed - if not self.registry[key].owner: - self.registry[key].owner = msg.sender - - def transfer_ownership(key, new_owner): - if self.registry[key].owner == msg.sender: - self.registry[key].owner = new_owner - - def set_value(key, new_value): - if self.registry[key].owner == msg.sender: - self.registry[key].value = new_value - - def ask(key): - return([self.registry[key].owner, self.registry[key].value], items=2) - -Note that in the last ask command, the function returns an array of 2 -values. If you wanted to call the registry, you would have needed to do -something like ``o = registry.ask(key, outsz=2)`` and you could have -then used ``o[0]`` and ``o[1]`` to recover the owner and value. - -Simple arrays in memory -~~~~~~~~~~~~~~~~~~~~~~~ - -The syntax for arrays in memory are different: they can only be finite -and cannot have tuples or more complicated structures. - -Example: - -:: - - def bitwise_or(x, y): - blah = array(1243) - blah[567] = x - blah[568] = y - blah[569] = blah[567] | blah[568] - return(blah[569]) - -There are also two functions for dealing with arrays: - -:: - - len(x) - -Returns the length of array x. - -:: - - slice(x, items=start, items=end) - -Takes a slice of x starting with position start and ending with position -end (note that we require ``end >= start``; otherwise the result will -almost certainly result in an error) - -Arrays and Functions -~~~~~~~~~~~~~~~~~~~~ - -Functions can also take arrays as arguments, and return arrays. - -:: - - def compose(inputs:arr): - return(inputs[0] + inputs[1] * 10 + inputs[2] * 100) - - def decompose(x): - return([x % 10, (x % 100) / 10, x / 100]:arr) - -Putting the ``:arr`` after a function argument means it is an array, and -putting it inside a return statement returns the value as an array (just -doing ``return([x,y,z])`` would return the integer which is the memory -location of the array). - -If a contract calls one of its functions, then it will autodetect which -arguments should be arrays and parse them accordingly, so this works -fine: - -:: - - def compose(inputs:arr, radix): - return(inputs[0] + inputs[1] * radix + inputs[1] * radix ** 2) - - def main(): - return self.compose([1,2,3,4,5], 100) - -However, if a contract wants to call another contract that takes arrays -as arguments, then you will need to put a "signature" into the extern -declaration: - -:: - - extern composer: [compose:[int256[],int256]:int256, main:[]:int256] - -If you want to determine the signature to use from a given file, you can -do: - -:: - - > serpent mk_signature compose_test.se - extern compose_test: [compose:[int256[],int256]:int256, main:[]:int256] - -Strings -~~~~~~~ - -There are two types of strings in Serpent: short strings, eg. -``"george"``, and long strings, eg. -``text("afjqwhruqwhurhqkwrhguqwhrkuqwrkqwhwhrugquwrguwegtwetwet")``. -Short strings, given simply in quotes as above, are treated as numbers; -long strings, surrounded by the ``text`` keyword as above, are treated -as array-like objects; you can do ``getch(str, index)`` and -``setch(str, index)`` to manipulate characters in strings (doing -``str[0]`` will treat the string as an array and try to fetch the first -32 characters as a number). - -To use strings as function arguments or outputs, use the ``str`` tag, -much like you would use ``arr`` for arrays. ``len(s)`` gives you the -length of a string, and ``slice`` works for strings the same way as for -arrays too. - -Here is an example of returning/retrieving a string: - -:: - - data str - - def t2(): - self.str = text("01") - log(data=self.str) - return(self.str, chars=2) - - def runThis(): - s = self.t2(outsz=2) - log(data=s) - -Macros -~~~~~~ - -**WARNING: Relatively new/untested feature, here be [STRIKEOUT:dragons] -serpents** - -Macros allow you to create rewrite rules which provide additional -expressivity to the language. For example, suppose that you wanted to -create a command that would compute the median of three values. You -could simply do: - -:: - - macro median($a, $b, $c): - min(min(max($a, $b), max($a, $c)), max($b, $c)) - -Then, if you wanted to use it somewhere in your code, you just do: - -:: - - x = median(5, 9, 7) - -Or to take the max of an array: - -:: - - macro maxarray($a:$asz): - $m = 0 - $i = 0 - while i < $asz: - $m = max($m, $a[i]) - $i += 1 - $m - - x = maxarray([1, 9, 5, 6, 2, 4]:6) - -For a highly contrived example of just how powerful macros can be, see -https://github.com/ethereum/serpent/blob/poc7/examples/peano.se - -Note that macros are not functions; they are copied into code every time -they are used. Hence, if you have a long macro, you may instead want to -make the macro call an actual function. Additionally, note that the -dollar signs on variables are important; if you omit a dollar sign in -the pattern $a then the macro will only match a variable actually called -a. You can also create dollar sign variables that are in the -substitution pattern, but not the search pattern; this will generate a -variable with a random prefix each instance of the macro. You can also -create new variables without a dollar sign inside a substitution -pattern, but then the same variable will be shared across all instances -of the pattern and with uses of that variable outside the pattern. - -Types -~~~~~ - -**WARNING: Relatively new/untested feature, here be [STRIKEOUT:dragons] -serpents** - -An excellent compliment to macros is Serpent's ghetto type system, which -can be combined with macros to produce quite interesting results. Let us -simply show this with an example: - -:: - - type float: [a, b, c] - - macro float($x) + float($y): - float($x + $y) - - macro float($x) - float($y): - float($x - $y) - - macro float($x) * float($y): - float($x * $y / 2^32) - - macro float($x) / float($y): - float($x * 2^32 / $y) - - macro unfloat($x): - $x / 2^32 - - macro floatfy($x): - float($x * 2^32) - - macro float($x) = float($y): - $x = $y - - macro with(float($x), float($y), $z): - with($x, $y, $z) - - a = floatfy(25) - b = a / floatfy(2) - c = b * b - return(unfloat(c)) - -This returns 156, the integer portion of 12.5^2. A purely integer-based -version of this code would have simply returned 144. An interesting use -case would be rewriting the `elliptic curve signature pubkey recovery -code `__ -using types in order to make the code neater by making all additions and -multiplications implicitly modulo P, or using `long integer -types `__ -to do RSA and other large-value-based cryptography in EVM code. - -Miscellaneous -~~~~~~~~~~~~~ - -The three other useful features in the tester environment are: - -- Block access - you can dig around ``s.block`` to see block data (eg. - ``s.block.number``, ``s.block.get_balance(addr)``, - ``s.block.get_storage_data(addr, index)``) -- Snapshots - you can do ``x = s.snapshot()`` and ``s.revert(x)`` -- Advancing blocks - you can do ``s.mine(100)`` and 100 blocks - magically pass by with a 60-second interval between blocks. - ``s.mine(100, addr)`` mines into a particular address. -- Full block data dump - type ``s.block.to_dict()`` - -Serpent also gives you access to many "special variables"; the full list -is: - -- ``tx.origin`` - the sender of the transaction -- ``tx.gasprice`` - gas price of the transaction -- ``msg.gas`` - gas remaining -- ``msg.sender`` - the sender of the message -- ``msg.value`` - the number of wei (smallest units of ether) sent with - the message -- ``self`` - the contract's own address -- ``self.balance`` - the contract's balance -- ``x.balance`` (for any x) - that account's balance -- ``block.coinbase`` - current block miner's address -- ``block.timestamp`` - current block timestamp -- ``block.prevhash`` - previous block hash -- ``block.difficulty`` - current block difficulty -- ``block.number`` - current block number -- ``block.gaslimit`` - current block gaslimit - -Serpent recognises the following "special functions": - -- ``def init():`` - executed upon contract creation, accepts no - parameters -- ``def shared():`` - executed before running ``init`` and user - functions -- ``def code():`` - executed before any user functions - -There are also special commands for a few crypto operations; -particularly: - -- ``addr = ecrecover(h, v, r, s)`` - determines the address that - produced the elliptic curve signature ``v, r, s`` of the hash ``h`` -- ``x = sha256(a, items=4)`` - returns the sha256 hash of the 128 bytes - consisting of the 4-item array starting from ``a`` -- ``x = ripemd160(a, items=4)`` - same as above but for ripemd160 -- To hash an arbitrary number of bytes, use chars syntax. Example: - ``x = sha256([0xf1fc122bc7f5d74df2b9441a42a1469500000000000000000000000000000000], chars=16)`` - - returns the sha256 of the first 16 bytes. Note: padding with - trailing zeroes, otherwise the first 16 bytes will be zeroes, and the - sha256 of it will be computed instead of the desired. -- you can also use sha3 instead of sha256, e.g. ``sha3(a, items=4)`` - ### Tips - -- If a function is not returning the result you expect, double-check - that all variables are correct: there is no error/warning when using - an undeclared variable. - -- ``Invalid argument count or LLL function`` usually means you just - called foo() instead of ``self.foo()``. - -- Sometimes you may be intending to use unsigned operators. eg div() - and lt() instead of '/' and '<'. - -- To upgrade Serpent, you may need to do - ``pip uninstall ethereum-serpent`` and ``python setup.py install``. - (Avoid ``pip install ethereum-serpent`` since it will get from PyPI - which is probably old.) (Also avoid using the master branch, which is - probably even older than the PyPI version; use the develop branch - instead.) - -- When calling abi\_contract(), if you get this type of error - ``Exception: Error (file "main", line 1, char 5): Invalid object member (ie. a foo.bar not mapped to anything)`` - make sure you are specifying correct path to the file you are - compiling. - -- If you get a core dump when calling ``abi_contract()``, check that - you do not have functions with the same name. - -- Use macro for constants, example: - - :: - - macro CONSTANT: 99 - -- Be careful that if your flow requires going through a number of - contracts, that someone can't just directly short-circuit and call - one of your latter contracts with data they've manipulated elsewhere. - Example: If you have contract C which gives someone ether, but relies - on computation from Contract A->B->C, that someone can't just call B - or C to give themselves ether. - -Other -~~~~~ - -http://mc2-umd.github.io/ethereumlab/docs/serpent\_tutorial.pdf - some -outdated but can generally be helpful diff --git a/old-docs-for-reference/main-wiki.rst/Serpent_3.0.rst b/old-docs-for-reference/main-wiki.rst/Serpent_3.0.rst deleted file mode 100644 index cbbebd7..0000000 --- a/old-docs-for-reference/main-wiki.rst/Serpent_3.0.rst +++ /dev/null @@ -1,40 +0,0 @@ -The following is a suggested spec for Serpent 3.0. - -1. Everything is strongly typed, but types are inferred, so there is no - need to specify types explicitly. - -For example, consider the code: - -:: - - data bar[6] - - def foo(): - x = 5 - y = [1,2,3,4,5,6] - z = "123123124" - w1 = y[1] - w2 = z[2] - self.bar = y - return(x) - -A script would run through the code and assign types: - -:: - - x: int - y: arr[int] - z: string - w1: int - w2: int - self.bar: arr[int] :: storage - -When checking the type for w1, the script would see the line -``w1 = y[1]``, note that ``y`` is already known as an ``arr[int]`` so -``y[1]`` will be recognized as ``int``. Meanwhile, ``z`` will be known -as ``string``, and so ``z[1]`` will be recognized as a character, ie. -``int``. Note that this means that ``y[1]`` will be compiled as -``(mload (add y 32))`` whereas ``z[2]`` will be compiled as -``(byte (mload (add z 2)) 0)``. ``self.bar = y`` will be processed -recursively so as to copy the entire contents of ``y`` into -``self.bar``. diff --git a/old-docs-for-reference/main-wiki.rst/Solidity,-Docs-and-ABI.rst b/old-docs-for-reference/main-wiki.rst/Solidity,-Docs-and-ABI.rst deleted file mode 100644 index 9fafeab..0000000 --- a/old-docs-for-reference/main-wiki.rst/Solidity,-Docs-and-ABI.rst +++ /dev/null @@ -1,291 +0,0 @@ -*NOTE: This is intended largely as a vague overview and a historical -reference. For specific details and the latest specification, see -`Ethereum Contract -ABI `__, -`Ethereum Natural Specification -Format `__ -and `Solidity -Tutorial `__.* - -An ABI is intended to serve as the de facto method for encoding & -decoding data into & out of transactions. - -For this ABI, contracts are treated as objects. They export a particular -interface, not dissimilar from that of an OO language, for example for a -contract ``Foo``: - -:: - - contract Foo - { - function sam(string32 in1) { ... } - function bar(uint256 in1, string in2) returns (string out1, bool out2) { ... } - function baz(uint32 in1, real in2) returns bool { ... } - - state: - uint256 tom; - } - -Note you haven't seen this language before. This is a new high level -language codenamed Solidity, that will feel mostly similar to something -between JavaScript and C++ but with a number of syntactic additions to -make it suitable for writing contracts within Ethereum. Language -additions include: - -- static typing; -- contracts as first-class entities; -- state as part of a contract able to map & segment information into - the storage; -- invariants, pre- and post-conditions as part of a contract; -- variadic return values with named components; -- a safe language subset allowing guaranteed static analysis & proofs; -- an inbuilt test-generation and execution environment for situations - where formal proofing is not practical. - -The above would result in three methods being exposed: ``bar``, ``baz`` -and ``sam``, roughly expressed in JSON as: - -:: - - { - "bar": { - "inputs": [ - "in1": "uint256", - "in2": "string" - ], - "outputs": [ - "out1": "string", - "out2": "bool" - ] - }, - "baz": { - "inputs": [ - "in1": "uint32", - "in2": "real" - ], - "outputs": [ - "__default": "bool" - ] - }, - "sam": { - "inputs": [ - "in1": "string32" - ], - "outputs": [] - } - } - -In previous versions of the proof-of-concept series, only simple 32-byte -values were supported; the ABI adds the ability to also have variably -sized arguments. - -ABI -~~~ - -See `Ethereum Contract -ABI `__. - -Documentation -~~~~~~~~~~~~~ - -It is expected that each method, together with the contract itself, will -be documented in several ways. Aside from informal descriptions, each -method should come with a formalised method to describe exactly its -effect on the state of Ethereum. It should also include, where possible, -pre- and post-conditions on the contract state, and the contract itself -should include invariants over its own state, again each translated into -natural language. - -For GavCoin, a meta coin that that is sub-divisible down to 1,000, and -includes two functions ``balance`` and ``send``, we might see the basic, -undocumented contract as: - -:: - - contract GavCoin - { - function send(address to, uint256 valueInmGAV) { - balances[to] += valueInmGAV; - balances[transaction.sender] -= valueInmGAV; - } - function balance(address who) constant returns (uint256 balanceInmGAV) { - balanceInmGAV = balances[who]; - } - - invariants: - reduce(0, +, map(valueOf, balances)) == 100000000000; - - construction: - balances[transaction.sender] = 100000000000; - - state: - mapping balances (address) returns uint256 with function(address a) returns uint256 { return a; }; - }; - -Of course it is wrong. A static checker will analyse this (with the -language assertion that the uint256 type must not be allowed to -underflow unless explicitly given that attribute) and come back with -something like: - -:: - - Line 8: >>> balances[transaction.sender] -= valueInmGAV <<<: - balances[...] may underflow with '-=' operation using unbounded operand valueInmGAV. - Suggestion: surround code with conditional to bound operand valueInmGAV. - -This is basically saying that it can see no reason why ``valueInmGAV`` -could be no bigger than ``balances[transaction.sender]``. And it's -right. We forgot to check the parameters. It's easily fixed by adding -the conditional and altering the method to: - -:: - - void send(address to, uint256 valueInmGAV) { - if (balances[transaction.sender] >= valueInmGAV) { - balances[to] += valueInmGAV; - balances[transaction.sender] -= valueInmGAV; - } - } - -This would then be formally documented: - -:: - - /// @title Some title here. - /// @author Homer Simpson - contract GavCoin - { - /// @notice Send `(valueInmGAV / 1000).fixed(0,3)` GAV from the account of - /// `message.caller.address()`, to an account accessible only by `to.address()`. - /// @dev This is the developer documentation. - /// @param to The docs for the first param. - /// @param valueInmGav The docs for the second param. - function send(address to, uint256 valueInmGAV) { - if (balances[message.caller] >= valueInmGAV) { - balances[to] += valueInmGAV; - balances[message.caller] -= valueInmGAV; - } - } - - /// @notice `(balanceInmGAV / 1000).fixed(0,3)` GAV is the total funds available to `who.address()`. - function balance(address who) constant returns (uint256 balanceInmGAV) { - balanceInmGAV = balances[who]; - } - - invariants: - /// @notice The sum total amount of GAV in the system is 1 million. - reduce(0, add, map(valueOf, balances)) == 100000000000; - - construction: - /// @notice Endows `message.caller.address()` with 1m GAV. - balances[message.caller] = 100000000000; - - state: - mapping balances(address) returns uint256 with function(address a) returns uint256 { return a; }; - }; - -This documentation would then allow the Ethereum browser to translate -any message (and thus transaction) going in to this contract into -English (and on to other languages hence). It would also allow a lay -viewer to immediately discern what the contract conforms to; in this -case they could see that it's premined in favour of the transaction -sender and that the total amount of coins in the system never changes. - -For example, should a dapp, malicious or otherwise, attempt to send a -transaction that gives all the user's GAV to itself, the user would, -prior to signing and submission, receive a message saying something -like: - -:: - - Untrusted dapp "Foo Sprocket dapp" attempting to transact in your name: - Send 45.780 GAV from the account of Your Name Here to an account accessible only by Foo Sprocket dapp. - Do you wish to allow this? - -Of course, they might be a bit more cunning and send it to an anonymous -address, however, by differentiating friends' (and other known people) -addresses from anonymous or untrusted addresses both visibly and -clearly, we can imagine a mechanism that, at least for simple contracts, -allow users a good level of security without excessive harm to their -experience. - -Getting the Documentation in -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The documentation, would be extracted from the source code ready to sit -in a (probably JSON) file: - -:: - - { - "source": "...", - "language": "Solidity", - "languageVersion": 1, - "methods": { - "send": { "notice": "Send `(valueInmGAV / 1000).fixed(0,3)` GAV from the account of `message.caller.address()`, to an account accessible only by `to.address()`." }, - "balance": { "notice": "`(balanceInmGAV / 1000).fixed(0,3)` GAV is the total funds available to `who.address()`." } - }, - "invariants": [ - { "notice": "The sum total amount of GAV in the system is 1 million." } - ], - "construction": [ - { "notice": "Endows `message.caller.address()` with 1m GAV." } - ] - } - -The full documentation format, that includes developer-specific -documentation includes several more attributes: - -:: - - { - "author": "Gav Wood", - "description": "Some description of this contract.", - "methods": { - "send": { - "title": "Send some GAV.", - "details": "..." - }, - "balance": { - "title": "Send some GAV.", - "details": "..." - } - }, - "invariants": [ - { "title": "...", "details": "Markdown description of the first invariant." } - ], - "construction": { - "details": "Creates the contract with..." - } - } - -This file would be hashed and distributed (either on a centralised -website or, more preferably, through Swarm). It would be referenced by -the Ethereum Singleton Trust contract in order to allow people or -organisations that you know or trust to help inform you of its audit -results and trustworth. Of course if you were a coder you could audit it -manually (in this case it's pretty trivial) and determine how well the -formal documentation matches the code, and also submit newer versions, -perhaps in different languages that incorporate changes you feel are -required to better descibe its actions & ramifications. - -The ABI-Description File -~~~~~~~~~~~~~~~~~~~~~~~~ - -So the ABI description file ("header file") for the contract would be -trivially derivable from the contract source code. It would be -distributed by the author for anyone who wanted to message or transact -with it. It would contain only enough information to compose the input -data for a transaction and to decode the output data. Here's how the -GAVCoin example contract would look: - -TODO: include ``const``\ ness in the JSON: - -:: - - [ - { "name": "send", "const": false, "input": [ { "name": "to", "type": "address" }, { "name": "valueInmGAV", "type": "uint256" } ], "output": [] }, - { "name": "balance", "const": true, "input": [ { "name": "who", "type": "address" } ], "output": [ { "name": "balanceInmGAV", "type": "uint256" } ] } - ] - -And that's it. Any questions to Gav. diff --git a/old-docs-for-reference/main-wiki.rst/Solidity-Changelog.rst b/old-docs-for-reference/main-wiki.rst/Solidity-Changelog.rst deleted file mode 100644 index c7bbe05..0000000 --- a/old-docs-for-reference/main-wiki.rst/Solidity-Changelog.rst +++ /dev/null @@ -1,145 +0,0 @@ -- Index access for types ``bytes1``, ..., ``bytes32`` (only read access - for now). - -0.2.1 (2016-01-30) -~~~~~~~~~~~~~~~~~~ - -- Inline arrays, i.e. ``var y = [1,x,f()];`` if there is a common type - for ``1``, ``x`` and ``f()``. Note that the result is always a - fixed-length memory array and conversion to dynamic-length memory - arrays is not yet possible. -- Import similar to ECMAScript6 import (``import "abc.sol" as d`` and - ``import {x, y} from "abc.sol"``). -- Commandline compiler solc automatically resolves missing imports and - allows for "include directories". -- Conditional: ``x ? y : z`` -- Bugfix: Fixed several bugs where the optimizer generated invalid - code. -- Bugfix: Enums and structs were not accessible to other contracts. -- Bugfix: Fixed segfault connected to function paramater types, - appeared during gas estimation. -- Bugfix: Type checker crash for wrong number of base constructor - parameters. -- Bugfix: Allow function overloads with different array types. -- Bugfix: Allow assignments of type ``(x) = 7``. -- Bugfix: Type ``uint176`` was not available. -- Bugfix: Fixed crash during type checking concerning constructor - calls. -- Bugfix: Fixed crash during code generation concerning invalid - accessors for struct types. -- Bugfix: Fixed crash during code generating concerning computing a - hash of a struct type. - -0.2.0 (2015-12-02) -~~~~~~~~~~~~~~~~~~ - -- **Breaking Change**: ``new ContractName.value(10)()`` has to be - written as ``(new ContractName).value(10)()`` -- Added ``selfdestruct`` as an alias for ``suicide``. -- Allocation of memory arrays using ``new``. -- Binding library functions to types via ``using x for y`` -- ``addmod`` and ``mulmod`` (modular addition and modular - multiplication with arbitrary intermediate precision) -- Bugfix: Constructor arguments of fixed array type were not read - correctly. -- Bugfix: Memory allocation of structs containing arrays or strings. -- Bugfix: Data location for explicit memory parameters in libraries was - set to storage. - -0.1.7 (2015-11-17) -~~~~~~~~~~~~~~~~~~ - -- Improved error messages for unexpected tokens. -- Proof-of-concept transcompilation to why3 for formal verification of - contracts. -- Bugfix: Arrays (also strings) as indexed parameters of events. -- Bugfix: Writing to elements of ``bytes`` or ``string`` overwrite - others. -- Bugfix: "Successor block not found" on Windows. -- Bugfix: Using string literals in tuples. -- Bugfix: Cope with invalid commit hash in version for libraries. -- Bugfix: Some test framework fixes on windows. - -0.1.6 (2015-10-16) -~~~~~~~~~~~~~~~~~~ - -- ``.push()`` for dynamic storage arrays. -- Tuple expressions (``(1,2,3)`` or ``return (1,2,3);``) -- Declaration and assignment of multiple variables - (``var (x,y,) = (1,2,3,4,5);`` or ``var (x,y) = f();``) -- Destructuring assignment (``(x,y,) = (1,2,3)``) -- Bugfix: Internal error about usage of library function with invalid - types. -- Bugfix: Correctly parse ``Library.structType a`` at statement level. -- Bugfix: Correctly report source locations of parenthesized - expressions (as part of "tuple" story). - -0.1.5 (2015-10-07) -~~~~~~~~~~~~~~~~~~ - -- Breaking change in storage encoding: Encode short byte arrays and - strings together with their length in storage. -- Report warnings -- Allow storage reference types for public library functions. -- Access to types declared in other contracts and libraries via ``.``. -- Version stamp at beginning of runtime bytecode of libraries. -- Bugfix: Problem with initialized string state variables and dynamic - data in constructor. -- Bugfix: Resolve dependencies concerning ``new`` automatically. -- Bugfix: Allow four indexed arguments for anonymous events. -- Bugfix: Detect too large integer constants in functions that accept - arbitrary parameters. - -0.1.4 (2015-09-30) -~~~~~~~~~~~~~~~~~~ - -- Bugfix: Returning fixed-size arrays. -- Bugfix: combined-json output of solc. -- Bugfix: Accessing fixed-size array return values. -- Bugfix: Disallow assignment from literal strings to storage pointers. -- Refactoring: Move type checking into its own module. - -0.1.3 (2015-09-25) -~~~~~~~~~~~~~~~~~~ - -- ``throw`` statement. -- Libraries that contain functions which are called via CALLCODE. -- Linker stage for compiler to insert other contract's addresses (used - for libraries). -- Compiler option to output runtime part of contracts. -- Compile-time out of bounds check for access to fixed-size arrays by - integer constants. -- Version string includes libevmasm/libethereum's version (contains the - optimizer). -- Bugfix: Accessors for constant public state variables. -- Bugfix: Propagate exceptions in clone contracts. -- Bugfix: Empty single-line comments are now treated properly. -- Bugfix: Properly check the number of indexed arguments for events. -- Bugfix: Strings in struct constructors. - -0.1.2 (2015-08-20) -~~~~~~~~~~~~~~~~~~ - -- Improved commandline interface. -- Explicit conversion between ``bytes`` and ``string``. -- Bugfix: Value transfer used in clone contracts. -- Bugfix: Problem with strings as mapping keys. -- Bugfix: Prevent usage of some operators. - -0.1.1 (2015-08-04) -~~~~~~~~~~~~~~~~~~ - -- Strings can be used as mapping keys. -- Clone contracts. -- Mapping members are skipped for structs in memory. -- Use only a single stack slot for storage references. -- Improved error message for wrong argument count. (#2456) -- Bugfix: Fix comparison between ``bytesXX`` types. (#2087) -- Bugfix: Do not allow floats for integer literals. (#2078) -- Bugfix: Some problem with many local variables. (#2478) -- Bugfix: Correctly initialise ``string`` and ``bytes`` state - variables. -- Bugfix: Correctly compute gas requirements for callcode. - -0.1.0 (2015-07-10) -~~~~~~~~~~~~~~~~~~ diff --git a/old-docs-for-reference/main-wiki.rst/Solidity-Features.rst b/old-docs-for-reference/main-wiki.rst/Solidity-Features.rst deleted file mode 100644 index 17802ca..0000000 --- a/old-docs-for-reference/main-wiki.rst/Solidity-Features.rst +++ /dev/null @@ -1,1586 +0,0 @@ -This is a list to explain and demonstrate new Solidity features as soon -as they are completed. It is used as a kind of changelog and items -introduced at some point might be changed at a later point. The official -reference is the -`Documentation `__ which should -always reflect the current state of the language. - -Special Type Treatment for Integer Literals -------------------------------------------- - -`PT `__ Expressions -only involving integer literals are now essentially treated as "big -integers" (i.e. they do not overflow) until they are actually used with -a non-literal. The type of the expression is only determined at that -point as the smallest integer type that can contain the resulting value. -Example: - -:: - - contract IntegerLiterals { - function f() { - // The following would have caused a type error in earlier versions (cannot add int8 to uint8), - // now the value of x is set to 9 and the type to uint8. - var x = -1 + 10; - // It is even possible to use literals that do not fit any of the Solidity types as long as - // the final value is small enough. The value of y will be 1, its type uint8. - var y = (0x100000000000000000001 * 0x100000000000000000001 * 0x100000000000000000001) & 0xff; - } - } - -Contracts Inherit all Members from Address ------------------------------------------- - -`PT `__ Contract -types are implicitly convertible to ``address`` and explicitly -convertible to and from all integer types. Furthermore, a contract type -contains all members of the address type with the semantics applying to -the contract's address, unless overwritten by the contract. - -:: - - contract Helper { - function getBalance() returns (uint bal) { - return this.balance; // balance is "inherited" from the address type - } - } - contract IsAnAddress { - Helper helper; - function setHelper(address a) { - helper = Helper(a); // Explicit conversion, comparable to a downcast - } - function sendAll() { - // send all funds to helper (both balance and send are address members) - helper.send(this.balance); - } - } - -ABI requires arguments to be padded to 32 bytes ------------------------------------------------ - -`PT `__ The latest -version of the ABI specification requires arguments to be padded to -multiples of 32 bytes. This is not a language feature that can be -demonstrated as code examples. Please see the automated tests -``SolidityEndToEndTests::packing_unpacking_types`` and -``SolidityEndToEndTests::packing_signed_types``. - -Specify value and gas for function calls ----------------------------------------- - -`PT `__ External -functions have member functions "gas" and "value" that allow to change -the default amount of gas (all) and wei (0) sent to the called contract. -"new expressions" also have the value member. - -:: - - contract Helper { - function getBalance() returns (uint bal) { return this.balance; } - } - contract Main { - Helper helper; - function Main() { helper = new Helper.value(20)(); } - /// @notice Send `val` Wei to `helper` and return its new balance. - function sendValue(uint val) returns (uint balanceOfHelper) { - return helper.getBalance.value(val)(); - } - } - -delete for structs ------------------- - -`PT `__ ``delete`` -clears all members of a struct. - -:: - - contract Contract { - struct Data { - uint deadline; - uint amount; - } - Data data; - function set(uint id, uint deadline, uint amount) { - data.deadline = deadline; - data.amount = amount; - } - function clear(uint id) { delete data; } - } - -Note that, unfortunately, this only works directly on structs for now, -so I would propose to not announce "delete" as a feature yet. - -Contract Inheritance --------------------- - -`PT1 `__ -`PT2 `__ Contracts -can inherit from each other. - -:: - - contract owned { - function owned() { owner = msg.sender; } - address owner; - } - - // Use "is" to derive from another contract. Derived contracts can access all members - // including private functions and storage variables. - contract mortal is owned { - function kill() { if (msg.sender == owner) suicide(owner); } - } - - // These are only provided to make the interface known to the compiler. - contract Config { function lookup(uint id) returns (address adr) {} } - contract NameReg { function register(string32 name) {} function unregister() {} } - - // Multiple inheritance is possible. Note that "owned" is also a base class of - // "mortal", yet there is only a single instance of "owned" (as for virtual - // inheritance in C++). - contract named is owned, mortal { - function named(string32 name) { - address ConfigAddress = 0xd5f9d8d94886e70b06e474c3fb14fd43e2f23970; - NameReg(Config(ConfigAddress).lookup(1)).register(name); - } - - // Functions can be overridden, both local and message-based function calls take - // these overrides into account. - function kill() { - if (msg.sender == owner) { - address ConfigAddress = 0xd5f9d8d94886e70b06e474c3fb14fd43e2f23970; - NameReg(Config(ConfigAddress).lookup(1)).unregister(); - // It is still possible to call a specific overridden function. - mortal.kill(); - } - } - } - - // If a constructor takes an argument, it needs to be provided in the header. - contract PriceFeed is owned, mortal, named("GoldFeed") { - function updateInfo(uint newInfo) { - if (msg.sender == owner) info = newInfo; - } - - function get() constant returns(uint r) { return info; } - - uint info; - } - -Function Modifiers ------------------- - -`PT `__ Modifiers -can be used to easily change the behaviour of functions, for example to -automatically check a condition prior to executing the function. They -are inheritable properties of contracts and may be overridden by derived -contracts. - -:: - - contract owned { - function owned() { owner = msg.sender; } - address owner; - - // This contract only defines a modifier but does not use it - it will - // be used in derived contracts. - // The function body is inserted where the special symbol "_" in the - // definition of a modifier appears. - modifier onlyowner { if (msg.sender == owner) _ } - } - contract mortal is owned { - // This contract inherits the "onlyowner"-modifier from "owned" and - // applies it to the "kill"-function, which causes that calls to "kill" - // only have an effect if they are made by the stored owner. - function kill() onlyowner { - suicide(owner); - } - } - contract priced { - // Modifiers can receive arguments: - modifier costs(uint price) { if (msg.value >= price) _ } - } - contract Register is priced, owned { - mapping (address => bool) registeredAddresses; - uint price; - function Register(uint initialPrice) { price = initialPrice; } - function register() costs(price) { - registeredAddresses[msg.sender] = true; - } - function changePrice(uint _price) onlyowner { - price = _price; - } - } - -Multiple modifiers can be applied to a function by specifying them in a -whitespace-separated list and will be evaluated in order. Explicit -returns from a modifier or function body immediately leave the whole -function, while control flow reaching the end of a function or modifier -body continues after the "\_" in the previous modifier. Arbitrary -expressions are allowed for modifier arguments and in this context, all -symbols visible from the function are visible in the modifier. Symbols -introduced in the modifier are not visible in the function (as they -might change by overriding). - -Conversion between String and Hash types ----------------------------------------- - -`PT `__ The explicit -conversion between ``string`` and ``hash`` types of equal size is now -allowed. Example: - -:: - - contract Test { - function convert(hash160 h, string20 s) returns (string20 res_s, hash160 res_h) { - res_s = string20(h); - res_h = hash160(s); - } - } - -Access to super ---------------- - -`PT `__ In the -following contract, the function ``kill`` is overridden by sibling -classes. Due to the fact that the sibling classes do not know of each -other, they can only call ``mortal.kill()`` with the effect that one of -the overrides is completely bypassed. A reasonable implementation would -call the kill functions in all classes in the inheritance hierarchy. - -:: - - contract mortal { function kill() { suicide(msg.sender); } } - contract named is mortal { function kill() { /*namereg.unregister();*/ mortal.kill(); } } - contract tokenStorage is mortal { function kill() { /*returnAllTokens();*/ mortal.kill(); } } - contract MyContract is named, tokenStorage {} - -The ``super`` keyword solves this. Its type is the type of the current -contract if it were empty, i.e. it contains all members of the current -class' bases. Access to a member of super invokes the usual virtual -member lookup, but it ends just above the current class. Using this -keyword, the following works as expected: - -:: - - contract mortal { function kill() { suicide(msg.sender); } } - contract named is mortal { function kill() { /*namereg.unregister();*/ super.kill(); } } - contract tokenStorage is mortal { function kill() { /*returnAllTokens();*/ super.kill(); } } - contract MyContract is named, tokenStorage {} - -State Variable Accessors ------------------------- - -`PT `__ Public state -variables now have accessors created for them. Basically any ``public`` -state variable can be accessed by calling a function with the same name -as the variable. - -:: - - contract test { - function test() { - data = 42; - } - uint256 data; - } - -For example in the above contract if you tried to call test's ``data()`` -method then you would obtain the result 42. - -:: - - contract test { - function test() { - data = 42; - } - private: - uint256 data; - } - -On the other hand on the above contract there is no accessor generated -since the state variable is private. - -Events ------- - -`PT `__ Events allow -the convenient usage of the EVM logging facilities. Events are -inheritable members of contracts. When they are called, they cause the -arguments to be stored in the transaction's log. Up to three parameters -can receive the attribute ``indexed`` which will cause the respective -arguments to be treated as log topics instead of data. The hash of the -signature of the event is always one of the topics. All non-indexed -arguments will be stored in the data part of the log. Example: - -:: - - contract ClientReceipt { - event Deposit(address indexed _from, hash indexed _id, uint _value); - function deposit(hash _id) { - Deposit(msg.sender, _id, msg.value); - } - } - -Here, the call to ``Deposit`` will behave identical to -``log3(msg.value, 0x50cb9fe53daa9737b786ab3646f04d0150dc50ef4e75f59509d83667ad5adb20, sha3(msg.sender), _id);``. -Note that the large hex number is equal to the sha3-hash of -"Deposit(address,hash256,uint256)", the event's signature. - -Fallback Functions ------------------- - -`PT `__ A contract -can have exactly one unnamed function. This function cannot have -arguments and is executed on a call to the contract if none of the other -functions matches the given function identifier (or if no data was -supplied at all). - -:: - - contract Test { - function() { x = 1; } - uint x; - } - - contract Caller { - function callTest(address testAddress) { - Test(testAddress).send(0); - // results in Test(testAddress).x becoming == 1. - } - } - -Events in Exported Interfaces ------------------------------ - -`PT `__ Events are -exported to the JSON and Solidity interfaces generated by the compiler. -The contract - -:: - - contract c { - event ev(uint indexed a); - } - -generates the JSON interface - -:: - - [ - { - "inputs" : [ - { - "indexed" : true, - "name" : "a", - "type" : "uint256" - }, - { - "indexed" : false, - "name" : "b", - "type" : "uint256" - } - ], - "name" : "ev", - "type" : "event" - } - ] - -and the Solidity interface -``contract c{event ev(uint256 indexed a,uint256 b);}``. - -Visibility Specifiers ---------------------- - -`PT `__ Functions -and storage variables can be specified as being ``public``, -``protected`` or ``private``, where the default for functions is -``public`` ``protected`` for storage variables. Public functions are -part of the external interface and can be called externally, while for -storage variables, an automatic accessor function is generated. -Non-public functions are only visible inside a contract and its derived -contracts (there is no distinction between ``protected`` and ``private`` -for now). - -:: - - contract c { - function f(uint a) private returns (uint b) { return a + 1; } - uint public data; - } - -External functions can call ``c.data()`` to retrieve the value of -``data`` in storage, but are not able to call ``f``. - -Numeric Literals with Ether Subdenominations --------------------------------------------- - -`PT `__ Numeric -literals can also be followed by the common ether subdenominations and -the value of the assigned to variable will be multiplied by the proper -amount. - -:: - - contract c { - function c() - { - val1 = 1 wei; // 1 - val2 = 1 szabo; // 1 * 10 ** 12 - val3 = 1 finney; // 1 * 10 ** 15 - val4 = 1 ether; // 1 * 10 ** 18 - } - uint256 val1; - uint256 val2; - uint256 val3; - uint256 val4; - } - -SHA3 with arbitrary arguments ------------------------------ - -`PT `__. ``sha3()`` -can now take an arbitrary number and type of arguments. - -:: - - contract c { - function c() - { - val2 = 123; - val1 = sha3("foo"); // sha3(0x666f6f) - val3 = sha3(val2, "bar", 1031); //sha3(0x7b626172407) - } - uint256 val1; - uint16 val2; - uint256 val3; - } - -Optional Parameter Names ------------------------- - -`PT `__. The names -for function parameters and return parameters are now optional. - -:: - - contract test { - function func(uint k, uint) returns(uint){ - return k; - } - } - -Generic call Method -------------------- - -`PT `__ Address -types (and contracts by inheritance) have a method ``call`` that can -receive an arbitrary number of arguments of arbitrary types (which can -be serialized in memory) and will invoke a message call on that address -while the arguments are ABI-serialized. If the first type has a -memory-length of exactly four bytes, it is not padded to 32 bytes, so it -is possible to specify a function signature. - -:: - - contract test { - function f(address addr, uint a) { - addr.call(string4(string32(sha3("fun(uint256)"))), a); - } - } - -Byte arrays ------------ - -`PT `__ Basic -support for variable-length byte arrays. This includes - ``bytes`` type -for storage variables - ``msg.data`` is of ``bytes`` type and contains -the calldata - functions taking arbitrary parameters (``call``, -``sha3``, ...) can be called with ``bytes`` arguments. - copying between -``msg.data`` and ``bytes`` storage variables - -What is not possible yet: - function parameters of ``bytes`` type - -local variables of ``bytes`` type - index or slice access - -:: - - contract c { - bytes data; - function() { data = msg.data; } - function forward(address addr) { addr.call(data); } - function getLength() returns (uint) { return addr.length; } - function clear() { delete data; } - } - -Enums ------ - -`PT `__ Solidity now -supports enums. Enums are explicitly convertible to all integer types -but implicit conversion is not allowed. - -:: - - contract test { - enum ActionChoices { GoLeft, GoRight, GoStraight, SitStill }; - function test() - { - choices = ActionChoices.GoStraight; - } - function getChoice() returns (uint d) - { - d = uint256(choices); - } - ActionChoices choices; - } - -Visibility Specifiers ---------------------- - -`PT `__ The -visibility of a function can be specified by giving at most one of the -specifiers ``external``, ``public``, ``inheritable`` or ``private``, -where ``public`` is the default. "External" functions can only be called -via message-calls, i.e. from other contracts or from the same contract -using ``this.function()`` (note that this also prevents calls to -overwritten functions in base classes). Furthermore, parameters of -"external" functions are immutable. "Public" functions can be called -from other contracts and from the same contract using stack-based calls. -"Inheritable" and "private" functions can only be called via stack-based -calls, while "inheritable" functions are only visible in the contract -itself and its derived contracts and "private" functions are not even -visible in derived contracts. - -:: - - contract Base { - function exte() external { } - function publ() public /* can be omitted */ { } - function inhe() inheritable { priv(); } - function priv() private { } - } - contract Derived is Base { - function g() { - this.exte(); - // impossible: exte(); - this.publ(); - publ(); - // impossible: this.inhe(); - inhe(); - // impossible: this.priv(); - // impossible: priv(); - } - } - -Import Statement ----------------- - -`PT `__ We can now -import other contracts and/or standard library contracts using the -``import`` keyword. - -:: - - import "mortal"; - - contract Test is mortal { - // since we import the standard library "mortal" contract and we inherit from it - // we can call the kill() function that it provides - function killMe() { kill();} - } - -Inline members initialization ------------------------------ - -`PT `__ Inline -members can be initialized at declaration time. - -:: - - contract test { - function test(){ - m_b = 6; - } - uint m_a = 5; - uint m_b; - } - -The arguments of the constructor of base contract -------------------------------------------------- - -`PT `__ It is -possible to pass arguments to the base contracts constructor. The -arguments for the base constructor in the header will be optional later. - -:: - - contract Base { - function Base(uint i) - { - m_i = i; - } - uint public m_i; - } - contract Derived is Base(0) { - function Derived(uint i) Base(i) {} - } - -Detect failed CALLs -------------------- - -`PT `__ If a CALL -fails, do not just silently continue. Currently, this issues a STOP but -it will throw an exception once we have exceptions. - -:: - - contract C { - function willFail() returns (uint) { - address(709).call(); - return 1; - } - } - -``willFail`` will always return an empty byte array (unless someone -finds the correct private key...). - -Basic features for arrays -------------------------- - -`PT `__ Byte arrays -and generic arrays of fixed and dynamic size are supported in calldata -and storage with the following features: Index access, copying (from -calldata to storage, inside storage, both including implicit type -conversion), enlarging and shrinking and deleting. Not supported are -memory-based arrays (i.e. usage in non-external functions or local -variables), array accessors and features like slicing. Access to an -array beyond its length will cause the execution to STOP (exceptions are -planned for the future). - -:: - - contract ArrayExample { - uint[7][] data; - bytes byteData; - function assign(uint[4][] input, bytes byteInput) external { - data = input; // will assign uint[4] to uint[7] correctly, would produce type error if reversed - byteData = byteInput; // bytes are stored in a compact way - } - function indexAccess() { - data.length += 20; - data[3][5] = data[3][2]; - byteData[2] = byteData[7]; // this will access sigle bytes - } - function clear() { - delete data[2]; // will clear all seven elements - data.length = 2; // clears everything after the second element - delete data; // clears the whole array - } - } - -Now Variable ------------- - -`PT `__ The global -scope contains an immutable variable called ``now`` which is an alias to -``block.timestamp``, i.e. it contains the timestamp of the current -block. - -:: - - contract TimedContract { - uint timeout = now + 4 weeks; - } - -HashXX and StringXX to bytesXX ------------------------------- - -[Link to PT] (https://www.pivotaltracker.com/story/show/88146508) + We -replace ``hash(XX*8)`` and ``stringXX`` by ``bytesXX``. + ``bytesXX`` -behaves as ``hash(XX*8)`` in terms of convertability and operators and -as ``stringXX`` in terms of layout in memory (alignment, etc). - -- ``byte`` is an alias for ``bytes1``. - -- ``string`` is reserved for future use. - -``msg.sig`` returns the function's signature hash -------------------------------------------------- - -[Link to PT] (https://www.pivotaltracker.com/story/show/86896308) New -magic type ``msg.sig`` that will provide the hash of the current -function signature as ``bytes4`` type. - -:: - - contract test { - function foo(uint256 a) returns (bytes4 value) { - return msg.sig; - } - } - -Calling that function will return ``2FBEBD38`` which is the hash of the -signature of ``foo(uint256)``. - -Constant variables ------------------- - -`PT `__ Added -``constant`` specifier for uint, mapping and bytesXX types. Variables -declared with ``constant`` specifier should be initialized at -declaration time and can not be changed later. For now local variables -can not be constant. Constant variables are not stored in Storage. - -:: - - contract Foo { - function getX() returns (uint r) { return x; } - uint constant x = 56; - } - -Anonymous Events ----------------- - -`PT `__ Added -``anonymous`` specifier for Event. For the event declared as anonymous -the hash of the signature of the event will not be added as a first -topic. The format is - -:: - - event ([index list]) anonymous; - -Anonymous property is also visible for ABI document. - -Tightly packed storage ----------------------- - -`PT `__ Items in -storage are packed tighly as far as possible according to the following -rules: - -- The first item in a storage slot is stored lower-order aligned. -- Elementary types use only that many bytes that are necessary to store - them. -- If an elementary type does not fit the remaining part of a storage - slot, it is moved to the next storage slot. -- Structs and array data always start a new slot and occupy whole slots - (but items inside a struct or array are packed tightly according to - these rules). - -Examples: - -:: - - contract C { - uint248 x; // 31 bytes: slot 0, offset 0 - uint16 y; // 2 bytes: slot 1, offset 0 (does not fit in slot 0) - uint240 z; // 30 bytes: slot 1, offset 2 bytes - uint8 a; // 1 byte: slot 2, offset 0 bytes - struct S { - uint8 a; // 1 byte, slot +0, offset 0 bytes - uint256 b; // 32 bytes, slot +1, offset 0 bytes (does not fit) - } - S structData; // 2 slots, slot 3, offset 0 bytes (does not really apply) - uint8 alpha; // 1 byte, slot 4 (start new slot after struct) - uint16[3] beta; // 3*16 bytes, slots 5+6 (start new slot for array) - uint8 gamma; // 1 byte, slot 7 (start new slot after array) - } - -Common Subexpression Elimination Excluding Memory and Storage -------------------------------------------------------------- - -`PT `__ The -optimizer splits code into blocks (at all operations that have non-local -side effects like JUMP, CALL, CREATE and for also all instructions that -access or modify memory or storage), analyses these blocks by creating -an expression graph and establishes equivalences in a bottom-up way, -simplifying expressions that e.g. involve constants. In the following -code-generation phase, it re-creates the set of instructions that -transform a given initial stack configuration into a given target stack -configuration utilizing the simplest representatives of these -equivalence classes. In conjunction with the already present -jump-optimization, the two code snippets given below should be compiled -into the same sequence of instructions: - -:: - - contract test { - function f(uint x, uint y) returns (uint z) { - var c = x + 3; - var b = 7 + (c * (8 - 7)) - x; - return -(-b | 0); - } - } - -:: - - contract test { - function f(uint x, uint y) returns (uint z) { - return 10; - } - } - -Common Subexpression Elimination for Memory and Storage -------------------------------------------------------- - -`PT `__ This adds -support for memory and storage operations to the common subexpression -eliminator. This makes it possible to e.g. stretch the equality -inference engine across SSTORE, MSTORE and even SHA3 computations (which -go via memory). Without optimizer (because of packed storage), there are -4 SLOAD, 3 SSTORE and 4 SHA3 operations. The optimizer reduces those to -a single SLOAD, SHA3 and SSTORE each. - -:: - - contract test { - struct s { uint8 a; uint8 b; uint8 c; } - mapping(uint => s) data; - function f(uint x, uint8 _a, uint8 _b, uint8 _c) { - data[x].a = _a; - data[x].b = _b; - data[x].c = data[x].a; - } - } - -External Types --------------- - -`PT `__ All -functions with visibility more than internal should have external types -(ABI types) otherwise raise an error. For Contract type external type is -address type. - -:: - - contract Foo {} - contract Test { - function func() { - Foo arg; - this.Poo(arg); - Poo(arg); - } - function Poo(Foo c) external {} - } - -the ABI interface for Poo is Poo(address) when the Solidity interface is -still Poo(Foo). - -Accessor for Arrays -------------------- - -`PT `__ For Arrays -the accessor is generated which accepts the index as parameter and -returns an array element - -:: - - contract test { - uint[3] public data; - function test() { - data[0] = 0; - data[1] = 1; - data[2] = 2; - } - } - -In the above contract if you tried to call the data(1) method of the -test you would obtain the result 1. - -Overloading Functions ---------------------- - -`PT `__ Contracts -can have multiple functions of the same name as long as the parameters -differ in number or type. If such an overloaded function is referenced, -it has to be called immediately to resolve the ambiguity using the types -of the arguments. It is an error if not exactly one of the possible -functions can be called with the given arguments. - -:: - - contract Base { - function f(uint a) {} - } - contract Derived is Base { - function f(uint8 b) {} - function g() { - // f(250); would create a type error since 250 can be implicitly - // converted both to a uint8 and to a uint type - f(2000); // calls f from Base - } - } - -Of course overloading a function does not need inheritance, i.e. -``f(uint a)`` could as well have been defined directly in ``Derived``. - -Overloaded functions are also present in the external interface. It is -an error if two externally visible functions differ by their Solidity -types but not by their external types, e.g. ``f(Derived _d)`` and -``f(address _a)`` both end up accepting an ``address`` type for the ABI -although they are considered different inside Solidity. - -Merging of Basic Blocks ------------------------ - -`PT `__ Blocks of -assembly instructions that do not contain jumps, stops or returns are -moved and modified according to the following rules: - -- if the control never simply flows into a block, but it is jumped to - unconditionally, the block is moved, eliminating the jump -- blocks that are never jumped to are removed - -These optimizations might sound not very powerful, but together with -"Common Subexpression Elimination" (which is does much more than its -name might suggest), the following contract is optimized to store ``8`` -in the mapping and return the value without any jump. - -:: - - contract c { - function () returns (uint) { return g(8); } - function g(uint pos) internal returns (uint) { setData(pos, 8); return getData(pos); } - function setData(uint pos, uint value) internal { data[pos] = value; } - function getData(uint pos) internal { return data[pos]; } - mapping(uint => uint) data; - } - -Interface contracts -------------------- - -`PT `__ Contracts -can be marked as "not fully implemented" by containing at least one -abstract function. A function is abstract if it does not have a body -defined. - -:: - - contract base { function foo(); } - contract derived is base { function foo() {} } - -For example in the above, foo is an abstract function and as such the -base contract is an interface contract. All non-interface contracts that -derive from it must implement its abstract functions. - -Bare Callcode -------------- - -`PT `__ The address -type receives a method ``callcode`` which is similar to ``call``, but -uses ``CALLCODE`` instead of ``CALL`` when the function is invoked. This -means that the code at the given address will be executed in the context -of the current contract. Example: - -:: - - contract Code { - uint m_data; - function (uint v) { m_data = v; } - } - contract ActualContract { - uint public m_data; - function f() { Code(0x12345).callcode(7); } - } - -Assuming the contract ``Code`` is deployed at the address ``0x12345``, -calling ``f()`` of ``ActualContract`` will result in ``m_data`` of -``ActualContract`` being modified. The user has to ensure that the -layout of storage in both contracts is suitable for callcode to be used. - -Gas Estimation --------------- - -`PT `__ Solidity -provides two ways to compute an upper bound on the gas usage of code: A -structural one, which can be used to identify expensive statements and a -functional one which tries to give an exact gas estimation for each -function. Some gas costs depend on the state of the virtual machine, -e.g. on the cost of ``sha3`` depends on the length of the argument and -writing to storage has different costs depending on whether the storage -slot had the value zero or not. - -For the structural gas estimation, the gas cost of each opcode is -computed assuming the intersection of all states in which the VM could -reach this opcode. These costs are accumulated for each opcode that -results from a specific statement (in some situations also other AST -nodes) in the AST. So in this mode, opcodes are not counted multiple -times even if they occur in loops. - -The functional gas estimation takes a different approach: For each -function in a contract, the execution of this function is "simulated". -As we want to provide an upper bound on the gas costs independent of the -actual arguments, this is sometimes not accurate and may even result in -"infinite" gas costs. Note that the gas costs of message-called -functions are not included in the gas costs of a function. - -Re-introduce string type ------------------------- - -`PT `__ ``string`` -is added as a type which behaves exactly like ``bytes`` with the -following differences: - index access is not allowed - it does not have -a length member - -In the ABI encoding (wiki already changed), string is a dynamic type -whose "number of elements" field is the number of bytes, not the number -of characters. The encoding of the string is assumed to be UTF-8, but is -not yet used inside Solidity. - -In-memory types ---------------- - -`PT `__ -Variables of reference type (structs and arrays including ``string`` and -``bytes``) can either point to memory, storage or calldata. The keywords -``storage`` and ``memory`` as part of their declaration are used to -indicate that (calldata cannot be used explicitly). Parameters (not -return parameters) of external functions are forced to point to -calldata. Parameters (also return parameters) of public and return -parameters of external functions are forced to point to memory. In all -other cases, if neither storage nor memory is given, function parameters -default to point to memory and local variables default to point to -storage. - -Note that this story enforces the constraints on memory-stored structs, -but does not yet fully implement the code-generation part. Arrays, on -the other hand, are fully implemented. - -As part of this change, references to storage are also cleaned up: An -assignment of a state variable to a local variable or temporary converts -it from a reference to a pointer. Assignments to storage pointers do not -modify storage but only change the pointer. This means that it is not -possible to assign a memory array to a storage pointer. Furthermore, it -is illegal to pass a memory-array as an argument to a function that -requires a storage reference (note that storage is statically allocated, -i.e. there is no place to put this value). Es an example: - -.. code:: js - - contract c { - uint[] x; - function f(uint[] memoryArray) { - x = memoryArray; // works, copies the array to storage - var y = x; // works, assigns a pointer - y[7]; // fine, returns the 8th element - y.length = 2; // fine, modifies storage - delete x; // fine, clears the array - // y = memoryArray; // does not work, would need to create a new temporary / unnamed array in storage, but storage is "statically" allocated - // delete y; // does not work, would set pointer to zero and does not make sense for pointer - } - } - -If possible (i.e. from anything to memory and from anything to a storage -reference that is not a pointer), conversions between these data -locations are performed automatically by the compiler. Sometimes, this -is still not possible, i.e. mappings cannot reside in memory (as their -size is unknown) and for now, some types in memory are not yet -implemented, this includes structs and multi-dimensional arrays. - -Of course, once a storage array is converted to memory, modifications do -not affect the array in storage. You can either assign the modified -array back to storage (though this would be vastly inefficient) or you -can pass around a storage pointer to begin with. As an example: - -.. code:: js - - contract BinarySearch { - /// Finds the position of _value in the sorted list _data. - /// Note that "internal" is important here, because storage references only work for internal or private functions - function find(uint[] storage _data, uint _value) internal returns (uint o_position) { - return find(_data, 0, _data.length, _value); - } - function find(uint[] storage _data, uint _begin, uint _len, uint _value) private returns (uint o_position) { - if (_len == 0 || (_len == 1 && _data[_begin] != _value)) - return uint(-1); // failure - uint halfLen = _len / 2; - uint v = _data[_begin + halfLen]; - if (_value < v) - return find(_data, _begin, halfLen, _value); - else if (_value > v) - return find(_data, _begin + halfLen + 1, halfLen - 1, _value); - else - return _begin + halfLen; - } - } - -On memory usage: Since memory is wiped after each external function -call, the Solidity runtime does not include proper memory management. It -includes a "level indicator" which points to the next free memory slot. -If memory is needed (because a storage object is copied to memory or an -external function is called), it is allocated starting from this -pointer. Functions that return objects stored in memory will not reset -this pointer. This means that temporary memory objects will still take -up space in memory even if they are not needed anymore. On the other -hand, if a function does not return any memory-stored object, it resets -the pointer to the value it had upon function entry (this is not yet -implemented). - -The EVM does not allow ``CALL`` to be used with variably-sized return -values. Because of this, return types of message-called functions which -are dynamically sized are transparently changed to ``void``. Clearing up -the confusion which might arise in face of the resulting error message -remains to do. - -Memory-stored objects as local variables are correctly zero-initialised: -Members of structs and elements of fixed-size arrays are recursively -initialised, dynamic arrays are set to zero length. ``delete x`` assigns -a new zero-initialised value to ``x``. - -Positive integers conversion to signed --------------------------------------- - -`PT `__ -Positive integer literals are now convertible to signed if in value -range. - -:: - - int8 x = 2; - -Exceptions in Solidity ----------------------- - -`PT `__ -Currently, there are two situations, where exceptions can happen in -Solidity: If you access an array beyond its length (i.e. x[i] where i >= -x.length) or if a function called via a message call does not finish -properly (i.e. it runs out of gas or throws an exception itself). In -such cases, Solidity will trigger an "invalid jump" and thus cause the -EVM to revert all changes made to the state. - -It is planned to also throw and catch exceptions manually. - -Structs in Memory ------------------ - -`PT `__ -Structs can be passed around as function arguments, be returned from -functions and created in memory. - -.. code:: js - - contract C { - struct S { uint a; uint b; } - struct A { uint x; uint y; S s; } - A data; - function f() internal returns (A) { - // Construct structs inline, pass to a function and return from it. - // Memory is allocated only once, pointers are passed around. - // Construction by member name is possible. - return g(A(5, 7, S({b: 1, a: 2}))); - } - function g(A _a) internal returns (A) { - _a.s.b = 2; - data = _a; // performs a copy - return _a; - } - } - -Flexible String Literals ------------------------- - -`PT `__ -String literals can be implicitly converted to ``bytesX`` (if they are -not too long), ``string`` and ``bytes``, especially, they can be much -longer than 32 bytes. - -.. code:: js - - contract C { - bytes32 x; - function greet() returns (string) { - x = "Hello, World!"; - return "Hello, World!"; - } - } - -Strings as Mapping Keys ------------------------ - -Strings are allowed as keys for mappings. - -.. code:: js - - contract C { - mapping (string => uint) counter; - function inc(string _s) { counter[_s]++; } - } - -Libraries (without inheritance) -------------------------------- - -`PT `__ - -Libraries are similar to contracts, but their purpose is that they are -deployed only once at a specific address and their functions are called -using CALLCODE, i.e. the library's code is called in the context of the -calling contract. - -.. code:: js - - library Math { - function max(uint a, uint b) returns (uint) { - if (a > b) return a; - else return b; - } - function min(uint a, uint b) returns (uint) { - if (a < b) return a; - else return b; - } - } - contract C { - function register(uint value) { - value = Math.max(10, Math.min(100, value)); // clamp value to [10, 100] - // ... - } - } - -The calls to ``Math.max`` and ``Math.min`` are both compiled as calls -(CALLCODEs) to an external contract. as the compiler cannot know where -the library will be deployed at, these addresses have to be filled into -the final bytecode by a linker. If the addresses are not given as -arguments to the compiler, the compiled hex code will contain -placeholders of the form ``__Math______`` (where ``Math`` is the name of -the library). The address can be filled manually by replacing all those -40 symbols by the hex encoding of the address of the library contract. - -Restrictions for libraries in comparison to contracts: - no state -variables - cannot inherit nor be inherited - -(these might be lifted at a later point) - -How to use the commandline compiler to link binaries: - -New option ``--libraries`` to either give a file containing the library -addresses or directly as a string (tries to open as a file). Syntax: -``:
[, or Whitespace] ...`` The address is a hex -string that is optionally prefixed with ``0x``. - -If solc is called with the option ``--link``, all input files are -interpreted to be unlinked binaries (hex-encoded) and are linked -in-place (if the input is read from stdin, it is written to stdout). All -options except ``--libraries`` are ignored (including ``-o``). - -Throw ------ - -`PT `__ - -throw is a statement that triggers a solidity exception and thus can be -used to revert changes made during the transaction. It does not take any -parameters and jumps to the error tag. - -:: - - contract Sharer { - function sendHalf(address addr) returns (uint balance) { - if (!addr.send(msg.value/2)) - throw; // also reverts the transfer to Sharer - return address(this).balance; - } - } - -Tightly Stored Byte Arrays and Strings --------------------------------------- - -`PT `__ - -Byte arrays (``bytes``) and strings (``string``) are stored more tightly -packed in storage: Short values (less than 32 bytes) are stored directly -together with the length: ```` (the 31 -higher-significant bytes contain the value, the least significant byte -contains the doubled length) Long values (at least 32 bytes) are stored -as they were stored before, just that the length is doubled and the -least significant bit is set to one to indicate "long string". - -Example: "abcdef" is stored as ``0x61626364656600000...000d`` while -``"abcabcabc....abc"`` (of length 40) is stored as ``0x0000000...0051`` -in the main slot, and ``616263616263...`` is stored in the data slots. - -Internal Types for Libraries ----------------------------- - -`PT `__ Storage -reference types are allowed to be passed to library functions. Together -with this change, it is now possible to access internal types of other -contracts and libraries and a compiler version stamp is added at the -beginning of library runtime code. - -Example: - -:: - - /// @dev Models a modifiable and iterable set of uint values. - library IntegerSet - { - struct data - { - /// Mapping item => index (or zero if not present) - mapping(uint => uint) index; - /// Items by index (index 0 is invalid), items with index[item] == 0 are invalid. - uint[] items; - /// Number of stored items. - uint size; - } - function insert(data storage self, uint value) returns (bool alreadyPresent) - { - uint index = self.index[value]; - if (index > 0) - return true; - else - { - if (self.items.length == 0) self.items.length = 1; - index = self.items.length++; - self.items[index] = value; - self.index[value] = index; - self.size++; - return false; - } - } - function remove(data storage self, uint value) returns (bool success) - { - uint index = self.index[value]; - if (index == 0) - return false; - delete self.index[value]; - delete self.items[index]; - self.size --; - } - function contains(data storage self, uint value) returns (bool) - { - return self.index[value] > 0; - } - function iterate_start(data storage self) returns (uint index) - { - return iterate_advance(self, 0); - } - function iterate_valid(data storage self, uint index) returns (bool) - { - return index < self.items.length; - } - function iterate_advance(data storage self, uint index) returns (uint r_index) - { - index++; - while (iterate_valid(self, index) && self.index[self.items[index]] == index) - index++; - return index; - } - function iterate_get(data storage self, uint index) returns (uint value) - { - return self.items[index]; - } - } - - /// How to use it: - contract User - { - /// Just a struct holding our data. - IntegerSet.data data; - /// Insert something - function insert(uint v) returns (uint size) - { - /// Sends `data` via reference, so IntegerSet can modify it. - IntegerSet.insert(data, v); - /// We can access members of the struct - but we should take care not to mess with them. - return data.size; - } - /// Computes the sum of all stored data. - function sum() returns (uint s) - { - for (var i = IntegerSet.iterate_start(data); IntegerSet.iterate_valid(data, i); i = IntegerSet.iterate_advance(data, i)) - s += IntegerSet.iterate_get(data, i); - } - } - -Destructuring Assignments -------------------------- - -`PT `__ Inline -tuples can be created and assigned to newly declared local variables or -already existing lvalues. This makes it possible to access multiple -return values from functions. - -``function f() returns (uint, uint, uint) { return (1,2,3); }`` - -:: - - var (a,b,c) = f(); - var (,x,) = f(); - var (,y) = f(); - var (z,) = f(); - -For newly declared variables it is not possible to specify the types of -variables, they will be inferred from the assigned value. Any component -in the assigned tuple can be left out. If the first or last element is -left out, they can consume an arbitrary number of values. At the end of -this code, we will have: ``a == 1``, ``b == 2``, ``c == 3``, ``x == 2``, -``y == 3``, ``z == 1``. - -For newly constructed tuples, elements may not be left out, except for -one special case that allows to distiguish between 1-tuples and single -expressions: ``(x)`` is equivalent to ``x``, but ``(x,)`` is a 1-tuple -containing ``x``. - -Assigning to pre-existing lvalues is similar to declaring multiple -variables and also allows wildcards: - -:: - - contract c { - string s; - struct Data {uint a; uint b;} - mapping(uint => Data) data; - function f() { - (s, data[45]) = ("abc", Data(1, 2)); - } - } - -``.push()`` for Dynamic Storage Arrays --------------------------------------- - -`PT `__ -Dynamically-sized storage arrays have a member function ``push``, such -that ``var l = arr.push(el);`` is equivalent to -``arr[arr.length++] = el; var l = arr.length;``. - -:: - - contract c { - struct Account { address owner; uint balance; } - Account[] accounts; - function newAccount(address _owner, uint _balance) { - accounts.push(Account(_owner, _balance)); - } - } - -Allocation of Dynamic Memory Arrays ------------------------------------ - -`PT `__ Dynamic -memory arrays can be allocated in the following way: - -:: - - contract c { - function f() { - uint[] memory x = new uint[](100); - uint[][] memory twoDim = new uint[][](20); - for (uint i = 0; i < twoDim.length; i++) - twoDim[i] = new uint[](30); - } - } - -This is a **breaking change** because of the way NewExpressions are -parsed: Expressions of the form ``new ContractName.value(10)()`` have to -be changed to ``(new ContractName).value(10)()``. - -Support for addmod and mulmod ------------------------------ - -`PT `__ Modular -arithmetics outside of the 256 bit field is provided by the ``addmod`` -and ``mulmod`` functions. ``addmod(x, y, z)`` computes ``(x+y) % z``, -only that it uses unbounded integers for the computations. Similarly, -``mulmod(x, y, z)`` computes ``(x*y) % z``. - -Attaching Library Functions to Types ------------------------------------- - -`PT `__ At the -contract level, statements of the form ``using Lib for Type;`` are -possible, where ``Lib`` has to be the name of a library and ``Type`` can -either be the name of a type or ``*``. The effect is that all functions -in ``Lib`` are attached to variables of type ``Type`` (or just all, if -``Y`` is ``*``) as member functions and expressions of the form -``x.function(a, b)`` are essentially equivalent to -``Lib.function(x, a, b)``. - -:: - - library Lib { - function sum(uint[] storage self) returns (uint s) { - for (uint i = 0; i < self.length; i++) - s += self[i]; - } - } - contract C { - using Lib for uint[]; - uint[] data; - function f() { - data.push(data.sum()); - } - } - -More Flexible Import --------------------- - -`PT `__ The import -statement will behave as a subset of the `ES6 -import `__. The ``export`` -keyword is not available, all symbols will be exported and there is no -"default export". The import statement behaves as follows: - -``import "filename";``: will import all symbols from ``"filename"`` (and -symbols imported there) into the current global scope (different than in -ES6 but backwards-compatible for Solidity). - -``import * as symbolName from "filename";`` creates a new global symbol -``symbolName`` whose members are all symbols from ``"filename"``. - -``import {symbol1 as alias, symbol2} from "filename";`` creates new -global symbols ``alias`` and ``symbol2`` which reference ``symbol1`` and -``symbal2`` from ``"filename"``, respectively. - -Another syntax that is not part of ES6, but probably convenient: - -``import "filename" as symbolName;`` is equivalent to -``import * as symbolName from "filename";``. - -Path Resolution -~~~~~~~~~~~~~~~ - -In the above, ``filename`` is always treated as a path to a file with -``/`` as directory separator, ``.`` as the current directory and ``..`` -as the parent directory. Path names that do not start with ``./`` or -``../`` are treated as absolute paths and the compiler has to be -instructed how to resolve the first element of that path. Using ``.`` or -``..`` is only valid at the beginning of the path. This hierarchy does -not need to strictly map onto the filesystem, it can also map to -resources discovered via e.g. ipfs, http or git. - -When the compiler is invoked, it is not only possible to specify how to -discover the first element of a path, but it is possible to specify path -prefix remappings so that e.g. ``github.com/ethereum/dapp-bin/library`` -is remapped to ``/usr/local/dapp-bin/library`` and the compiler will -read the files from there. If remapping keys are prefixes of each other, -the longest is tried first. This allows for a "fallback-remapping" with -e.g. "" maps to "/usr/local/include/solidity". - -Changes to solc Interface -~~~~~~~~~~~~~~~~~~~~~~~~~ - -For solc, these remappings are provided as ``key=value`` arguments, -where the ``=value`` part is optional (and defaults to ``key`` in that -case). All remapping values that are regular files are compiled -(including their dependencies). This mechanism is completely -backwards-compatible (as long as no filename contains a ``=``) and thus -not a breaking change. solc will only read files in directory(ies) where -input files reside or in remapping targets. - -Index access for fixed bytes type ---------------------------------- - -`PT `__ Single -bytes of expressions of type ``bytes8``, ..., ``bytes32`` are accessible -using ``[i]``. Example: - -:: - - contract C { - function f(bytes32 a, uint i) returns (byte) { return a[i]; } - } - -Write access is not supported, as it is actually quite difficult and -blurs the distinction between value and reference types. diff --git a/old-docs-for-reference/main-wiki.rst/Solidity-Tutorial.rst b/old-docs-for-reference/main-wiki.rst/Solidity-Tutorial.rst deleted file mode 100644 index f6643e1..0000000 --- a/old-docs-for-reference/main-wiki.rst/Solidity-Tutorial.rst +++ /dev/null @@ -1,7 +0,0 @@ -See also `Russian version (русский -перевод) `__ - --------------- - -English version moved to a new -`site `__. diff --git a/old-docs-for-reference/main-wiki.rst/Solidity-standard-library.rst b/old-docs-for-reference/main-wiki.rst/Solidity-standard-library.rst deleted file mode 100644 index 9b971cc..0000000 --- a/old-docs-for-reference/main-wiki.rst/Solidity-standard-library.rst +++ /dev/null @@ -1,175 +0,0 @@ -Solidity standard library -========================= - -overview -~~~~~~~~ - -This is poc of solidity standard library. Probably all of the contracts, -but ``owned`` && ``mortal`` will be removed soon. - -Here is solidity tutorial prepared by Eris team. -`Click `__ - -contracts -~~~~~~~~~ - -- `owned <#owned>`__ -- `mortal <#mortal>`__ - -owned -^^^^^ - -:: - - contract owned{ - function owned() { - owner = msg.sender; - } - - modifier onlyowner() { - if(msg.sender==owner) _ - } - - address owner; - } - -mortal -^^^^^^ - -:: - - import "owned"; - - contract mortal is owned { - function kill() { - if (msg.sender == owner) suicide(owner); - } - } - -poc\_contracts -~~~~~~~~~~~~~~ - -- `Coin <#coin1>`__ -- `Config <#config>`__ -- `CoinReg <#coinreg>`__ -- `configUser <#configuser>`__ -- `Config <#config>`__ -- `named <#named>`__ -- `NameReg <#namereg>`__ -- `service <#service>`__ -- `std <#std>`__ - -coin -^^^^ - -:: - - import "CoinReg"; - import "Config"; - import "configUser"; - - contract coin is configUser { - function coin(string3 name, uint denom) { - CoinReg(Config(configAddr()).lookup(3)).register(name, denom); - } - } - -Coin -^^^^ - -:: - - contract Coin { - function isApprovedFor(address _target,address _proxy) constant returns(bool _r) {} - function isApproved(address _proxy)constant returns(bool _r){} - function sendCoinFrom(address _from,uint256 _val,address _to){} - function coinBalanceOf(address _a)constant returns(uint256 _r){} - function sendCoin(uint256 _val,address _to){} - function coinBalance()constant returns(uint256 _r){} - function approve(address _a){} - } - -CoinReg -^^^^^^^ - -:: - - contract CoinReg { - function count()constant returns(uint256 r){} - function info(uint256 i)constant returns(address addr,string3 name,uint256 denom){} - function register(string3 name,uint256 denom){}function unregister(){} - } - -configUser -^^^^^^^^^^ - -:: - - contract configUser { - function configAddr()constant returns(address a){ - return 0xc6d9d2cd449a754c494264e1809c50e34d64562b; - } - } - -Config -^^^^^^ - -:: - - contract Config { - function lookup(uint256 service)constant returns(address a){} - function kill(){}function unregister(uint256 id){} - function register(uint256 id,address service){} - } - -configUser -^^^^^^^^^^ - -:: - - import "Config"; - import "NameReg"; - import "configUser"; - - contract named is configUser { - function named(string32 name) { - NameReg(Config(configAddr()).lookup(1)).register(name); - } - } - -NameReg -^^^^^^^ - -:: - - contract NameReg { - function register(string32 name){} - function addressOf(string32 name)constant returns(address addr){} - function unregister(){}function nameOf(address addr)constant returns(string32 name){} - } - -service -^^^^^^^ - -:: - - import "Config"; - import "configUser"; - - contract service is configUser { - function service(uint _n){ - Config(configAddr()).register(_n, this); - } - } - -std -^^^ - -:: - - import "owned"; - import "mortal"; - import "Config"; - import "configUser"; - import "NameReg"; - import "named"; diff --git a/old-docs-for-reference/main-wiki.rst/Standardized_Contract_APIs.rst b/old-docs-for-reference/main-wiki.rst/Standardized_Contract_APIs.rst deleted file mode 100644 index 02e3782..0000000 --- a/old-docs-for-reference/main-wiki.rst/Standardized_Contract_APIs.rst +++ /dev/null @@ -1,374 +0,0 @@ -Although Ethereum allows developers to create absolutely any kind of -application without restriction to specific feature types, and prides -itself on its "lack of features", there is nevertheless a need to -standardize certain very common use cases in order to allow users and -applications to more easily interact with each other. This includes -sending currency units, registering names, making offers on exchanges, -and other similar functions. A standard typically consists of a set of -function signatures for a few methods, eg. ``send``, ``register``, -``delete``, providing the set of arguments and their formats in the -`Ethereum contract -ABI `__ -language. - -The standards described below have sample implementations available -`here `__. - -All function names are in lower camelCase (eg. ``sendCoin``) and all -event names are in upper CamelCase (eg. ``CoinTransfer``). Input -variables are in underscore-prefixed lower camelCase (eg. ``_offerId``), -and output variables are ``_r`` for pure getter (ie. constant) -functions, ``_success`` (always boolean) when denoting success or -failure, and other values (eg. ``_maxValue``) for methods that perform -an action but need to return a value as an identifier. Addresses are -referred to using ``_address`` when generic, and otherwise if a more -specific description exists (eg. ``_from``, ``_to``). - -Transferable Fungibles -====================== - -Also known as tokens, coins and sub-currencies. - -Methods -~~~~~~~ - -totalSupply -^^^^^^^^^^^ - -.. code:: js - - function totalSupply() constant returns (uint256 supply) - -Get the total token supply - -balanceOf -^^^^^^^^^ - -.. code:: js - - function balanceOf(address _owner) constant returns (uint256 balance) - -Get the account balance of another account with address ``_owner`` - -transfer -^^^^^^^^ - -.. code:: js - - function transfer(address _to, uint256 _value) returns (bool success) - -Send ``_value`` amount of tokens to address ``_to`` - -transferFrom -^^^^^^^^^^^^ - -.. code:: js - - function transferFrom(address _from, address _to, uint256 _value) returns (bool success) - -Send ``_value`` amount of tokens from address ``_from`` to address -``_to`` - -The ``transferFrom`` method is used for a withdraw workflow, allowing -contracts to send tokens on your behalf, for example to "deposit" to a -contract address and/or to charge fees in sub-currencies; the command -should fail unless the ``_from`` account has deliberately authorized the -sender of the message via some mechanism; we propose these standardized -APIs for approval: - -approve -^^^^^^^ - -.. code:: js - - function approve(address _spender, uint256 _value) returns (bool success) - -Allow ``_spender`` to withdraw from your account, multiple times, up to -the ``_value`` amount. If this function is called again it overwrites -the current allowance with ``_value``. - -allowance -^^^^^^^^^ - -.. code:: js - - function allowance(address _owner, address _spender) constant returns (uint256 remaining) - -Returns the amount which ``_spender`` is still allowed to withdraw from -``_owner``. - -Events -~~~~~~ - -Transfer -^^^^^^^^ - -.. code:: js - - event Transfer(address indexed _from, address indexed _to, uint256 _value) - -Triggered when tokens are transferred. - -Approval -^^^^^^^^ - -.. code:: js - - event Approval(address indexed _owner, address indexed _spender, uint256 _value) - -Triggered whenever ``approve(address _spender, uint256 _value)`` is -called. - -TF Registries -------------- - -Token registries contain information about tokens. There is at least one -global registry (though other may create more like the global Registry) -to which you can add your token. Adding your token to it would increase -the experience of the user that the GUI Client can use or not. - -symbol -^^^^^^ - -.. code:: js - - setSymbol(string _s) - symbol(address _token) constant returns (string) - -Sets or returns a short sequence of letters that are used to represent -the unit of the coin. When setting, it assumes the ``msg.sender`` is the -token. Solidity string is on UTF-8 format so this should support any -character supported by UTF-8. Symbols are chosen by the contract and -it's up to the client to decide how to handle different currencies with -similar or identical symbols. - -Examples or symbols: ``USDX``, ``BOB$``, ``Ƀ``, ``% of shares``. - -name -^^^^ - -.. code:: js - - setName(string _s) - name(address _token) constant returns (string) - -Sets or returns the name of a token. Solidity string is on UTF-8 format -so this should support any character supported by UTF-8. Names are -chosen by the contract and it's up to the client to decide how to handle -different currencies with similar or identical names. - -Examples of names: ``e-Dollar``, ``BobToken``, ``Bitcoin-Eth``. - -baseUnit -^^^^^^^^ - -.. code:: js - - setBaseUnit(uint _s) - baseUnit(address _token) constant returns (uint256) - -Sets or returns the base unit of a token. Although most tokens are -displayed to the final user as containing decimal points, token values -are unsigned integers counting in the smallest possible unit. The client -should always display the total units divided by ``baseUnit``. Base -units can be any integer but we suggest only using powers of 10. At the -moment there is no support for multiple sub-units. - -Example: Bob has a balance of 100000 BobTokens, whose base unit is 100. -His balance will be displayed on the client as **BOB$1000.00** - -Registries ----------- - -Registries (eg. domain name systems) have the following API: - -Methods -~~~~~~~ - -reserve -^^^^^^^ - -.. code:: js - - reserve(string _name) returns (bool _success) - -Reserves a name and sets its owner to you if it is not yet reserved. - -owner -^^^^^ - -.. code:: js - - owner(string _name) constant returns (address _r) - -Get the owner of a particular name. - -transfer -^^^^^^^^ - -.. code:: js - - transfer(string _name, address _newOwner) - -Transfer ownership of a name. - -setAddr -^^^^^^^ - -.. code:: js - - setAddr(string _name, address _address) - -Set the primary address associated with a name (similar to an A record -in traditional DNS.) - -addr -^^^^ - -.. code:: js - - addr(string _name) constant returns (address _r) - -Get the primary address associated with a name. - -setContent -^^^^^^^^^^ - -.. code:: js - - setContent(string _name, bytes32 _content) - -If you are the owner of a name, sets its associated content. - -content -^^^^^^^ - -.. code:: js - - content(string _name) constant returns (bytes32 _r) - -Get the content associated with a name. - -setSubRegistrar -^^^^^^^^^^^^^^^ - -.. code:: js - - setSubRegistrar(string _name, address _subRegistrar) - -Records the name as referring to a sub-registrar at the given address. - -subRegistrar -^^^^^^^^^^^^ - -.. code:: js - - subRegistrar(string _name) constant returns (address _r) - -Gets the sub-registrar associated with the given name. - -disown -^^^^^^ - -.. code:: js - - disown(string _name) - -Relinquishes control over a name that you currently control. - -Events -~~~~~~ - -Changed -^^^^^^^ - -.. code:: js - - event Changed(string name, bytes32 indexed __hash_name) - -Triggered when changed to a domain happen. - -Data feeds ----------- - -The data feed standard is a *templated standard*, ie. in the below -descriptions one should be free to replace ```` with any desired data -type, eg. ``uint256``, ``bytes32``, ``address``, ``real192x64``. - -Methods -~~~~~~~ - -get -^^^ - -.. code:: js - - get(bytes32 _key) returns ( _r) - -Get the value associated with a key. - -set -^^^ - -.. code:: js - - set(bytes32 _key, _value) - -Set the value associated with a key if you are the owner. - -setFee -^^^^^^ - -.. code:: js - - setFee(uint256 _fee) - -Sets the fee. - -setFeeCurrency -^^^^^^^^^^^^^^ - -.. code:: js - - setFeeCurrency(address _feeCurrency) - -Sets the currency that the fee is paid in - -The latter two methods are optional; also, note that the fee may be -charged either in ether or subcurrency; if the contract charges in ether -then the ``setFeeCurrency`` method is unnecessary. - -Forwarding contracts (eg. multisig) ------------------------------------ - -Forwarding contracts will likely work very differently depending on what -the authorization policy of each one is. However, there are some -standard workflows that should be used as much as possible: - -Methods -~~~~~~~ - -execute -^^^^^^^ - -.. code:: js - - execute(address _to, uint _value, bytes _data) returns (bytes32 _id) - -Create a message with the desired recipient, value and data. Returns a -"pending ID" for the transaction. - -confirm -^^^^^^^ - -.. code:: js - - confirm(bytes32 _id) returns (bool _success) - -Confirm a pending message with a particular ID using your account; -returns success or failure. If enough confirmations are made, sends the -message along. - -Access policies can be of any form, eg. multisig, an arbitrary CNF -boolean formula, a scheme that depends on the *value* or *contents* of a -transaction, etc. diff --git a/old-docs-for-reference/main-wiki.rst/Subtleties.rst b/old-docs-for-reference/main-wiki.rst/Subtleties.rst deleted file mode 100644 index 657afdc..0000000 --- a/old-docs-for-reference/main-wiki.rst/Subtleties.rst +++ /dev/null @@ -1,163 +0,0 @@ -Memory ------- - -- Storage is a key/value store where keys and values are both 32 bytes -- Values on the stack are 32 bytes -- Memory is a byte-array. Memory starts off zero-size, but can be - expanded in 32-byte chunks by simply accessing or storing memory at - indices greater than its current size. -- The fee for expanding memory is determined via a - subtract-the-integrals method. Specifically, - ``TOTALFEE(SZ) = SZ * 3 + floor(SZ**2 / 512)`` is the total fee for - expanding the memory to ``SZ`` 32-byte chunks (note: partially filled - chunks are counted, so 33 bytes = 2 chunks), and if a particular - operation expands memory from size ``x`` to ``y``, the additional gas - cost is ``TOTALFEE(y) - TOTALFEE(x)`` -- If an operation writes a slice of data zero bytes wide to memory, - even if the start index of the slice exceeds the current memory size, - memory is NOT expanded. - -Nonces ------- - -- If an externally-owned account sends a transaction, its nonce is - incremented before execution -- If an externally-owned account creates a contract, its nonce is - incremented before execution -- If a contract sends a message, no nonce increments happen -- If a contract creates a contract, the nonce is incremented before the - rest of the sub-execution -- The pre-increment nonce is used to determine the contract address -- Nonce increments are never reverted - -Exceptional conditions ----------------------- - -- The following count as exceptions: - - - Execution running out of gas - - An operation trying to take more slots off the stack than are - available on the stack - - Jumping to a bad jump destination - - An invalid opcode (note: the code of an account is assumed to be - followed by an infinite tail of STOP instructions, so the program - counter "walking off" the end of the code is not an invalid opcode - exception. However, jumping outside the code is an exception, - because STOP is not a valid jump destination) - -- If a transaction triggers an exception, then: - - - The value transfer from sender to recipient still takes place - - The fee transfer from sender to miner still takes place - - The entire ``STARTGAS`` is added to ``gas_used`` - - All other execution is reverted - -- If a contract-producing transaction triggers an exception, then: - - - The fee transfer from sender to miner still takes place - - The endowment is subtracted from the sender's account - - The account that would have been created gets created anyway, - keeps its original endowment, but has the empty string as its code - - The entire ``STARTGAS`` is added to ``gas_used`` - - All other execution is reverted - -- If a ``CALL`` operation's sub-execution triggers an exception, then: - - - Ether value is still sent - - All gas is consumed - - ``0`` is appended onto the stack - - All other execution is reverted - -- If a ``CREATE`` operation's sub-execution triggers an exception, - then: - - - Ether value is lost - - All gas is consumed - - All other execution is reverted - - The current implementations add ``0`` onto the stack, but it does - not matter, since with 0 gas remaining the parent execution will - instaquit anyway - -- After a successful ``CREATE`` operation's sub-execution, if the - operation returns ``x``, ``5 * len(x)`` gas is subtracted from the - remaining gas before the contract is created. If the remaining gas is - less than ``5 * len(x)``, then no gas is subtracted, the code of the - created contract becomes the empty string, but this is not treated as - an exceptional condition - no reverts happen. -- If a contract tries to ``CALL`` or ``CREATE`` a contract with either - (i) insufficient balance, or (ii) stack depth already at maximum - (1024), the sub-execution and transfer do not occur at all, no gas - gets consumed, and 0 is added to the stack. -- Because of the depth limit, a contract may not be aware that a call - that it is about to make is going to fail. Contract programmers - should be very careful about this, and either use the 0 pushed to the - stack to catch errors or use, eg, the identity contract to "test the - waters" before making a substantial number of calls. - -Arithmetic ----------- - -- All arithmetic is modulo 2256. For division, modulo and comparison, - both signed and unsigned operators exist (eg. ``(0 - 27) / 3`` - returns -9 if ``SDIV`` is used, but - ``38597363079105398474523661669562635951089994888546854679819194669304376546636`` - if ``DIV`` is used. -- Truncation and modulo operations with negative operators in the - ``SDIV``/``SMOD`` case are handled as in Python (eg. , ) -- ``DIV``, ``SDIV``, ``MOD`` and ``SMOD`` with dividend (second - argument) equal to 0 push 0 to the stack. - -Other operations -~~~~~~~~~~~~~~~~ - -- The ``CREATE`` opcode takes three values: endowment (ie. initial - amount of ether), memory start and memory length, and pushes onto the - stack the address of the new contract. ``CREATE`` gives the - initializing sub-execution all the gas that you have (and if gas - remains then it gets refunded back to the parent execution) -- The ``CALL`` opcode takes seven values: gas, recipient, ether value, - memory location of start of input data, length of input data, memory - location to put start of output data, length of output data. It puts - onto the stack either 1 for success (ie. did not run out of gas) or 0 - for failure. -- When a contract calls ``SUICIDE``, its ether is immediately sent to - the desired address, but the contract continues existing until the - end of transaction execution. Note that this leads to the interesting - effect that, unlike Bitcoin where funds can be locked away forever - but never destroyed, if a contract either SUICIDEs into itself or - receives ether in the context of the same transaction execution after - it has SUICIDED that ether is actually destroyed. -- If contract A calls contract B calls contract A, then the inner - execution of A will have its own, fresh, memory, stack and PC, but it - will modify and read the same balance and storage. -- If contract initialization returns an empty array, then no contract - will be created. This allows you to "abuse" contract initialization - as an atomic multi-operation, which might be useful in some protocols - where you want to do multiple things but you don't want some of them - to be able to process without others. -- ``JUMP`` and ``JUMPI`` instructions are only allowed to jump onto - destinations that are (1) occupied by a ``JUMPDEST`` opcode, and (2) - are not inside ``PUSH`` data. Note that properly processing these - conditions requires preprocessing the code; a particularly - pathological use case is - ``PUSH2 JUMPDEST PUSH1 PUSH2 JUMPDEST PUSH1 PUSH2 JUMPDEST PUSH1 ...``, - as this code has all ``JUMPDEST``\ s invalid but an alternative piece - of code equivalent to this but only with the leading ``PUSH2`` - replaced with another op (eg. ``BALANCE``) will have all - ``JUMPDESTS``\ s valid. -- ``CALL`` has a multi-part gas cost: - - - 40 base - - 9000 additional if the value is nonzero - - 25000 additional if the destination account does not yet exist - (note: there is a difference between zero-balance and - nonexistent!) - -- ``CALLCODE`` operates similarly to call, except without the potential - for a 25000 gas surcharge. -- The child message of a nonzero-value ``CALL`` operation (NOT the - top-level message arising from a transaction!) gains an additional - 2300 gas on top of the gas supplied by the calling account; this - stipend can be considered to be paid out of the 9000 mandatory - additional fee for nonzero-value calls. This ensures that a call - recipient will always have enough gas to log that it received funds. diff --git a/old-docs-for-reference/main-wiki.rst/Swarm-Hash.rst b/old-docs-for-reference/main-wiki.rst/Swarm-Hash.rst deleted file mode 100644 index 530ea2b..0000000 --- a/old-docs-for-reference/main-wiki.rst/Swarm-Hash.rst +++ /dev/null @@ -1,100 +0,0 @@ -Introduction -============ - -Swarm Hash (a.k.a. -```bzzhash`` `__) -is a Merkle tree hash designed for the purpose of efficient storage and -retrieval in content-addressed storage, both local and networked. While -it is used in -`Swarm `__, -there is nothing Swarm-specific in it and the authors recommend it as a -drop-in substitute of sequential-iterative hash functions (like SHA3) -whenever one is used for referencing integrity-sensitive content, as it -constitutes an improvement in terms of performance and usability without -compromising security. For instance in the `URL Hint -Protocol `__. - -In particular, it can take advantage of parallelisms (including SMP and -massively-parallel architectures such as GPU's) for faster calculation -and verification, can be used to verify the integrity of partial content -without having to transmit all of it. Proofs of security to the -underlying hash function carry over to Swarm Hash. - -Description -=========== - -Swarm Hash is constructed using a regular hash function (in our case, -SHA3) with a generalization of Merkle's tree hash scheme. The basic unit -of hashing is a *chunk*, that can be either a *leaf chunk* containing a -section of the content to be hashed or an *inner chunk* containing -hashes of its children, which can be of either variety. - -Hashes of leaf chunks are defined as the hashes of the concatenation of -the 64-bit length (in LSB-first order) of the content and the content -itself. Because of the inclusion of the length, it is resistant to -length extension attacks, even if the underlying hash function is not. -Note that this "safety belt" measure is extensively used in the latest -edition of OpenPGP standard. It is, however, important to emphasize that -Swarm Hash is obviously vulnerable to length extension attacks, but can -be easily protected against them, when necessary, using similar measures -in a higher layer. A possibly very profitable performance optimization -(not currently implemented) is to initialize the hash calculation with -the length of the standard chunk size (e.g. 4096 bytes), thus saving the -repeated hashing thereof. - -Hashes of inner chunks are defined as the hashes of the concatenation of -the 64-bit length (in LSB-first order) of the content hashed by the -entire (sub-) tree rooted on this chunk and the hashes of its children. - -To distinguish between the two, one should compare the length of the -chunk to the 64-bit number with which every chunk begins. If the chunk -is exactly 8 bytes longer than this number, it is a leaf chunk. If it is -shorter than that, it is an inner chunk. Otherwise, it is not a valid -Swarm Hash chunk. - -Strict interpretation -===================== - -A strict Swarm Hash is one where every chunk with the possible exception -of those on the rightmost branch is of a specified length, i.e. 4 -kilobytes. Those on the rightmost branch are no longer, but possibly -shorter than this length. The hash tree must be balanced, meaning that -all root-to-leaf branches are of the same length. - -The strict interpretation is unique in that only one hash value matches -a particular content. The strict interpretation is only vulnerable to -length extension attacks if the length of the content is a multiple of -the chunk size, and the number of leaf chunks is an integer power of -branching size (the fix maximum chunk size divided by hash length). - -A `parallelized implementation in -Go `__ is -available as well as `a command-line -tool `__ -for hashing files on the local filesystem using the strict -interpretation. - -Loose interpretations -===================== - -Swarm Hash interpreted less strictly may allow for different tree -structures, imposing fewer restrictions or none at all. In this way, -different hash values can resolve to the same content, which might have -some adverse security implications. - -However, it might open the door for different applications where this -does not constitute a vulnerability. For example, accepting single-leaf -hashes in addition to strict Swarm hashes allows for referencing files -without having to implement the whole thing. - -References -========== - -- `Merkle tree `__ -- `Length extension attack on - wikipedia `__ -- `IETF RFC4880 `__ -- `bzzhash - code `__ -- `Swarm documentation and draft - specs `__ diff --git a/old-docs-for-reference/main-wiki.rst/The-Solidity-Programming-Language.rst b/old-docs-for-reference/main-wiki.rst/The-Solidity-Programming-Language.rst deleted file mode 100644 index d1c6243..0000000 --- a/old-docs-for-reference/main-wiki.rst/The-Solidity-Programming-Language.rst +++ /dev/null @@ -1,362 +0,0 @@ -This page is not actively maintained. -===================================== - -The current Solidity documentation can be found at -http://ethereum.github.io/solidity/ - -Foreword -======== - -Solidity is roughly speaking, an object-oriented language designed for -writing contracts in Ethereum. Contracts are (typically) small programs -which govern the behaviour of accounts within the Ethereum state. These -programs operate within the context of the Ethereum environment. Such -accounts are able to pass messages between themselves as well as doing -practically Turing complete computation. - -Solidity is perhaps the first example of a *contract-oriented* -programming language; a slight tweak on the notion of -object-orientation. While closely related to object-oriented languages, -this is a language designed specifically to help express agreements that -must encode ideas and relationships relevant to Real Life, or some -formal model thereof. As such we see notions such as ownership, -identity, protections and restrictions forming a core part of the -vocabulary and idiomatic grammar. - -We see language grammar actually tieing in with many of the aspects of -this: the ``event`` primitives along with the ``indexed`` keyword -explicitly address the logging environment which Ethereum provides. The -variadic return values mimic the fact that output data of Ethereum's -calling mechanism is, like the input data, an arbitrary byte array. - -Basic Contract Anatomy -====================== - -Hello, World! -------------- - -No language would be complete without a Hello World program. Operating -within the Ethereum environment, Solidity has no obvious way of -"outputting" a string. The closest we can do is to use a log event to -place a string into the blockchain: - -:: - - contract HelloWorld { - event Print(string out); - function() { Print("Hello, World!"); } - } - -This contract, if placed on the blockchain and called, would create a -log entry on the blockchain of type ``Print`` with a parameter -``"Hello, World!"``. Easy, eh? - -The Contract ------------- - -The contract is the basic structure of Solidity. It is a prototype of an -object which lives on the blockchain. A contract may be instantiated -into a contract-account (or 'object', or sometimes just 'account') at -which point it gets a uniquely identifying address with which is may be -called. The address here is similar to a reference or pointer in C-like -languages, or just a plain old object in Javascript. Like plain objects -in many object-oriented languages, contracts can never run themselves - -they may only be called, or, put another way, they can only react to the -receipt of a message; they can never be proactive. - -We denote a contract with the ``contract`` keyword and a name, followed -by its definition enclosed in braces (``{`` & ``}``). Here is the most -basic contract: - -:: - - contract MostBasicContract { - } - -It doesn't do anything. To make it do something when it receives a -message, we can introduce a function. The function you've already seen -is the so-called default function. Why this is default will be properly -explained later, but for now, suffice it to say that it is simply the -function that gets called when this contract (well, an instantiation of -it, anyway) receives a message from the Ethereum Environment. - -The syntax of a function is similar to Javascript: it begins with the -``function`` keyword, then has a parenthesised parameter list, and -finally has a braced expression block. - -:: - - contract MostBasicContract { - function() { - // executed when a message is received. - } - } - -This expression block is very similar to other C-like languages -including Javascript. Within our expression block, we are able to do -arbitrary computation; for instance, we might try to determine what the -sum of 1 and 1 is and place it into a variable called ``two``: - -:: - - contract Simple { - function() { - var two = 1 + 1; - } - } - -Unlike in Javascript, all variables must be declared prior to use and -typed. However, for convenience, ``var`` is provided as a way to -automatically determine the type through the expression it is -initialised to. In this case, the type is ``uint``, but more on the -types later. - -Simple Types ------------- - -The type system in Solidity revolves largely around the 256-bit word -size of the EVM. To this end, there are 4 major types, each of which are -specifically 256-bits wide: - -- ``uint``: 256-bit unsigned integer, operable with bitwise and - unsigned arithmetic operations. -- ``int``: 256-bit signed integer, operable with bitwise and signed - arithmetic operations. -- ``real``: 256-bit signed fixed-point quantity, 127-bit left of the - point, 128-bit right. -- ``bytes32``: sequence of 32 bytes (256 bit in total). - -In addition to these, there is the intrinsic ``address`` type used for -identifying specific accounts and a bool type for representing true and -false: - -- ``address``: account identifier, 160-bits. -- ``bool``: two-state value. - -Most of the time, we'll tend to use ``uint`` and ``bytes32``; the former -if we intend to do arithmetic, the latter when we need to identify or -refer to pieces of data, events, &c. - -So to declare a variable it is very similar to the C-like languages: we -simply place the type, followed by the variable name and finish the -expression with a ``;``. For example to declare a uint named ``x`` we -would write: - -:: - - uint x; - -If we then wanted to assign ``69`` to it, we'd use the assignment -operator, ``=`` (not forgetting to place the trailing ``;``: - -:: - - uint x; - x = 69; - -There is a shorthand to declaring and assigning; those two statements -may be collapsed over the ``x`` into: - -:: - - uint x = 69; - -In this situation, where we are simultaneously declaring and -initialising the variable, we are able to substitute the type with the -keyword ``var``. If we do this, the type will be determined through the -type of the expression we are assigning: - -:: - - var x = 69; - -If we were to assign a decimal, ``var`` would become equivalent to a -real: - -:: - - var x = 69; // here, "var" is equivalent to "uint". - var y = 69.42; // here, "var" is equivalent to "real". - -Literals --------- - -Solidity includes three types of literals; these are used for expressing -specific, well-known values. - -Integers -======== - -Integer literals are formed from a sequence of numbers in the range 0-9. -They are interpreted as decimals. Examples include ``69`` and -``01000000``. - -In terms of literals, addresses are formed from the characters ``0x`` -followed directly by a sequence of pairs of hexadecimal numbers, in the -range 0-9 and a-f (not case sensitive). They are interpreted as -hexadecimal-encoded bytes. Examples include: - -:: - - address a = 0x0123456789abcdef0123; - -Byte Strings -============ - -Byte string literals are formed by a sequence of arbitrary characters -contained between quote characters (``"``). They are generally -interpreted as zero-terminated ASCII encoded text, similar to C. The -terminating zero need not be supplied. An examples would be: -``"Hello, World!"``. - -Reals -===== - -Reals are formed similar to integers except that they include a decimal -point and at least one number on either side of it. An example would be: -``3.14159265`` and ``42.000001``. - -Parameters and Returns ----------------------- - -Messages can have arbitrary input and output data. Since functions are -our way of expressing how messages should be handled, they need a way of -expressing how this data should be utilised. As such, like in Javascript -and C, functions may take parameters as input; unlike in Javascript and -C, they may so return arbitrary parameters as output. The input -parameters, and types, must be named, type followed by name. For -example, suppose we want our contract to accept messages that present -two integers, we would write something like: - -:: - - contract Simple { - function(uint _a, uint _b) { - // do something with _a and _b. - } - } - -Parameters are not allowed to be altered; they are so-called *constant* -values and as such may not be used on the left-hand side of an -expression. - -Returning information through the message is equally simple using the -same syntax with the ``returns`` keyword. For example, suppose we wished -to return two results: the sum and the product of the two given -integers, then we would write: - -:: - - contract Simple { - function(uint _a, uint _b) returns (uint o_sum, uint o_product) { - o_sum = _a + _b; - o_product = _a * _b; - } - } - -Return parameters are always reset to zero; if they are not explicitly -set, then they - -Arithmetic & Flow-control -------------------------- - -There are a number of - -On-hand, we also have the Keccak, aka SHA-3 function. So, - -Fields -~~~~~~ - -Contracts may have data members. - -Constant -~~~~~~~~ - -Methods -------- - -Constant -~~~~~~~~ - -The Constructor ---------------- - -The Environment ---------------- - -More Complex Typing -=================== - -Contracts & Forward Declarations --------------------------------- - -External Calls -~~~~~~~~~~~~~~ - -Limiting Gas and Passing Value -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Arrays ------- - -There is also a special type - -- ``byte[]``: dynamic-length packed byte array. - -Mappings --------- - -Structs and Enums ------------------ - -Advanced Solidity -================= - -Visibility ----------- - -- Public -- Private -- External - -Inheritance ------------ - -Function Modifiers ------------------- - -Logging -------- - -Calling conventions -------------------- - -The Solidity Library -==================== - -owned -~~~~~ - -multiowned -~~~~~~~~~~ - -mortal -~~~~~~ - -named -~~~~~ - -daylimit -~~~~~~~~ - -Solidity 2.0 -============ - -Invariants ----------- - -Pre- & Post-conditions ----------------------- - -The dynamic Keyword -------------------- diff --git a/old-docs-for-reference/main-wiki.rst/URL-Hint-Protocol.rst b/old-docs-for-reference/main-wiki.rst/URL-Hint-Protocol.rst deleted file mode 100644 index c2672e9..0000000 --- a/old-docs-for-reference/main-wiki.rst/URL-Hint-Protocol.rst +++ /dev/null @@ -1,74 +0,0 @@ -There exists a root ``Registry`` contract at address 0x42 (this is the -auctioning thing). There exists a contract interface, ``register``, -which ``Registry`` implements. - -Entries in ``register``, when looked up (indexed by a string32 name) -have several value fields, including ``content`` and ``register``. - -``content`` is the content hash which gets loaded when you enter this -name into Mist/AZ. - -``register`` is the address of a subregistry contract (some contract -implementing ``register``) which gets queried recursively. - -Example -~~~~~~~ - -- ``eth://gavofyork`` results in the main Registry (at 0x42) being - queried for the entry ``gavofyork``. The content field of this entry - (a SHA3 hash of a zip file OR manifest) is used to display content - (see Content section for more info). - -URL Composition ---------------- - -All URLs canonically begin ``eth://`` and are a number of components, -each separated by a ``/``. The field ``register`` is used to do a -recursive lookup. - -So the components of ``gavofyork/tools/site/contact`` would comprise -four components, in order: ``gavofyork``, ``tools``, ``site``, -``contact``. - -Any periods ``.`` before the left-most slash ``/`` delineate components -which are specified in reverse order. - -So non-canonical forms of the above address are: - -- ``tools.gavofyork/site/contact`` -- ``site.tools.gavofyork/contact`` -- ``contact.site.tools.gavofyork`` - -NOTE: any periods after the leftmost ``/`` are treated no differently -than other alphanumeric characters. - -Example -~~~~~~~ - -- ``eth://gavofyork/site`` results in the main Registry (at 0x42) being - queried for the entry ``gavofyork``. The register field of this entry - (an address of a ``register``-implementing contract) is then queried - for the entry ``site``. The ``content`` field of this entry is used - to display content. - -Content -======= - -Normally Swarm would be used to determine the content from the content -hash. - -For 1.0, this will not be possible, so we will fall back to using HTTP -distribution. To enable this we will include one or many URLHint -contracts, which provide hints of URLs that allow downloading of -particular content hashes. Find the contract in dapp-bin. - -The content downloaded should be treated in many ways (and hashed) to -discover what the content is. Possible ways include base 64 encoding, -hex encoding and raw, and any content-cropping needed (e.g. a HTML page -should have everything up to body tags removed). - -It will be up to the dapp/content uploader to keep URLHint entries -updated. - -The address of the URLHint contract will be specified on an ad-hoc basis -and users will be able to enter additional ones into their browser. diff --git "a/old-docs-for-reference/main-wiki.rst/Useful-\303\220app-Patterns.rst" "b/old-docs-for-reference/main-wiki.rst/Useful-\303\220app-Patterns.rst" deleted file mode 100644 index 2525c8a..0000000 --- "a/old-docs-for-reference/main-wiki.rst/Useful-\303\220app-Patterns.rst" +++ /dev/null @@ -1,19 +0,0 @@ -The following page is a collection of useful patterns, Ðapps can use, -such as talking to the blockchain reliably. - -The example patterns can possibly change, so don't rely fully on them as -of yet. - -Examples --------- - -- | 3 ways of instantiating web3: - | https://gist.github.com/frozeman/fbc7465d0b0e6c1c4c23 - -- | Contract deployment by code: - | (Outdated, use - ``web3.contract(abiArray).new({}, function(e, res){...})``) - https://gist.github.com/frozeman/655a9325a93ac198416e - -- Test a contract transaction with a ``call`` before actually sending: - https://gist.github.com/ethers/2d8dfaaf7f7a2a9e4eaa diff --git a/old-docs-for-reference/main-wiki.rst/Web3-Secret-Storage-Definition.rst b/old-docs-for-reference/main-wiki.rst/Web3-Secret-Storage-Definition.rst deleted file mode 100644 index 4c41236..0000000 --- a/old-docs-for-reference/main-wiki.rst/Web3-Secret-Storage-Definition.rst +++ /dev/null @@ -1,227 +0,0 @@ -This documents version 3 of the Web3 Secret Storage Definition. - -Definition ----------- - -The actual encoding and decoding of the file remains largely unchanged -from version 1, except that the crypto algorithm is no longer fixed to -AES-128-CBC (AES-128-CTR is now the minimal requirement). Most of the -meanings/algorithm are similar to version 1, except ``mac``, which is -given as the SHA3 (keccak-256) of the concatenation of the last 16 bytes -of the derived key together with the full ``ciphertext``. - -Secret key files are stored directly in ``~/.web3/keystore`` (for -Unix-like systems) and ``~/AppData/Web3/keystore`` (for Windows). They -may be named anything, but a good convention is ``.json``, where -```` is the 128-bit UUID given to the secret key (a -privacy-preserving proxy for the secret key's address). - -All such files have an associated password. To derive a given ``.json`` -file's secret key, first derive the file's encryption key; this is done -through taking the file's password and passing it through a key -derivation function as described by the ``kdf`` key. KDF-dependent -static and dynamic parameters to the KDF function are described in -``kdfparams`` key. - -PBKDF2 must be supported by all minimally-compliant implementations, -denoted though: - -- ``kdf``: ``pbkdf2`` - -For PBKDF2, the ``kdfparams`` include: - -- ``prf``: Must be ``hmac-sha256`` (may be extended in the future); -- ``c``: number of iterations; -- ``salt``: salt passed to PBKDF; -- ``dklen``: length for the derived key. Must be >= 32. - -Once the file's key has been derived, it should be verified through the -derivation of the MAC. The MAC should be calculated as the SHA3 -(keccak-256) hash of the byte array formed as the concatenations of the -second-leftmost 16 bytes of the derived key with the ``ciphertext`` -key's contents, i.e.: - -:: - - KECCAK(DK[16..31] ++ ) - -(where ``++`` is the concatenation operator) - -This value should be compared to the contents of the ``mac`` key; if -they are different, an alternative password should be requested (or the -operation cancelled). - -After the file's key has been verified, the cipher text (the -``ciphertext`` key in the file) may be decrypted using the symmetric -encryption algorithm specified by the ``cipher`` key and parameterised -through the ``cipherparams`` key. If the derived key size and the -algorithm's key size are mismatched, the zero padded, rightmost bytes of -the derived key should be used as the key to the algorithm. - -All minimally-compliant implementations must support the AES-128-CTR -algorithm, denoted through: - -- ``cipher``: ``aes-128-ctr`` - -This cipher takes the following parameters, given as keys to the -``cipherparams`` key: - -- ``iv``: 128-bit initialisation vector for the cipher. - -The key for the cipher is the leftmost 16 bytes of the derived key, i.e. -``DK[0..15]`` - -The creation/encryption of a secret key should be essentially the -reverse of these instructions. Make sure the ``uuid``, ``salt`` and -``iv`` are actually random. - -In addition to the ``version`` field, which should act as a "hard" -identifier of version, implementations may also use ``minorversion`` to -track smaller, non-breaking changes to the format. - -Test Vectors ------------- - -Details: - -- Address: ``008aeeda4d805471df9b2a5b0f38a0c3bcba786b`` -- ICAP: ``XE542A5PZHH8PYIZUBEJEO0MFWRAPPIL67`` -- UUID: ``3198bc9c-6672-5ab3-d9954942343ae5b6`` -- Password: ``testpassword`` -- Secret: - ``7a28b5ba57c53603b0b07b56bba752f7784bf506fa95edc395f5cf6c7514fe9d`` - -PBKDF2-SHA-256 -~~~~~~~~~~~~~~ - -Test vector using AES-128-CTR and PBKDF2-SHA-256: - -File contents of -``~/.web3/keystore/3198bc9c-6672-5ab3-d9954942343ae5b6.json``: - -.. code:: json - - { - "crypto" : { - "cipher" : "aes-128-ctr", - "cipherparams" : { - "iv" : "6087dab2f9fdbbfaddc31a909735c1e6" - }, - "ciphertext" : "5318b4d5bcd28de64ee5559e671353e16f075ecae9f99c7a79a38af5f869aa46", - "kdf" : "pbkdf2", - "kdfparams" : { - "c" : 262144, - "dklen" : 32, - "prf" : "hmac-sha256", - "salt" : "ae3cd4e7013836a3df6bd7241b12db061dbe2c6785853cce422d148a624ce0bd" - }, - "mac" : "517ead924a9d0dc3124507e3393d175ce3ff7c1e96529c6c555ce9e51205e9b2" - }, - "id" : "3198bc9c-6672-5ab3-d995-4942343ae5b6", - "version" : 3 - } - -Intermediates: - -- Derived key: - ``f06d69cdc7da0faffb1008270bca38f5e31891a3a773950e6d0fea48a7188551`` -- MAC Body: - ``e31891a3a773950e6d0fea48a71885515318b4d5bcd28de64ee5559e671353e16f075ecae9f99c7a79a38af5f869aa46`` -- MAC - ``517ead924a9d0dc3124507e3393d175ce3ff7c1e96529c6c555ce9e51205e9b2`` -- Cipher key: ``f06d69cdc7da0faffb1008270bca38f5`` - -Scrypt -~~~~~~ - -Test vector using AES-128-CTR and Scrypt: - -.. code:: json - - { - "crypto" : { - "cipher" : "aes-128-ctr", - "cipherparams" : { - "iv" : "83dbcc02d8ccb40e466191a123791e0e" - }, - "ciphertext" : "d172bf743a674da9cdad04534d56926ef8358534d458fffccd4e6ad2fbde479c", - "kdf" : "scrypt", - "kdfparams" : { - "dklen" : 32, - "n" : 262144, - "r" : 1, - "p" : 8, - "salt" : "ab0c7876052600dd703518d6fc3fe8984592145b591fc8fb5c6d43190334ba19" - }, - "mac" : "2103ac29920d71da29f15d75b4a16dbe95cfd7ff8faea1056c33131d846e3097" - }, - "id" : "3198bc9c-6672-5ab3-d995-4942343ae5b6", - "version" : 3 - } - -Intermediates: - -- Derived key: - ``fac192ceb5fd772906bea3e118a69e8bbb5cc24229e20d8766fd298291bba6bd`` -- MAC Body - ``bb5cc24229e20d8766fd298291bba6bdd172bf743a674da9cdad04534d56926ef8358534d458fffccd4e6ad2fbde479c`` -- MAC: - ``2103ac29920d71da29f15d75b4a16dbe95cfd7ff8faea1056c33131d846e3097`` -- Cipher key: ``fac192ceb5fd772906bea3e118a69e8b`` - -Alterations from Version 1 --------------------------- - -This version fixes several inconsistencies with the version 1 published -`here `__. -In brief these are: - -- Capitalisation is unjustified and inconsistent (``scrypt`` lowercase, - ``Kdf`` mixed-case, ``MAC`` uppercase). -- ``Address`` unnecessary and compromises privacy. -- ``Salt`` is intrinsically a parameter of the key derivation function - and deserves to be associated with it, not with the crypto in - general. -- ``SaltLen`` unnecessary (just derive it from ``Salt``). -- The key derivation function is given, yet the crypto algorithm is - hard specified. -- ``Version`` is intrinsically numeric yet is a string (structured - versioning would be possible with a string, but can be considered out - of scope for a rarely changing configuration file format). -- KDF and cipher are notionally sibling concepts yet are organised - differently. -- MAC is calculated through a whitespace agnostic piece of data(!) - -Changes have been made to the format to give the following file, -functionally equivalent to the example given on the previously linked -page: - -.. code:: json - - { - "crypto": { - "cipher": "aes-128-cbc", - "ciphertext": "07533e172414bfa50e99dba4a0ce603f654ebfa1ff46277c3e0c577fdc87f6bb4e4fe16c5a94ce6ce14cfa069821ef9b", - "cipherparams": { - "iv": "16d67ba0ce5a339ff2f07951253e6ba8" - }, - "kdf": "scrypt", - "kdfparams": { - "dklen": 32, - "n": 262144, - "p": 1, - "r": 8, - "salt": "06870e5e6a24e183a5c807bd1c43afd86d573f7db303ff4853d135cd0fd3fe91" - }, - "mac": "8ccded24da2e99a11d48cda146f9cc8213eb423e2ea0d8427f41c3be414424dd", - "version": 1 - }, - "id": "0498f19a-59db-4d54-ac95-33901b4f1870", - "version": 2 - } - -Alterations from Version 2 --------------------------- - -Version 2 was an early C++ implementation with a number of bugs. All -essentials remain unchanged from it. diff --git a/old-docs-for-reference/main-wiki.rst/What-is-Ethereum.rst b/old-docs-for-reference/main-wiki.rst/What-is-Ethereum.rst deleted file mode 100644 index a9b1be9..0000000 --- a/old-docs-for-reference/main-wiki.rst/What-is-Ethereum.rst +++ /dev/null @@ -1,188 +0,0 @@ -What is Ethereum? -================= - -Ethereum, like any advanced system, will mean different things to -different people. As you read this section, some bits may not resonate -with you or even make sense. That is fine, just skip to the next -paragraph and hopefully that one will be more enlightening. If you reach -the end of this section and still feel confused, then jump on a forum -and start asking questions. - -A World Computer ----------------- - - "It is very possible that ... one machine would suffice to solve all - the problems ... of the whole [world]" - Sir Charles Darwin, 1946\* - -In a technical sense, Ethereum is a "world computer". Harking back to -the days of the mainframe, and probably about as fast, Ethereum can be -viewed as a single computer that the whole world can use. It notionally -has only a single processor (no multi-threading or parallel execution), -but as much memory as required. Anybody can upload programs to the -Ethereum World Computer and anybody can request that a program that has -been uploaded be executed. This does not mean that anyone can ask any -program to do anything; on the contrary: the author of the program can -specify that requests from anyone but themselves be ignored, for -example. Also, in a very strong sense, every program has its own -permanent storage that persists between executions. Furthermore, as long -as it is in demand, the Ethereum World Computer will always be there: it -can't be shut down or turned off. - -You may ask, "why would anyone use such a system?" and again there are -many reasons. The main reason is because it makes what you want to do -cheaper and easier. This statement needs to be broken down somewhat, -which is what the following paragraphs explore. - -An Internet Service Platform ----------------------------- - - "Technology gives us the facilities that lessen the barriers of time - and distance - the telegraph and cable, the telephone, radio, and - the rest." - Emily Greene Balch - -In a more practical sense, Ethereum is an internet service platform for -guaranteed computation. More than that, as a platform, it provides a set -of integral features which are very useful to the developer: - -- user authentication, via seamless integration of cryptographic - signatures -- fully customizable payment logic; easily create your own payment - system without any reliance on third parties -- 100% ddos resistant up-time, guaranteed by being a fully - decentralized blockchain-based platform -- no-fuss storage: forget about having to set up secure databases; - Ethereum gives you as much storage as you want -- ultimate interoperability: everything in the Ethereum ecosystem can - trivially interact with everything else, from reputation to custom - currencies -- server free zone: your whole application can be deployed on the - blockchain meaning no need for setting up or maintaining servers; let - your users pay for the cost of their using your service. - -Over the last twenty years in particular, we have seen an acceleration -in the development of services and infrastructure to make the overhead -of working as a team or running businesses simpler and less expensive, -mainly thanks to the internet. The likes of eBay, Drivy and Airbnb have -made setting up a shop, car rental company or hotel much easier. These -are platforms that allow people to realize their idea quickly, as long -as the service they want to provide fits the template offered by the -platform. Outside Ethereum, it is very costly to create a new platform -if those that already exist do not fit your needs. Ethereum can be seen -as a platform for platforms: it allows people to easily create the -infrastructure to make it easy to set up new services on the internet. -Furthermore, any infrastructure created on Ethereum sits alongside -everyone else's creations, and so can interact with those other -platforms in a guaranteed and seamless manner. Importantly, because -there is not a company or indeed any entity in charge of or controlling -Ethereum, the cost of running the infrastructure doesn't have to include -any profit margin, so we are likely to see lower costs. - -With the coming of the Mix IDE and the Mist browser, the functionality -of Ethereum as a deployment platform for internet services will become -more clear. The take-home message from this section, however, is that -Ethereum is poised to disrupt industries as diverse as finance and -supply chains. - -Opt-in Social Contracts ------------------------ - - "This is an era of organization" - Theodore Roosevelt, 1912\*\* - -At a more abstract level, it is a facility for enabling smart -organization, in the sense of groups of entities working together for a -particular cause. In the simplest scenario, we have two people working -together to achieve a trade. Ultimately, Ethereum could be used to run -countries. Somewhere in between there are groups of people wanting to -organize baby-sitting circles, film-making collectives, discussion -groups, communal houses, etc, and they all have to decide the rules with -which they will operate together. Arguably, the harder task is how to -implement and enforce the rules, especially given the variety of -characters, abilities and motivations that the human race provides. In -other words, how do you stop Jo hogging the camera equipment, or Dave -never doing his turn of the childcare? Ethereum provides a platform on -which rules can be defined and, to an ever increasing degree as -technology improves, see enforced. For example, the camera could be -listening to the blockchain and only record if the film-making -collective's dapp approves Jo's access code. - -Crowdfunding is a key example in the advancement organizational tools. -It provides a couple of really important functions: a way for -individuals to work together for a particular cause (in this case giving -a wedge of cash to a person or group) and a mechanism for individuals to -interact meaningfully with potentially large companies (such as a games -studio). The first follows from the previous paragraph, but the second -point is impressive also, because in general individuals can only -communicate with large organizations on the organization's terms, which -often default to "ignore"; in the same way you ignore the bacteria on -your skin. As it stands, you might be disgruntled by the crowdfunding -recipient taking your money and spending it in a wholey inappropriate -and therefore inefficient manner. However, it's hard to get the -operating company to act on your behalf against the recipient. After -all, the crowdfunding service provider is likely to be a large company -and there isn't a universal mechanism with which you can meaningfully -communicate with it if it does not want you to. Ethereum can help by -allowing you to define post-funding milestones or conditions to stage -the payment of the total amount raised, and then enforce those -conditions for you. As times goes on, we will get more creative in the -ways in which Ethereum can interact with the real world and the ability -of Ethereum to check that milestones have been completed will extend -beyond the obvious such as "30% of the crowd that funded the project (by -value) have voted that the milestone has been passed". - -Part of the Decentralization Revolution ---------------------------------------- - - "No matter who you vote for, the government always gets in" - The - Bonzo Dog Doo-Dah Band, 1992 - -Philosophically, it is the next step in re-decentralizing the internet. -A decentralized system is one that anyone can unilaterally join and -participate in, one in which all participants contribute to the running -and maintanence, and one in which any participant can unilaterally leave -and when they do, the system continues regardless. In a decentralized -system, there is no entity that can prevent participation or arbitrarily -censor the content or usage. The internet was designed to be -decentralized, but the way we use it has become increasingly -centralized, to the point where censorship and exclusion are accepted -and expected. Blockchain technology, introduced by Satoshi Nakamoto with -the proof-of-concept implementation of a simple value transfer system -known as bitcoin, represents the best digital system we have (after the -internet itself) for administering multi-user interactions without any -need for centralized coordination or oversight. Effectively, a -decentralized system is its own authority for enforcing the rules (e.g. -'you can only spend your money once' in bitcoin, or 'whatever rule you -programmed in to your smart contract' in Ethereum), so participants can -be confident that the rules they expect to be enforced will be, without -any danger of corruption, bribery, nepotism, political bias, exclusion, -arbitrary exceptions, human oversight or absence of staff. - -Ethereum allows people to safely interact trustlessly by entering into -neutrally enforceable agreements in a completely peer-to-peer fashion. -Now, it must be remembered that Ethereum can only enforce within its own -digital limits; Ethereum does not remove the need for an external -authority for adjudication over disputes outside its realm---"the other -party punched me in the face after putting in the Ethereum contract that -he wouldn't" is non-sense, but rules exist elsewhere to cover this---but -what Ethereum does do is allow us to push the boundary on what the -digital realm can cover. - -Conclusion ----------- - -Gavin Wood has distilled the description of Ethereum to being a -collection of non-localized singleton programmable data structures. What -this means will depend on where you are coming from, but wherever you -are, it's probably going to be better with Ethereum. - -Notes -~~~~~ - -\*Copeland, Jack (2006). Colossus: The Secrets of Bletchley Park's -Codebreaking Computers. Oxford University Press. p.109 - -Note that T.J.Watson, the former head of IBM, almost certainly never -said, "I think there is a world market for maybe five computers", -although for a time (late 1940s, early 1950s) it was indeed the case -that there was, in the United States, a market for about five computers. - -\*\*Presidential speech, Milwaukee, Wisconsin. diff --git a/old-docs-for-reference/main-wiki.rst/Whisper-Overview.rst b/old-docs-for-reference/main-wiki.rst/Whisper-Overview.rst deleted file mode 100644 index 9ed8acd..0000000 --- a/old-docs-for-reference/main-wiki.rst/Whisper-Overview.rst +++ /dev/null @@ -1,175 +0,0 @@ -Example ("Dream") API Usage -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code:: js - - var shh = web3.shh; - var appName = "My silly app!"; - var myName = "Gav Would"; - var myIdentity = shh.newIdentity(); - - shh.post({ - "from": myIdentity, - "topic": [ web3.fromAscii(appName) ], - "payload": [ web3.fromAscii(myName), web3.fromAscii("What is your name?") ], - "ttl": 100, - "priority": 1000 - }); - - var replyWatch = shh.watch({ - "topic": [ web3.fromAscii(appName), myIdentity ], - "to": myIdentity - }); - // could be "topic": [ web3.fromAscii(appName), null ] if we wanted to filter all such - // messages for this app, but we'd be unable to read the contents. - - replyWatch.arrived(function(m) - { - // new message m - console.log("Reply from " + web3.toAscii(m.payload) + " whose address is " + m.from); - }); - - var broadcastWatch = shh.watch({ "topic": [ web3.fromAscii(appName) ] }); - broadcastWatch.arrived(function(m) - { - if (m.from != myIdentity) - { - // new message m: someone's asking for our name. Let's tell them. - var broadcaster = web3.toAscii(m.payload).substr(0, 32); - console.log("Broadcast from " + broadcaster + "; replying to tell them our name."); - shh.post({ - "from": eth.key, - "to": m.from, - "topics": [ eth.fromAscii(appName), m.from ], - "payload": [ eth.fromAscii(myName) ], - "ttl": 2, - "priority": 500 - }); - } - }); - -Basic operation -~~~~~~~~~~~~~~~ - -``post`` takes a JSON object containing four key parameters: - -.. code:: js - - shh.post({ "topic": t, "payload": p, "ttl": ttl, "workToProve": work }); - -- ``topic``, provided as either a list of, or a single, arbitrary data - items that are used to encode the abstract topic of this message, - later used to filter messages for those that are of interest; -- ``payload``, provided similarly to topic but left as an unformatted - byte array provides the data to be sent. -- ``ttl`` is a time for the message to live on the network, specified - in seconds. This defaults to 50. -- ``work`` is the amount of priority you want the packet to have on the - network. It is specified in milliseconds of processing time on your - machine. This defaults to 50. - -Two other parameters optionally specify the addressing: recipient -(``to``), sender (``from``). The latter is meaningless unless a -recipient has been specified. - -Use cases -~~~~~~~~~ - -- ``shh.post({ "topic": t, "payload": p });`` No signature, no - encryption: Anonymous broadcast; a bit like an anonymous - subject-filtered twitter feed. -- ``shh.post({ "from": myIdentity, "topic": t, "payload": p });`` Open - signature, no encryption: Clear-signed broadcast; a bit like a normal - twitter feed - anyone interested can see a particular identity is - sending particular stuff out to no-one in particular. -- ``shh.post({ "to": recipient, "topic": t, "payload": p });`` No - signature, encryption: Encrypted anonymous message; a bit like an - anonymous drop-box - message is private to the owner of the dropbox. - They can't tell from whom it is. -- ``shh.post({ "from": myIdentity, "to": recipient, "topic": t, "payload": p });`` - Secret signature, encryption: Encrypted signed message; like a secure - e-mail. One identity tells another something - nobody else can read - it. The recipient alone knows it came from the sender. -- ``shh.post({ "from": myIdentity, "to": recipient, "topic": t, "payload": p, "deniable": d });`` - Secret signature, encryption with optional plausible deniability. If - boolean parameter ``d`` is **false**, it is equivalent to the - previous call. If ``d`` is **true**, recipient cannot prove to any - third party that the message originates from sender, though still can - verify it for herself. This is achieved by the digital signature - being calculated on the symmetric session encryption key instead of - the message body. - -In addition to the basic use cases, there will also be support for -secure multi-casting. For this, you set up a group with -``shh.newGroup``: - -:: - - var group = shh.newGroup(eth.key, [ recipient1, recipient2 ]); - -Then can use this as a recipient as you would normally: - -:: - - shh.post({ "from": eth.key, "to": group, "topic": t, "payload": p }); - -The ``newGroup`` actually does something like: - -:: - - var group = shh.newIdentity(); - shh.post([ "from": myIdentity, "to": recipient1, "topic": [invSHA3(2^255), recipient1], "payload": secretFromPublic(group) ]); - shh.post([ "from": myIdentity, "to": recipient2, "topic": [invSHA3(2^255), recipient2], "payload": secretFromPublic(group) ]); - return keypair; - -Here, the ``invSHA3(2^255)`` topic is a sub-band topic (intercepted by -the Whisper protocol layer) which takes the key and adds it to the key -database. When a packet is addressed to ``group``, it encrypts with -group's public key. ``group`` is not generally used for signing. -``secretFromPublic`` obviously isn't a public API and invSHA3 is only -possible because we know each item of the topic is SHA3ed prior to -amalgamation in the final topic. - -When signing a message (one with a ``from`` parameter), the message-hash -is the hash of the clear-text (unencrypted) payload. - -Topics is constructed from a number of components - this simply -compresses (sha3 + crop) each into a final set of 4-byte crypto-secure -hashes. When composing filters, it's the same process. Importantly, all -such hashes given in the filters must be includes in. - -To filter on sender/recipient, they should be encoded within the topic -by the sender. - -Silent Operation -~~~~~~~~~~~~~~~~ - -In normal operation (and assuming a non-degenerate attack condition), -there is a trade-off between true anonymity/plausible deniability over -ones communications and efficiency of operation. The more one advertises -to ones peers attempting to "fish" for useful messages and steer such -message towards oneself, the more one reveals to ones peers. - -For a securely anonymous dynamic two-way conversation, this trade-off -becomes problematic; significant topic-advertising would be necessary -for the point-to-point conversation to happen with sensible latency and -yet so little about the topic can be advertised to guide messages home -without revealing substantial information should there be adversary -peers around an endpoint. (If substantial numbers of adversary peers -surround both endpoints, a tunnelling system similar to TOR must be used -to guarantee security.) - -In this situation, dynamic topic generation would be used. This -effectively turns the datagram-orientated channel into a -connection-oriented channel. The endpoint to begin the conversation -sends a point-to-point (i.e. signed and encrypted) conversation-begin -message that contains a randomly chosen 256-bit topic seed. The seed is -combined (by both endpoints) with a message nonce (beginning at 0 and -incrementing over the course of the conversation) to provide a secure -chain of single-use topics. It then generates a bloom filter using -randomly selected bits from the new topic to match against and gives the -filter to its peers; once a randomly selected minimum of messages -fitting this filter have been collected (we assume one of these is the -message we are interested in), we send our reply, deriving a new topic -(incrementing the nonce), then advertise for that with yet another topic -(another nonce increment) with another randomly selected group of bits. diff --git a/old-docs-for-reference/main-wiki.rst/Whisper-PoC-2-Protocol-Spec.rst b/old-docs-for-reference/main-wiki.rst/Whisper-PoC-2-Protocol-Spec.rst deleted file mode 100644 index 9cbeb25..0000000 --- a/old-docs-for-reference/main-wiki.rst/Whisper-PoC-2-Protocol-Spec.rst +++ /dev/null @@ -1,388 +0,0 @@ -This page, in addition to the Whisper Wire Specification, details the -full Whisper protocol for the first proof-of-concept and sets the vision -for the final design. It evolve alongside the Whisper protocol as the -prototype is refined. From it you should be able to develop compliant -Whisper implementations. This document is intended to give only the base -specification. Many of the aspects leading to an implementation of -Whisper are game theoretic and best not prescribed in the specification, -but rather left to individual implementation teams to determine for -themselves. - -What Whisper Is (and Is Not) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Whisper combines aspects of both DHTs and datagram messaging systems -(e.g. UDP). As such it may be likened and compared to both, not -dissimilar to the matter/energy duality (apologies to physicists for the -blatant abuse of a fundamental and beautiful natural principle). - -Whisper is a pure identity-based messaging system. Whisper provides a -low-level (non-application-specific) but easily-accessible API without -being based upon or prejudiced by the low-level hardware attributes and -characteristics, particularly the notion of singular endpoints. - -Alternatively, Whisper may be likened to a DHT with a per-entry -configurable TTL and conventions for the signing and encryption of -values. In this sense, Whisper provides the ability to have -multiply-indexable, non-unique entries (i.e. the same entry having -multiple keys, some or all of which may be the same as other entries). - -As such, Whisper is not a typical communications system. It is not -designed to replace or substitute TCP/IP, UDP, HTTP or any other -traditional protocols; it is not designed to provide a connection -oriented system, nor for simply delivering data betwixt a pair of -specific network endpoints; it does not have a primary goal of -maximising bandwidth or minimising latency (though as with any -transmission system, these are concerns). - -Whisper is a new protocol designed expressly for a new paradigm of -application development. It is designed from the ground up for easy and -efficient multi-casting and broadcasting. Similarly, low-level -partially-asynchronous communications is an important goal. Low-value -traffic reduction or retardation is another goal (which might also be -likened to the quest for QoS). It is designed to be a building block in -next generation dapps which require large-scale many-to-many -data-discovery, signal negotiation and modest transmissions with an -absolute minimum of fuss and the expectation that one has a very -reasonable assurance of complete privacy. - -Pitch-Black Darkness -~~~~~~~~~~~~~~~~~~~~ - -Whisper operates around the notion of being user-configurable with -regard to how much information it leaks concerning the dapp content and -ultimately, the user activities. To understand information leakage, it -is important to distinguish between mere encryption, and *darkness*. -Many protocols, both those designed around p2p and more traditional -client/server models provide a level of encryption. For some, encryption -forms an intrinsic part of the protocol and, applied alone, delivers its -primary requirement. While decentralising and encrypting is a great -start on building a legitimately "post-Snowden" Web, it is not the end. - -Even with encrypted communications, well-funded attackers are still able -to compromise ones privacy, often quite easily. Bulk metadata collection -becomes the new battleground, and is at once dismissed as a privacy -concern by authorities yet trumpeted as the Next Big Thing by big-data -outfits. In the case of a simple client/server model, metadata betrays -with which hosts one communicates - this is often plenty enough to -compromise privacy given that content is, in many cases, largely -determinable from the host. - -With decentralised communications systems, e.g. a basic non-routed but -encrypted VoIP call or Telehash communication, a network packet-sniffing -attacker may not be able to determine the specific content of a -transmission, but with the help of ISP IP address logs they would be -able to determine to whom one communicated, when and how often. For -certain types of applications in various jurisdictions, this is enough -to be a concerning lack of privacy. - -Even with encryption and packet forwarding through a third relay node, -there is still ample room for a determined bulk transmissions-collector -to execute statistical attacks on timing and bandwidth, effectively -using their knowledge of certain network invariants and the fact that -only a finite amount of actors are involved (i.e. that nodes tend to -forward messages between the same two peers with minimal latency and -that there aren't all that many pairs of nodes that are trying to -communicate via the same relay). There are ways to mitigate this attack -vector, such as using multiple third-party relays and switching between -them randomly or to use very strict framing, however both are imperfect -and can lead to substantial inefficiencies. - -A truly dark system is one that is utterly uncompromising in information -leakage from metadata. At its most secure mode of operation, Whisper can -(at a considerable cost of bandwidth and latency) deliver 100% dark -operation. Even better, this applies not only for metadata collection -from inter-peer conduits (i.e. backbone dragnet devices), but even -against a much more arduous "100% - 2" attack; i.e. where every node in -the network were compromised (though functional) save a pair running -dapps for people that wanted to communicate without anybody else -knowing. - -Routing and Lack Thereof -~~~~~~~~~~~~~~~~~~~~~~~~ - -Fundamentally, at least with the present state of computer science, all -systems present a trade off between the efficiency of deterministic (and -thus supposedly optimal) routing and darkness (or, put another way, -routing privacy). One of Whisper's differences is in providing a -user-configurable trade-off between ones routing privacy and ones -routing efficiency. - -At its most dark, Whisper nodes are entirely reactive - they receive and -record pieces of data and forward them trying to maximise the utility of -information transmission to the peers. These pieces of information -include what is known as a *topic*, which may be viewed both as a -secure-probabilistic routing endpoint and/or a DHT multi-key. - -However, Whisper is also designed to be able to route probabilistically -using two methods, both giving away minimal routing information and both -being exceptionally resilient to statistical attacks from large-scale -metadata collection. - -The first builds on the functionality of the ÐΞV-p2p backend. This -backend provides the ability of Whisper to rate peers and, over time, -probabilistically alter (or *steer*) its set of peers to those which -tend to deliver useful (on-topic, timely, required for ones dapps to -function) information. Ultimately, as the network evolves and the -peer-set is steered, the number of hops between this peer and any others -that tend to be good conduits of useful information (be they the -emitters or simply the well-positioned hubs) will tend to 0. - -Peer steering also provides the incentive for nodes to provide useful -information to peers. The fear of being identified as an -under-performing peer and thus being rotated out in favour of other -nodes gives all nodes incentive to cooperate and share the most useful -information. Useful in this case means provably difficult to author (use -of a proof-of-work function helps here); a low time-to-live; and -well-corresponding to any provided information on what might be useful -(read on for more). - -The second is more dynamic. Nodes are informed by their dapps over what -sort of topics are useful. Nodes are then allowed to advertise to each -peer describing these topics. Topics may be described, using masks or -Bloom filters, and thus in an incomplete manner, to reduce the amount of -information leaked and make passive statistical attacks arbitrarily -difficult to execute. The determination of the amount of information to -give to peers is both made through an explicit setting from the user and -through topic/traffic modelling: "Given the information coming from this -peer and my models of information distribution made from total traffic, -am I receiving the amount of useful valuable information that I would -expect to receive? If so, narrowing it down with additional description -information to the peer may be warranted." - -These settings can even be configured per-peer (more -trusted/longer-lasting peers may be afforded greater amounts of -information), and per-dapp (those dapps that may be more sensitive could -be afforded less advertising than others). We can also make use of -proof-of-work algorithms to minimise the changes of both DoS attacks and -'everything-but' attacks (where a peer is flooded with almost-useful -information prompting it to give away more about its true requirements -than it would do otherwise). - -Through combining and reducing the Blooms/masks, weaker Nth-level -information can be provided to peers about their peers' interests, -forming a probabilistic topic-reception vortex around nodes, the -"topic-space" gravity-well getting weaker and less certain the farther -away with the network hop distance from any interested peers. - -Basic Protocol Elements ------------------------ - -Envelopes -~~~~~~~~~ - -There are two key concepts in Whisper: *Envelopes* and *Messages*. -Envelopes may be considered items should Whisper be considered a DHT. -Should Whisper be considered a datagram messaging system then envelopes -become the packet format which house the potentially encrypted -datagrams. Envelopes are necessarily comprehensible by any node (i.e. -they themselves are unencrypted). - -They contain information to the entry/datagram such as the original time -to live (*TTL*), the absolute time for *expiry* and, importantly, the -*topics*. Topics are a set of indexes to this item, recorded in order to -help an interested party ("recipient") find it or have it routed to -them. They might be likened to binary tags or keywords. Envelopes -additionally contain a nonce allowing the original insertion node -("sender") to prove that some arbitrary amount of work was done in its -composition. Finally, envelopes contain a message-\ *data* field; this -stores the actual payload, together with some information and -potentially a signature; together this forms a message. This field may -be encrypted. - -Envelopes are transmitted as RLP-encoded structures. The precise -definition is given by: - -[``expiry``: ``P``, ``ttl``: ``P``, [``topic0``: ``B_4``, ``topic1``: -``B_4``, ...], ``data``: ``B``, ``nonce``: ``P``] - -Here, ``ttl`` is given in seconds, ``expiry`` is the Unix time of the -intended expiry date/time for the envelope. Following this point in time -the envelope should no longer be transmitted (or stored, unless there is -some extenuating circumstance). Prior to this point in time less the -``ttl`` (i.e. the implied insertion time), the envelope is considered -utterly invalid and should be dropped immediately and the transmitting -peer punished. - -``nonce`` is an arbitrary value. We say the work proved through the -value of the SHA3 of the concatenation of the nonce and the SHA3 of the -RLP of the packet save the nonce (i.e. just a 4-item RLP list), each of -the components as a fixed-length 256-bit hash. When this final hash is -interpreted as a BE-encoded value, the smaller it is, the higher the -work proved. This is used later to judge a peer. - -Topics -~~~~~~ - -Topics are cryptographically secure, probabilistic -partial-classifications of the message. Each topic in the set (order is -unimportant) is determined as the first (left) 4 bytes of the SHA3-256 -hash of some arbitrary data given by the original author of the message. -These might e.g. correspond to "twitter" hash-tags or an intended -recipient's public key hashed with some session nonce or -application-identity. - -Four bytes was chosen to minimise space should a large number of topics -be mentioned while still keeping a sufficiently large space to avoid -large-scale topic-collision (though it may yet be reviewed and possibly -made dynamic in later revisions of the protocol). - -Messages -~~~~~~~~ - -A message is formed as the concatenation of a single byte for flags (at -present only a single flag is used), followed by any additional data (as -stipulated by the flags) and finally the actual payload. This series of -bytes is what forms the ``data`` item of the envelope and is always -encrypted. - -In the present protocol version, no explicit authentication token is -given to indicate that the data field is encrypted; any would-be readers -of the message must know ahead of time, through the choice of topic that -they have specifically filtered for, that the message is encrypted with -a particular key. This is likely to be altered in a further PoC to -include a MAC. - -Any determination that the message is indeed from a particular sender is -left for a higher-level to address. This is noted through the Javascript -API allowing the ``to`` parameter to be passed only at the point of -specifying the filter. Since the signature is a part of the message and -not outside in the envelope, those unable to decrypt the message data -are also unable to access any signature. - -- ``flags``: 1 byte -- (``signature``: 65 bytes) -- ``payload``: not fixed - -Bit 0 of the flags determines whether the signature exists. All other -bits are not yet given a purpose and should be set randomly. A message -is invalid if bit 0 is set but the total data is less than 66 bytes -(since this wouldn't allow it to contain a signature). - -Payloads are encrypted in one of two ways. If the message has a specific -recipient, then by using ECIES with the specific recipient's SECP-256k1 -public key. If the message has no recipient, then by AES-256 with a -randomly generated key. This key is then XORed with each of the *full* -topics to form a salted topic. Each salted topic is stored prior to the -encrypted data *in the same order as the corresponding topics are in the -envelope header*. - -As a recipient, payloads are decrypted in one of two ways. Through use -of topics, it should be known whether the envelope is encrypted to a -specific recipient (in which case use the private key to decrypt) or to -a general multicast audience. In the latter case, we assume that at -least one topic is known (since otherwise, the envelope could not be -properly "identified"). In this case, we match the known *full* topic to -one of the abridged topics in the envelope, determine the index and -de-salt the according salted-key at the beginning of the data segment in -order to retrieve the final key. - -Encryption using the full topic with "routing" using the abridged topic -ensures that nodes which are merely transiently storing the message and -have no interest in the contents (thus have access only to routing -information via the abridged topics) have no intrinsic ability to read -the content of the message. - -The signature, if provided, is the SHA3-256 hash of the unencrypted -payload signed using ECDSA with the insertion-identity's secret key. - -The signature portion is formed as the concatenation of the *r*, *s* and -*v* parameters of the SECP-256k1 ECDSA signature, in that order. ``v`` -is non-normalised and should be either 27 or 28. ``r`` and ``s`` are -both big-endian encoded, fixed-width 32-byte unsigned. - -The payload is otherwise unformatted binary data. - -In the Javascript API, the distinction between envelopes and messages is -blurred. This is because dapps should know nothing about envelopes whose -message cannot be inspected; the fact that nodes pass envelopes around -regardless of their ability to decode the message (or indeed their -interest in it at all) is an important component in Whisper's dark -communications strategy. - -Basic Operation -~~~~~~~~~~~~~~~ - -Nodes are expected to receive and send envelopes continuously, as per -the `protocol -specification `__. -They should maintain a map of envelopes, indexed by expiry time, and -prune accordingly. They should also efficiently deliver messages to the -front-end API through maintaining mappings between topics and envelopes. - -When a node's envelope memory becomes exhausted, a node may drop -envelopes it considers unimportant or unlikely to please its peers. -Nodes should consider peers good that pass them envelopes with low TTLs -and high proofs-of-work. Nodes should consider peers bad that pass then -expired envelopes or, worse, those that have an implied insertion time -prior to the present. - -Nodes should always keep messages that its dapps have created. Though -not in PoC-1, later editions of this protocol may allow dapps to mark -messages as being "archived" and these should be stored and made -available for additional time. - -Nodes should retain a set of per-dapp topics it is interested in. - -Inserting (Authoring) Messages -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To insert a message, little more is needed than to place the envelope -containing it in the node's envelope set that it maintains; the node -should, according to its normal heuristics retransmit the envelope in -due course. Composing an envelope from a basic payload, possible -identities for authoring and access, a number of topics, a time-to-live -and some parameters concerning work-proving targets is done though a few -steps: - -- Compose ``data`` through concatenating the relevant flag byte, a - signature of the payload if the user specified a valid author - identity, and the user-given payload. -- Encrypt the data if an access ("destination") identity's public key - is given by the user. -- Compose ``topics`` from the first 4 bytes of the SHA3 of each topic. -- Set user-given attribute ``ttl``. -- Set the ``expiry`` as the present Unix time plus the time-to-live. -- Set the ``nonce`` as that which provides the most work proved as per - the previous definition, after some fixed amount of time of cycling - through candidates or after a candidate surpasses some boundary; - either should be given by the user. - -Topic Masking and Advertising -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Nodes can advertise their topics of interest to each other. For that -purpose they use a special type of Whisper message (TopicFilterPacket). -The size of Bloom Filter they send to each other must be 64 bytes. -Subsequently the rating system will be introduced -- peers sending -useful messages will be rated higher then those sending random messages. - -A message matches the bloom filter, if any one of the topics in this -message, converted to the Whisper bloom hash, will match the bloom -filter. - -Whisper bloom function accepts AbridgedTopic as a parameter (size: 4 -bytes), and produces a 64-byte hash, where three bits (at the most) are -set to one, and the rest are set to zeros, according to the following -algorithm: - -0. Set all the bits in the resulting 64-byte hash to zero. - -1. We take 9 bits form the AbridgedTopic, and convert to integer value - (range: 0 - 511). - -2. This value defines the index of the bit in the resulting 512-bit - hash, which should be set to one. - -3. Repeat steps 1 & 2 for the second and third bit to be set in the - resulting hash. - -Thus, in order to produce the bloom, we use 27 bits out of 32 in the -AbridgedTopic. For more details, please see the implementation of the -function: TopicBloomFilterBase::bloom() [libwhisper/BloomFilter.h]. - -Coming changes -~~~~~~~~~~~~~~ - -Also being considered for is support for plausible deniability through -the use of session keys and a formalisation of the multicast mechanism. diff --git a/old-docs-for-reference/main-wiki.rst/Whisper-PoC-2-Wire-Protocol.rst b/old-docs-for-reference/main-wiki.rst/Whisper-PoC-2-Wire-Protocol.rst deleted file mode 100644 index 6d9c41d..0000000 --- a/old-docs-for-reference/main-wiki.rst/Whisper-PoC-2-Wire-Protocol.rst +++ /dev/null @@ -1,90 +0,0 @@ -Peer-to-peer communications between nodes running Whisper clients run -using the underlying `ÐΞVp2p Wire -Protocol `__. - -This is a preliminary wire protocol for the Whisper subsystem. It will -change. - -Whisper Sub-protocol -~~~~~~~~~~~~~~~~~~~~ - -**Status** [``+0x00``: ``P``, ``protocolVersion``: ``P``] Inform a peer -of the **whisper** status. This message should be send *after* the -initial handshake and *prior* to any **whisper** related messages. \* -``protocolVersion`` is one of: \* ``0x02`` for PoC-7. - -**Messages** [``+0x01``: ``P``, [``expiry1``: ``P``, ``ttl1``: ``P``, -[``topic1x1``: ``B_4``, ``topic1x2``: ``B_4``, ...], ``data1``: ``B``, -``nonce1``: ``P``], [``expiry2``: ``P``, ...], ...] Specify one or more -messages. Nodes should not resend the same message to a peer in the same -session, nor send a message back to a peer from which it received. This -packet may be empty. The packet must be sent at least once per second, -and only after receiving a **Messages** message from the peer. - -**TopicFilter** [``+0x02``: ``P``, ``bloom``: ``B_64``] Specify the -bloom filter of the topics that the sender is interested in. The bloom -method is defined below. - -Session Management -~~~~~~~~~~~~~~~~~~ - -For the Whisper sub-protocol, upon an active session, a ``Status`` -message must be sent. Following the reception of the peer's ``Status`` -message, the Whisper session is active. The peer with the greatest Node -Id should send a **Messages** message to begin the message rally. From -that point, peers take it in turns to send (possibly empty) Messages -packets. - -Topics and Abridged Topics -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*Topics* are 32-byte hashes, typically generated from dapp-specified -data. The *abridged topic* is the first 4 bytes of the topic. Abridged -topics allow the identification (within the bounds of an acceptably high -probability) of a given topic, useful for determining the utility of a -topic for a given peer, yet do not give away the full topic information -itself, allowing it to be used as a strong encryption key whose secret -is not inherently available. - -Bloomed Topics -~~~~~~~~~~~~~~ - -The Bloom filter used in the ``TopicFilter`` message type is a means a -identifying a number of topics to a peer without compromising (too much) -privacy over precisely what topics are of interest. Precise control over -the information content (and thus efficiency of the filter) may be -maintained through the addition of bits. - -Blooms are formed by the bitwise OR operation on a number of bloomed -topics. The bloom function takes the abridged topic (the first four -bytes of the SHA3 of the dapp/user level topic description) and projects -them onto a 512-bit slice; in total, three bits are marked for each -bloomed topic. - -The projection function is defined as a mapping from a a 4-byte slice -``S`` to a 512-bit slice ``D``; for ease of explanation, ``S`` will -dereference to bytes, whereas ``D`` will dereference to bits. - -:: - - LET D[*] = 0 - FOREACH i IN { 0, 1, 2 } DO - LET n = S[i] - IF S[3] & (2 ** i) THEN n += 512 - D[n] = 1 - END FOR - -In formal notation: - -:: - - D[i] := f(0) == i || f(1) == i || f(2) == i - -where: - -:: - - f(x) := S[x] + S[3][x] * 512 - -(assuming a byte value ``S[i]`` may be further dereferenced into a bit -value) diff --git a/old-docs-for-reference/main-wiki.rst/Whisper-Wire-Protocol.rst b/old-docs-for-reference/main-wiki.rst/Whisper-Wire-Protocol.rst deleted file mode 100644 index 7eb0102..0000000 --- a/old-docs-for-reference/main-wiki.rst/Whisper-Wire-Protocol.rst +++ /dev/null @@ -1,32 +0,0 @@ -Peer-to-peer communications between nodes running Whisper clients run -using the underlying `ÐΞVp2p Wire -Protocol `__. - -This is a preliminary wire protocol for the Whisper subsystem. It will -change. - -Whisper Sub-protocol -~~~~~~~~~~~~~~~~~~~~ - -**Status** [``+0x00``: ``P``, ``protocolVersion``: ``P``] Inform a peer -of the **whisper** status. This message should be send *after* the -initial handshake and *prior* to any **whisper** related messages. \* -``protocolVersion`` is one of: \* ``0x02`` for PoC-7. - -**Messages** [``+0x01``: ``P``, [``expiry1``: ``P``, ``ttl1``: ``P``, -[``topic1x1``: ``B_4``, ``topic1x2``: ``B_4``, ...], ``data1``: ``B``, -``nonce1``: ``P``], [``expiry2``: ``P``, ...], ...] Specify one or more -messages. Nodes should not resend the same message to a peer in the same -session, nor send a message back to a peer from which it received. This -packet may be empty. The packet must be sent at least once per second, -and only after receiving a **Messages** message from the peer. - -Session Management -~~~~~~~~~~~~~~~~~~ - -For the Whisper sub-protocol, upon an active session, a ``Status`` -message must be sent. Following the reception of the peer's ``Status`` -message, the Whisper session is active. The peer with the greatest Node -Id should send a **Messages** message to begin the message rally. From -that point, peers take it in turns to send (possibly empty) Messages -packets. diff --git a/old-docs-for-reference/main-wiki.rst/Whisper.rst b/old-docs-for-reference/main-wiki.rst/Whisper.rst deleted file mode 100644 index 654c4c0..0000000 --- a/old-docs-for-reference/main-wiki.rst/Whisper.rst +++ /dev/null @@ -1,171 +0,0 @@ -Use case -~~~~~~~~ - -- Dapps that need to publish small amounts of information to each other - and have the publication last some substantial amount of time. For - example, a currency exchange dapp may use it to record an offer to - sell some currency at a particular rate on an exchange. In this case, - it may last anything between tens of minutes and days. The offer - wouldn't be binding, merely a hint to get a potential deal started. - -- Dapps that need to signal to each other in order to ultimately - collaborate on a transaction. For example, a currency exchange dapp - may use it to coordinate an offer prior to creating one (or two, - depending on how the exchange is structured) transactions on the - exchange. - -- Dapps that need to provide non-real-time hinting or general - communications between each other. E.g. a small chat-room app. - -- Dapps that need to provide dark (plausible denial over perfect - network traffic analysis) comms to two correspondents that know - nothing of each other but a hash. This could be a dapp for a - whistleblower to communicate to a known journalist exchange some - small amount of verifiable material and arrange between themselves - for some other protocol (Swarm, perhaps) to handle the bulk transfer. - -In general, think transactions, but without the eventual archival, any -necessity of being bound to what is said or automated execution & state -change. - -Specs -~~~~~ - -- **Low-level** API only exposed to dapps, never to users. -- **Low-bandwidth** Not designed for large data transfers. -- **Uncertain-latency** Not designed for RTC. -- **Dark** No reliable methods for tracing packets or -- Typical usage: -- Low-latency, 1-1 or 1-N signaling messages. -- High latency, high TTL 1-\* publication messages. - -Messages less than 64K bytes, typically around 256 bytes. - -Existing solutions -~~~~~~~~~~~~~~~~~~ - -- UDP: Similar in API-level, native multicasting. No TTL, security or - privacy safeguards. -- `0MQ `__: A distributed messaging system, no - inherent privacy safeguards. -- `Bitmessage `__: Similar in - the basic approach of P2P network exchanging messages with baseline - PKI for dark comms. Higher-level (e-mail replacement, only "several - thousand/day", larger mails), fixed TTL and no hinting to optimize - for throughput. Unclear incentivisation. -- `TeleHash `__: - Secure connection-orientated RTC comms. Similar in approach to - BitTorrent (uses modified Kademila tech), but rather than discovering - peers for a given hash, it routes to the recipient given its hash. - Uses DHT to do deterministic routing therefore insecure against - simple statistical packet-analysis attacks against a large-scale - attacker. Connection oriented, so no TTL and not designed for - asynchronous data publication. -- `Tox `__: - Higher-level (IM & AV chat) replacement. - -Basic Design -~~~~~~~~~~~~ - -Uses the ``"shh"`` protocol string of ÐΞVP2P. - -Rest coming soon, once I've finished prototyping. Gav. - -Considerations for Defeating Traffic Analysis -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -(from lokiverloren) All existing protocols for location obscured instant -messaging have complicated problems to do with routing. - -The Bitmessage protocol propagates messages blindly across the network, -and the proper recipient knows how to decrypt it and receives it (just -like everyone else) but then stores it and lets its' user know it's got -a new message. The problem with this of course is that it greatly -increases the exposure of the whole network to a body of encrypted -material that ideally should not be easily accessed at all. - -None of the others listed above particularly have any means to hide the -source and destination of messages. I believe it is one of the core -objectives of the Whisper protocol to hide location of sender and -receiver and in transit, make it difficult if not impossible to -establish one, the other or both. - -The Tor system has a protocol for enabling connections between two nodes -without either knowing where the other is, it is the Rendezvous protocol -used for hidden services. Most readers of this will already understand -how it works, but what happens is that a hidden service (the equivalent -of a server listening on a port in the TCP/IP protocol) selects at -random a number (I think, usually 6) 'introducer' nodes. In order to do -this it establishes the standard 3-hop chain to each of the introducers, -and when a user wants to establish a connection with a hidden service, -they propagate a request to connect with hidden service that is -associated with a particular public key. I'm not sure about how this -request is propagated, obviously it would also have to be done through a -circuit or the rendezvous introducer node knows who might be about to -establish a circuit. Once one's client knows a valid rendezvous node it -then establishes a connection to it and requests to have traffic relayed -through its' circuit to the hidden service. - -I think there really isn't a better way to implement 'dark' parts of the -connection protocol, because there has to be a different identity for a -relay node as a client node, the same principle applies in Ethereum. -However, using the rendezvous, it again makes possible something for -connections between nodes that know each other (though they don't know -the account or identity of the initiator) something other than the -uniform 3 hop circuit. For generating a circuit to an exit node in Tor, -it is of no danger that your client knows the identity of the relays in -each hop along the way, but to do that *within* the network compromises -location obfuscation security, tying your ethereum identity with your -router identity (I think it may need to be explicitly pointed out that -routing function is something that Ethereum nodes will perform). When -connecting to a rendezvous, you do not thereby reveal your location to -the rendezvous, and the rendezvous does not know the location of the -hidden service either, and establishing these connections only requires -a public directory to be created for routers. It is not consequential -information for an attacker and can be revealed directly by probing for -a relevant server at your IP addresses anyway. - -The contribution I would like to make to the discussion is this: - -1. It is implied that the whisper protocol has to work through a system - of location obfuscation relays like Tor. Not only this, but it must - therefore also be using some form of the rendezvous protocol used in - Tor for hidden services. - -2. However, as Tor was originally designed first to be a way to stop - webservers logging your IP address in association with a session - cookie and record, then secondarily added the ability to implement - the equivalent of TCP/IP routing (listening ports) within the context - of location obfuscation in the form of the rendezvous protocol, it is - an artifact, a legacy of the first purpose that leads to the uniform - utilisation of 3 hop nodes and connections that remain open rather - than a session (connectionless) protocol like used in HTTP. What I - suggest is that, depending on the needs of a particular connection, - there can be occasion to mix up the obfuscation process so that it is - further obscured from traffic analysis in the case of malicious nodes - performing data gathering for an attacker. - -Instead of a connection like is normal between a browser and web server, -for example, which is usually left open because of the latency of -reestablishing such a connection, to make further requests, instead -there can be a session cookie, and then you can alter the way your -client sends data through the 'connection' to a hidden node. The -connection, between two routing nodes, could be direct, 1 proxy -intermediary, 2, or 3, it could use shared secrets instead and route -fragments of datagrams across multiple heteregenous circuits, as well, -and the receiver would then wait for sufficient fragments to assemble -the original packets. Indeed, it could be possible in the case of (not -quite related to whisper, but to the distributed data storage protocol) -larger streams, break the stream up into parts and alter the obfuscation -method through the process, further confusing the traffic analysis data. - -The same considerations apply, fundamentally, the only differences have -to do with the size of the data being transmitted, whether it's for a -messaging system or distributed filesystem. The other criteria for -deciding how to scramble the routing is latency. For some purposes one -wants lower latency, and other purposes, greater security is vitally -important. When in the process streams are fragmented into parts, it can -also increase security to apply an All Or Nothing Transform to the -entire package, then if part is intercepted but not the complete -message, it is impossible to assemble the data, not even for -cryptanalysis purposes. diff --git a/old-docs-for-reference/main-wiki.rst/White-Paper.rst b/old-docs-for-reference/main-wiki.rst/White-Paper.rst deleted file mode 100644 index fab24e4..0000000 --- a/old-docs-for-reference/main-wiki.rst/White-Paper.rst +++ /dev/null @@ -1,1691 +0,0 @@ -A Next-Generation Smart Contract and Decentralized Application Platform -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Satoshi Nakamoto's development of Bitcoin in 2009 has often been hailed -as a radical development in money and currency, being the first example -of a digital asset which simultaneously has no backing or "`intrinsic -value `__" -and no centralized issuer or controller. However, another, arguably more -important, part of the Bitcoin experiment is the underlying blockchain -technology as a tool of distributed consensus, and attention is rapidly -starting to shift to this other aspect of Bitcoin. Commonly cited -alternative applications of blockchain technology include using -on-blockchain digital assets to represent custom currencies and -financial instruments (`"colored -coins" `__), -the ownership of an underlying physical device (`"smart -property" `__), non-fungible -assets such as domain names (`"Namecoin" `__), as -well as more complex applications involving having digital assets being -directly controlled by a piece of code implementing arbitrary rules -(`"smart -contracts" `__) or -even blockchain-based "`decentralized autonomous -organizations `__" -(DAOs). What Ethereum intends to provide is a blockchain with a built-in -fully fledged Turing-complete programming language that can be used to -create "contracts" that can be used to encode arbitrary state transition -functions, allowing users to create any of the systems described above, -as well as many others that we have not yet imagined, simply by writing -up the logic in a few lines of code. - -Table of Contents -~~~~~~~~~~~~~~~~~ - -- `History <#history>`__ - - - `Bitcoin As A State Transition - System <#bitcoin-as-a-state-transition-system>`__ - - `Mining <#mining>`__ - - `Merkle Trees <#merkle-trees>`__ - - `Alternative Blockchain - Applications <#alternative-blockchain-applications>`__ - - `Scripting <#scripting>`__ - -- `Ethereum <#ethereum>`__ - - - `Ethereum Accounts <#ethereum-accounts>`__ - - `Messages and Transactions <#messages-and-transactions>`__ - - `Ethereum State Transition - Function <#ethereum-state-transition-function>`__ - - `Code Execution <#code-execution>`__ - - `Blockchain and Mining <#blockchain-and-mining>`__ - -- `Applications <#applications>`__ - - - `Token Systems <#token-systems>`__ - - `Financial - derivatives <#financial-derivatives-and-stable-value-currencies>`__ - - `Identity and Reputation - Systems <#identity-and-reputation-systems>`__ - - `Decentralized File Storage <#decentralized-file-storage>`__ - - `Decentralized Autonomous - Organizations <#decentralized-autonomous-organizations>`__ - - `Further Applications <#further-applications>`__ - -- `Miscellanea And Concerns <#miscellanea-and-concerns>`__ - - - `Modified GHOST Implementation <#modified-ghost-implementation>`__ - - `Fees <#fees>`__ - - `Computation And - Turing-Completeness <#computation-and-turing-completeness>`__ - - `Currency And Issuance <#currency-and-issuance>`__ - - `Mining Centralization <#mining-centralization>`__ - - `Scalability <#scalability>`__ - -- `Conclusion <#conclusion>`__ -- `Notes and Further Reading <#notes-and-further-reading>`__ - -Introduction to Bitcoin and Existing Concepts ---------------------------------------------- - -History -~~~~~~~ - -The concept of decentralized digital currency, as well as alternative -applications like property registries, has been around for decades. The -anonymous e-cash protocols of the 1980s and the 1990s, mostly reliant on -a cryptographic primitive known as Chaumian blinding, provided a -currency with a high degree of privacy, but the protocols largely failed -to gain traction because of their reliance on a centralized -intermediary. In 1998, Wei Dai's -`b-money `__ became the first proposal -to introduce the idea of creating money through solving computational -puzzles as well as decentralized consensus, but the proposal was scant -on details as to how decentralized consensus could actually be -implemented. In 2005, Hal Finney introduced a concept of "`reusable -proofs of work `__", a system which -uses ideas from b-money together with Adam Back's computationally -difficult Hashcash puzzles to create a concept for a cryptocurrency, but -once again fell short of the ideal by relying on trusted computing as a -backend. In 2009, a decentralized currency was for the first time -implemented in practice by Satoshi Nakamoto, combining established -primitives for managing ownership through public key cryptography with a -consensus algorithm for keeping track of who owns coins, known as "proof -of work". - -The mechanism behind proof of work was a breakthrough in the space -because it simultaneously solved two problems. First, it provided a -simple and moderately effective consensus algorithm, allowing nodes in -the network to collectively agree on a set of canonical updates to the -state of the Bitcoin ledger. Second, it provided a mechanism for -allowing free entry into the consensus process, solving the political -problem of deciding who gets to influence the consensus, while -simultaneously preventing sybil attacks. It does this by substituting a -formal barrier to participation, such as the requirement to be -registered as a unique entity on a particular list, with an economic -barrier - the weight of a single node in the consensus voting process is -directly proportional to the computing power that the node brings. Since -then, an alternative approach has been proposed called *proof of stake*, -calculating the weight of a node as being proportional to its currency -holdings and not computational resources; the discussion of the relative -merits of the two approaches is beyond the scope of this paper but it -should be noted that both approaches can be used to serve as the -backbone of a cryptocurrency. - -Bitcoin As A State Transition System -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. figure:: http://vitalik.ca/files/statetransition.png?2 - :alt: statetransition.png - - statetransition.png - -From a technical standpoint, the ledger of a cryptocurrency such as -Bitcoin can be thought of as a state transition system, where there is a -"state" consisting of the ownership status of all existing bitcoins and -a "state transition function" that takes a state and a transaction and -outputs a new state which is the result. In a standard banking system, -for example, the state is a balance sheet, a transaction is a request to -move $X from A to B, and the state transition function reduces the value -in A's account by $X and increases the value in B's account by $X. If -A's account has less than $X in the first place, the state transition -function returns an error. Hence, one can formally define: - -:: - - APPLY(S,TX) -> S' or ERROR - -In the banking system defined above: - -:: - - APPLY({ Alice: $50, Bob: $50 },"send $20 from Alice to Bob") = { Alice: $30, Bob: $70 } - -But: - -:: - - APPLY({ Alice: $50, Bob: $50 },"send $70 from Alice to Bob") = ERROR - -The "state" in Bitcoin is the collection of all coins (technically, -"unspent transaction outputs" or UTXO) that have been minted and not yet -spent, with each UTXO having a denomination and an owner (defined by a -20-byte address which is essentially a cryptographic public key[1]). A -transaction contains one or more inputs, with each input containing a -reference to an existing UTXO and a cryptographic signature produced by -the private key associated with the owner's address, and one or more -outputs, with each output containing a new UTXO to be added to the -state. - -The state transition function ``APPLY(S,TX) -> S'`` can be defined -roughly as follows: - -1. For each input in ``TX``: - - - If the referenced UTXO is not in ``S``, return an error. - - If the provided signature does not match the owner of the UTXO, - return an error. - -2. If the sum of the denominations of all input UTXO is less than the - sum of the denominations of all output UTXO, return an error. -3. Return ``S`` with all input UTXO removed and all output UTXO added. - -The first half of the first step prevents transaction senders from -spending coins that do not exist, the second half of the first step -prevents transaction senders from spending other people's coins, and the -second step enforces conservation of value. In order to use this for -payment, the protocol is as follows. Suppose Alice wants to send 11.7 -BTC to Bob. First, Alice will look for a set of available UTXO that she -owns that totals up to at least 11.7 BTC. Realistically, Alice will not -be able to get exactly 11.7 BTC; say that the smallest she can get is -6+4+2=12. She then creates a transaction with those three inputs and two -outputs. The first output will be 11.7 BTC with Bob's address as its -owner, and the second output will be the remaining 0.3 BTC "change", -with the owner being Alice herself. - -Mining -~~~~~~ - -.. figure:: http://vitalik.ca/files/block_picture.png - :alt: block\_picture.jpg - - block\_picture.jpg - -If we had access to a trustworthy centralized service, this system would -be trivial to implement; it could simply be coded exactly as described, -using a centralized server's hard drive to keep track of the state. -However, with Bitcoin we are trying to build a decentralized currency -system, so we will need to combine the state transaction system with a -consensus system in order to ensure that everyone agrees on the order of -transactions. Bitcoin's decentralized consensus process requires nodes -in the network to continuously attempt to produce packages of -transactions called "blocks". The network is intended to produce roughly -one block every ten minutes, with each block containing a timestamp, a -nonce, a reference to (ie. hash of) the previous block and a list of all -of the transactions that have taken place since the previous block. Over -time, this creates a persistent, ever-growing, "blockchain" that -constantly updates to represent the latest state of the Bitcoin ledger. - -The algorithm for checking if a block is valid, expressed in this -paradigm, is as follows: - -1. Check if the previous block referenced by the block exists and is - valid. -2. Check that the timestamp of the block is greater than that of the - previous block[2] and less than 2 hours into the future -3. Check that the proof of work on the block is valid. -4. Let ``S[0]`` be the state at the end of the previous block. -5. Suppose ``TX`` is the block's transaction list with ``n`` - transactions. For all ``i`` in ``0...n-1``, set - ``S[i+1] = APPLY(S[i],TX[i])`` If any application returns an error, - exit and return false. -6. Return true, and register ``S[n]`` as the state at the end of this - block. - -Essentially, each transaction in the block must provide a valid state -transition from what was the canonical state before the transaction was -executed to some new state. Note that the state is not encoded in the -block in any way; it is purely an abstraction to be remembered by the -validating node and can only be (securely) computed for any block by -starting from the genesis state and sequentially applying every -transaction in every block. Additionally, note that the order in which -the miner includes transactions into the block matters; if there are two -transactions A and B in a block such that B spends a UTXO created by A, -then the block will be valid if A comes before B but not otherwise. - -The one validity condition present in the above list that is not found -in other systems is the requirement for "proof of work". The precise -condition is that the double-SHA256 hash of every block, treated as a -256-bit number, must be less than a dynamically adjusted target, which -as of the time of this writing is approximately 2187. The purpose of -this is to make block creation computationally "hard", thereby -preventing sybil attackers from remaking the entire blockchain in their -favor. Because SHA256 is designed to be a completely unpredictable -pseudorandom function, the only way to create a valid block is simply -trial and error, repeatedly incrementing the nonce and seeing if the new -hash matches. - -At the current target of ~2187, the network must make an average of ~269 -tries before a valid block is found; in general, the target is -recalibrated by the network every 2016 blocks so that on average a new -block is produced by some node in the network every ten minutes. In -order to compensate miners for this computational work, the miner of -every block is entitled to include a transaction giving themselves 25 -BTC out of nowhere. Additionally, if any transaction has a higher total -denomination in its inputs than in its outputs, the difference also goes -to the miner as a "transaction fee". Incidentally, this is also the only -mechanism by which BTC are issued; the genesis state contained no coins -at all. - -In order to better understand the purpose of mining, let us examine what -happens in the event of a malicious attacker. Since Bitcoin's underlying -cryptography is known to be secure, the attacker will target the one -part of the Bitcoin system that is not protected by cryptography -directly: the order of transactions. The attacker's strategy is simple: - -1. Send 100 BTC to a merchant in exchange for some product (preferably a - rapid-delivery digital good) -2. Wait for the delivery of the product -3. Produce another transaction sending the same 100 BTC to himself -4. Try to convince the network that his transaction to himself was the - one that came first. - -Once step (1) has taken place, after a few minutes some miner will -include the transaction in a block, say block number 270000. After about -one hour, five more blocks will have been added to the chain after that -block, with each of those blocks indirectly pointing to the transaction -and thus "confirming" it. At this point, the merchant will accept the -payment as finalized and deliver the product; since we are assuming this -is a digital good, delivery is instant. Now, the attacker creates -another transaction sending the 100 BTC to himself. If the attacker -simply releases it into the wild, the transaction will not be processed; -miners will attempt to run ``APPLY(S,TX)`` and notice that ``TX`` -consumes a UTXO which is no longer in the state. So instead, the -attacker creates a "fork" of the blockchain, starting by mining another -version of block 270000 pointing to the same block 269999 as a parent -but with the new transaction in place of the old one. Because the block -data is different, this requires redoing the proof of work. Furthermore, -the attacker's new version of block 270000 has a different hash, so the -original blocks 270001 to 270005 do not "point" to it; thus, the -original chain and the attacker's new chain are completely separate. The -rule is that in a fork the longest blockchain is taken to be the truth, -and so legitimate miners will work on the 270005 chain while the -attacker alone is working on the 270000 chain. In order for the attacker -to make his blockchain the longest, he would need to have more -computational power than the rest of the network combined in order to -catch up (hence, "51% attack"). - -Merkle Trees -~~~~~~~~~~~~ - -.. figure:: https://raw.githubusercontent.com/ethereum/www/master-postsale/src/extras/gh_wiki/spv_bitcoin.png - :alt: SPV in bitcoin - - SPV in bitcoin - -*Left: it suffices to present only a small number of nodes in a Merkle -tree to give a proof of the validity of a branch.* - -*Right: any attempt to change any part of the Merkle tree will -eventually lead to an inconsistency somewhere up the chain.* - -An important scalability feature of Bitcoin is that the block is stored -in a multi-level data structure. The "hash" of a block is actually only -the hash of the block header, a roughly 200-byte piece of data that -contains the timestamp, nonce, previous block hash and the root hash of -a data structure called the Merkle tree storing all transactions in the -block. A Merkle tree is a type of binary tree, composed of a set of -nodes with a large number of leaf nodes at the bottom of the tree -containing the underlying data, a set of intermediate nodes where each -node is the hash of its two children, and finally a single root node, -also formed from the hash of its two children, representing the "top" of -the tree. The purpose of the Merkle tree is to allow the data in a block -to be delivered piecemeal: a node can download only the header of a -block from one source, the small part of the tree relevant to them from -another source, and still be assured that all of the data is correct. -The reason why this works is that hashes propagate upward: if a -malicious user attempts to swap in a fake transaction into the bottom of -a Merkle tree, this change will cause a change in the node above, and -then a change in the node above that, finally changing the root of the -tree and therefore the hash of the block, causing the protocol to -register it as a completely different block (almost certainly with an -invalid proof of work). - -The Merkle tree protocol is arguably essential to long-term -sustainability. A "full node" in the Bitcoin network, one that stores -and processes the entirety of every block, takes up about 15 GB of disk -space in the Bitcoin network as of April 2014, and is growing by over a -gigabyte per month. Currently, this is viable for some desktop computers -and not phones, and later on in the future only businesses and hobbyists -will be able to participate. A protocol known as "simplified payment -verification" (SPV) allows for another class of nodes to exist, called -"light nodes", which download the block headers, verify the proof of -work on the block headers, and then download only the "branches" -associated with transactions that are relevant to them. This allows -light nodes to determine with a strong guarantee of security what the -status of any Bitcoin transaction, and their current balance, is while -downloading only a very small portion of the entire blockchain. - -Alternative Blockchain Applications -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The idea of taking the underlying blockchain idea and applying it to -other concepts also has a long history. In 2005, Nick Szabo came out -with the concept of "`secure property titles with owner -authority `__", a document -describing how "new advances in replicated database technology" will -allow for a blockchain-based system for storing a registry of who owns -what land, creating an elaborate framework including concepts such as -homesteading, adverse possession and Georgian land tax. However, there -was unfortunately no effective replicated database system available at -the time, and so the protocol was never implemented in practice. After -2009, however, once Bitcoin's decentralized consensus was developed a -number of alternative applications rapidly began to emerge. - -- **Namecoin** - created in 2010, `Namecoin `__ - is best described as a decentralized name registration database. In - decentralized protocols like Tor, Bitcoin and BitMessage, there needs - to be some way of identifying accounts so that other people can - interact with them, but in all existing solutions the only kind of - identifier available is a pseudorandom hash like - ``1LW79wp5ZBqaHW1jL5TCiBCrhQYtHagUWy``. Ideally, one would like to be - able to have an account with a name like "george". However, the - problem is that if one person can create an account named "george" - then someone else can use the same process to register "george" for - themselves as well and impersonate them. The only solution is a - first-to-file paradigm, where the first registerer succeeds and the - second fails - a problem perfectly suited for the Bitcoin consensus - protocol. Namecoin is the oldest, and most successful, implementation - of a name registration system using such an idea. -- **Colored coins** - the purpose of `colored - coins `__ - is to serve as a protocol to allow people to create their own digital - currencies - or, in the important trivial case of a currency with one - unit, digital tokens, on the Bitcoin blockchain. In the colored coins - protocol, one "issues" a new currency by publicly assigning a color - to a specific Bitcoin UTXO, and the protocol recursively defines the - color of other UTXO to be the same as the color of the inputs that - the transaction creating them spent (some special rules apply in the - case of mixed-color inputs). This allows users to maintain wallets - containing only UTXO of a specific color and send them around much - like regular bitcoins, backtracking through the blockchain to - determine the color of any UTXO that they receive. -- **Metacoins** - the idea behind a metacoin is to have a protocol that - lives on top of Bitcoin, using Bitcoin transactions to store metacoin - transactions but having a different state transition function, - ``APPLY'``. Because the metacoin protocol cannot prevent invalid - metacoin transactions from appearing in the Bitcoin blockchain, a - rule is added that if ``APPLY'(S,TX)`` returns an error, the protocol - defaults to ``APPLY'(S,TX) = S``. This provides an easy mechanism for - creating an arbitrary cryptocurrency protocol, potentially with - advanced features that cannot be implemented inside of Bitcoin - itself, but with a very low development cost since the complexities - of mining and networking are already handled by the Bitcoin protocol. - Metacoins have been used to implement some classes of financial - contracts, name registration and decentralized exchange. - -Thus, in general, there are two approaches toward building a consensus -protocol: building an independent network, and building a protocol on -top of Bitcoin. The former approach, while reasonably successful in the -case of applications like Namecoin, is difficult to implement; each -individual implementation needs to bootstrap an independent blockchain, -as well as building and testing all of the necessary state transition -and networking code. Additionally, we predict that the set of -applications for decentralized consensus technology will follow a power -law distribution where the vast majority of applications would be too -small to warrant their own blockchain, and we note that there exist -large classes of decentralized applications, particularly decentralized -autonomous organizations, that need to interact with each other. - -The Bitcoin-based approach, on the other hand, has the flaw that it does -not inherit the simplified payment verification features of Bitcoin. SPV -works for Bitcoin because it can use blockchain depth as a proxy for -validity; at some point, once the ancestors of a transaction go far -enough back, it is safe to say that they were legitimately part of the -state. Blockchain-based meta-protocols, on the other hand, cannot force -the blockchain not to include transactions that are not valid within the -context of their own protocols. Hence, a fully secure SPV meta-protocol -implementation would need to backward scan all the way to the beginning -of the Bitcoin blockchain to determine whether or not certain -transactions are valid. Currently, all "light" implementations of -Bitcoin-based meta-protocols rely on a trusted server to provide the -data, arguably a highly suboptimal result especially when one of the -primary purposes of a cryptocurrency is to eliminate the need for trust. - -Scripting -~~~~~~~~~ - -Even without any extensions, the Bitcoin protocol actually does -facilitate a weak version of a concept of "smart contracts". UTXO in -Bitcoin can be owned not just by a public key, but also by a more -complicated script expressed in a simple stack-based programming -language. In this paradigm, a transaction spending that UTXO must -provide data that satisfies the script. Indeed, even the basic public -key ownership mechanism is implemented via a script: the script takes an -elliptic curve signature as input, verifies it against the transaction -and the address that owns the UTXO, and returns 1 if the verification is -successful and 0 otherwise. Other, more complicated, scripts exist for -various additional use cases. For example, one can construct a script -that requires signatures from two out of a given three private keys to -validate ("multisig"), a setup useful for corporate accounts, secure -savings accounts and some merchant escrow situations. Scripts can also -be used to pay bounties for solutions to computational problems, and one -can even construct a script that says something like "this Bitcoin UTXO -is yours if you can provide an SPV proof that you sent a Dogecoin -transaction of this denomination to me", essentially allowing -decentralized cross-cryptocurrency exchange. - -However, the scripting language as implemented in Bitcoin has several -important limitations: - -- **Lack of Turing-completeness** - that is to say, while there is a - large subset of computation that the Bitcoin scripting language - supports, it does not nearly support everything. The main category - that is missing is loops. This is done to avoid infinite loops during - transaction verification; theoretically it is a surmountable obstacle - for script programmers, since any loop can be simulated by simply - repeating the underlying code many times with an if statement, but it - does lead to scripts that are very space-inefficient. For example, - implementing an alternative elliptic curve signature algorithm would - likely require 256 repeated multiplication rounds all individually - included in the code. -- **Value-blindness** - there is no way for a UTXO script to provide - fine-grained control over the amount that can be withdrawn. For - example, one powerful use case of an oracle contract would be a - hedging contract, where A and B put in $1000 worth of BTC and after - 30 days the script sends $1000 worth of BTC to A and the rest to B. - This would require an oracle to determine the value of 1 BTC in USD, - but even then it is a massive improvement in terms of trust and - infrastructure requirement over the fully centralized solutions that - are available now. However, because UTXO are all-or-nothing, the only - way to achieve this is through the very inefficient hack of having - many UTXO of varying denominations (eg. one UTXO of 2k for every k up - to 30) and having O pick which UTXO to send to A and which to B. -- **Lack of state** - UTXO can either be spent or unspent; there is no - opportunity for multi-stage contracts or scripts which keep any other - internal state beyond that. This makes it hard to make multi-stage - options contracts, decentralized exchange offers or two-stage - cryptographic commitment protocols (necessary for secure - computational bounties). It also means that UTXO can only be used to - build simple, one-off contracts and not more complex "stateful" - contracts such as decentralized organizations, and makes - meta-protocols difficult to implement. Binary state combined with - value-blindness also mean that another important application, - withdrawal limits, is impossible. -- **Blockchain-blindness** - UTXO are blind to blockchain data such as - the nonce, the timestamp and previous block hash. This severely - limits applications in gambling, and several other categories, by - depriving the scripting language of a potentially valuable source of - randomness. - -Thus, we see three approaches to building advanced applications on top -of cryptocurrency: building a new blockchain, using scripting on top of -Bitcoin, and building a meta-protocol on top of Bitcoin. Building a new -blockchain allows for unlimited freedom in building a feature set, but -at the cost of development time, bootstrapping effort and security. -Using scripting is easy to implement and standardize, but is very -limited in its capabilities, and meta-protocols, while easy, suffer from -faults in scalability. With Ethereum, we intend to build an alternative -framework that provides even larger gains in ease of development as well -as even stronger light client properties, while at the same time -allowing applications to share an economic environment and blockchain -security. - -Ethereum --------- - -The intent of Ethereum is to create an alternative protocol for building -decentralized applications, providing a different set of tradeoffs that -we believe will be very useful for a large class of decentralized -applications, with particular emphasis on situations where rapid -development time, security for small and rarely used applications, and -the ability of different applications to very efficiently interact, are -important. Ethereum does this by building what is essentially the -ultimate abstract foundational layer: a blockchain with a built-in -Turing-complete programming language, allowing anyone to write smart -contracts and decentralized applications where they can create their own -arbitrary rules for ownership, transaction formats and state transition -functions. A bare-bones version of Namecoin can be written in two lines -of code, and other protocols like currencies and reputation systems can -be built in under twenty. Smart contracts, cryptographic "boxes" that -contain value and only unlock it if certain conditions are met, can also -be built on top of the platform, with vastly more power than that -offered by Bitcoin scripting because of the added powers of -Turing-completeness, value-awareness, blockchain-awareness and state. - -Ethereum Accounts -~~~~~~~~~~~~~~~~~ - -In Ethereum, the state is made up of objects called "accounts", with -each account having a 20-byte address and state transitions being direct -transfers of value and information between accounts. An Ethereum account -contains four fields: - -- The **nonce**, a counter used to make sure each transaction can only - be processed once -- The account's current **ether balance** -- The account's **contract code**, if present -- The account's **storage** (empty by default) - -"Ether" is the main internal crypto-fuel of Ethereum, and is used to pay -transaction fees. In general, there are two types of accounts: -**externally owned accounts**, controlled by private keys, and -**contract accounts**, controlled by their contract code. An externally -owned account has no code, and one can send messages from an externally -owned account by creating and signing a transaction; in a contract -account, every time the contract account receives a message its code -activates, allowing it to read and write to internal storage and send -other messages or create contracts in turn. - -Note that "contracts" in Ethereum should not be seen as something that -should be "fulfilled" or "complied with"; rather, they are more like -"autonomous agents" that live inside of the Ethereum execution -environment, always executing a specific piece of code when "poked" by a -message or transaction, and having direct control over their own ether -balance and their own key/value store to keep track of persistent -variables. - -Messages and Transactions -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The term "transaction" is used in Ethereum to refer to the signed data -package that stores a message to be sent from an externally owned -account. Transactions contain: - -- The recipient of the message -- A signature identifying the sender -- The amount of ether to transfer from the sender to the recipient -- An optional data field -- A ``STARTGAS`` value, representing the maximum number of - computational steps the transaction execution is allowed to take -- A ``GASPRICE`` value, representing the fee the sender pays per - computational step - -The first three are standard fields expected in any cryptocurrency. The -data field has no function by default, but the virtual machine has an -opcode using which a contract can access the data; as an example use -case, if a contract is functioning as an on-blockchain domain -registration service, then it may wish to interpret the data being -passed to it as containing two "fields", the first field being a domain -to register and the second field being the IP address to register it to. -The contract would read these values from the message data and -appropriately place them in storage. - -The ``STARTGAS`` and ``GASPRICE`` fields are crucial for Ethereum's -anti-denial of service model. In order to prevent accidental or hostile -infinite loops or other computational wastage in code, each transaction -is required to set a limit to how many computational steps of code -execution it can use. The fundamental unit of computation is "gas"; -usually, a computational step costs 1 gas, but some operations cost -higher amounts of gas because they are more computationally expensive, -or increase the amount of data that must be stored as part of the state. -There is also a fee of 5 gas for every byte in the transaction data. The -intent of the fee system is to require an attacker to pay -proportionately for every resource that they consume, including -computation, bandwidth and storage; hence, any transaction that leads to -the network consuming a greater amount of any of these resources must -have a gas fee roughly proportional to the increment. - -Messages -~~~~~~~~ - -Contracts have the ability to send "messages" to other contracts. -Messages are virtual objects that are never serialized and exist only in -the Ethereum execution environment. A message contains: - -- The sender of the message (implicit) -- The recipient of the message -- The amount of ether to transfer alongside the message -- An optional data field -- A ``STARTGAS`` value - -Essentially, a message is like a transaction, except it is produced by a -contract and not an external actor. A message is produced when a -contract currently executing code executes the ``CALL`` opcode, which -produces and executes a message. Like a transaction, a message leads to -the recipient account running its code. Thus, contracts can have -relationships with other contracts in exactly the same way that external -actors can. - -Note that the gas allowance assigned by a transaction or contract -applies to the total gas consumed by that transaction and all -sub-executions. For example, if an external actor A sends a transaction -to B with 1000 gas, and B consumes 600 gas before sending a message to -C, and the internal execution of C consumes 300 gas before returning, -then B can spend another 100 gas before running out of gas. - -Ethereum State Transition Function -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. figure:: http://vitalik.ca/files/ethertransition.png?1 - :alt: ethertransition.png - - ethertransition.png - -The Ethereum state transition function, ``APPLY(S,TX) -> S'`` can be -defined as follows: - -1. Check if the transaction is well-formed (ie. has the right number of - values), the signature is valid, and the nonce matches the nonce in - the sender's account. If not, return an error. -2. Calculate the transaction fee as ``STARTGAS * GASPRICE``, and - determine the sending address from the signature. Subtract the fee - from the sender's account balance and increment the sender's nonce. - If there is not enough balance to spend, return an error. -3. Initialize ``GAS = STARTGAS``, and take off a certain quantity of gas - per byte to pay for the bytes in the transaction. -4. Transfer the transaction value from the sender's account to the - receiving account. If the receiving account does not yet exist, - create it. If the receiving account is a contract, run the contract's - code either to completion or until the execution runs out of gas. -5. If the value transfer failed because the sender did not have enough - money, or the code execution ran out of gas, revert all state changes - except the payment of the fees, and add the fees to the miner's - account. -6. Otherwise, refund the fees for all remaining gas to the sender, and - send the fees paid for gas consumed to the miner. - -For example, suppose that the contract's code is: - -:: - - if !self.storage[calldataload(0)]: - self.storage[calldataload(0)] = calldataload(32) - -Note that in reality the contract code is written in the low-level EVM -code; this example is written in Serpent, one of our high-level -languages, for clarity, and can be compiled down to EVM code. Suppose -that the contract's storage starts off empty, and a transaction is sent -with 10 ether value, 2000 gas, 0.001 ether gasprice, and 64 bytes of -data, with bytes 0-31 representing the number ``2`` and bytes 32-63 -representing the string ``CHARLIE``. The process for the state -transition function in this case is as follows: - -1. Check that the transaction is valid and well formed. -2. Check that the transaction sender has at least 2000 \* 0.001 = 2 - ether. If it is, then subtract 2 ether from the sender's account. -3. Initialize gas = 2000; assuming the transaction is 170 bytes long and - the byte-fee is 5, subtract 850 so that there is 1150 gas left. -4. Subtract 10 more ether from the sender's account, and add it to the - contract's account. -5. Run the code. In this case, this is simple: it checks if the - contract's storage at index ``2`` is used, notices that it is not, - and so it sets the storage at index ``2`` to the value ``CHARLIE``. - Suppose this takes 187 gas, so the remaining amount of gas is 1150 - - 187 = 963 -6. Add 963 \* 0.001 = 0.963 ether back to the sender's account, and - return the resulting state. - -If there was no contract at the receiving end of the transaction, then -the total transaction fee would simply be equal to the provided -``GASPRICE`` multiplied by the length of the transaction in bytes, and -the data sent alongside the transaction would be irrelevant. - -Note that messages work equivalently to transactions in terms of -reverts: if a message execution runs out of gas, then that message's -execution, and all other executions triggered by that execution, revert, -but parent executions do not need to revert. This means that it is -"safe" for a contract to call another contract, as if A calls B with G -gas then A's execution is guaranteed to lose at most G gas. Finally, -note that there is an opcode, ``CREATE``, that creates a contract; its -execution mechanics are generally similar to ``CALL``, with the -exception that the output of the execution determines the code of a -newly created contract. - -Code Execution -~~~~~~~~~~~~~~ - -The code in Ethereum contracts is written in a low-level, stack-based -bytecode language, referred to as "Ethereum virtual machine code" or -"EVM code". The code consists of a series of bytes, where each byte -represents an operation. In general, code execution is an infinite loop -that consists of repeatedly carrying out the operation at the current -program counter (which begins at zero) and then incrementing the program -counter by one, until the end of the code is reached or an error or -``STOP`` or ``RETURN`` instruction is detected. The operations have -access to three types of space in which to store data: - -- The **stack**, a last-in-first-out container to which values can be - pushed and popped -- **Memory**, an infinitely expandable byte array -- The contract's long-term **storage**, a key/value store. Unlike stack - and memory, which reset after computation ends, storage persists for - the long term. - -The code can also access the value, sender and data of the incoming -message, as well as block header data, and the code can also return a -byte array of data as an output. - -The formal execution model of EVM code is surprisingly simple. While the -Ethereum virtual machine is running, its full computational state can be -defined by the tuple -``(block_state, transaction, message, code, memory, stack, pc, gas)``, -where ``block_state`` is the global state containing all accounts and -includes balances and storage. At the start of every round of execution, -the current instruction is found by taking the ``pc``\ th byte of -``code`` (or 0 if ``pc >= len(code)``), and each instruction has its own -definition in terms of how it affects the tuple. For example, ``ADD`` -pops two items off the stack and pushes their sum, reduces ``gas`` by 1 -and increments ``pc`` by 1, and ``SSTORE`` pushes the top two items off -the stack and inserts the second item into the contract's storage at the -index specified by the first item. Although there are many ways to -optimize Ethereum virtual machine execution via just-in-time -compilation, a basic implementation of Ethereum can be done in a few -hundred lines of code. - -Blockchain and Mining -~~~~~~~~~~~~~~~~~~~~~ - -.. figure:: http://vitalik.ca/files/apply_block_diagram.png - :alt: apply\_block\_diagram.png - - apply\_block\_diagram.png - -The Ethereum blockchain is in many ways similar to the Bitcoin -blockchain, although it does have some differences. The main difference -between Ethereum and Bitcoin with regard to the blockchain architecture -is that, unlike Bitcoin, Ethereum blocks contain a copy of both the -transaction list and the most recent state. Aside from that, two other -values, the block number and the difficulty, are also stored in the -block. The basic block validation algorithm in Ethereum is as follows: - -1. Check if the previous block referenced exists and is valid. -2. Check that the timestamp of the block is greater than that of the - referenced previous block and less than 15 minutes into the future -3. Check that the block number, difficulty, transaction root, uncle root - and gas limit (various low-level Ethereum-specific concepts) are - valid. -4. Check that the proof of work on the block is valid. -5. Let ``S[0]`` be the state at the end of the previous block. -6. Let ``TX`` be the block's transaction list, with ``n`` transactions. - For all ``i`` in ``0...n-1``, set ``S[i+1] = APPLY(S[i],TX[i])``. If - any applications returns an error, or if the total gas consumed in - the block up until this point exceeds the ``GASLIMIT``, return an - error. -7. Let ``S_FINAL`` be ``S[n]``, but adding the block reward paid to the - miner. -8. Check if the Merkle tree root of the state ``S_FINAL`` is equal to - the final state root provided in the block header. If it is, the - block is valid; otherwise, it is not valid. - -The approach may seem highly inefficient at first glance, because it -needs to store the entire state with each block, but in reality -efficiency should be comparable to that of Bitcoin. The reason is that -the state is stored in the tree structure, and after every block only a -small part of the tree needs to be changed. Thus, in general, between -two adjacent blocks the vast majority of the tree should be the same, -and therefore the data can be stored once and referenced twice using -pointers (ie. hashes of subtrees). A special kind of tree known as a -"Patricia tree" is used to accomplish this, including a modification to -the Merkle tree concept that allows for nodes to be inserted and -deleted, and not just changed, efficiently. Additionally, because all of -the state information is part of the last block, there is no need to -store the entire blockchain history - a strategy which, if it could be -applied to Bitcoin, can be calculated to provide 5-20x savings in space. - -A commonly asked question is "where" contract code is executed, in terms -of physical hardware. This has a simple answer: the process of executing -contract code is part of the definition of the state transition -function, which is part of the block validation algorithm, so if a -transaction is added into block ``B`` the code execution spawned by that -transaction will be executed by all nodes, now and in the future, that -download and validate block ``B``. - -Applications ------------- - -In general, there are three types of applications on top of Ethereum. -The first category is financial applications, providing users with more -powerful ways of managing and entering into contracts using their money. -This includes sub-currencies, financial derivatives, hedging contracts, -savings wallets, wills, and ultimately even some classes of full-scale -employment contracts. The second category is semi-financial -applications, where money is involved but there is also a heavy -non-monetary side to what is being done; a perfect example is -self-enforcing bounties for solutions to computational problems. -Finally, there are applications such as online voting and decentralized -governance that are not financial at all. - -Token Systems -~~~~~~~~~~~~~ - -On-blockchain token systems have many applications ranging from -sub-currencies representing assets such as USD or gold to company -stocks, individual tokens representing smart property, secure -unforgeable coupons, and even token systems with no ties to conventional -value at all, used as point systems for incentivization. Token systems -are surprisingly easy to implement in Ethereum. The key point to -understand is that all a currency, or token system, fundamentally is a -database with one operation: subtract X units from A and give X units to -B, with the proviso that (i) A had at least X units before the -transaction and (2) the transaction is approved by A. All that it takes -to implement a token system is to implement this logic into a contract. - -The basic code for implementing a token system in Serpent looks as -follows: - -:: - - def send(to, value): - if self.storage[msg.sender] >= value: - self.storage[msg.sender] = self.storage[msg.sender] - value - self.storage[to] = self.storage[to] + value - -This is essentially a literal implementation of the "banking system" -state transition function described further above in this document. A -few extra lines of code need to be added to provide for the initial step -of distributing the currency units in the first place and a few other -edge cases, and ideally a function would be added to let other contracts -query for the balance of an address. But that's all there is to it. -Theoretically, Ethereum-based token systems acting as sub-currencies can -potentially include another important feature that on-chain -Bitcoin-based meta-currencies lack: the ability to pay transaction fees -directly in that currency. The way this would be implemented is that the -contract would maintain an ether balance with which it would refund -ether used to pay fees to the sender, and it would refill this balance -by collecting the internal currency units that it takes in fees and -reselling them in a constant running auction. Users would thus need to -"activate" their accounts with ether, but once the ether is there it -would be reusable because the contract would refund it each time. - -Financial derivatives and Stable-Value Currencies -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Financial derivatives are the most common application of a "smart -contract", and one of the simplest to implement in code. The main -challenge in implementing financial contracts is that the majority of -them require reference to an external price ticker; for example, a very -desirable application is a smart contract that hedges against the -volatility of ether (or another cryptocurrency) with respect to the US -dollar, but doing this requires the contract to know what the value of -ETH/USD is. The simplest way to do this is through a "data feed" -contract maintained by a specific party (eg. NASDAQ) designed so that -that party has the ability to update the contract as needed, and -providing an interface that allows other contracts to send a message to -that contract and get back a response that provides the price. - -Given that critical ingredient, the hedging contract would look as -follows: - -1. Wait for party A to input 1000 ether. -2. Wait for party B to input 1000 ether. -3. Record the USD value of 1000 ether, calculated by querying the data - feed contract, in storage, say this is $x. -4. After 30 days, allow A or B to "reactivate" the contract in order to - send $x worth of ether (calculated by querying the data feed contract - again to get the new price) to A and the rest to B. - -Such a contract would have significant potential in crypto-commerce. One -of the main problems cited about cryptocurrency is the fact that it's -volatile; although many users and merchants may want the security and -convenience of dealing with cryptographic assets, they many not wish to -face that prospect of losing 23% of the value of their funds in a single -day. Up until now, the most commonly proposed solution has been -issuer-backed assets; the idea is that an issuer creates a sub-currency -in which they have the right to issue and revoke units, and provide one -unit of the currency to anyone who provides them (offline) with one unit -of a specified underlying asset (eg. gold, USD). The issuer then -promises to provide one unit of the underlying asset to anyone who sends -back one unit of the crypto-asset. This mechanism allows any -non-cryptographic asset to be "uplifted" into a cryptographic asset, -provided that the issuer can be trusted. - -In practice, however, issuers are not always trustworthy, and in some -cases the banking infrastructure is too weak, or too hostile, for such -services to exist. Financial derivatives provide an alternative. Here, -instead of a single issuer providing the funds to back up an asset, a -decentralized market of speculators, betting that the price of a -cryptographic reference asset (eg. ETH) will go up, plays that role. -Unlike issuers, speculators have no option to default on their side of -the bargain because the hedging contract holds their funds in escrow. -Note that this approach is not fully decentralized, because a trusted -source is still needed to provide the price ticker, although arguably -even still this is a massive improvement in terms of reducing -infrastructure requirements (unlike being an issuer, issuing a price -feed requires no licenses and can likely be categorized as free speech) -and reducing the potential for fraud. - -Identity and Reputation Systems -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The earliest alternative cryptocurrency of all, -`Namecoin `__, attempted to use a Bitcoin-like -blockchain to provide a name registration system, where users can -register their names in a public database alongside other data. The -major cited use case is for a -`DNS `__ system, -mapping domain names like "bitcoin.org" (or, in Namecoin's case, -"bitcoin.bit") to an IP address. Other use cases include email -authentication and potentially more advanced reputation systems. Here is -the basic contract to provide a Namecoin-like name registration system -on Ethereum: - -:: - - def register(name, value): - if !self.storage[name]: - self.storage[name] = value - -The contract is very simple; all it is is a database inside the Ethereum -network that can be added to, but not modified or removed from. Anyone -can register a name with some value, and that registration then sticks -forever. A more sophisticated name registration contract will also have -a "function clause" allowing other contracts to query it, as well as a -mechanism for the "owner" (ie. the first registerer) of a name to change -the data or transfer ownership. One can even add reputation and -web-of-trust functionality on top. - -Decentralized File Storage -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Over the past few years, there have emerged a number of popular online -file storage startups, the most prominent being Dropbox, seeking to -allow users to upload a backup of their hard drive and have the service -store the backup and allow the user to access it in exchange for a -monthly fee. However, at this point the file storage market is at times -relatively inefficient; a cursory look at various `existing -solutions `__ -shows that, particularly at the "uncanny valley" 20-200 GB level at -which neither free quotas nor enterprise-level discounts kick in, -monthly prices for mainstream file storage costs are such that you are -paying for more than the cost of the entire hard drive in a single -month. Ethereum contracts can allow for the development of a -decentralized file storage ecosystem, where individual users can earn -small quantities of money by renting out their own hard drives and -unused space can be used to further drive down the costs of file -storage. - -The key underpinning piece of such a device would be what we have termed -the "decentralized Dropbox contract". This contract works as follows. -First, one splits the desired data up into blocks, encrypting each block -for privacy, and builds a Merkle tree out of it. One then makes a -contract with the rule that, every N blocks, the contract would pick a -random index in the Merkle tree (using the previous block hash, -accessible from contract code, as a source of randomness), and give X -ether to the first entity to supply a transaction with a simplified -payment verification-like proof of ownership of the block at that -particular index in the tree. When a user wants to re-download their -file, they can use a micropayment channel protocol (eg. pay 1 szabo per -32 kilobytes) to recover the file; the most fee-efficient approach is -for the payer not to publish the transaction until the end, instead -replacing the transaction with a slightly more lucrative one with the -same nonce after every 32 kilobytes. - -An important feature of the protocol is that, although it may seem like -one is trusting many random nodes not to decide to forget the file, one -can reduce that risk down to near-zero by splitting the file into many -pieces via secret sharing, and watching the contracts to see each piece -is still in some node's possession. If a contract is still paying out -money, that provides a cryptographic proof that someone out there is -still storing the file. - -Decentralized Autonomous Organizations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The general concept of a "decentralized autonomous organization" is that -of a virtual entity that has a certain set of members or shareholders -which, perhaps with a 67% majority, have the right to spend the entity's -funds and modify its code. The members would collectively decide on how -the organization should allocate its funds. Methods for allocating a -DAO's funds could range from bounties, salaries to even more exotic -mechanisms such as an internal currency to reward work. This essentially -replicates the legal trappings of a traditional company or nonprofit but -using only cryptographic blockchain technology for enforcement. So far -much of the talk around DAOs has been around the "capitalist" model of a -"decentralized autonomous corporation" (DAC) with dividend-receiving -shareholders and tradable shares; an alternative, perhaps described as a -"decentralized autonomous community", would have all members have an -equal share in the decision making and require 67% of existing members -to agree to add or remove a member. The requirement that one person can -only have one membership would then need to be enforced collectively by -the group. - -A general outline for how to code a DAO is as follows. The simplest -design is simply a piece of self-modifying code that changes if two -thirds of members agree on a change. Although code is theoretically -immutable, one can easily get around this and have de-facto mutability -by having chunks of the code in separate contracts, and having the -address of which contracts to call stored in the modifiable storage. In -a simple implementation of such a DAO contract, there would be three -transaction types, distinquished by the data provided in the -transaction: - -- ``[0,i,K,V]`` to register a proposal with index ``i`` to change the - address at storage index ``K`` to value ``V`` -- ``[0,i]`` to register a vote in favor of proposal ``i`` -- ``[2,i]`` to finalize proposal ``i`` if enough votes have been made - -The contract would then have clauses for each of these. It would -maintain a record of all open storage changes, along with a list of who -voted for them. It would also have a list of all members. When any -storage change gets to two thirds of members voting for it, a finalizing -transaction could execute the change. A more sophisticated skeleton -would also have built-in voting ability for features like sending a -transaction, adding members and removing members, and may even provide -for `Liquid -Democracy `__-style -vote delegation (ie. anyone can assign someone to vote for them, and -assignment is transitive so if A assigns B and B assigns C then C -determines A's vote). This design would allow the DAO to grow -organically as a decentralized community, allowing people to eventually -delegate the task of filtering out who is a member to specialists, -although unlike in the "current system" specialists can easily pop in -and out of existence over time as individual community members change -their alignments. - -An alternative model is for a decentralized corporation, where any -account can have zero or more shares, and two thirds of the shares are -required to make a decision. A complete skeleton would involve asset -management functionality, the ability to make an offer to buy or sell -shares, and the ability to accept offers (preferably with an -order-matching mechanism inside the contract). Delegation would also -exist Liquid Democracy-style, generalizing the concept of a "board of -directors". - -Further Applications -~~~~~~~~~~~~~~~~~~~~ - -**1. Savings wallets**. Suppose that Alice wants to keep her funds safe, -but is worried that she will lose or someone will hack her private key. -She puts ether into a contract with Bob, a bank, as follows: - -- Alice alone can withdraw a maximum of 1% of the funds per day. -- Bob alone can withdraw a maximum of 1% of the funds per day, but - Alice has the ability to make a transaction with her key shutting off - this ability. -- Alice and Bob together can withdraw anything. - -Normally, 1% per day is enough for Alice, and if Alice wants to withdraw -more she can contact Bob for help. If Alice's key gets hacked, she runs -to Bob to move the funds to a new contract. If she loses her key, Bob -will get the funds out eventually. If Bob turns out to be malicious, -then she can turn off his ability to withdraw. - -**2. Crop insurance**. One can easily make a financial derivatives -contract but using a data feed of the weather instead of any price -index. If a farmer in Iowa purchases a derivative that pays out -inversely based on the precipitation in Iowa, then if there is a -drought, the farmer will automatically receive money and if there is -enough rain the farmer will be happy because their crops would do well. -This can be expanded to natural disaster insurance generally. - -**3. A decentralized data feed**. For financial contracts for -difference, it may actually be possible to decentralize the data feed -via a protocol called -"`SchellingCoin `__". -SchellingCoin basically works as follows: N parties all put into the -system the value of a given datum (eg. the ETH/USD price), the values -are sorted, and everyone between the 25th and 75th percentile gets one -token as a reward. Everyone has the incentive to provide the answer that -everyone else will provide, and the only value that a large number of -players can realistically agree on is the obvious default: the truth. -This creates a decentralized protocol that can theoretically provide any -number of values, including the ETH/USD price, the temperature in Berlin -or even the result of a particular hard computation. - -**4. Smart multisignature escrow**. Bitcoin allows multisignature -transaction contracts where, for example, three out of a given five keys -can spend the funds. Ethereum allows for more granularity; for example, -four out of five can spend everything, three out of five can spend up to -10% per day, and two out of five can spend up to 0.5% per day. -Additionally, Ethereum multisig is asynchronous - two parties can -register their signatures on the blockchain at different times and the -last signature will automatically send the transaction. - -**5. Cloud computing**. The EVM technology can also be used to create a -verifiable computing environment, allowing users to ask others to carry -out computations and then optionally ask for proofs that computations at -certain randomly selected checkpoints were done correctly. This allows -for the creation of a cloud computing market where any user can -participate with their desktop, laptop or specialized server, and -spot-checking together with security deposits can be used to ensure that -the system is trustworthy (ie. nodes cannot profitably cheat). Although -such a system may not be suitable for all tasks; tasks that require a -high level of inter-process communication, for example, cannot easily be -done on a large cloud of nodes. Other tasks, however, are much easier to -parallelize; projects like SETI@home, folding@home and genetic -algorithms can easily be implemented on top of such a platform. - -**6. Peer-to-peer gambling**. Any number of peer-to-peer gambling -protocols, such as Frank Stajano and Richard Clayton's -`Cyberdice `__, -can be implemented on the Ethereum blockchain. The simplest gambling -protocol is actually simply a contract for difference on the next block -hash, and more advanced protocols can be built up from there, creating -gambling services with near-zero fees that have no ability to cheat. - -**7. Prediction markets**. Provided an oracle or SchellingCoin, -prediction markets are also easy to implement, and prediction markets -together with SchellingCoin may prove to be the first mainstream -application of `futarchy `__ as a -governance protocol for decentralized organizations. - -**8. On-chain decentralized marketplaces**, using the identity and -reputation system as a base. - -Miscellanea And Concerns ------------------------- - -Modified GHOST Implementation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The "Greedy Heaviest Observed Subtree" (GHOST) protocol is an innovation -first introduced by Yonatan Sompolinsky and Aviv Zohar in `December -2013 `__. -The motivation behind GHOST is that blockchains with fast confirmation -times currently suffer from reduced security due to a high stale rate - -because blocks take a certain time to propagate through the network, if -miner A mines a block and then miner B happens to mine another block -before miner A's block propagates to B, miner B's block will end up -wasted and will not contribute to network security. Furthermore, there -is a centralization issue: if miner A is a mining pool with 30% -hashpower and B has 10% hashpower, A will have a risk of producing a -stale block 70% of the time (since the other 30% of the time A produced -the last block and so will get mining data immediately) whereas B will -have a risk of producing a stale block 90% of the time. Thus, if the -block interval is short enough for the stale rate to be high, A will be -substantially more efficient simply by virtue of its size. With these -two effects combined, blockchains which produce blocks quickly are very -likely to lead to one mining pool having a large enough percentage of -the network hashpower to have de facto control over the mining process. - -As described by Sompolinsky and Zohar, GHOST solves the first issue of -network security loss by including stale blocks in the calculation of -which chain is the "longest"; that is to say, not just the parent and -further ancestors of a block, but also the stale descendants of the -block's ancestor (in Ethereum jargon, "uncles") are added to the -calculation of which block has the largest total proof of work backing -it. To solve the second issue of centralization bias, we go beyond the -protocol described by Sompolinsky and Zohar, and also provide block -rewards to stales: a stale block receives 87.5% of its base reward, and -the nephew that includes the stale block receives the remaining 12.5%. -Transaction fees, however, are not awarded to uncles. - -Ethereum implements a simplified version of GHOST which only goes down -seven levels. Specifically, it is defined as follows: - -- A block must specify a parent, and it must specify 0 or more uncles -- An uncle included in block B must have the following properties: -- It must be a direct child of the kth generation ancestor of B, where - 2 <= k <= 7. -- It cannot be an ancestor of B -- An uncle must be a valid block header, but does not need to be a - previously verified or even valid block -- An uncle must be different from all uncles included in previous - blocks and all other uncles included in the same block - (non-double-inclusion) -- For every uncle U in block B, the miner of B gets an additional - 3.125% added to its coinbase reward and the miner of U gets 93.75% of - a standard coinbase reward. - -This limited version of GHOST, with uncles includable only up to 7 -generations, was used for two reasons. First, unlimited GHOST would -include too many complications into the calculation of which uncles for -a given block are valid. Second, unlimited GHOST with compensation as -used in Ethereum removes the incentive for a miner to mine on the main -chain and not the chain of a public attacker. - -Fees -~~~~ - -Because every transaction published into the blockchain imposes on the -network the cost of needing to download and verify it, there is a need -for some regulatory mechanism, typically involving transaction fees, to -prevent abuse. The default approach, used in Bitcoin, is to have purely -voluntary fees, relying on miners to act as the gatekeepers and set -dynamic minimums. This approach has been received very favorably in the -Bitcoin community particularly because it is "market-based", allowing -supply and demand between miners and transaction senders determine the -price. The problem with this line of reasoning is, however, that -transaction processing is not a market; although it is intuitively -attractive to construe transaction processing as a service that the -miner is offering to the sender, in reality every transaction that a -miner includes will need to be processed by every node in the network, -so the vast majority of the cost of transaction processing is borne by -third parties and not the miner that is making the decision of whether -or not to include it. Hence, tragedy-of-the-commons problems are very -likely to occur. - -However, as it turns out this flaw in the market-based mechanism, when -given a particular inaccurate simplifying assumption, magically cancels -itself out. The argument is as follows. Suppose that: - -1. A transaction leads to ``k`` operations, offering the reward ``kR`` - to any miner that includes it where ``R`` is set by the sender and - ``k`` and ``R`` are (roughly) visible to the miner beforehand. -2. An operation has a processing cost of ``C`` to any node (ie. all - nodes have equal efficiency) -3. There are ``N`` mining nodes, each with exactly equal processing - power (ie. ``1/N`` of total) -4. No non-mining full nodes exist. - -A miner would be willing to process a transaction if the expected reward -is greater than the cost. Thus, the expected reward is ``kR/N`` since -the miner has a ``1/N`` chance of processing the next block, and the -processing cost for the miner is simply ``kC``. Hence, miners will -include transactions where ``kR/N > kC``, or ``R > NC``. Note that ``R`` -is the per-operation fee provided by the sender, and is thus a lower -bound on the benefit that the sender derives from the transaction, and -``NC`` is the cost to the entire network together of processing an -operation. Hence, miners have the incentive to include only those -transactions for which the total utilitarian benefit exceeds the cost. - -However, there are several important deviations from those assumptions -in reality: - -1. The miner does pay a higher cost to process the transaction than the - other verifying nodes, since the extra verification time delays block - propagation and thus increases the chance the block will become a - stale. -2. There do exist nonmining full nodes. -3. The mining power distribution may end up radically inegalitarian in - practice. -4. Speculators, political enemies and crazies whose utility function - includes causing harm to the network do exist, and they can cleverly - set up contracts where their cost is much lower than the cost paid by - other verifying nodes. - -(1) provides a tendency for the miner to include fewer transactions, and - (2) increases ``NC``; hence, these two effects at least partially - cancel each other out. (3) and (4) are the major issue; to solve - them we simply institute a floating cap: no block can have more - operations than ``BLK_LIMIT_FACTOR`` times the long-term exponential - moving average. Specifically: - - blk.oplimit = floor((blk.parent.oplimit \* (EMAFACTOR - 1) + - floor(parent.opcount \* BLK\_LIMIT\_FACTOR)) / EMA\_FACTOR) - -``BLK_LIMIT_FACTOR`` and ``EMA_FACTOR`` are constants that will be set -to 65536 and 1.5 for the time being, but will likely be changed after -further analysis. - -There is another factor disincentivizing large block sizes in Bitcoin: -blocks that are large will take longer to propagate, and thus have a -higher probability of becoming stales. In Ethereum, highly gas-consuming -blocks can also take longer to propagate both because they are -physically larger and because they take longer to process the -transaction state transitions to validate. This delay disincentive is a -significant consideration in Bitcoin, but less so in Ethereum because of -the GHOST protocol; hence, relying on regulated block limits provides a -more stable baseline. - -Computation And Turing-Completeness -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -An important note is that the Ethereum virtual machine is -Turing-complete; this means that EVM code can encode any computation -that can be conceivably carried out, including infinite loops. EVM code -allows looping in two ways. First, there is a ``JUMP`` instruction that -allows the program to jump back to a previous spot in the code, and a -``JUMPI`` instruction to do conditional jumping, allowing for statements -like ``while x < 27: x = x * 2``. Second, contracts can call other -contracts, potentially allowing for looping through recursion. This -naturally leads to a problem: can malicious users essentially shut -miners and full nodes down by forcing them to enter into an infinite -loop? The issue arises because of a problem in computer science known as -the halting problem: there is no way to tell, in the general case, -whether or not a given program will ever halt. - -As described in the state transition section, our solution works by -requiring a transaction to set a maximum number of computational steps -that it is allowed to take, and if execution takes longer computation is -reverted but fees are still paid. Messages work in the same way. To show -the motivation behind our solution, consider the following examples: - -- An attacker creates a contract which runs an infinite loop, and then - sends a transaction activating that loop to the miner. The miner will - process the transaction, running the infinite loop, and wait for it - to run out of gas. Even though the execution runs out of gas and - stops halfway through, the transaction is still valid and the miner - still claims the fee from the attacker for each computational step. -- An attacker creates a very long infinite loop with the intent of - forcing the miner to keep computing for such a long time that by the - time computation finishes a few more blocks will have come out and it - will not be possible for the miner to include the transaction to - claim the fee. However, the attacker will be required to submit a - value for ``STARTGAS`` limiting the number of computational steps - that execution can take, so the miner will know ahead of time that - the computation will take an excessively large number of steps. -- An attacker sees a contract with code of some form like - ``send(A,contract.storage[A]); contract.storage[A] = 0``, and sends a - transaction with just enough gas to run the first step but not the - second (ie. making a withdrawal but not letting the balance go down). - The contract author does not need to worry about protecting against - such attacks, because if execution stops halfway through the changes - get reverted. -- A financial contract works by taking the median of nine proprietary - data feeds in order to minimize risk. An attacker takes over one of - the data feeds, which is designed to be modifiable via the - variable-address-call mechanism described in the section on DAOs, and - converts it to run an infinite loop, thereby attempting to force any - attempts to claim funds from the financial contract to run out of - gas. However, the financial contract can set a gas limit on the - message to prevent this problem. - -The alternative to Turing-completeness is Turing-incompleteness, where -``JUMP`` and ``JUMPI`` do not exist and only one copy of each contract -is allowed to exist in the call stack at any given time. With this -system, the fee system described and the uncertainties around the -effectiveness of our solution might not be necessary, as the cost of -executing a contract would be bounded above by its size. Additionally, -Turing-incompleteness is not even that big a limitation; out of all the -contract examples we have conceived internally, so far only one required -a loop, and even that loop could be removed by making 26 repetitions of -a one-line piece of code. Given the serious implications of -Turing-completeness, and the limited benefit, why not simply have a -Turing-incomplete language? In reality, however, Turing-incompleteness -is far from a neat solution to the problem. To see why, consider the -following contracts: - -:: - - C0: call(C1); call(C1); - C1: call(C2); call(C2); - C2: call(C3); call(C3); - ... - C49: call(C50); call(C50); - C50: (run one step of a program and record the change in storage) - -Now, send a transaction to A. Thus, in 51 transactions, we have a -contract that takes up 250 computational steps. Miners could try to -detect such logic bombs ahead of time by maintaining a value alongside -each contract specifying the maximum number of computational steps that -it can take, and calculating this for contracts calling other contracts -recursively, but that would require miners to forbid contracts that -create other contracts (since the creation and execution of all 26 -contracts above could easily be rolled into a single contract). Another -problematic point is that the address field of a message is a variable, -so in general it may not even be possible to tell which other contracts -a given contract will call ahead of time. Hence, all in all, we have a -surprising conclusion: Turing-completeness is surprisingly easy to -manage, and the lack of Turing-completeness is equally surprisingly -difficult to manage unless the exact same controls are in place - but in -that case why not just let the protocol be Turing-complete? - -Currency And Issuance -~~~~~~~~~~~~~~~~~~~~~ - -The Ethereum network includes its own built-in currency, ether, which -serves the dual purpose of providing a primary liquidity layer to allow -for efficient exchange between various types of digital assets and, more -importantly, of providing a mechanism for paying transaction fees. For -convenience and to avoid future argument (see the current -mBTC/uBTC/satoshi debate in Bitcoin), the denominations will be -pre-labelled: - -- 1: wei -- 1012: szabo -- 1015: finney -- 1018: ether - -This should be taken as an expanded version of the concept of "dollars" -and "cents" or "BTC" and "satoshi". In the near future, we expect -"ether" to be used for ordinary transactions, "finney" for -microtransactions and "szabo" and "wei" for technical discussions around -fees and protocol implementation; the remaining denominations may become -useful later and should not be included in clients at this point. - -The issuance model will be as follows: - -- Ether will be released in a currency sale at the price of 1000-2000 - ether per BTC, a mechanism intended to fund the Ethereum organization - and pay for development that has been used with success by other - platforms such as Mastercoin and NXT. Earlier buyers will benefit - from larger discounts. The BTC received from the sale will be used - entirely to pay salaries and bounties to developers and invested into - various for-profit and non-profit projects in the Ethereum and - cryptocurrency ecosystem. -- 0.099x the total amount sold (60102216 ETH) will be allocated to the - organization to compensate early contributors and pay ETH-denominated - expenses before the genesis block. -- 0.099x the total amount sold will be maintained as a long-term - reserve. -- 0.26x the total amount sold will be allocated to miners per year - forever after that point. - -+--------------------------+-------------+----------------+-----------------+ -| Group | At launch | After 1 year | After 5 years | -+==========================+=============+================+=================+ -| Currency units | 1.198X | 1.458X | 2.498X | -+--------------------------+-------------+----------------+-----------------+ -| Purchasers | 83.5% | 68.6% | 40.0% | -+--------------------------+-------------+----------------+-----------------+ -| Reserve spent pre-sale | 8.26% | 6.79% | 3.96% | -+--------------------------+-------------+----------------+-----------------+ -| Reserve used post-sale | 8.26% | 6.79% | 3.96% | -+--------------------------+-------------+----------------+-----------------+ -| Miners | 0% | 17.8% | 52.0% | -+--------------------------+-------------+----------------+-----------------+ - -**Long-Term Supply Growth Rate (percent)** - -.. figure:: https://www.ethereum.org/gh_wiki/inflation.svg - :alt: SPV in bitcoin - - SPV in bitcoin - -*Despite the linear currency issuance, just like with Bitcoin over time -the supply growth rate nevertheless tends to zero* - -The two main choices in the above model are (1) the existence and size -of an endowment pool, and (2) the existence of a permanently growing -linear supply, as opposed to a capped supply as in Bitcoin. The -justification of the endowment pool is as follows. If the endowment pool -did not exist, and the linear issuance reduced to 0.217x to provide the -same inflation rate, then the total quantity of ether would be 16.5% -less and so each unit would be 19.8% more valuable. Hence, in the -equilibrium 19.8% more ether would be purchased in the sale, so each -unit would once again be exactly as valuable as before. The organization -would also then have 1.198x as much BTC, which can be considered to be -split into two slices: the original BTC, and the additional 0.198x. -Hence, this situation is *exactly equivalent* to the endowment, but with -one important difference: the organization holds purely BTC, and so is -not incentivized to support the value of the ether unit. - -The permanent linear supply growth model reduces the risk of what some -see as excessive wealth concentration in Bitcoin, and gives individuals -living in present and future eras a fair chance to acquire currency -units, while at the same time retaining a strong incentive to obtain and -hold ether because the "supply growth rate" as a percentage still tends -to zero over time. We also theorize that because coins are always lost -over time due to carelessness, death, etc, and coin loss can be modeled -as a percentage of the total supply per year, that the total currency -supply in circulation will in fact eventually stabilize at a value equal -to the annual issuance divided by the loss rate (eg. at a loss rate of -1%, once the supply reaches 26X then 0.26X will be mined and 0.26X lost -every year, creating an equilibrium). - -Note that in the future, it is likely that Ethereum will switch to a -proof-of-stake model for security, reducing the issuance requirement to -somewhere between zero and 0.05X per year. In the event that the -Ethereum organization loses funding or for any other reason disappears, -we leave open a "social contract": anyone has the right to create a -future candidate version of Ethereum, with the only condition being that -the quantity of ether must be at most equal to -``60102216 * (1.198 + 0.26 * n)`` where ``n`` is the number of years -after the genesis block. Creators are free to crowd-sell or otherwise -assign some or all of the difference between the PoS-driven supply -expansion and the maximum allowable supply expansion to pay for -development. Candidate upgrades that do not comply with the social -contract may justifiably be forked into compliant versions. - -Mining Centralization -~~~~~~~~~~~~~~~~~~~~~ - -The Bitcoin mining algorithm works by having miners compute SHA256 on -slightly modified versions of the block header millions of times over -and over again, until eventually one node comes up with a version whose -hash is less than the target (currently around 2192). However, this -mining algorithm is vulnerable to two forms of centralization. First, -the mining ecosystem has come to be dominated by ASICs -(application-specific integrated circuits), computer chips designed for, -and therefore thousands of times more efficient at, the specific task of -Bitcoin mining. This means that Bitcoin mining is no longer a highly -decentralized and egalitarian pursuit, requiring millions of dollars of -capital to effectively participate in. Second, most Bitcoin miners do -not actually perform block validation locally; instead, they rely on a -centralized mining pool to provide the block headers. This problem is -arguably worse: as of the time of this writing, the top three mining -pools indirectly control roughly 50% of processing power in the Bitcoin -network, although this is mitigated by the fact that miners can switch -to other mining pools if a pool or coalition attempts a 51% attack. - -The current intent at Ethereum is to use a mining algorithm where miners -are required to fetch random data from the state, compute some randomly -selected transactions from the last N blocks in the blockchain, and -return the hash of the result. This has two important benefits. First, -Ethereum contracts can include any kind of computation, so an Ethereum -ASIC would essentially be an ASIC for general computation - ie. a better -CPU. Second, mining requires access to the entire blockchain, forcing -miners to store the entire blockchain and at least be capable of -verifying every transaction. This removes the need for centralized -mining pools; although mining pools can still serve the legitimate role -of evening out the randomness of reward distribution, this function can -be served equally well by peer-to-peer pools with no central control. - -This model is untested, and there may be difficulties along the way in -avoiding certain clever optimizations when using contract execution as a -mining algorithm. However, one notably interesting feature of this -algorithm is that it allows anyone to "poison the well", by introducing -a large number of contracts into the blockchain specifically designed to -stymie certain ASICs. The economic incentives exist for ASIC -manufacturers to use such a trick to attack each other. Thus, the -solution that we are developing is ultimately an adaptive economic human -solution rather than purely a technical one. - -Scalability -~~~~~~~~~~~ - -One common concern about Ethereum is the issue of scalability. Like -Bitcoin, Ethereum suffers from the flaw that every transaction needs to -be processed by every node in the network. With Bitcoin, the size of the -current blockchain rests at about 15 GB, growing by about 1 MB per hour. -If the Bitcoin network were to process Visa's 2000 transactions per -second, it would grow by 1 MB per three seconds (1 GB per hour, 8 TB per -year). Ethereum is likely to suffer a similar growth pattern, worsened -by the fact that there will be many applications on top of the Ethereum -blockchain instead of just a currency as is the case with Bitcoin, but -ameliorated by the fact that Ethereum full nodes need to store just the -state instead of the entire blockchain history. - -The problem with such a large blockchain size is centralization risk. If -the blockchain size increases to, say, 100 TB, then the likely scenario -would be that only a very small number of large businesses would run -full nodes, with all regular users using light SPV nodes. In such a -situation, there arises the potential concern that the full nodes could -band together and all agree to cheat in some profitable fashion (eg. -change the block reward, give themselves BTC). Light nodes would have no -way of detecting this immediately. Of course, at least one honest full -node would likely exist, and after a few hours information about the -fraud would trickle out through channels like Reddit, but at that point -it would be too late: it would be up to the ordinary users to organize -an effort to blacklist the given blocks, a massive and likely infeasible -coordination problem on a similar scale as that of pulling off a -successful 51% attack. In the case of Bitcoin, this is currently a -problem, but there exists a blockchain modification `suggested by Peter -Todd `__ -which will alleviate this issue. - -In the near term, Ethereum will use two additional strategies to cope -with this problem. First, because of the blockchain-based mining -algorithms, at least every miner will be forced to be a full node, -creating a lower bound on the number of full nodes. Second and more -importantly, however, we will include an intermediate state tree root in -the blockchain after processing each transaction. Even if block -validation is centralized, as long as one honest verifying node exists, -the centralization problem can be circumvented via a verification -protocol. If a miner publishes an invalid block, that block must either -be badly formatted, or the state ``S[n]`` is incorrect. Since ``S[0]`` -is known to be correct, there must be some first state ``S[i]`` that is -incorrect where ``S[i-1]`` is correct. The verifying node would provide -the index ``i``, along with a "proof of invalidity" consisting of the -subset of Patricia tree nodes needing to process -``APPLY(S[i-1],TX[i]) -> S[i]``. Nodes would be able to use those nodes -to run that part of the computation, and see that the ``S[i]`` generated -does not match the ``S[i]`` provided. - -Another, more sophisticated, attack would involve the malicious miners -publishing incomplete blocks, so the full information does not even -exist to determine whether or not blocks are valid. The solution to this -is a challenge-response protocol: verification nodes issue "challenges" -in the form of target transaction indices, and upon receiving a node a -light node treats the block as untrusted until another node, whether the -miner or another verifier, provides a subset of Patricia nodes as a -proof of validity. - -Conclusion ----------- - -The Ethereum protocol was originally conceived as an upgraded version of -a cryptocurrency, providing advanced features such as on-blockchain -escrow, withdrawal limits, financial contracts, gambling markets and the -like via a highly generalized programming language. The Ethereum -protocol would not "support" any of the applications directly, but the -existence of a Turing-complete programming language means that arbitrary -contracts can theoretically be created for any transaction type or -application. What is more interesting about Ethereum, however, is that -the Ethereum protocol moves far beyond just currency. Protocols around -decentralized file storage, decentralized computation and decentralized -prediction markets, among dozens of other such concepts, have the -potential to substantially increase the efficiency of the computational -industry, and provide a massive boost to other peer-to-peer protocols by -adding for the first time an economic layer. Finally, there is also a -substantial array of applications that have nothing to do with money at -all. - -The concept of an arbitrary state transition function as implemented by -the Ethereum protocol provides for a platform with unique potential; -rather than being a closed-ended, single-purpose protocol intended for a -specific array of applications in data storage, gambling or finance, -Ethereum is open-ended by design, and we believe that it is extremely -well-suited to serving as a foundational layer for a very large number -of both financial and non-financial protocols in the years to come. - -Notes and Further Reading -------------------------- - -Notes -^^^^^ - -1. A sophisticated reader may notice that in fact a Bitcoin address is - the hash of the elliptic curve public key, and not the public key - itself. However, it is in fact perfectly legitimate cryptographic - terminology to refer to the pubkey hash as a public key itself. This - is because Bitcoin's cryptography can be considered to be a custom - digital signature algorithm, where the public key consists of the - hash of the ECC pubkey, the signature consists of the ECC pubkey - concatenated with the ECC signature, and the verification algorithm - involves checking the ECC pubkey in the signature against the ECC - pubkey hash provided as a public key and then verifying the ECC - signature against the ECC pubkey. -2. Technically, the median of the 11 previous blocks. -3. Internally, 2 and "CHARLIE" are both numbers, with the latter being - in big-endian base 256 representation. Numbers can be at least 0 and - at most 2256-1. - -Further Reading -^^^^^^^^^^^^^^^ - -1. Intrinsic value: - http://bitcoinmagazine.com/8640/an-exploration-of-intrinsic-value-what-it-is-why-bitcoin-doesnt-have-it-and-why-bitcoin-does-have-it/ -2. Smart property: https://en.bitcoin.it/wiki/Smart\_Property -3. Smart contracts: https://en.bitcoin.it/wiki/Contracts -4. B-money: http://www.weidai.com/bmoney.txt -5. Reusable proofs of work: http://www.finney.org/~hal/rpow/ -6. Secure property titles with owner authority: - http://szabo.best.vwh.net/securetitle.html -7. Bitcoin whitepaper: http://bitcoin.org/bitcoin.pdf -8. Namecoin: https://namecoin.org/ -9. Zooko's triangle: http://en.wikipedia.org/wiki/Zooko's\_triangle -10. Colored coins whitepaper: - https://docs.google.com/a/buterin.com/document/d/1AnkP\_cVZTCMLIzw4DvsW6M8Q2JC0lIzrTLuoWu2z1BE/edit -11. Mastercoin whitepaper: https://github.com/mastercoin-MSC/spec -12. Decentralized autonomous corporations, Bitcoin Magazine: - http://bitcoinmagazine.com/7050/bootstrapping-a-decentralized-autonomous-corporation-part-i/ -13. Simplified payment verification: - https://en.bitcoin.it/wiki/Scalability#Simplifiedpaymentverification -14. Merkle trees: http://en.wikipedia.org/wiki/Merkle\_tree -15. Patricia trees: http://en.wikipedia.org/wiki/Patricia\_tree -16. GHOST: - http://www.cs.huji.ac.il/~avivz/pubs/13/btc\_scalability\_full.pdf -17. StorJ and Autonomous Agents, Jeff Garzik: - http://garzikrants.blogspot.ca/2013/01/storj-and-bitcoin-autonomous-agents.html -18. Mike Hearn on Smart Property at Turing Festival: - http://www.youtube.com/watch?v=Pu4PAMFPo5Y -19. Ethereum RLP: - https://github.com/ethereum/wiki/wiki/%5BEnglish%5D-RLP -20. Ethereum Merkle Patricia trees: - https://github.com/ethereum/wiki/wiki/%5BEnglish%5D-Patricia-Tree -21. Peter Todd on Merkle sum trees: - http://sourceforge.net/p/bitcoin/mailman/message/31709140/ diff --git a/old-docs-for-reference/main-wiki.rst/_Footer.rst b/old-docs-for-reference/main-wiki.rst/_Footer.rst deleted file mode 100644 index 96fe85d..0000000 --- a/old-docs-for-reference/main-wiki.rst/_Footer.rst +++ /dev/null @@ -1,17 +0,0 @@ -[ `English `__ \| [Japanese] -(https://github.com/ethereum/wiki/wiki/日本語版) \| -`Romanian `__ -\| -`German `__ -\| -`Chinese `__ -\| -`Italian `__ -\| -`Spanish `__ -\| -`French `__ -\| `فارسی -(Persian) `__ -\| [한글 (Korean)] -(https://github.com/ethereum/wiki/wiki/%5BKorean%5D-White-Paper) ] diff --git a/old-docs-for-reference/main-wiki.rst/_Sidebar.rst b/old-docs-for-reference/main-wiki.rst/_Sidebar.rst deleted file mode 100644 index f46ff3b..0000000 --- a/old-docs-for-reference/main-wiki.rst/_Sidebar.rst +++ /dev/null @@ -1,129 +0,0 @@ -Basics -~~~~~~ - -- `Home `__ -- `Ethereum - Whitepaper `__ -- `Design - Rationale `__ -- `Ethereum Yellow Paper `__ -- `FAQ `__ - -Ethereum Clients -~~~~~~~~~~~~~~~~ - -- `Webthree - (C++) `__ -- `Geth (Go) `__ -- `pyeth (Python) `__ - -Dapp Development -~~~~~~~~~~~~~~~~ - -- `Dapp Developer - Resources `__ -- `JavaScript - API `__ -- `JSON RPC API `__ -- `Solidity `__ -- `Solidity - Features `__ -- `Useful dapp - Patterns `__ -- `Standardized Contract - APIs `__ -- `Dapp using - Meteor `__ -- `Ethereum development - tutorial `__ -- `Mix - Tutorial `__ -- `Mix Features `__ -- `Serpent `__ -- `LLL `__ -- `Mutan `__ - -Infrastructure -~~~~~~~~~~~~~~ - -- `Morden Testnet `__ -- `Inter-exchange Client Address - Protocol `__ -- `URL Hint - Protocol `__ -- `NatSpec - Determination `__ -- `Network - Status `__ -- `Raspberry - Pi `__ -- `Exchange - Integration `__ -- `Mining `__ -- `Licensing `__ - -ÐΞV Technologies -~~~~~~~~~~~~~~~~ - -- `RLP Encoding `__ -- `RLPx Node Discovery - Protocol `__ -- `ÐΞVp2p Wire - Protocol `__ -- `ÐΞVp2p - Whitepaper `__ - (WiP) -- `Web3 Secret - Storage `__ - -Ethereum Technologies -~~~~~~~~~~~~~~~~~~~~~ - -- `Patricia - Tree `__ -- `Wire - protocol `__ -- `Light client - protocol `__ -- `Subtleties `__ -- `Solidity, Docs & - ABI `__ -- `NatSpec - Format `__ -- `Contract - ABI `__ -- `Bad Block - Reporting `__ -- `Bad Chain - Canary `__ -- `Extra Data `__ -- `Brain Wallet `__ - -Ethash/Dashimoto -~~~~~~~~~~~~~~~~ - -- `Ethash `__ -- `Ethash C API `__ -- `Ethash DAG `__ - -Whisper -~~~~~~~ - -- `Whisper Proposal `__ -- `Whisper - Overview `__ -- `PoC-1 Wire - protocol `__ -- `PoC-2 Wire - protocol `__ -- `PoC-2 - Whitepaper `__ - -Misc -~~~~ - -- `Hard Problems of - Cryptocurrency `__ -- `Chain - Fibers `__ -- `Glossary `__ diff --git a/old-docs-for-reference/main-wiki.rst/enode-url-format.rst b/old-docs-for-reference/main-wiki.rst/enode-url-format.rst deleted file mode 100644 index 2915ecd..0000000 --- a/old-docs-for-reference/main-wiki.rst/enode-url-format.rst +++ /dev/null @@ -1,23 +0,0 @@ -An Ethereum node can be described with a URL scheme "enode". - -The hexadecimal node ID is encoded in the username portion of the URL, -separated from the host by an @ sign. The hostname can only be given as -an IP address, DNS domain names are not allowed. The port in the host -name section is the TCP listening port. If the TCP and UDP (discovery) -ports differ, the UDP port is specified as query parameter "discport". - -In the following example, the node URL describes a node with IP address -``10.3.58.6``, TCP listening port ``30303`` and UDP discovery port -``30301``. - -:: - - enode://6f8a80d14311c39f35f516fa664deaaaa13e85b2f7493f37f6144d86991ec012937307647bd3b9a82abe2974e1407241d54947bbb39763a4cac9f77166ad92a0@10.3.58.6:30303?discport=30301 - -The enode url scheme is used by the Node discovery protocol and can be -used in the ``bootnodes`` command line option of the client or as the -argument to ``suggestPeer(nodeURL)`` function in the JSRE. - -See also - -https://github.com/ethereum/go-ethereum/wiki/Command-Line-Options - -https://github.com/ethereum/go-ethereum/wiki/JavaScript-Console diff --git "a/old-docs-for-reference/main-wiki.rst/e\317\200-Programme.rst" "b/old-docs-for-reference/main-wiki.rst/e\317\200-Programme.rst" deleted file mode 100644 index 69ebb20..0000000 --- "a/old-docs-for-reference/main-wiki.rst/e\317\200-Programme.rst" +++ /dev/null @@ -1,24 +0,0 @@ -The Ethereum Raspberry Pi (eπ) Programme -======================================== - -The eπ programme is aimed to get as many nodes distributed around the -world as possible. Any existing Ethereum meetup group is eligible to -apply. - -We will offer to loan the group a set of equipment to run an Ethereum -node. This will include: - -- Raspberry Pi 2 Model B; -- 64 GB fast memory card; -- PSU. - -We expect you guys to be the ones to run the install -(https://github.com/ethereum/wiki/wiki/Raspberry-Pi-instructions). - -Your node will be placed on both our public and curated node lists, and -aside from allowing us to show dots all over the world, will help us -better understand network dynamics and emergent effects stemming from -our propagation strategies. - -To apply for the programme, send an application including your name, -meetup group name/town and an address for shipment to epi@ethereum.org. diff --git a/old-docs-for-reference/main-wiki.rst/libp2p-Whitepaper.rst b/old-docs-for-reference/main-wiki.rst/libp2p-Whitepaper.rst deleted file mode 100644 index 1efc23a..0000000 --- a/old-docs-for-reference/main-wiki.rst/libp2p-Whitepaper.rst +++ /dev/null @@ -1,82 +0,0 @@ -**NOTE:** *This is a work-in-progress* - -For Ethereum to succeed, and for the ultimate goals of Ethereum to be -achieved, Ethereum needs to employ a number of secure decentralised data -systems. The generalised Turing-complete, extensible-state blockchain is -one component in this, but for it to be leveraged to its full potential -for building decentralised applications (dapps), a suite of additional -data systems are necessary. Each decentralised-datasystem solves -specific needs; in general it is difficult to predict what data systems -will ultimately be required since the decentralised paradigm is not -immediately comparable, like-for-like with traditional centralised -architected systems. - -Three types of data systems in particular are required for many current -massively multi-user applications (MMAs, aka generally Web-based -applications but also mobile phone apps and e.g. MMORPGs). In addition -to a transactional database ("Ethereum"), a publication and download -system would be required in addition to a generalised low-level -"bulletin-board" system for posting messages. - -We can, however, imagine many more such types of decentralised -communications systems in the future including, e.g., those for -identity-based RTC. Each of these components have a number of shared -prerequisites, such as peer-discovery and recording; network -well-formedness; transport-level buffering, scheduling and framing; and -authentication and security. Any computer scientist worth their salt -would instantly scream out "abstraction opportunity!". - -What it is -~~~~~~~~~~ - -libp2p (aka ÐΞVp2p) aims to provide a lightweight abstraction layer that -provides these low-level algorithms, protocols and services in a -transparent framework without predetermining the eventual -transmission-use-cases of the protocols. - -Its specific aims are to provide a language-agnostic API and -specification which is: - *Universal:* Pairwise addressing (ala -Telehash), broadcast (ala Bitcoin), groupwise (some DHT designs & -filesharing) are all reasonable. There may be others. It should provide -only the network structure, not dictate usage over it. - *Ubiquitous:* -The same peer-set/-network should be able to be used for all protocols. -- *Secure:* Encryption between physical peers is a given. Peer -introduction can provide a good level of defence against systematic MitM -attacks. - *Efficient:* Framing and prioritisation to guarantee QoS over -each protocol. Multiplexing allows access to limited resources to be -easily controlled between p2p protocols. Kademlia-style network -well-formedness guarantees a low maximum hope distance to any peer in -the network and its group. - *Simple:* A minimal, developer-driven API -gives source-level future-proofing. - -Ultimately, additional secondary features will also be explored: - *DPI -security:* Framing and bandwidth control can be used to control traffic -shape. - *Transport-layer Agnostic:* TCP/IP v4 and v6 are provided with -initial protocol specifications. Others should be able to be added on at -later dates without altering the API. Mesh networking devices could even -ultimately implement this natively. - -Basic Design -~~~~~~~~~~~~ - -- Peers can each be identified by a node-ID. -- Provides ability *only* to communicate with peers. -- Everything happens in typed, ordered datagrams. -- Any number of datagram types can be registered - these are - automatically negotiated at the handshake. -- Peers can be requested via a libp2p physical endpoint. -- Peers can be rated per-protocol using a local metric. -- Peer set is dynamic and "steered" by libp2p internally, going from - ratings. -- First packets are either DH key exchange or, if node known from peer - introduction, PKI-encrypted session key, or if node known from - previous session, new session key encrypted by old. Retry can be made - after failed negotiation using prior knowledge, with the - corresponding removal of any trust. -- Peer-set is made up from multiple sub-protocol slots. -- Each slot is given over to maximise rating for that particular - sub-protocol. - -There is no preordained inter-node message routing system (this is left -to a higher-level), and no preordained high-level identity system -(again, higher level). diff --git a/old-docs-for-reference/main-wiki.rst/newBlockFilter-Improvement-Proposal.rst b/old-docs-for-reference/main-wiki.rst/newBlockFilter-Improvement-Proposal.rst deleted file mode 100644 index 59077e1..0000000 --- a/old-docs-for-reference/main-wiki.rst/newBlockFilter-Improvement-Proposal.rst +++ /dev/null @@ -1,57 +0,0 @@ -Currently a filter created with ``eth_newBlockFilter`` and call -``eth_getFilterLogs``, or ``get_filterChanges`` should return ``[null]`` -or ``[null, null,...]`` If multiple blocks came in since the last poll. - -Thats fine as you can check for the current block e.g. using: - -.. code:: js - - web3.eth.filter('latest').watch(function(err, res){ - // i can get the current block here - web3.eth.getBlock('latest'); - }); - -The problem is that when a lot of blocks came in since the last time you -polled with a return of ``[null, null, null, ...]``, your callback will -fire multiple times accordingly, but using ``eth.getBlock`` inside will -always give me the latest block, which is actually wrong. - -New Proposal -============ - -After discussing with Gavin we came up with the following improvement: - -.. code:: js - - // eth_newBlockFilter will receive no parameter - {"jsonrpc":"2.0","method":"eth_newBlockFilter","params":[],"id":529} - - // poll - {"jsonrpc":"2.0","method":"eth_getFilterChanges","params":["0xb"],"id":530} // we assume the filter ID is "0xb" - - // should return one or more blocks, - // depending on how much arrived since the last poll - { - "id": 530, - "jsonrpc": "2.0", - "result": ['0x234234234..','0x342342342..'] // block hashes of the incoming blocks - } - -.. code:: js - - // eth_newPendingTransactionFilter will receive no parameter - {"jsonrpc":"2.0","method":"eth_newPendingTransactionFilter","params":[],"id":529} - - // poll - {"jsonrpc":"2.0","method":"eth_getFilterChanges","params":["0xb"],"id":530} // we assume the filter ID is "0xb" - - // should return one or more pending transactions, - // which were added to the pending state since the last poll - { - "id": 530, - "jsonrpc": "2.0", - "result": ['0x234234234..','0x342342342..'] // tx hashes of new pending transactions - } - -**Note** This requires that ``eth_getTransactionByHash`` also return -pending transactions! diff --git a/old-docs-for-reference/main-wiki.rst/web.js-0.9.rst b/old-docs-for-reference/main-wiki.rst/web.js-0.9.rst deleted file mode 100644 index 49050fa..0000000 --- a/old-docs-for-reference/main-wiki.rst/web.js-0.9.rst +++ /dev/null @@ -1,41 +0,0 @@ -Web3.js 0.9 changes - -I would like to apply KISS principle to web3.js. I used the library -recently much more and I realised that we are doing to many things -implicitly. eg: - -1, newFilter it should either get all logs or poll for new logs. It's -shouldn't do both in the same time. In my story, I don't want to poll -for filter changes, but I want to get all logs between block X and Y. -Same as caktux here: https://github.com/ethereum/web3.js/issues/250 - -examples of new solution - -1st. - -\`\`\` var x = web3.eth.filter(...); // sync: eth\_newFilter -x.watch(function (err, log) { // async poll: eth\_getFilterChanges - -}) \`\`\` - -2nd. - -\`\`\` web3.eth.filter(..., function (err, x) { // async: eth\_newFilter -x.watch(function (err, log) { // async poll: eth\_getFilterChanges - -:: - - }) - -}) - -\`\`\` - -3rd. - -``var x = web3.eth.filter(...) // sync: eth_newFilter var logs = x.logs(); // sync: eth_getFilterLogs`` - -4th. \`\`\` var x = web3.eth.filter(...) // sync: eth\_newFilter var -logs = x.logs(function (err, logs) { // sync: eth\_getFilterLogs - -} \`\`\` diff --git "a/old-docs-for-reference/main-wiki.rst/\303\220\316\236Vp2p-Wire-Protocol.rst" "b/old-docs-for-reference/main-wiki.rst/\303\220\316\236Vp2p-Wire-Protocol.rst" deleted file mode 100644 index 3257360..0000000 --- "a/old-docs-for-reference/main-wiki.rst/\303\220\316\236Vp2p-Wire-Protocol.rst" +++ /dev/null @@ -1,111 +0,0 @@ -Peer-to-peer communications between nodes running Ethereum/Whisper/&c. -clients are designed to be governed by a simple wire-protocol making use -of existing ÐΞV technologies and standards such as -`RLP `__ wherever practical. - -This document is intended to specify this protocol comprehensively. - -Low-Level -~~~~~~~~~ - -ÐΞVp2p nodes communicate by sending messages using RLPx, an encrypted -and authenticated transport protocol. Peers are free to advertise and -accept connections on any TCP ports they wish, however, a default port -on which the connection may be listened and made will be 30303. Though -TCP provides a connection-oriented medium, ÐΞVp2p nodes communicate in -terms of packets. RLPx provides facilities to send and receive packets. -For more information about RLPx, refer to the `protocol -specification `__. - -ÐΞVp2p nodes find peers through the RLPx discovery protocol DHT. Peer -connections can also be initiated by supplying the endpoint of a peer to -a client-specific RPC API. - -Payload Contents -~~~~~~~~~~~~~~~~ - -There are a number of different types of payload that may be encoded -within the RLP. This ''type'' is always determined by the first entry of -the RLP, interpreted as an integer. - -ÐΞVp2p is designed to support arbitrary sub-protocols (aka -*capabilities*) over the basic wire protocol. Each sub-protocol is given -as much of the message-ID space as it needs (all such protocols must -statically specify how many message IDs they require). On connection and -reception of the ``Hello`` message, both peers have equivalent -information about what subprotocols they share (including versions) and -are able to form consensus over the composition of message ID space. - -Message IDs are assumed to be compact from ID 0x10 onwards (0x00-0x10 is -reserved for ÐΞVp2p messages) and given to each shared (equal-version, -equal name) sub-protocol in alphabetic order. Sub-protocols that are not -shared are ignored. If multiple versions are shared of the same (equal -name) sub-protocol, the numerically highest wins, others are ignored. - -P2P -~~~ - -**Hello** ``0x00`` [``p2pVersion``: ``P``, ``clientId``: ``B``, -[[``cap1``: ``B_3``, ``capVersion1``: ``P``], [``cap2``: ``B_3``, -``capVersion2``: ``P``], ``...``], ``listenPort``: ``P``, ``nodeId``: -``B_64``] First packet sent over the connection, and sent once by both -sides. No other messages may be sent until a Hello is received. \* -``p2pVersion`` Specifies the implemented version of the P2P protocol. -Now must be 1. \* ``clientId`` Specifies the client software identity, -as a human-readable string (e.g. "Ethereum(++)/1.0.0"). \* ``cap`` -Specifies a peer capability name as a length-3 ASCII string. Current -supported capabilities are ``eth``, ``shh``. \* ``capVersion`` Specifies -a peer capability version as a positive integer. Current supported -versions are 34 for ``eth``, and 1 for ``shh``. \* ``listenPort`` -specifies the port that the client is listening on (on the interface -that the present connection traverses). If 0 it indicates the client is -not listening. \* ``nodeId`` is the Unique Identity of the node and -specifies a 512-bit hash that identifies this node. - -**Disconnect** ``0x01`` [``reason``: ``P``] Inform the peer that a -disconnection is imminent; if received, a peer should disconnect -immediately. When sending, well-behaved hosts give their peers a -fighting chance (read: wait 2 seconds) to disconnect to before -disconnecting themselves. \* ``reason`` is an optional integer -specifying one of a number of reasons for disconnect: \* ``0x00`` -Disconnect requested; \* ``0x01`` TCP sub-system error; \* ``0x02`` -Breach of protocol, e.g. a malformed message, bad RLP, incorrect magic -number &c.; \* ``0x03`` Useless peer; \* ``0x04`` Too many peers; \* -``0x05`` Already connected; \* ``0x06`` Incompatible P2P protocol -version; \* ``0x07`` Null node identity received - this is automatically -invalid; \* ``0x08`` Client quitting; \* ``0x09`` Unexpected identity -(i.e. a different identity to a previous connection/what a trusted peer -told us). \* ``0x0a`` Identity is the same as this node (i.e. connected -to itself); \* ``0x0b`` Timeout on receiving a message (i.e. nothing -received since sending last ping); \* ``0x10`` Some other reason -specific to a subprotocol. - -**Ping** ``0x02`` [] Requests an immediate reply of ``Pong`` from the -peer. - -**Pong** ``0x03`` [] Reply to peer's ``Ping`` packet. - -**NotImplemented (was GetPeers)** ``0x04`` - -**NotImplemented (was Peers)** ``0x05`` - -Node identity and reputation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The identity of a ÐΞVp2p node is a secp256k1 public key. - -Nodes are free to store ratings for given IDs (how useful the node has -been in the past) and give preference accordingly. Nodes may also track -node IDs (and their provenance) in order to help determine potential -man-in-the-middle attacks. Clients are free to mark down new nodes and -use the node ID as a means of determining a node's reputation. - -Session Management -~~~~~~~~~~~~~~~~~~ - -Upon connecting, all clients (i.e. both sides of the connection) must -send a ``Hello`` message. Upon receiving the ``Hello`` message and -verifying compatibility of the network and versions, a session is active -and any other P2P messages may be sent. - -At any time, a Disconnect message may be sent. diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index 65b1ff4..0000000 --- a/requirements.txt +++ /dev/null @@ -1,3 +0,0 @@ -restructuredtext-lint==0.14.2 -Pigments==1.6 -Sphinx==1.3.6 diff --git a/rst_lint.py b/rst_lint.py deleted file mode 100644 index 30ebb67..0000000 --- a/rst_lint.py +++ /dev/null @@ -1,116 +0,0 @@ -# Load in our dependencies -import os -import sys - - -BASE_DIR = os.path.dirname(__file__) -SOURCE_DIR = os.path.join(BASE_DIR, "source") - - -from docutils.core import Publisher -from docutils.parsers.rst.directives import register_directive -from docutils.parsers.rst import roles - -from sphinx.application import Sphinx -from sphinx.domains.std import StandardDomain -# Just importing the directives also triggers registration. -from sphinx.directives import * # NOQA - - -sphinx = Sphinx( - srcdir=SOURCE_DIR, - confdir=SOURCE_DIR, - outdir=os.path.join(BASE_DIR, 'build'), - doctreedir=os.path.join(BASE_DIR, 'build', 'doctree'), - buildername='html', -) - - -class PublisherWithSphinxEnv(Publisher): - def get_settings(self, *args, **kwargs): - kwargs.setdefault('env', sphinx.env) - return Publisher.get_settings(self, *args, **kwargs) - - -# -# MONKEYPATCHING!!!! -# -# The restructuredtext_lint library uses the `Publisher` class from `docutils` -# to generate linting errors. Within this class, a `settings` object is -# generated which is then passed into the various directives which produce the -# errors and warnings. Sphinx has some very specific needs in terms of what -# this settings object looks like, specifically, an `env` property that needs -# to be present. -# -# Here we monkeypatch the `docutils.core.Publisher` object with our own -# subclass which includes the sphinx `env` object such that when the Sphinx -# directives are used, they have the internals that they need available. -from docutils import core -core.Publisher = PublisherWithSphinxEnv - -# This import **MUST** occur after the `core.Publisher` monkeypatch. -import restructuredtext_lint as rst_lint - - -# The Glossary directive is special and needs to be registered on it's own. -for role_name, role in StandardDomain.roles.items(): - roles.register_local_role(role_name, role) -for role_name, role in StandardDomain.directives.items(): - register_directive(role_name, role) - - -INFO = 10 -WARNING = 20 -ERROR = 30 - -LEVELS = { - 'INFO': INFO, - 'WARNING': WARNING, - 'ERROR': ERROR, -} - - -def lint(dir=SOURCE_DIR, log_level=WARNING): - errors = [] - - for root, subdirs, files in os.walk(SOURCE_DIR): - for filename in files: - extension = filename.rpartition('.')[2].lower() - if extension == "rst": - abs_path = os.path.abspath(os.path.join(root, filename)) - rel_path = os.path.relpath(abs_path, SOURCE_DIR) - - # Sphinx maintains a list of `docnames` that it has found which - # are the relative paths to the docs from the SOURCE_DIR - # without the file extension. The `sphinx.env.temp_data` - # dictionary needs to have the current docname populuated while - # it's being processed for the Sphinx directives to function - # properly. - docname = rel_path.rpartition('.')[0] - sphinx.env.temp_data['docname'] = docname - linting_errors = rst_lint.lint_file(os.path.join(root, filename)) - if linting_errors: - errors.extend(linting_errors) - - if errors: - for error in errors: - message = "{prefix}: {full_file_path}:{line_no}: {message}\n".format( - prefix=error.type, - full_file_path=os.path.relpath(error.source), - line_no=error.line, - message=error.message, - ) - if LEVELS[error.type] < log_level: - continue - elif LEVELS[error.type] < ERROR: - sys.stdout.write(message) - else: - sys.stderr.write(message) - if any(error.type == "ERROR" for error in errors): - sys.exit(1) - else: - sys.exit(0) - - -if __name__ == "__main__": - lint() diff --git a/source/about.rst b/source/about.rst deleted file mode 100644 index 4953a8b..0000000 --- a/source/about.rst +++ /dev/null @@ -1,91 +0,0 @@ -*************************************** -The Classic Documentation Initiative -*************************************** -|Gitter| - -.. |Gitter| image:: img/classic-guide.svg - :target: https://gitter.im/ethereumclassic/classic-guide?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge - -Purpose and Audience -=============================================================================== - -This guide should serve to be an entry level for all Ethereum users and developers. -The goal is to create documentation with information, short tutorials, and examples that will cover all of the basic and intermediate functionality of using Ethereum to interact with dapps or develop a dapp. - -Any information that is overly specific, technical, or not necessary to accomplish the documentation's goal will remain on the Ethereum Github Wiki. It may be referenced in this guide if necessary. - -Although much of the information will be similar between the Frontier Guide and the Homestead Guide, efforts need to be made to make sure the information ported over is still accurate. -This document is client agnostic and examples and tutorials may be based on any client that the author decides to write on, as long as a distinction is made as to what client is being used in the examples/tutorials. - -Although overly specific and technical documentation will not be included in the first iterations of this guide, community use and popularity of this guide will dictate future decisions to move Github wiki documentation to this format. - -Examples of overly specific and technical documentation include: - -* ETHash, CASPER, ABI, RLP, or other technical specs. -* Full API specs for protocols. Caveat: If an example, information, or tutorial needs to reference API calls for a client or interface in order to fulfill its example it is acceptable to reference the specific call. Be sure to make a reference where the user can find remaining pieces of the specific documentation that may be on the GitHub Wiki. - -Resources for Exemplary Documentation -=============================================================================== - -Here are some examples of previous Ethereum documentation + good examples of documentation. - -* Solidity Docs - https://ethereum.github.io/solidity/docs/home/ -* Frontier Guide - https://ethereum.gitbooks.io/frontier-guide/content/ -* Gav’s TurboEthereum Guide - https://gavofyork.gitbooks.io/turboethereum/content/ -* Ancient EthereumBuilder’s Guide - https://ethereumbuilders.gitbooks.io/guide/content/en/index.html -* Other Ethereum Links: https://souptacular.gitbooks.io/ethereum-tutorials-and-tips-by-hudson/content/giant_ethereum_resource_list.html -* Django Docs - https://docs.djangoproject.com/en/1.9/ - -Restructured Text Markup, Sphinx -======================================= - -* Best Cheat Sheet - https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst -* Quick Reference - http://docutils.sourceforge.net/docs/user/rst/quickref.html -* Official Cheat Sheet - http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt -> http://docutils.sourceforge.net/docs/user/rst/cheatsheet.html -* RST Primer http://sphinx-doc.org/rest.html -* http://sphinx-doc.org/markup/inline.html - -Compilation and Deployment -=============================================================================== - -We use `make` with the autogenerated read-the-docs `Makefile` to build the doc. - -.. code-block:: bash - - git clone https://github.com/ethereum/homestead-guide - cd homestead-guide - make html - -Processing Tips -=============================================================================== - -Fix section delimiter lines (always use 80-long ones to have correct length, unless the title is greater than 80 chars in length) - -.. code-block:: bash - - for f in `ls source/*/*.rst`; do cat $f|perl -pe 's/\=+$/================================================================================/' > $f.o; mv $f.o $f; done; done - for f in `ls source/*/*.rst`; do cat $f|perl -pe 's/\*+$/********************************************************************************/' > $f.o; mv $f.o $f; done - for f in `ls source/*/*.rst`; do cat $f|perl -pe 's/\-+$/--------------------------------------------------------------------------------/' > $f.o; mv $f.o $f; done - for f in `ls source/*/*.rst`; do cat $f|perl -pe 's/\++$/++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++/' > $f.o; mv $f.o $f; done - for f in `ls source/*/*.rst`; do cat $f|perl -pe 's/\#+$/################################################################################/' > $f.o; mv $f.o $f; done - -Referencing Old Documentation -=============================================================================== - -old-docs-for-reference folder has all of the Frontier Gitbook and Ethereum Wiki doc. Feel free to copy/paste information from those documents that is still relevant. - -Migrate and Convert Old Wiki Content Using Pandoc -=============================================================================== - -If you still want to clone the absolute latest Ethereum Wiki and Frontier Guide docs: - -.. code-block:: bash - - git clone git@github.com:ethereum/go-ethereum.wiki.git - git clone git@github.com:ethereum/wiki.wiki.git - - mkdir main-wiki.rst - mkdir go-ethereum-wiki.rst - - for f in `ls wiki.wiki/*.md`; do pandoc $f -o main-wiki.rst/`basename $f .md`.rst; done - for f in `ls go-ethereum.wiki/*.md`; do pandoc $f -o go-ethereum-wiki.rst/`basename $f .md`.rst; done diff --git a/source/account-management.rst b/source/account-management.rst deleted file mode 100644 index 1dfc8fa..0000000 --- a/source/account-management.rst +++ /dev/null @@ -1,440 +0,0 @@ -******************************************************************************** -Account Management -******************************************************************************** - -.. _Accounts: - -Accounts -================================================================================ - -Accounts play a central role in Ethereum. There are two types of accounts: *externally owned accounts* (EOAs) and *contract accounts*. Here we focus on externally owned accounts, which will be referred to simply as *accounts*. Contract accounts will be referred to as *contracts* and are :ref:`discussed in detail in Contracts `. This generic notion of account subsuming both externally owned accounts and contracts is justified in that these entities are so called *state objects*. These entities have a state: accounts have balance and contracts have both balance and contract storage. The state of all accounts is the state of the Ethereum network which is updated with every block and which the network really needs to reach a consensus about. -Account are essential for users to interact with the Ethereum blockchain via transactions. - -If we restrict Ethereum to only externally owned accounts and allow only transactions between them, we arrive at an "altcoin" system that is less powerful than bitcoin itself and can only be used to transfer ether. - -Accounts represent identities of external agents (e.g., human personas, mining nodes or automated agents). Accounts use public key cryptography to sign transaction so that the EVM can securely validate the identity of a transaction sender. - -Keyfiles -================================================================================ - -Every account is defined by a pair of keys, a private key and public key. Accounts are indexed by their *address* which is derived from the public key by taking the last 20 bytes. Every private key/address pair is encoded in a *keyfile*. Keyfiles are JSON text files which you can open and view in any text editor. The critical component of the keyfile, your account’s private key, is always encrypted, and it is encrypted with the password you enter when you create the account. Keyfiles are found in the ``keystore`` subdirectory of your Ethereum node’s data directory. Make sure you backup your keyfiles regularly! See the section :ref:`backup-and-restore-accounts` for more information. - -Creating a key is tantamount to creating an account. - -* You don't need to tell anybody else you're doing it -* You don't need to synchronize with the blockchain -* You don't need to run a client -* You don't even need to be connected to the internet - -Of course your new account will not contain any Ether. But it'll be yours and you can be certain that without your key and your password, nobody else can ever access it. - -It is safe to transfer the entire directory or any individual keyfile between Ethereum nodes. - -.. Warning:: Note that in case you are adding keyfiles to your node from a different node, the order of accounts may change. So make sure you do not rely or change the index in your scripts or code snippets. - -.. _creating_an_account: - -Creating an account -================================================================================ - -.. Warning:: **Remember your passwords and `backup your keyfiles `_.** In order to send transactions from an account, including sending ether, you must have BOTH the keyfile and the password. Be absolutely sure to have a copy of your keyfile AND remember the password for that keyfile, and store them both as securely as possible. There are no escape routes here; lose the keyfile or forget your password and all your ether is gone. It is NOT possible to access your account without a password and there is no *forgot my password* option here. Do not forget it. - -Using ``geth account new`` --------------------------------------------------------------------------------- - -Once you have the geth client installed, creating an account is merely a case of executing the ``geth account new`` command in a terminal. - -Note that you do not have to run the geth client or sync up with the blockchain to use the ``geth account`` command. - -.. code-block:: Bash - - $ geth account new - - Your new account is locked with a password. Please give a password. Do not forget this password. - Passphrase: - Repeat Passphrase: - Address: {168bc315a2ee09042d83d7c5811b533620531f67} - -For non-interactive use you supply a plaintext password file as argument to the ``--password`` flag. The data in the file consists of the raw bytes of the password optionally followed by a single newline. - -.. code-block:: Bash - - $ geth --password /path/to/password account new - -.. Warning:: Using the ``--password`` flag is meant to be used only for testing or automation in trusted environments. It is a bad idea to save your password to file or expose it in any other way. If you do use the ``--password`` flag with a password file, make sure the file is not readable or even listable for anyone but you. You can achieve this in Mac/Linux systems with: - -.. code-block:: Bash - - touch /path/to/password - chmod 600 /path/to/password - cat > /path/to/password - >I type my pass - - -To list all the accounts with keyfiles currently in you’re ``keystore`` folder use the ``list`` subcommand of the ``geth account`` command: - -.. code-block:: Bash - - $ geth account list - - account #0: {a94f5374fce5edbc8e2a8697c15331677e6ebf0b} - account #1: {c385233b188811c9f355d4caec14df86d6248235} - account #2: {7f444580bfef4b9bc7e14eb7fb2a029336b07c9d} - - -The filenames of keyfiles has the format ``UTC---
``. The order of accounts when listing, is lexicographic, but as a consequence of the timestamp format, it is actually order of creation. - - -Using geth console --------------------------------------------------------------------------------- - -In order to create a new account using geth, we must first start geth in console mode (or you can use ``geth attach`` to attach a console to an already running instance): - -.. code-block:: Bash - - > geth console 2>> file_to_log_output - instance: Geth/v1.4.0-unstable/linux/go1.5.1 - coinbase: coinbase: [object Object] - at block: 865174 (Mon, 18 Jan 2016 02:58:53 GMT) - datadir: /home/USERNAME/.ethereum - -The console allows you to interact with your local node by issuing commands. For example, try the command to list your accounts: - -.. code-block:: Javascript - - > eth.accounts - - { - code: -32000, - message: "no keys in store" - } - -This shows that you have no accounts. You can also create an account from the console: - -.. code-block:: Javascript - - > personal.newAccount() - Passphrase: - Repeat passphrase: - "0xb2f69ddf70297958e582a0cc98bce43294f1007d" - -.. Note:: Remember to use a strong and randomly generated password. - -We just created our first account. If we try to list our accounts again we can see our new account: - -.. code-block:: Javascript - - > eth.accounts - ["0xb2f69ddf70297958e582a0cc98bce43294f1007d"] - - -.. _using-mist-ethereum-wallet: - -Using Mist Ethereum wallet --------------------------------------------------------------------------------- - -For the command line averse, there is now a GUI-based option for creating accounts: The “official” Mist Ethereum wallet. The Mist Ethereum wallet, and its parent Mist project, are being developed under the auspices of the Ethereum Foundation, hence the “official” status. Versions of the wallet app are available for Linux, Mac OS X, and Windows. - -.. Warning:: The Mist wallet is beta software. Please beware and use it at your own risk. - -Creating an account using the GUI Mist Ethereum wallet couldn’t be easier. In fact, your first account is created during the installation of the app. - -1. `Download the latest version of the wallet app `_ for your operating system. Opening the Wallet App will kick off syncing a full copy of the Ethereum blockchain on your computer, since you will in effect be running a full geth node. - -2. Unzip the downloaded folder and run the Ethereum-Wallet executable file. - -.. image:: img/51Downloading.png - :width: 582px - :height: 469px - :scale: 75 % - :alt: downloading-mist - :align: center - -3. Wait for the blockchain to fully sync, then follow the instructions on the screen and your first account will be created. - -4. When you launch the Mist Ethereum wallet for the first time, you will see the account you created during the installation process. By default it will be named MAIN ACCOUNT (ETHERBASE). - -.. image:: img/51OpeningScreen.png - :width: 1024px - :height: 938px - :scale: 50 % - :alt: opening-screen - :align: center - -5. Creating additional accounts is easy; just click on ADD ACCOUNT in the app’s main screen and enter the required password. - -.. Note:: The Mist wallet is still in active development, so details of the steps outlined above may change with upgrades. - - -Creating a Multi-Signature Wallet in Mist --------------------------------------------------------------------------------- - -The Mist Ethereum wallet has an option to secure your wallet balance with a multisig wallet. The advantage of using a multisig wallet is that it requires authorization from more than one account to withdrawal larger amounts from your balance. Before you can create a multisig wallet, you'll need to create more than one account. - -It's very easy to create account files in Mist. In the 'Accounts' section click 'Add Account'. Pick a strong yet easy-to-remember password (remember there is no password recovery option), confirm it, and your account is created. Create at least 2 accounts. Secondary accounts can be created on separate computers running Mist if you prefer (and theoretically make your multisig more secure doing it this way). You only need the public keys (your deposit addresses) of your secondary accounts when creating the multisig wallet (copy/paste them, do not ever type them by hand). Your primary account will be needed to create the multisig wallet contract, so it must be on the computer you are creating the multisig wallet on. - -Now that you have your accounts setup, be safe and back them up (if your computer crashes, you will lose your balance if you do not have a backup). Click 'Backup' in the top menu. Choose the 'keystore' folder, opposite-click on it / choose 'copy' (do NOT choose 'cut', that would be very bad). Navigate to your desktop, opposite-click in a blank area and choose 'paste'. You may want to rename this new copy of the 'keystore' folder to something like 'Ethereum-keystore-backup-year-month-day' so you have quick recognition of it later. At this point you can then add the folder contents to a zip / rar file (and even password-protect the archive with another strong yet easy-to-remember password if backing up online), copy it to a USB Drive, burn it to a CD / DVD, or upload it to online storage (Dropbox / Google Drive / etc). - -You now should add approximately no less than 0.02 ETH to your primary account (the account you will initiate creation of a multisig wallet with). This is required for the transaction fee when you create the multisig wallet contract. An additional 1 ETH (or more) is also needed, because Mist currently requires this to assure wallet contract transactions have enough 'gas' to execute properly...so no less than about 1.02 ETH total for starters. - -You will be entering the full addresses of all the accounts you are attaching to this multisig wallet, when you create it. I recommend copying / pasting each address into a plain text editor (notepad / kedit / etc), after going to each account's details page in Mist, and choosing 'copy address' from the right-side column of buttons. Never type an address by hand, or you run a very high risk of typos and could lose your balance sending transactions to the wrong address. - -We are now ready to create the multisig wallet. Under 'Wallet Contracts', select 'Add Wallet Contract'. Give it a name, select the primary account owner, and choose 'Multisignature Wallet Contract'. You will see something like this appear: - -"This is a joint account controlled by X owners. You can send up to X ether per day. Any transaction over that daily limit requires the confirmation of X owners." - -Set whatever amount of owners (accounts) you are attaching to this multisig wallet, whatever you want for a daily withdrawal limit (that only requires one account to withdrawal that amount), and how many owners (accounts) are required to approve any withdrawal amount over the daily limit. - -Now add the addresses of the accounts that you copied / pasted into your text editor earlier, confirm all your settings are correct, and click 'Create' at the bottom. You will then need to enter your password to send the transaction. In the 'Wallet Contracts' section it should show your new wallet, and say 'creating'. - -When wallet creation is complete, you should see your contract address on the screen. Select the entire address, copy / paste it into a new text file in your text editor, and save the text file to your desktop as 'Ethereum-Wallet-Address.txt', or whatever you want to name it. - -Now all you need to do is backup the 'Ethereum-Wallet-Address.txt' file the same way you backed up your account files, and then you are ready to load your new multisig wallet with ETH using this address. - -If you are restoring from backup, simply copy the files inside the 'Ethereum-keystore-backup' folder over into the 'keystore' folder mentioned in the first section of this walkthrough. FYI, you may need to create the 'keystore' folder if it's a brand new install of Mist on a machine it was never installed on before (the first time you create an account is when this folder is created). As for restoring a multisig wallet, instead of choosing 'Multisignature Wallet Contract' like we did before when creating it, we merely choose 'Import Wallet' instead. - -Troubleshooting: - -* Mist won't sync. One solution that works well is syncing your PC hardware clock with an NTP server so the time is exactly correct...then reboot. - -* Mist starts after syncing, but is a blank white screen. Chances are you are running the "xorg" video drivers on a Linux-based OS (Ubuntu, Linux Mint, etc). Try installing the manufacturer's video driver instead. - -* "Wrong password" notice. This seems to be a false notice on occasion on current Mist versions. Restart Mist and the problem should go away (if you indeed entered the correct password). - - -Using Eth --------------------------------------------------------------------------------- - -Every options related to key management available using geth can be used the same way in eth. - -Below are "account" related options: - -.. code-block:: Javascript - - > eth account list // List all keys available in wallet. - > eth account new // Create a new key and add it to the wallet. - > eth account update [|
, ... ] // Decrypt and re-encrypt given keys. - > eth account import [||] // Import keys from given source and place in wallet. - -Below are "wallet" related option: - -.. code-block:: Javascript - - > eth wallet import //Import a presale wallet. - -.. Note:: the 'account import' option can only be used to import generic key file. the 'wallet import' option can only be used to import a presale wallet. - -It is also possible to access keys management from the integrated console (using the built-in console or geth attach): - -.. code-block:: Javascript - - > web3.personal - { - listAccounts: [], - getListAccounts: function(callback), - lockAccount: function(), - newAccount: function(), - unlockAccount: function() - } - - -Using EthKey (deprecated) --------------------------------------------------------------------------------- - -Ethkey is a CLI tool of the C++ implementation that allows you to interact with the Ethereum wallet. With it you can list, inspect, create, delete and modify keys and inspect, create and sign transactions. - -We will assume you have not yet run a client such as eth or anything in the Aleth series of clients. If you have, you can skip this section. -To create a wallet, run ``ethkey`` with the ``createwallet`` command: - -.. code-block:: Bash - - > ethkey createwallet - -Please enter a MASTER passphrase to protect your key store (make it strong!): -You'll be asked for a "master" passphrase. This protects your privacy and acts as a default password for any keys. You'll need to confirm it by entering the same text again. - -.. Note:: Use a strong randomly generated password. - -We can list the keys within the wallet simply by using the list command: - -.. code-block:: Bash - - > ethkey list - - No keys found. - -We haven't yet created any keys, and it's telling us so! Let's create one. - -To create a key, we use the ``new`` command. To use it we must pass a name - this is the name we'll give to this account in the wallet. Let's call it "test": - -.. code-block:: Bash - - > ethkey new test - -Enter a passphrase with which to secure this account (or nothing to use the master passphrase). -It will prompt you to enter a passphrase to protect this key. If you just press enter, it'll use the default "master" passphrase. Typically this means you won't need to enter the passphrase for the key when you want to use the account (since it remembers the master passphrase). In general, you should try to use a different passphrase for each key since it prevents one compromised passphrase from giving access to other accounts. However, out of convenience you might decide that for low-security accounts to use the same passphrase. - -Here, let's give it the incredibly imaginative passphrase of 123. (Never ever use simple passwords like this for anything else than ephemeral test accounts). -Once you enter a passphrase, it'll ask you to confirm it by entering again. Enter 123 a second time. -Because you gave it its own passphrase, it'll also ask you to provide a hint for this password which will be displayed to you whenever it asks you to enter it. The hint is stored in the wallet and is itself protected by the master passphrase. Enter the truly awful hint of 321 backwards. - -.. code-block:: Bash - - > ethkey new test - - Enter a passphrase with which to secure this account (or nothing to use the master passphrase): - Please confirm the passphrase by entering it again: - Enter a hint to help you remember this passphrase: 321 backwards - Created key 055dde03-47ff-dded-8950-0fe39b1fa101 - Name: test - Password hint: 321 backwards - ICAP: XE472EVKU3CGMJF2YQ0J9RO1Y90BC0LDFZ - Raw hex: 0092e965928626f8880629cec353d3fd7ca5974f - -All normal (aka direct) ICAP addresses begin with XE so you should be able to recognize them easily. Notice also that the key has another identifier after Created key. This is known as the UUID. This is a unique identifier for the key that has absolutely nothing to do with the account itself. Knowing it does nothing to help an attacker discover who you are on the network. It also happens to be the filename for the key, which you can find in either ~/.web3/keys (Mac or Linux) or $HOME/AppData/Web3/keys (Windows). -Now let's make sure it worked properly by listing the keys in the wallet: - -.. code-block:: Bash - - > ethkey list - 055dde03-47ff-dded-8950-0fe39b1fa101 0092e965… XE472EVKU3CGMJF2YQ0J9RO1Y90BC0LDFZ test - -It reports one key on each line (for a total of one key here). In this case our key is stored in a file 055dde... and has an ICAP address beginning XE472EVK.... Not especially easy things to remember so rather helpful that it has its proper name, test, too. - -Importing your presale wallet -================================================================================ - - -Using Mist Ethereum wallet --------------------------------------------------------------------------------- - -Importing your presale wallet using the GUI Mist Ethereum wallet is very easy. In fact, you will be asked if you want to import your presale wallet during the installation of the app. - -.. Warning:: Mist wallet is beta software. Beware and use it at your own risk. - -Instructions for installing the Mist Ethereum wallet are given in the section :ref:`Creating an account: Using Mist Ethereum wallet `. - -Simply drag-and-drop your ``.json`` presale wallet file into the designated area and enter your password to import your presale account. - -.. image:: img/51PresaleImportInstall.png - :width: 582px - :height: 469px - :scale: 75 % - :alt: presale-import - :align: center - -If you choose not to import your presale wallet during installation of the app, you can import it at any time by selecting the ``Accounts`` menu in the app’s menu bar and then selecting ``Import Pre-sale Accounts``. - -.. Note:: The Mist wallet is still in active development, so details of the steps outlined above may change with upgrades. - -Using geth --------------------------------------------------------------------------------- - -If you have a standalone installation of geth, importing your presale wallet is accomplished by executing the following command in a terminal: - -.. code-block:: Bash - - geth wallet import /path/to/my/presale-wallet.json - -You will be prompted to enter your password. - -Updating an account -================================================================================ - -You are able to upgrade your keyfile to the latest keyfile format and/or upgrade your keyfile password. - -Using geth --------------------------------------------------------------------------------- - -You can update an existing account on the command line with the ``update`` subcommand with the account address or index as parameter. Remember that the account index reflects the order of creation (lexicographic order of keyfile names containing the creation time). - -.. code-block:: Bash - - geth account update b0047c606f3af7392e073ed13253f8f4710b08b6 - -or - -.. code-block:: Bash - - geth account update 2 - -For example: - -.. code-block:: Bash - - $ geth account update a94f5374fce5edbc8e2a8697c15331677e6ebf0b - - Unlocking account a94f5374fce5edbc8e2a8697c15331677e6ebf0b | Attempt 1/3 - Passphrase: - 0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b - account 'a94f5374fce5edbc8e2a8697c15331677e6ebf0b' unlocked. - Please give a new password. Do not forget this password. - Passphrase: - Repeat Passphrase: - 0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b - -The account is saved in the newest version in encrypted format, you are prompted for a passphrase to unlock the account and another to save the updated file. This same command can be used to migrate an account of a deprecated format to the newest format or change the password for an account. - -For non-interactive use the passphrase can be specified with the ``--password`` flag: - -.. code-block:: Bash - - geth --password account update a94f5374fce5edbc8e2a8697c15331677e6ebf0bs - -Since only one password can be given, only format update can be performed, changing your password is only possible interactively. - -.. Note:: account update has the side effect that the order of your accounts may change. After a successful update, all previous formats/versions of that same key will be removed! - - -.. _backup-and-restore-accounts: - -Backup and restore accounts -================================================================================ - -Manual backup/restore --------------------------------------------------------------------------------- - -You must have an account’s keyfile to be able to send any transaction from that account. Keyfiles are found in the keystore subdirectory of your Ethereum node’s data directory. The default data directory locations are platform specific: - -- Windows: ``C:\Users\username\%appdata%\Roaming\Ethereum\keystore`` -- Linux: ``~/.ethereum/keystore`` -- Mac: ``~/Library/Ethereum/keystore`` - -To backup your keyfiles (accounts), copy either the individual keyfiles within the ``keystore`` subdirectory or copy the entire ``keystore`` folder. - -To restore your keyfiles (accounts), copy the keyfiles back into the ``keystore`` subdirectory, where they were originally. - -Importing an unencrypted private key --------------------------------------------------------------------------------- - -Importing an unencrypted private key is supported by ``geth`` - -.. code-block:: Bash - - geth account import /path/to/ - -This command imports an unencrypted private key from the plain text file ```` and creates a new account and prints the address. -The keyfile is assumed to contain an unencrypted private key as canonical EC raw bytes encoded into hex. -The account is saved in encrypted format, you are prompted for a passphrase. You must remember this passphrase to unlock your account in the future. - -An example where the data directory is specified. If the ``--datadir`` flag is not used, the new account will be created in the default data directory, i.e., the keyfile will be places in the ``keyfiles`` subdirectory of the data directory. - -.. code-block:: Bash - - $ geth --datadir /someOtherEthDataDir account import ./key.prv - The new account will be encrypted with a passphrase. - Please enter a passphrase now. - Passphrase: - Repeat Passphrase: - Address: {7f444580bfef4b9bc7e14eb7fb2a029336b07c9d} - -For non-interactive use the passphrase can be specified with the ``--password`` flag: - -.. code-block:: Bash - - geth --password account import - - -.. Note:: Since you can directly copy your encrypted accounts to another Ethereum instance, this import/export mechanism is not needed when you transfer an account between nodes. - -.. Warning:: When you copy keys into an existing node's ``keystore``, the order of accounts you are used to may change. Therefore you make sure you either do not rely on the account order or double-check and update the indexes used in your scripts. diff --git a/source/conf.py b/source/conf.py deleted file mode 100644 index ae159bb..0000000 --- a/source/conf.py +++ /dev/null @@ -1,366 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Ethereum Classic documentation build configuration file, modified by -# realcodywburns on Sat Jul 30 7:30:05 2016. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys -import os -import shlex - -# 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. -#sys.path.insert(0, os.path.abspath('.')) - -# -- General configuration ------------------------------------------------ -# def setup(sphinx): - # sys.path.insert(0, os.path.abspath('./utils')) - # from SolidityLexer import SolidityLexer - # sphinx.add_lexer('Solidity', SolidityLexer()) - -# 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.todo', - 'sphinx.ext.mathjax', - 'sphinx.ext.ifconfig', -] - -# 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 encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'Ethereum Classic' -copyright = u'2016, Ethereum classic community' -author = u'Ethereum classic community' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = u'0.1' -# The full version, including alpha/beta/rc tags. -release = u'0.1' - -# 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 - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all -# documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# highlight_language = 'Solidity' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - -# If true, keep warnings as "system message" paragraphs in the built documents. -#keep_warnings = False - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True - - -# -- 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 themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# 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'] - -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -#html_extra_path = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' -#html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# Now only 'ja' uses this config value -#html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -#html_search_scorer = 'scorer.js' - -# Output file base name for HTML help builder. -htmlhelp_basename = 'classicguidedoc' - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', -'papersize': 'a4paper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', -'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, 'classicguide.tex', u'Ethereum Classic Documentation', - u'Ethereum classic community', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- 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, 'classicguide', u'Ethereum Classic Documentation', - [author], 1) -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- 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, 'classicguide', u'Ethereum Classic Documentation', - author, 'classicguide', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False - - -# -- Options for Epub output ---------------------------------------------- - -# Bibliographic Dublin Core info. -epub_title = project -epub_author = author -epub_publisher = author -epub_copyright = copyright - -# The basename for the epub file. It defaults to the project name. -#epub_basename = project - -# The HTML theme for the epub output. Since the default themes are not optimized -# for small screen space, using the same theme for HTML and epub output is -# usually not wise. This defaults to 'epub', a theme designed to save visual -# space. -#epub_theme = 'epub' - -# The language of the text. It defaults to the language option -# or 'en' if the language is not set. -#epub_language = '' - -# The scheme of the identifier. Typical schemes are ISBN or URL. -#epub_scheme = '' - -# 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 tuple containing the cover image and cover page html template filenames. -#epub_cover = () - -# A sequence of (type, uri, title) tuples for the guide element of content.opf. -#epub_guide = () - -# HTML files that should be inserted before the pages created by sphinx. -# The format is a list of tuples containing the path and title. -#epub_pre_files = [] - -# HTML files shat should be inserted after the pages created by sphinx. -# The format is a list of tuples containing the path and title. -#epub_post_files = [] - -# A list of files that should not be packed into the epub file. -epub_exclude_files = ['search.html'] - -# The depth of the table of contents in toc.ncx. -#epub_tocdepth = 3 - -# Allow duplicate toc entries. -#epub_tocdup = True - -# Choose between 'default' and 'includehidden'. -#epub_tocscope = 'default' - -# Fix unsupported image types using the Pillow. -#epub_fix_images = False - -# Scale large images. -#epub_max_image_width = 0 - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#epub_show_urls = 'inline' - -# If false, no index is generated. -#epub_use_index = True diff --git a/source/contracts-and-transactions/accessing-contracts-and-transactions.rst b/source/contracts-and-transactions/accessing-contracts-and-transactions.rst deleted file mode 100644 index f41fab0..0000000 --- a/source/contracts-and-transactions/accessing-contracts-and-transactions.rst +++ /dev/null @@ -1,273 +0,0 @@ -******************************************************************************** -Accessing Contracts and Transactions -******************************************************************************** - -RPC -================================================================================ - -In previous sections we have seen how contracts can be written, deployed and interacted with. Now it's time to dive in the details of communicating -with the Ethereum network and smart contracts. - -An Ethereum node offers a `RPC `_ interface. This interface gives Ðapp's access to the Ethereum -blockchain and functionality that the node provides, such as compiling smart contract code. It uses a subset of the -`JSON-RPC 2.0 `_ specification (no support for notifications or named parameters) as serialisation protocol and -is available over HTTP and IPC (unix domain sockets on linux/OSX and named pipe's on Windows). - -If you are not interested in the details but are looking for an easy to use javascript library you can skip the following sections and continue with :ref:`Using Web3 `. - -Conventions -================================================================================ -The RPC interface uses a couple of conventions that are not part of the JSON-RPC 2.0 specification: - -* Numbers are hex encoded. This decision was made because some languages have no or limited support for working with extremly large numbers. To prevent - these type of errors numbers are hex encoded and it is up to the deverloper to parse these numbers and handle them appropriately. See the - `hex encoding section `_ on the wiki for examples. -* Default block number, several RPC methods accept a block number. In some cases it's not possible to give a block number or not very convenient. For - these cases the default block number can be one of these strings ["earliest", "latest", "pending"]. See the - `wiki page `_ for a list of RPC methods that use the default block parameters. - - -Deploy contract -================================================================================ -We will go through the different steps to deploy the following contract using only the RPC interface. - -.. code:: js - - contract Multiply7 { - event Print(uint); - function multiply(uint input) returns (uint) { - Print(input * 7); - return input * 7; - } - } - -The first thing to do is make sure the HTTP RPC interface is enabled. This means for geth we supply the ``--rpc`` flag on startup and for eth the ``-j`` -flag. In this example we use the geth node on a private development chain. Using this approach we don't need ether on the real network. - -.. code:: bash - - > geth --rpc --dev --mine --minerthreads 1 --unlock 0 console 2>>geth.log - -This will start the HTTP RPC interface on ``http://localhost:8545``. - -.. note:: geth supports `CORS `_, see the ``--rpccorsdomain`` flag for more information. - -We can verify that the interface is running by retrieving the coinbase address and balance using `curl `_. Please -note that data in these examples will differ on your local node. If you want to try these command replace the request params accordingly. - -.. code:: bash - - > curl --data '{"jsonrpc":"2.0","method":"eth_coinbase", "id":1}' localhost:8545 - {"id":1,"jsonrpc":"2.0","result":["0xeb85a5557e5bdc18ee1934a89d8bb402398ee26a"]} - - > curl --data '{"jsonrpc":"2.0","method":"eth_getBalance", "params": ["0xeb85a5557e5bdc18ee1934a89d8bb402398ee26a"], "id":2}' localhost:8545 - {"id":2,"jsonrpc":"2.0","result":"0x1639e49bba16280000"} - -Remember when we said that numbers are hex encoded? In this case the balance is returned in Wei as a hex string. If we want to have the balance in -Ether as a number we can use web3 from the geth console. - -.. code:: js - - > web3.fromWei("0x1639e49bba16280000", "ether") - "410" - -Now that we have some ether on our private development chain we can deploy the contract. The first step is to verify that the solidity compiler is -available. We can retrieve available compilers using the ``eth_getCompilers`` RPC method. - -.. code:: bash - - > curl --data '{"jsonrpc":"2.0","method": "eth_getCompilers", "id": 3}' localhost:8545 - {"id":3,"jsonrpc":"2.0","result":["Solidity"]} - -We can see that the solidity compiler is available. If it's not available follow `these `_ -instructions. - -The next step is to compile the Multiply7 contract to byte code that can be send to the EVM. - -.. code:: bash - - > curl --data '{"jsonrpc":"2.0","method": "eth_compileSolidity", "params": ["contract Multiply7 { event Print(uint); function multiply(uint input) returns (uint) { Print(input * 7); return input * 7; } }"], "id": 4}' localhost:8545 - {"id":4,"jsonrpc":"2.0","result":{"Multiply7":{"code":"0x6060604052605f8060106000396000f3606060405260e060020a6000350463c6888fa18114601a575b005b60586004356007810260609081526000907f24abdb5865df5079dcc5ac590ff6f01d5c16edbc5fab4e195d9febd1114503da90602090a15060070290565b5060206060f3","info":{"source":"contract Multiply7 { event Print(uint); function multiply(uint input) returns (uint) { Print(input * 7); return input * 7; } }","language":"Solidity","languageVersion":"0.2.2","compilerVersion":"0.2.2","compilerOptions":"--bin --abi --userdoc --devdoc --add-std --optimize -o /tmp/solc205309041","abiDefinition":[{"constant":false,"inputs":[{"name":"input","type":"uint256"}],"name":"multiply","outputs":[{"name":"","type":"uint256"}],"type":"function"},{"anonymous":false,"inputs":[{"indexed":false,"name":"","type":"uint256"}],"name":"Print","type":"event"}],"userDoc":{"methods":{}},"developerDoc":{"methods":{}}}}}} - -Now that we have the compiled code we need to determine how much gas it costs to deploy it. The RPC interface has an ``eth_estimateGas`` method that will -give us an estimate. - -.. code:: bash - - > curl --data '{"jsonrpc":"2.0","method": "eth_estimateGas", "params": [{"from": "0xeb85a5557e5bdc18ee1934a89d8bb402398ee26a", "data": "0x6060604052605f8060106000396000f3606060405260e060020a6000350463c6888fa18114601a575b005b60586004356007810260609081526000907f24abdb5865df5079dcc5ac590ff6f01d5c16edbc5fab4e195d9febd1114503da90602090a15060070290565b5060206060f3"}], "id": 5}' localhost:8545 - {"id":5,"jsonrpc":"2.0","result":"0xb8a9"} - -And finally deploy the contract. - -.. code:: bash - - > curl --data '{"jsonrpc":"2.0","method": "eth_sendTransaction", "params": [{"from": "0xeb85a5557e5bdc18ee1934a89d8bb402398ee26a", "gas": "0xb8a9", "data": "0x6060604052605f8060106000396000f3606060405260e060020a6000350463c6888fa18114601a575b005b60586004356007810260609081526000907f24abdb5865df5079dcc5ac590ff6f01d5c16edbc5fab4e195d9febd1114503da90602090a15060070290565b5060206060f3"}], "id": 6}' localhost:8545 - {"id":6,"jsonrpc":"2.0","result":"0x3a90b5face52c4c5f30d507ccf51b0209ca628c6824d0532bcd6283df7c08a7c"} - -The transaction is accepted by the node and a transaction hash is returned. We can use this hash to track the transaction. - -The next step is to determine the address where our contract is deployed. Each executed transaction will create a receipt. This receipt contains -various information about the transaction such as in which block the transaction was included and how much gas was used by the EVM. If a transaction -creates a contract it will also contain the contract address. We can retrieve the receipt with the ``eth_getTransactionReceipt`` RPC method. - -.. code:: bash - - > curl --data '{"jsonrpc":"2.0","method": "eth_getTransactionReceipt", "params": ["0x3a90b5face52c4c5f30d507ccf51b0209ca628c6824d0532bcd6283df7c08a7c"], "id": 7}' localhost:8545 - {"id":7,"jsonrpc":"2.0","result":{"transactionHash":"0x3a90b5face52c4c5f30d507ccf51b0209ca628c6824d0532bcd6283df7c08a7c","transactionIndex":"0x0","blockNumber":"0x4c","blockHash":"0xe286656e478a1b99030e318d0f5c3a61a644f25e63deaa8be52e80da1e7b0c47","cumulativeGasUsed":"0xb8a9","gasUsed":"0xb8a9","contractAddress":"0x6ff93b4b46b41c0c3c9baee01c255d3b4675963d","logs":[]}} - -We can see that our contract was created on ``0x6ff93b4b46b41c0c3c9baee01c255d3b4675963d``. If you got null instead of a receipt the transaction has -not been included in a block yet. Wait for a moment and check if your miner is running and retry it. - - -Interacting with smart contracts -================================================================================ -Now that our contract is deployed we can interact with it. There are 2 methods for this, sending a transaction or :ref:`using call as previously explained `. In this example we will be sending a transaction to the multiply method of the contract. - -If we look at the documentation for the `eth_sendTransaction `_ we can see that we need to supply -several arguments. In our case we need to specify the ``from``, ``to`` and ``data`` arguments. ``From`` is the public address of our account and ``to`` -the contract address. The ``data`` argument is a bit harder. It contains a payload that defines which method must be called and with which arguments. -This is were the ABI comes into play. The ABI defines how to define and encode data for the EVM. You can read -`all the details about the ABI here `_. - -The bytes of the payload is the function selector and defines which method is called. This is done by taking the first 4 bytes from the Keccak hash -over the function name and its argument types and hex encode it. The `multiply` function accepts an `uint` which is an -`alias `_ for `uint256`. This leaves us with: - -.. code:: js - - > web3.sha3("multiply(uint256)").substring(0, 8) - "c6888fa1" - -See for details `this page `_. - -The next step is to encode the arguments. We only have one uint256, lets assume we supply the value 6. The ABI has a -`section `_ which specifies how to encode uint256 types. - - `int: enc(X) is the big-endian two's complement encoding of X, padded on the higher-oder (left) side with 0xff for negative X and with zero bytes - for positive X such that the length is a multiple of 32 bytes.` - -This encodes to ``0000000000000000000000000000000000000000000000000000000000000006``. - -Combining the function selector and the encoded argument our ``data`` will be ``0xc6888fa10000000000000000000000000000000000000000000000000000000000000006``. - -Lets try it: - -.. code:: bash - - > curl --data '{"jsonrpc":"2.0","method": "eth_sendTransaction", "params": [{"from": "0xeb85a5557e5bdc18ee1934a89d8bb402398ee26a", "to": "0x6ff93b4b46b41c0c3c9baee01c255d3b4675963d", "data": "0xc6888fa10000000000000000000000000000000000000000000000000000000000000006"}], "id": 8}' localhost:8545 - {"id":8,"jsonrpc":"2.0","result":"0x759cf065cbc22e9d779748dc53763854e5376eea07409e590c990eafc0869d74"} - -Since we sent a transaction we got the transaction hash returned. If we retrieve the receipt we can see something new: - -.. code-block:: js - :emphasize-lines: 7 - - { - blockHash: "0xbf0a347307b8c63dd8c1d3d7cbdc0b463e6e7c9bf0a35be40393588242f01d55", - blockNumber: 268, - contractAddress: null, - cumulativeGasUsed: 22631, - gasUsed: 22631, - logs: [{ - address: "0x6ff93b4b46b41c0c3c9baee01c255d3b4675963d", - blockHash: "0xbf0a347307b8c63dd8c1d3d7cbdc0b463e6e7c9bf0a35be40393588242f01d55", - blockNumber: 268, - data: "0x000000000000000000000000000000000000000000000000000000000000002a", - logIndex: 0, - topics: ["0x24abdb5865df5079dcc5ac590ff6f01d5c16edbc5fab4e195d9febd1114503da"], - transactionHash: "0x759cf065cbc22e9d779748dc53763854e5376eea07409e590c990eafc0869d74", - transactionIndex: 0 - }], - transactionHash: "0x759cf065cbc22e9d779748dc53763854e5376eea07409e590c990eafc0869d74", - transactionIndex: 0 - } - -The receipt contains a log. This log was generated by the EVM on transaction execution and included in the receipt. If we look at the multipy function -we can see that the Print event was raised with the input times 7. Since the argument for the Print event was a uint256 we can decode it according to -the ABI rules which will leave us with the expected decimal 42. Apart from the data it is worth noting that topics can be used to determine which -event created the log: - -.. code:: js - - > web3.sha3("Print(uint256)") - "24abdb5865df5079dcc5ac590ff6f01d5c16edbc5fab4e195d9febd1114503da" - -You can read more about events, topics and indexing in the `Solidity tutorial `_. - -This was just a brief introduction into some of the most common tasks. See for a full list of available RPC methods the -`RPC wiki page `_. - -.. _using_web3.js: - -Web3.js -================================================================================ -As we have seen in the previous example using the JSON-RPC interface can be quite tedious and error-prone, especially when we have to deal with the -ABI. Web3.js is a javascript library that works on top of the Ethereum RPC interface. Its goal is to provide a more user friendly interface and -reducing the chance for errors. - -Deploying the Multiply7 contract using web3 would look like: - -.. code:: js - - var source = 'contract Multiply7 { event Print(uint); function multiply(uint input) returns (uint) { Print(input * 7); return input * 7; } }'; - var compiled = web3.eth.compile.solidity(source); - var code = compiled.Multiply7.code; - var abi = compiled.Multiply7.info.abiDefinition; - - web3.eth.contract(abi).new({from: "0xeb85a5557e5bdc18ee1934a89d8bb402398ee26a", data: code}, function (err, contract) { - if (!err && contract.address) - console.log("deployed on:", contract.address); - } - ); - - deployed on: 0x0ab60714033847ad7f0677cc7514db48313976e2 - -Load a deployed contract and send a transaction: - -.. code:: js - - var source = 'contract Multiply7 { event Print(uint); function multiply(uint input) returns (uint) { Print(input * 7); return input * 7; } }'; - var compiled = web3.eth.compile.solidity(source); - var Multiply7 = web3.eth.contract(compiled.Multiply7.info.abiDefinition); - var multi = Multiply7.at("0x0ab60714033847ad7f0677cc7514db48313976e2") - multi.multiply.sendTransaction(6, {from: "0xeb85a5557e5bdc18ee1934a89d8bb402398ee26a"}) - -Register a callback which is called when the ``Print`` event created a log. - -.. code:: js - - multi.Print(function(err, data) { console.log(JSON.stringify(data)) }) - {"address":"0x0ab60714033847ad7f0677cc7514db48313976e2","args": {"":"21"},"blockHash":"0x259c7dc07c99eed9dd884dcaf3e00a81b2a1c83df2d9855ce14c464b59f0c8b3","blockNumber":539,"event":"Print","logIndex":0, "transactionHash":"0x5c115aaa5418118457e96d3c44a3b66fe9f2bead630d79455d0ecd832dc88d48","transactionIndex":0} - -See for more information the `web3.js `_ wiki page. - -Console -================================================================================ - -The geth `console `_ offers a command line interface with a javascript runtime. It -can connect to a local or remote geth or eth node. It will load the web3.js library that users can use. This allows users to deploy and interact with -smart contract from the console using web3.js. In fact the examples in the :ref:`Web3.js ` section can by copied into the console. - - -Viewing Contracts and Transactions -================================================================================ - -There are several online blockchain explorers available that will allow you to inspect the Ethereum blockchain. -See for a list: :ref:`Blockchain explorers `. - - -.. _blockchain_explorers: - -Hosted blockchain explorers --------------------------------------------------------------------------------- - -- `EtherChain `_ -- `EtherCamp `_ -- `EtherScan `_ (and for `Testnet `_) - -Other Resources --------------------------------------------------------------------------------- - -* `EtherNodes `_ - Geographic distribution of nodes and split by client -* `EtherListen `_ - Realtime Ethereum transaction visualizer and audializer - diff --git a/source/contracts-and-transactions/account-types-gas-and-transactions.rst b/source/contracts-and-transactions/account-types-gas-and-transactions.rst deleted file mode 100644 index e56777b..0000000 --- a/source/contracts-and-transactions/account-types-gas-and-transactions.rst +++ /dev/null @@ -1,198 +0,0 @@ -.. _account-types-gas-and-transactions: - -******************************************************************************** -Account Types, Gas, and Transactions -******************************************************************************** - -EOA vs contract accounts -================================================================================ - -There are two types of accounts in Ethereum - - Externally Owned Accounts - - Contracts Accounts - -This distinction might be eliminated in Serenity. - -Externally owned accounts (EOAs) --------------------------------------------------------------------------------- - -An externally controlled account - -- has an Ether balance, -- can send transactions (ether transfer or trigger contract code), -- is controlled by private keys, -- has no associated code. - -Contract accounts --------------------------------------------------------------------------------- - -A contract - -- has an Ether balance, -- has associated code, -- code execution is triggered by transactions or messages (calls) received from other contracts. -- when executed - - perform operations of arbitrary complexity (Turing completeness) - - manipulate its own persistent storage, i.e., can have its own permanent state - - can call other contracts - - -All action on the Ethereum block chain is set in motion by transactions fired from externally owned accounts. Every time a contract account receives a transaction, its code is executed as instructed by the input parameters sent as part of the transaction. The contract code is executed by the Ethereum Virtual Machine on each node participating in the network as part of their verification of new blocks. - -This execution needs to be completely deterministic, its only context is the position of the block on the blockchain and all data available. -The blocks on the blockchain represent units of time, the blockchain itself is a temporal dimension and represents the entire history of states at the discrete time points designated by the blocks on the chain. - -All Ether balances and values are denominated in units of wei: 1 Ether is 1e18 wei. - -.. note:: "Contracts" in Ethereum should not be seen as something that should be "fulfilled" or "complied with"; rather, they are more like "autonomous agents" that live inside of the Ethereum execution environment, always executing a specific piece of code when "poked" by a message or transaction, and having direct control over their own ether balance and their own key/value store to store their permanent state. - -What is a transaction? -================================================================================ - -The term "transaction" is used in Ethereum to refer to the signed data package that stores a message to be sent from an externally owned account to another account on the blockchain. - -Transactions contain: - - the recipient of the message, - - a signature identifying the sender and proving their intention to send the message via the blockchain to the recipient, - - ``VALUE`` field - The amount of wei to transfer from the sender to the recipient, - - an optional data field, which can contain the message sent to a contract, - - a ``STARTGAS`` value, representing the maximum number of computational steps the transaction execution is allowed to take, - - a ``GASPRICE`` value, representing the fee the sender is willing to pay for gas. One unit of gas corresponds to the execution of one atomic instruction, i.e., a computational step. - -What is a message? -================================================================================ - -Contracts have the ability to send "messages" to other contracts. Messages are virtual objects that are never serialized and exist only in the Ethereum execution environment. -They can be conceived of as function calls. - -A message contains: - - the sender of the message (implicit). - - the recipient of the message - - ``VALUE`` field - The amount of wei to transfer alongside the message to the contract address, - - an optional data field, that is the actual input data to the contract - - a ``STARTGAS`` value, which limits the maximum amount of gas the code execution triggered by the message can incur. - -Essentially, a message is like a transaction, except it is produced by a contract and not an external actor. A message is produced when a contract currently executing code executes the ``CALL`` or ``DELEGATECALL`` opcodes, which produces and executes a message. Like a transaction, a message leads to the recipient account running its code. Thus, contracts can have relationships with other contracts in exactly the same way that external actors can. - -What is gas? -================================================================================ - -Ethereum implements an execution environment on the blockchain called the Ethereum Virtual Machine (EVM). Every node participating in the network runs the EVM as part of the block verification protocol. They go through the transactions listed in the block they are verifying and run the code as triggered by the transaction within the EVM. Each and every full node in the network does the same calculations and stores the same values. Clearly Ethereum is not about optimising efficiency of computation. Its parallel processing is redundantly parallel. This is to offer an efficient way to reach consensus on the system state without needing trusted third parties, oracles or violence monopolies. But importantly they are not there for optimal computation. The fact that contract executions are redundantly replicated across nodes, naturally makes them expensive, which generally creates an incentive not to use the blockchain for computation that can be done offchain. - -When you are running a decentralized application (dapp), it interacts with the blockchain to read and modify its state, but dapps will typically only put the business logic and state that are crucial for consensus on the blockchain. - -When a contract is executed as a result of being triggered by a message or transaction, every instruction is executed on every node of the network. This has a cost: for every executed operation there is a specified cost, expressed in a number of gas units. - -Gas is the name for the execution fee that senders of transactions need to pay for every operation made on an Ethereum blockchain. The name gas is inspired by the view that this fee acts as cryptofuel, driving the motion of smart contracts. Gas is purchased for ether from the miners that execute the code. Gas and ether are decoupled deliberately since units of gas align with computation units having a natural cost, while the price of ether generally fluctuates as a result of market forces. The two are mediated by a free market: the price of gas is actually decided by the miners, who can refuse to process a transaction with a lower gas price than their minimum limit. To get gas you simply need to add ether to your account. The Ethereum clients automatically purchase gas for your Ether in the amount you specify as your maximum expenditure for the transaction. - -The Ethereum protocol charges a fee per computational step that is executed in a contract or transaction to prevent deliberate attacks and abuse on the Ethereum network. Every transaction is required to include a gas limit and a fee that it is willing to pay per gas. Miners have the choice of including the transaction and collecting the fee or not. If the total amount of gas used by the computational steps spawned by the transaction, including the original message and any sub-messages that may be triggered, is less than or equal to the gas limit, then the transaction is processed. If the total gas exceeds the gas limit, then all changes are reverted, except that the transaction is still valid and the fee can still be collected by the miner. All excess gas not used by the transaction execution is reimbursed to the sender as Ether. You do not need to worry about overspending, since you are only charged for the gas you consume. This means that it is useful as well as safe to send transactions with a gas limit well above the estimates. - -Estimating transaction costs -================================================================================ - -The total ether cost of a transaction is based on 2 factors: - -``gasUsed`` is the total gas that is consumed by the transaction - -``gasPrice`` price (in ether) of one unit of gas specified in the transaction - -**Total cost = gasUsed * gasPrice** - -gasUsed --------------------------------------------------------------------------------- - -Each operation in the EVM was assigned a number of how much gas it consumes. ``gasUsed`` is the sum of all the gas for all the operations executed. There is a `spreadsheet `_ which offers a glimpse to some of the analysis behind this. - -For estimating ``gasUsed``, there is an `estimateGas API `_ that can be used but has some caveats. - -gasPrice --------------------------------------------------------------------------------- - -A user constructs and signs a transaction, and each user may specify whatever ``gasPrice`` they desire, which can be zero. However, the Ethereum clients launched at Frontier had a default gasPrice of 0.05e12 wei. As miners optimize for their revenue, if most transactions are being submitted with a gasPrice of 0.05e12 wei, it would be difficult to convince a miner to accept a transaction that specified a lower, or zero, gasPrice. - -Example transaction cost --------------------------------------------------------------------------------- - -Let’s take a contract that just adds 2 numbers. The EVM OPCODE ``ADD`` consumes 3 gas. - -The approximate cost, using the default gas price (as of January 2016), would be: - -3 \* 0.05e12 = 1.5e11 wei - -Since 1 Ether is 1e18 wei, the total cost would be 0.00000015 Ether. - -This is a simplification since it ignores some costs, such as the cost of passing the 2 numbers to contract, before they can even be added. - -* `question `_ -* `gas fees `_ -* `gas cost calculator `_ -* `Ethereum Gas Prices `_ - -================= ========= ============================= -Operation Name Gas Cost Remark -================= ========= ============================= -step 1 default amount per execution cycle -stop 0 free -suicide 0 free -sha3 20 -sload 20 get from permanent storage -sstore 100 put into permanent storage -balance 20 -create 100 contract creation -call 20 initiating a read-only call -memory 1 every additional word when expanding memory -txdata 5 every byte of data or code for a transaction -transaction 500 base fee transaction -contract creation 53000 changed in homestead from 21000 -================= ========= ============================= - -Account interactions example - betting contract -================================================================================ - -As previously mentioned, there are two types of accounts: - -* **Externally owned account (EOAs)**: an account controlled by a private key, and if you own the private key associated with the EOA you have the ability to send ether and messages from it. -* **Contract**: an account that has its own code, and is controlled by code. - -By default, the Ethereum execution environment is lifeless; nothing happens and the state of every account remains the same. However, any user can trigger an action by sending a transaction from an externally owned account, setting Ethereum's wheels in motion. If the destination of the transaction is another EOA, then the transaction may transfer some ether but otherwise does nothing. However, if the destination is a contract, then the contract in turn activates, and automatically runs its code. - -The code has the ability to read/write to its own internal storage (a database mapping 32-byte keys to 32-byte values), read the storage of the received message, and send messages to other contracts, triggering their execution in turn. Once execution stops, and all sub-executions triggered by a message sent by a contract stop (this all happens in a deterministic and synchronous order, ie. a sub-call completes fully before the parent call goes any further), the execution environment halts once again, until woken by the next transaction. - -Contracts generally serve four purposes: - -* Maintain a data store representing something which is useful to either other contracts or to the outside world; one example of this is a contract that simulates a currency, and another is a contract that records membership in a particular organization. -* Serve as a sort of externally-owned account with a more complicated access policy; this is called a "forwarding contract" and typically involves simply resending incoming messages to some desired destination only if certain conditions are met; for example, one can have a forwarding contract that waits until two out of a given three private keys have confirmed a particular message before resending it (ie. multisig). More complex forwarding contracts have different conditions based on the nature of the message sent. The simplest use case for this functionality is a withdrawal limit that is overrideable via some more complicated access procedure. A wallet contract is a good example of this. -* Manage an ongoing contract or relationship between multiple users. Examples of this include a financial contract, an escrow with some particular set of mediators, or some kind of insurance. One can also have an open contract that one party leaves open for any other party to engage with at any time; one example of this is a contract that automatically pays a bounty to whoever submits a valid solution to some mathematical problem, or proves that it is providing some computational resource. -* Provide functions to other contracts, essentially serving as a software library. - -Contracts interact with each other through an activity that is alternately called either "calling" or "sending messages". A "message" is an object containing some quantity of ether, a byte-array of data of any size, the addresses of a sender and a recipient. When a contract receives a message, it has the option of returning some data, which the original sender of the message can then immediately use. In this way, sending a message is exactly like calling a function. - -Because contracts can play such different roles, we expect that contracts will be interacting with each other. As an example, consider a situation where Alice and Bob are betting 100 GavCoin that the temperature in San Francisco will not exceed 35ºC at any point in the next year. However, Alice is very security-conscious, and as her primary account uses a forwarding contract which only sends messages with the approval of two out of three private keys. Bob is paranoid about quantum cryptography, so he uses a forwarding contract which passes along only messages that have been signed with Lamport signatures alongside traditional ECDSA (but because he's old fashioned, he prefers to use a version of Lamport sigs based on SHA256, which is not supported in Ethereum directly). - -The betting contract itself needs to fetch data about the San Francisco weather from some contract, and it also needs to talk to the GavCoin contract when it wants to actually send the GavCoin to either Alice or Bob (or, more precisely, Alice or Bob's forwarding contract). We can show the relationships between the accounts thus: - -.. image:: ../img/contract_relationship.png -.. - :align: center - -When Bob wants to finalize the bet, the following steps happen: - -1. A transaction is sent, triggering a message from Bob's EOA to his forwarding contract. -2. Bob's forwarding contract sends the hash of the message and the Lamport signature to a contract which functions as a Lamport signature verification library. -3. The Lamport signature verification library sees that Bob wants a SHA256-based Lamport sig, so it calls the SHA256 library many times as needed to verify the signature. -4. Once the Lamport signature verification library returns 1, signifying that the signature has been verified, it sends a message to the contract representing the bet. -5. The bet contract checks the contract providing the San Francisco temperature to see what the temperature is. -6. The bet contract sees that the response to the messages shows that the temperature is above 35ºC, so it sends a message to the GavCoin contract to move the GavCoin from its account to Bob's forwarding contract. - -Note that the GavCoin is all "stored" as entries in the GavCoin contract's database; the word "account" in the context of step 6 simply means that there is a data entry in the GavCoin contract storage with a key for the bet contract's address and a value for its balance. After receiving this message, the GavCoin contract decreases this value by some amount and increases the value in the entry corresponding to Bob's forwarding contract's address. We can see these steps in the following diagram: - -.. image:: ../img/contract_relationship2.png -.. - :align: center - -Signing transactions offline -================================================================================ - -[ Maybe add this to the FAQ and point to the ethkey section of turboethereum guide? ] - -* `Resilience Raw Transaction Broadcaster `_ diff --git a/source/contracts-and-transactions/contracts.rst b/source/contracts-and-transactions/contracts.rst deleted file mode 100644 index 777d346..0000000 --- a/source/contracts-and-transactions/contracts.rst +++ /dev/null @@ -1,508 +0,0 @@ -.. _Contracts: - -******************************************************************************** -Contracts -******************************************************************************** - -What is a contract? -================================================================================ - -A contract is a collection of code (its functions) and data (its state) that -resides at a specific address on the Ethereum blockchain. Contract accounts are -able to pass messages between themselves as well as doing practically Turing -complete computation. Contracts live on the blockchain in a Ethereum-specific -binary format called Ethereum Virtual Machine (EVM) bytecode. - -Contracts are typically written in some high level language such as `Solidity -`_ and then compiled into bytecode -to be uploaded on the blockchain. - -.. seealso:: Other languages also exist, notably Serpent and LLL, which are described further in the :ref:`ethereum-high-level-languages` section of this documentation. - -:ref:`IDE-or-development-framework` lists the integrated development environments, developer tools that help you develop in these languages, offering testing, and deployment support among other features. - -.. _ethereum-high-level-languages: - -Ethereum high level languages -=========================================================================== - -Contracts live on the blockchain in an Ethereum-specific binary format (EVM bytecode) that is executed by the Ethereum Virtual Machine (EVM). However, contracts are typically written in a higher level language and then compiled using the EVM compiler into byte code to be deployed to the blockchain. - -Below are the different high level languages developers can use to write smart contracts for Ethereum. - -Solidity --------------------------------------------------------------------------------- - -Solidity is a language similar to JavaScript which allows you to develop contracts and compile to EVM bytecode. It is currently the flagship language of Ethereum and the most popular. - -* `Solidity Documentation `_ - Solidity is the flagship Ethereum high level language that is used to write contracts. -* `Solidity online realtime compiler `_ -* `Standardized Contract APIs `__ -* `Useful Ðapp Patterns `__ - Code snippets which are useful for Ðapp development. - -Serpent --------------------------------------------------------------------------------- - -Serpent is a language similar to Python which can be used to develop contracts and compile to EVM bytecode. It is intended to be maximally clean and simple, combining many of the efficiency benefits of a low-level language with ease-of-use in programming style, and at the same time adding special domain-specific features for contract programming. Serpent is compiled using _`LLL`. - -* `Serpent on the ethereum wiki `_ -* `Serpent EVM compiler `_ - -LLL --------------------------------------------------------------------------------- - -`Lisp Like Language (LLL) `_ is a low level language similar to Assembly. It is meant to be very simple and minimalistic; essentially just a tiny wrapper over coding in EVM directly. - -* `LIBLLL in GitHub `_ -* `Examples of LLL `_ - -Mutan (deprecated) --------------------------------------------------------------------------------- - -`Mutan `_ is a statically typed, C-like language designed and developed by Jeffrey Wilcke. It is no longer maintained. - - -Writing a contract -================================================================================ - -No language would be complete without a Hello World program. Operating within -the Ethereum environment, Solidity has no obvious way of "outputting" a string. -The closest we can do is to use a *log event* to place a string into the -blockchain: - -.. code:: js - - contract HelloWorld { - event Print(string out); - function() { Print("Hello, World!"); } - } - -This contract will create a log entry on the blockchain of type Print with a -parameter "Hello, World!" each time it is executed. - -.. seealso:: `Solidity docs `_ has more examples and guidelines to writing Solidity code. - -Compiling a contract -================================================================================ - -Compilation of solidity contracts can be accomplished via a number of -mechanisms. - -* Using the ``solc`` compiler via the command line. -* Using ``web3.eth.compile.solidity`` in the javascript console provided by - ``geth`` or ``eth`` (This still requires the ``solc`` compiler to be - installed). -* The `online Solidity realtime compiler `_. -* The `Meteor dapp Cosmo for building solidity contracts `_. -* The `Mix IDE `_. -* The `Ethereum Wallet `_. - -.. note:: More information on solc and compiling Solidity contract code can be found `here `_. - - -Setting up the solidity compiler in geth --------------------------------------------------------------------------------- - -If you start up your ``geth`` node, you can check which compilers are -available. - -.. code:: bash - - > web3.eth.getCompilers(); - ["lll", "solidity", "serpent"] - -This command returns an array of strings indicating which compilers are -currently available. - -.. note:: - The ``solc`` compiler is installed with ``cpp-ethereum``. Alternatively, - you can `build it yourself - `_. - - -If your ``solc`` executable is in a non-standard location you can specify a -custom path to the ``solc`` executable using th ``--solc`` flag. - -.. code:: bash - - $ geth --solc /usr/local/bin/solc - -Alternatively, you can set this option at runtime via the console: - -.. code:: bash - - > admin.setSolc("/usr/local/bin/solc") - solc, the solidity compiler commandline interface - Version: 0.2.2-02bb315d/.-Darwin/appleclang/JIT linked to libethereum-1.2.0-8007cef0/.-Darwin/appleclang/JIT - path: /usr/local/bin/solc - -.. _compile_a_simple_contract: - -Compiling a simple contract --------------------------------------------------------------------------------- - -Let's compile a simple contract source: - -.. code:: bash - - > source = "contract test { function multiply(uint a) returns(uint d) { return a * 7; } }" - -This contract offers a single method **multiply** which is called with a -positive integer ``a`` and returns ``a * 7``. - -You are ready to compile solidity code in the ``geth`` JS console using -`eth\.compile\.solidity\(\) -`_: - - -.. code:: bash - - > contract = eth.compile.solidity(source).test - { - code: '605280600c6000396000f3006000357c010000000000000000000000000000000000000000000000000000000090048063c6888fa114602e57005b60376004356041565b8060005260206000f35b6000600782029050604d565b91905056', - info: { - language: 'Solidity', - languageVersion: '0', - compilerVersion: '0.9.13', - abiDefinition: [{ - constant: false, - inputs: [{ - name: 'a', - type: 'uint256' - } ], - name: 'multiply', - outputs: [{ - name: 'd', - type: 'uint256' - } ], - type: 'function' - } ], - userDoc: { - methods: { - } - }, - developerDoc: { - methods: { - } - }, - source: 'contract test { function multiply(uint a) returns(uint d) { return a * 7; } }' - } - } - -.. note:: - The compiler is also available via `RPC - `__ and therefore via - `web3\.js `__ to any in-browser Ðapp connecting to - ``geth`` via RPC/IPC. - - -The following example shows how you interface ``geth`` via JSON-RPC to -use the compiler. - -.. code:: bash - - $ geth --datadir ~/eth/ --loglevel 6 --logtostderr=true --rpc --rpcport 8100 --rpccorsdomain '*' --mine console 2>> ~/eth/eth.log - $ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_compileSolidity","params":["contract test { function multiply(uint a) returns(uint d) { return a * 7; } }"],"id":1}' http://127.0.0.1:8100 - -The compiler output for one source will give you contract objects each -representing a single contract. The actual return value of -``eth.compile.solidity`` is a map of contract name to contract object pairs. -Since our contract's name is ``test``, ``eth.compile.solidity(source).test`` -will give you the contract object for the test contract containing the -following fields: - - -.. glossary:: - - ``code`` - The compiled EVM bytecode - - ``info`` - Additional metadata output from the compiler - - ``source`` - The source code - - ``language`` - The contract language (Solidity, Serpent, LLL) - - ``languageVersion`` - The contract language version - - ``compilerVersion`` - The solidity compiler version that was used to compile this contract. - - ``abiDefinition`` - The `Application Binary Interface Definition `__ - - ``userDoc`` - The `NatSpec Doc `__ for users. - - ``developerDoc`` - The `NatSpec Doc `__ for developers. - - -The immediate structuring of the compiler output (into ``code`` and ``info``) -reflects the two very different **paths of deployment**. The compiled EVM code -is sent off to the blockchain with a contract creation transaction while the -rest (info) will ideally live on the decentralised cloud as publicly verifiable -metadata complementing the code on the blockchain. - -If your source contains multiple contracts, the output will contain an entry -for each contact, the corresponding contract info object can be retrieved with -the name of the contract as attribute name. You can try this by inspecting the -most current GlobalRegistrar code: - -.. code:: js - - contracts = eth.compile.solidity(globalRegistrarSrc) - - -Create and deploy a contract -================================================================================ - -Before you begin this section, make sure you have both an unlocked account as -well as some funds. - -You will now create a contract on the blockchain by `sending a transaction `__ to the empty address with the EVM code from the previous section as data. - -.. note:: - This can be accomplished much easier using the `online Solidity realtime - compiler `_ or the `Mix IDE - `_ program. - - -.. code:: js - - var primaryAddress = eth.accounts[0] - var abi = [{ constant: false, inputs: [{ name: 'a', type: 'uint256' } ] - var MyContract = eth.contract(abi) - var contract = MyContract.new(arg1, arg2, ..., {from: primaryAddress, data: evmByteCodeFromPreviousSection}) - -All binary data is serialised in hexadecimal form. Hex strings always have a -hex prefix ``0x``. - -.. note:: - Note that ``arg1, arg2, ...`` are the arguments for the contract - constructor, in case it accepts any. If the contract does not require any - constructor arguments then these arguments can be omitted. - -It is worth pointing out that this step requires you to pay for execution. Your -balance on the account (that you put as sender in the ``from`` field) will be -reduced according to the gas rules of the EVM once your transaction makes it -into a block. After some time, your transaction should appear included in a -block confirming that the state it brought about is a consensus. Your contract -now lives on the blockchain. - -The asynchronous way of doing the same looks like this: - -.. code-block:: js - - MyContract.new([arg1, arg2, ...,]{from: primaryAccount, data: evmCode}, function(err, contract) { - if (!err && contract.address) - console.log(contract.address); - }); - - -.. _interacting_with_a_contract: - -Interacting with a contract -================================================================================ - -Interaction with a contract is typically done using an abstraction layer such -as the `eth.contract\(\) -`_ -function which returns a javascript object with all of the contract functions -available as callable functions in javascript. - -The standard way to describe the available functions of a contract is the `ABI -definition `_. -This object is an array which describles the call signature and return values -for each available contract function. - -.. code-block:: js - - var Multiply7 = eth.contract(contract.info.abiDefinition); - var myMultiply7 = Multiply7.at(address); - -Now all the function calls specified in the ABI are made available on the -contract instance. You can just call those methods on the contract instance -in one of two ways. - -.. code-block:: js - - > myMultiply7.multiply.sendTransaction(3, {from: address}) - "0x12345" - > myMultiply7.multiply.call(3) - 21 - -When called using ``sendTransaction`` the function call is executed via sending -a transaction. This will cost ether to send and the call will be recorded -forever on the blockchain. The return value of calls made in this manner is -the hash of the stransaction. - -When called using ``call`` the function is executed locally in the EVM and the -return value of the function is returned with the function. Calls made in this -manner are not recorded on the blockchain and thus, cannot modify the internal -state of the contract. This manner of call is referred to as a **constant** -function call. Calls made in this manner do not cost any ether. - - -You should use ``call`` if you are interested only in the return value and use -``sendTransaction`` if you only care about *side effects* on the state of the -contract. - -In the example above, there are no side effects, therefore ``sendTransaction`` -only burns gas and increases the entropy of the universe. - - -Contract metadata -================================================================================ - -In the previous sections we explained how you create a contract on the -blockchain. Now we will deal with the rest of the compiler output, the -**contract metadata** or contract info. - -When interacting with a contract you did not create you might want -documentation or to look at the source code. Contract authors are encouraged -to make such information available by registering it on the blockchain or -through a third party service, such as `EtherChain -`_. The ``admin`` API provides -convenience methods to fetch this bundle for any contract that chose to -register. - -.. code:: js - - // get the contract info for contract address to do manual verification - var info = admin.getContractInfo(address) // lookup, fetch, decode - var source = info.source; - var abiDef = info.abiDefinition - - -The underlying mechanism that makes this work is is that: - -* contract info is uploaded somewhere identifiable by a *URI* which - is publicly accessible -* anyone can find out what the *URI* is only knowing the contracts - address - -These requirements are achieved using a 2 step blockchain registry. The first -step registers the contract code (hash) with a content hash in a contract -called ``HashReg``. The second step registers a url with the content hash in -the ``UrlHint`` contract. These `registry contracts -`__ -were part of the Frontier release and have carried on into Homestead. - -By using this scheme, it is sufficient to know a contract's address to look up the url and fetch the actual contract metadata info bundle. - -So if you are a conscientious contract creator, the steps are the following: - -1. Deploy the contract itself to the blockchain -2. Get the contract info json file. -3. Deploy contract info json file to any url of your choice -4. Register codehash ->content hash -> url - -The JS API makes this process very easy by providing helpers. Call -``admin.register`` to extract info from the contract, write out its json -serialisation in the given file, calculates the content hash of the file and -finally registers this content hash to the contract's code hash. Once you -deployed that file to any url, you can use ``admin.registerUrl`` to register -the url with your content hash on the blockchain as well. (Note that in case a -fixed content addressed model is used as document store, the url-hint is no -longer necessary.) - -.. code-block:: js - - source = "contract test { function multiply(uint a) returns(uint d) { return a * 7; } }" - // compile with solc - contract = eth.compile.solidity(source).test - // create contract object - var MyContract = eth.contract(contract.info.abiDefinition) - // extracts info from contract, save the json serialisation in the given file, - contenthash = admin.saveInfo(contract.info, "~/dapps/shared/contracts/test/info.json") - // send off the contract to the blockchain - MyContract.new({from: primaryAccount, data: contract.code}, function(error, contract){ - if(!error && contract.address) { - // calculates the content hash and registers it with the code hash in `HashReg` - // it uses address to send the transaction. - // returns the content hash that we use to register a url - admin.register(primaryAccount, contract.address, contenthash) - // here you deploy ~/dapps/shared/contracts/test/info.json to a url - admin.registerUrl(primaryAccount, hash, url) - } - }); - - -Testing contracts and transactions -================================================================================ - -Often you need to resort to a low level strategy of testing and debugging -contracts and transactions. This section introduces some debug tools and -practices you can use. In order to test contracts and transactions without -real-word consequences, you best test it on a private blockchain. This can be -achieved with configuring an alternative network id (select a unique integer) -and/or disable peers. It is recommended practice that for testing you use an -alternative data directory and ports so that you never even accidentally clash -with your live running node (assuming that runs using the defaults. Starting -your ``geth`` with in VM debug mode with profiling and highest logging -verbosity level is recommended: - -.. code:: bash - - geth --datadir ~/dapps/testing/00/ --port 30310 --rpcport 8110 --networkid 4567890 --nodiscover --maxpeers 0 --vmdebug --verbosity 6 --pprof --pprofport 6110 console 2>> ~/dapp/testint/00/00.log - -Before you can submit any transactions, you need set up your private test -chain. See :ref:`test-networks`. - -.. code:: js - - // create account. will prompt for password - personal.newAccount(); - // name your primary account, will often use it - primary = eth.accounts[0]; - // check your balance (denominated in ether) - balance = web3.fromWei(eth.getBalance(primary), "ether"); - -.. code:: js - - // assume an existing unlocked primary account - primary = eth.accounts[0]; - - // mine 10 blocks to generate ether - - // starting miner - miner.start(4); - // sleep for 10 blocks (this can take quite some time). - admin.sleepBlocks(10); - // then stop mining (just not to burn heat in vain) - miner.stop(); - balance = web3.fromWei(eth.getBalance(primary), "ether"); - -After you create transactions, you can force process them with the following lines: - -.. code:: js - - miner.start(1); - admin.sleepBlocks(1); - miner.stop(); - -You can check your pending transactions with: - -.. code:: js - - // shows transaction pool - txpool.status - // number of pending txs - eth.getBlockTransactionCount("pending"); - // print all pending txs - eth.getBlock("pending", true).transactions - -If you submitted contract creation transaction, you can check if the desired code actually got inserted in the current blockchain: - -.. code:: js - - txhash = eth.sendTansaction({from:primary, data: code}) - //... mining - contractaddress = eth.getTransactionReceipt(txhash); - eth.getCode(contractaddress) diff --git a/source/contracts-and-transactions/developer-tools.rst b/source/contracts-and-transactions/developer-tools.rst deleted file mode 100644 index 130b959..0000000 --- a/source/contracts-and-transactions/developer-tools.rst +++ /dev/null @@ -1,246 +0,0 @@ -.. _dapps: - -******************************************************************************** -Dapps -******************************************************************************** - -A dapp is service that enables direct interaction between end users and providers (e.g. connecting buyers and sellers in some marketplace, owners and storers in file storage). Ethereum dapps typically interface users via an HTML/Javascript web application using a Javascript API to communicate with the blockchain. Dapps would typically have their own suite of associated contracts on the blockchain which they use to encode business logic and allow persistent storage of their consensus-critical state. Remember that because of the redundant nature of computation on the Ethereum network, the gas costs of execution will always be higher than private execution offchain. This incentivizes dapp developers to restrict the amount of code they execute and amount of data they store on the blockchain. - -Dapp directories -==================================== - -Dapps that use Ethereum are compiled to the following lists. They are listed in various stages of development (concept, working prototype, live/deployed). If you are developing a dapp, consider adding an entry to these listings: - -* `Ethercasts State of the Ðapps `_ -* `Dappslist `_ -* `Dappcentral `_ - Sortable pages for Dapps with instructions, code validation, and network stats. -* `Dapps Mailing List `_ - Mailing list for developers on Ethereum (discontinued). - -The offered decentralised services listed cover a wide range of areas including finance, insurance, prediction markets, social networks, distributed computation and storage, gambling, marketplace, internet of things, governance, collaboration, development and games. - -* What apps can we eventually expect? https://www.reddit.com/r/ethereum/comments/2mnl7f/the_top_10_ether_dapps_of_2015/cm63nsf - -In the future, dapps are likely to be listed and distributed in `dappstores `_ integrated in dapp browsers. - -Dapp browsers -=========================== - -* `Mist `_ - official GUI dapp browser developed by the foundation, alpha stage. Mist as Wallet dapp is in beta. -* `Syng `_ - Mobile Ethereum browser (alpha) by Jarrad Hope - supported by DEVgrants -* `MetaMask `_ - Aaron Kumavis Davis's in-browser GUI. `Epicenter Bitcoin interview on github `_ - supported by DEVgrants -* `AlethZero `_ - C++ eth client GUI, (discontinued). -* `Supernova `_ - (discontinued). - -******************************************************************************** -Developer Tools -******************************************************************************** - - -Dapp development requires an understanding of the Web3 Javascript API, the JSON RPC API, and the Solidity programming language. - -.. note:: There are developer tools that help you develop, test, and deploy dapps in a way that automatically utilizes the resources listed below. - - -* `Web3 JavaScript API `__ - This is the main JavaScript SDK to use when you want to interact with an Ethereum node. -* `JSON RPC API `__ - This is the low level JSON RPC 2.0 interface to interface with a node. This API is used by the `Web3 JavaScript API `__. -* `Solidity Docs `__ - - Solidity is the Ethereum developed Smart Contract language, which compiles to EVM (Ethereum Virtual Machine) opcodes. -* :ref:`test-networks` - Test networks help developers develop and test Ethereum code and network interactions without spending their own Ether on the main network. Test network options are listed below. -* :ref:`IDE-or-development-framework`. This assists you in developing, - debugging, and deploying Ethereum applications. - - -.. _IDE-or-development-framework: - -Dapp development resources -===================================================== - -* `Smart contracts ELI5 `_ -* https://blog.slock.it/a-primer-to-the-decentralized-autonomous-organization-dao-69fb125bd3cd - - -* `A 101 noob's intro to programming smart contracts `_ - - - - -* `Standardised contract APIs listing `_ - -Examples ----------------------- - -* `example use of pricefeed - web3 script printing all account balances `_ -* `Example Ethereum contracts `_ - - -https://dappsforbeginners.wordpress.com/tutorials/your-first-dapp/ - -https://github.com/ethereum/wiki/wiki/Dapp-Developer-Resources - -Tutorials --------------- - -* `Dapp tutorials on ethereum.org `_ -* `Dapps for beginners tutorial series `_ -* `Eris' Solidity Tutorial Series `_ -* `Tutorials on advanced Solidity `_ -* http://ethereumj.io/blog/2015/09/09/friendly-ether-bot/ -* https://github.com/ConsenSys/ether-pudding - - -Mix-IDE -================================================================================ - -Mix is the official Ethereum IDE that allows developers to build and deploy contracts and decentralized applications on top of the Ethereum blockchain. It includes a Solidity source code debugger. -:ref:`sec:mix` - -IDEs/Frameworks -================================================================================ - -Below are developer frameworks and IDEs used for writing Ethereum dapps. - -* `Truffle `__ - Truffle is a development environment, testing framework and asset pipeline for Ethereum. -* `Dapple `__ - Dapple is a tool for Solidity developers to help build and manage complex contract systems on Ethereum-like blockchains. -* `Populus `__ - Populus is a Smart Contract development framework written in python. -* `Eris-PM `__ - The Eris Package Manager deploys and tests smart contract systems on private and public chains. -* `Embark `__ - Embark is a Ðapp development framework written in JavaScript. -* `EtherScripter \(obsolete, discontinued\) `_ -* `Resilience Raw Transaction Broadcaster `_ - - -Ethereum-console -================================================================================ - -Commandline console for Ethereum nodes. - -`Ethconsole `_ connects to an Ethereum node running in the background (tested with eth and geth) via IPC and provides an interactive javascript console containing the web3 object with admin additions. - -Here you could find a list of available commands `ethereum node control commands `_ - -To use this console you would need to start a local ethereum node with ipc communication socket enabled (file ``geth.ipc`` in data directory). -By default ipc socket should be located at you local home directory in .ethereum after you started a node. -You could also set ``--test`` option to use specific node test commands. - -.. code:: Console - - > eth --test - > ethconsole ipc://path/to/geth.ipc - -In the console you could then type - -.. code:: Console - - > web3.eth. (arguments, function(){}) - -Here the defenition of ``--test`` mode node commands: - -.. code:: Console - - > web3.test.addBlock("[RLP]", function(){}) - Add a block from a string containing it's hex RLP - > web3.test.rewindToBlock:("[int]", function(){}) - Reset the blockchain to specified block number - > web3.test.mineBlocks:("[int]", function(){}) - Mine a certain amount of NoProof blocks into chain - > web3.test.modifyTimestamp:("[int]", function(){}) - Set current block timestamp - > web3.test.setChainParams:("[json]", function(){}) - Reset the blockchain with given node configuration file - -More information about node `configuration <../network/test-networks.html#custom-networks-eth>`_ file. - -Base layer services -================================================= - -Whisper --------------------------- - -.. * TODO - Add Whisper documentation here! -.. `Whisper: the Multi DHT Messaging System with Routing Privacy. Vision & Roadmap.` - DEVCON-0 talk youtube video - -* `What is Whisper and what is it used for `_ - stackexchange Q&A -* `Gavin Wood: Shh! Whisper `_ - DEVCON-1 talk youtube video -* `Whisper overview and dream API usage `_ - -* `ELI5 `_ - - -Swarm ---------------------------- - -Swarm is a distributed storage platform and content distribution service, a native base layer service of the Ethereum web 3 stack. The primary objective of Swarm is to provide a sufficiently decentralized and redundant store of Ethereum's public record, in particular to store and distribute dapp code and data as well as block chain data. From an economic point of view, it allows participants to efficiently pool their storage and bandwidth resources in order to provide the aforementioned services to all participants. - -From the end user's perspective, Swarm is not that different from WWW, except that uploads are not to a specific server. The objective is to peer-to-peer storage and serving solution that is DDOS-resistant, zero-downtime, fault-tolerant and censorship-resistant as well as self-sustaining due to a built-in incentive system which uses peer to peer accounting and allows trading resources for payment. Swarm is designed to deeply integrate with the devp2p multiprotocol network layer of Ethereum as well as with the Ethereum blockchain for domain name resolution, service payments and content availability insurance. - - -ÐΞVcon talks on swarm -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -* `Viktor Trón, Daniel A. Nagy: Swarm `_ - Ethereum ÐΞVcon-1 talk on youtube -* `Daniel A. Nagy: Keeping the Public Record Safe and Accessible `_ - Ethereum ÐΞVcon-0 talk on youtube - -Code and status -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -* [source](https://github.com/ethereum/go-ethereum/tree/swarm) -* [issues on github](https://github.com/ethereum/go-ethereum/labels/swarm) -* [development roadmap]() - -* `ethersphere on twitter `_ -* `swarm gitter room `_ -* `swarm subreddit `_ - -Storage on and offchain - -* https://www.reddit.com/r/ethereum/comments/3hkv2f/eli5_storage_in_the_ethereum_blockchain/ -* https://www.reddit.com/r/ethereum/comments/3npsoz/ethereum_ipfs_and_filecoin/ -* `What is swarm and what is it used for? `_ - stackexchange Q&A - -Ethereum Alarm Clock --------------------------------------------------------------------------------- - -* **Author:** Piper Merriam -* **Website:** `alarm_main_website`_. -* **Documentation:** `alarm_documentation`_. - -A marketplace that facilitates scheduling transactions to occur at a later -time. Serves a similar role to things like *crontab* in unix, or *setTimeout* -in javascript. - -* `Decentralized cron service in Ethereum proposal `_ - by Peter Szilagyi - - -Ethereum Computation Market --------------------------------------------------------------------------------- - -* **Author:** Piper Merriam -* **Website:** `computation_market_main_website`_. -* **Documentation:** `computation_market_documentation`_. - -A marketplace that facilitates verifiable execution of computations off-chain. -Allows for very expernsive computations to be used within the EVM without -having to actually pay the high gas costs of executing them on-chain. - -.. _alarm_main_website: http://www.ethereum-alarm-clock.com/ -.. _alarm_documentation: http://docs.ethereum-alarm-clock.com/ -.. _computation_market_main_website: http://www.ethereum-computation-market.com/ -.. _computation_market_documentation: http://docs.ethereum-computation-market.com/ - - -BTCRelay -------------------------------------------------- - -`BTCrelay `_ - * `More information `_ (about ETH/BTC 2-way peg without modifying bitcoin code). - * `BTCrelay audit `_ - -RANDAO ------------------------------------------ - - -Random number -* https://www.reddit.com/r/ethereum/comments/49yld7/eli5_how_does_a_service_like_szabodice_grab_a/ - - -.. _the-EVM: - -The EVM -================================================================================ - -The Ethereum Virtual Machine (EVM) is the runtime environment for smart contracts in Ethereum. It is not only sandboxed, but actually completely isolated, which means that code running inside the EVM has no access to network, filesystem, or other processes. Smart contracts even have limited access to other smart contracts. - -Contracts live on the blockchain in an Ethereum-specific binary format (EVM bytecode). However, contracts are typically written in an Ethereum high level language, compiled into byte code using an EVM compiler, and finally uploaded on the blockchain using an Ethereum client. diff --git a/source/contracts-and-transactions/ethereum-tests/blockchain_tests/index.rst b/source/contracts-and-transactions/ethereum-tests/blockchain_tests/index.rst deleted file mode 100644 index 93c4f63..0000000 --- a/source/contracts-and-transactions/ethereum-tests/blockchain_tests/index.rst +++ /dev/null @@ -1,139 +0,0 @@ -.. _blockchain_tests: - -################################################################################ -Blockchain Tests -################################################################################ - -Found in ``/BlockTests``, the blockchain tests aim is to test the basic verification of a blockchain. - -``/BlockTests`` - general blockchain tests. All blocks are built on network: **Frontier** -``/BlockTests/Homestead`` - homestead blockchain tests. All blocks are built on network: **Homestead** -``/BlockTests/TestNetwork`` - transition blockchain tests. All blocks before 5th are built on network: **Frontier**, then each block should correspond to Homestead rules. - -It is based around the notion of executing a list of single blocks, described by the ``blocks`` portion of the test. The first block is the modified genesis block as described by the ``genesisBlockHeader`` portion of the test. A set of pre-existing accounts are detailed in the ``pre`` portion and form the world state of the genesis block. - -It is generally expected that the test implementer will read ``genesisBlockHeader`` and ``pre`` and build the corresponding blockchain in the client. Then the new blocks, described by its RLP found in the ``rlp`` object of the ``blocks`` (RLP of a complete block, not the block header only), is read. If the client concludes that the block is valid, it should execute the block and verify the parameters given in ``blockHeader`` (block header of the new block), ``transactions`` (transaction list) and ``uncleHeaders`` (list of uncle headers). If the client concludes that the block is invalid, it should verify that no ``blockHeader``, ``transactions`` or ``uncleHeaders`` object is present in the test. The client is expected to iterate through the list of blocks and ignore invalid blocks. - -Basic structure --------------------------------------------------------------------------------- - -:: - - { - "ValidBlocks": { - "genesisBlockHeader": { ... }, - "pre": { ... }, - "blocks" : [ - { - "chainname" : "A", - "blocknumber" : "1", - "rlp": { ... }, - "blockHeader": { ... }, - "transactions": { ... }, - "uncleHeaders": { ... } - }, - { - "chainname" : "A", - "blocknumber" : "2", - "rlp": { ... }, - "blockHeader": { ... }, - "transactions": { ... }, - "uncleHeaders": { ... } - } - ] - }, - "SomeInvalidBlocks": { - "genesisBlockHeader": { ... }, - "pre": { ... }, - "blocks" : [ - { - "chainname" : "B", - "blocknumber" : "3", - "chainnetwork" : "Frontier", - "rlp": { ... }, - }, - { - "blocknumber" : "1", - "rlp": { ... }, - "blockHeader": { ... }, - "transactions": { ... }, - "uncleHeaders": { ... } - }, - { - "blocknumber" : "1", - "chainnetwork" : "Homestead", - "rlp": { ... }, - }, - { - "blocknumber" : "2", - "rlp": { ... }, - "blockHeader": { ... }, - "transactions": { ... }, - "uncleHeaders": { ... } - } - ] - }, - ... - } - - -Sections --------------------------------------------------------------------------------- - -* The ``genesisBlockHeader`` section - -``coinbase``: - The 160-bit address to which all fees collected from the successful mining of this block be - transferred, as returned by the **COINBASE** instruction. -``difficulty``: - A scalar value corresponding to the difficulty level of this block. This can be alculated - from the previous block’s difficulty level and the timestamp, as returned by the **DIFFICULTY** instruction. -``gasLimit``: - A scalar value equal to the current limit of gas expenditure per block, as returned by the **GASLIMIT** instruction. -``number``: - A scalar value equal to the number of ancestor blocks. The genesis block has a number of zero. -``timestamp``: - A scalar value equal to the reasonable output of Unix’s time() at this block’s inception, as returned by the **TIMESTAMP** instruction. -``parentHash``: - The Keccak 256-bit hash of the parent block’s header, in its entirety -``bloom``: - The Bloom filter composed from indexable information (logger address and log topics) - contained in each log entry from the receipt of each transaction in the transactions list. -``extraData``: - An arbitrary byte array containing data relevant to this block. This must be 1024 bytes or fewer. -``gasUsed``: - A scalar value equal to the total gas used in transactions in this block. -``nonce``: - A 256-bit hash which proves that a sufficient amount of computation has been carried out on this block. -``receiptTrie``: - The Keccak 256-bit hash of the root node of the trie structure populated with the receipts of each transaction in the transactions list portion of the block. -``stateRoot``: - The Keccak 256-bit hash of the root node of the state trie, after all transactions are executed and finalisations applied. -``transactionsTrie``: - The Keccak 256-bit hash of the root node of the trie structure populated with each transaction in the transactions list portion of the block. -``uncleHash``: - The Keccak 256-bit hash of the uncles list portion of this block - -* ``pre`` section: as described in State Tests. - -* ``postState`` section: as described in State Tests (section - post). - -* ``blocks`` section is a list of block objects, which have the following format: - -* ``rlp`` section contains the complete rlp of the new block as described in the yellow paper in section 4.3.3. - -* ``blockHeader`` section describes the block header of the new block in the same format as described in `genesisBlockHeader`. - -* ``transactions`` section is a list of transactions which have the same format as in Transaction Tests. - -* ``uncleHeaders`` section is a list of block headers which have the same format as descibed in `genesisBlockHeader`. - -Optional BlockHeader Sections (Information fields) --------------------------------------------------------------------------------- - -``"blocknumber" = "int"`` is section which defines what is the order of this block. -It is used to define a situation when you have 3 blocks already imported but then it comes new version of the block 2 and 3 and thus you might have new best blockchain with blocks 1 2' 3' instead previous. If `blocknumber` is undefined then it is assumed that blocks are imported one by one. When running test, this field could be used for information purpose only. - -``"chainname" = "string"`` This is used for defining forks in the same test. You could mine blocks to chain "A": 1, 2, 3 then to chain "B": 1, 2, 3, 4 (chainB becomes primary). Then again to chain "A": 4, 5, 6 (chainA becomes primary) and so on. chainname could also be defined in uncle header section. If defined in uncle header it tells on which chain's block uncle header would be populated from. When running test, this field could be used for information purpose only. - -``"chainnetwork" = "string"`` Defines on which network rules this block was mined. (see the difference https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2.mediawiki). When running test, this field could be used for information purpose only. \ No newline at end of file diff --git a/source/contracts-and-transactions/ethereum-tests/difficulty_tests/index.rst b/source/contracts-and-transactions/ethereum-tests/difficulty_tests/index.rst deleted file mode 100644 index 1b46738..0000000 --- a/source/contracts-and-transactions/ethereum-tests/difficulty_tests/index.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. _difficulty_tests: - -################################################################################ -Difficulty Tests -################################################################################ - -Found in ``\Basic Tests\difficulty*.json`` files. This tests are designed to just check the difficulty formula of a block. - -difficulty = DIFFICULTY(currentBlockNumber, currentTimestamp, parentTimestamp, parentDifficulty) - -described at [EIP2](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2.mediawiki) point 4 with homestead changes. - -So basically this .json tests are just to check how this function is calculated on different function parameters (parentDifficulty, currentNumber) in it's extremum points. - -There are several test files: - -``difficulty.json`` - Normal Frontier/Homestead chain difficulty tests defined manually -``difficultyFrontier.json`` - Same as above, but auto-generated tests -``difficultyMorden.json`` - Tests for testnetwork difficulty. (it has different homestead transition block) -``difficultyOlimpic.json`` - Olympic network. (no homestead) -``difficultyHomestead.json`` - Tests for homestead difficulty (regardless of the block number) -``difficultyCustomHomestead.json`` - Tests for homestead difficulty (regardless of the block number) - -Basic structure --------------------------------------------------------------------------------- -:: - - { - "difficultyTest" : { - "parentTimestamp" : "42", - "parentDifficulty" : "1000000", - "currentTimestamp" : "43", - "currentBlockNumber" : "42", - "currentDifficulty" : "1000488" - } - } - -Sections --------------------------------------------------------------------------------- -* ``parentTimestamp`` - indicates the timestamp of a previous block -* ``parentDifficulty`` - indicates the difficulty of a previous block -* ``currentTimestamp`` - indicates the timestamp of a current block -* ``currentBlockNumber`` - indicates the number of a current block (previous block number = currentBlockNumber - 1) -* ``currentDifficulty`` - indicates the difficulty of a current block \ No newline at end of file diff --git a/source/contracts-and-transactions/ethereum-tests/index.rst b/source/contracts-and-transactions/ethereum-tests/index.rst deleted file mode 100644 index b0b274b..0000000 --- a/source/contracts-and-transactions/ethereum-tests/index.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. _Ethereum Tests: - -################################################################################ -Ethereum Tests -################################################################################ -| Common tests for all clients to test against. The `git repo `_ updated regulary with new tests. -| This section describes basic test concepts and templates which are created by cpp-client. -| - -.. toctree:: - :maxdepth: 2 - - using-testeth.rst - blockchain_tests/index.rst - state_tests/index.rst - rlp_tests/index.rst - difficulty_tests/index.rst - transaction_tests/index.rst - vm_tests/index.rst diff --git a/source/contracts-and-transactions/ethereum-tests/rlp_tests/index.rst b/source/contracts-and-transactions/ethereum-tests/rlp_tests/index.rst deleted file mode 100644 index 7c6279f..0000000 --- a/source/contracts-and-transactions/ethereum-tests/rlp_tests/index.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. _rlp_tests: - -################################################################################ -RLP Tests -################################################################################ - -Describes an **RLP** (https://github.com/ethereum/wiki/wiki/RLP) encoding using the .json file. -The client should read the rlp byte stream, **decode** and check whether the contents match it's json representation. Then it should try do it reverse - **encode** json rlp representation into rlp byte stream and check whether it matches the given rlp byte stream. - -If it is an invalid RLP byte stream in the test, then 'in' field would contain string 'INVALID' - -Some RLP byte streams are expected to be generated by fuzz test suite. For those examples 'in' field would contain string 'VALID' as it means that rlp should be easily decoded. - -RLP tests are located in in ``/RLPTests`` - -**Note** that RLP tests are testing a single RLP object encoding. Not a stream of RLP objects in one array. - -Basic structure --------------------------------------------------------------------------------- - -:: - - { - "rlpTest": { - "in": "dog", - "out": "83646f67" - }, - - "multilist": { - "in": [ "zw", [ 4 ], 1 ], - "out": "c6827a77c10401" - }, - - "validRLP": { - "in": "VALID", - "out": "c7c0c1c0c3c0c1c0" - }, - - "invalidRLP": { - "in": "INVALID", - "out": "bf0f000000000000021111" - }, - ... - } - -Sections --------------------------------------------------------------------------------- - -* ``in`` - json object (array, int, string) representation of the rlp byte stream (\*except values 'VALID' and 'INVALID') -* ``out`` - string of rlp bytes stream \ No newline at end of file diff --git a/source/contracts-and-transactions/ethereum-tests/state_tests/index.rst b/source/contracts-and-transactions/ethereum-tests/state_tests/index.rst deleted file mode 100644 index c648c30..0000000 --- a/source/contracts-and-transactions/ethereum-tests/state_tests/index.rst +++ /dev/null @@ -1,117 +0,0 @@ -.. _state_tests: - -################################################################################ -State Tests -################################################################################ - -Found in ``/StateTest``, the state tests aim is to test the basic workings of the state in isolation. - -It is based around the notion of executing a single transaction, described by the ``transaction`` portion of the test. The overarching environment in which it is executed is described by the ``env`` portion of the test and includes attributes of the current and previous blocks. A set of pre-existing accounts are detailed in the ``pre`` portion and form the world state prior to execution. Similarly, a set of accounts are detailed in the ``post`` portion to specify the end world state. Since the data of the blockchain is not given, the opcode ``BLOCKHASH`` could not return the hashes of the corresponding blocks. Therefore we define the hash of block number ``n`` to be ``SHA256("n")``. - -The log entries (``logs``) as well as any output returned from the code (``output``) is also detailed. - -It is generally expected that the test implementer will read ``env``, ``transaction`` and ``pre`` then check their results against ``logs``, ``out``, and ``post``. - -Basic structure --------------------------------------------------------------------------------- - -:: - - { - "test name 1": { - "env": { ... }, - "logs": { ... }, - "out": { ... }, - "post": { ... }, - "pre": { ... }, - "transaction": { ... }, - }, - "test name 2": { - "env": { ... }, - "logs": { ... }, - "out": { ... }, - "post": { ... }, - "pre": { ... }, - "transaction": { ... }, - }, - ... - } - - -Sections --------------------------------------------------------------------------------- - -* **The** ``env`` **section:** - -| ``currentCoinbase`` -| The current block's coinbase address, to be returned by the `COINBASE` instruction. -| ``currentDifficulty`` -| The current block's difficulty, to be returned by the `DIFFICULTY` instruction. -| ``currentGasLimit`` -| The current block's gas limit. -| ``currentNumber`` -| The current block's number. Also indicates network rules for the transaction. Since blocknumber = **1000000** Homestead rules are applied to transaction. (see https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2.mediawiki) -| ``currentTimestamp`` -| The current block's timestamp. -| ``previousHash`` -| The previous block's hash. -| - -* **The** ``transaction`` **section:** - -| ``data`` -| The input data passed to the execution, as used by the `CALLDATA`... instructions. Given as an array of byte values. See $DATA_ARRAY. -| ``gasLimit`` -| The total amount of gas available for the execution, as would be returned by the `GAS` instruction were it be executed first. -| ``gasPrice`` -| The price of gas for the transaction, as used by the `GASPRICE` instruction. -| ``nonce`` -| Scalar value equal to the number of transactions sent by the sender. -| ``address`` -| The address of the account under which the code is executing, to be returned by the `ADDRESS` instruction. -| ``secretKey`` -| The secret key as can be derived by the v,r,s values if the transaction. -| ``to`` -| The address of the transaction's recipient, to be returned by the `ORIGIN` instruction. -| ``value`` -| The value of the transaction (or the endowment of the create), to be returned by the `CALLVALUE`` instruction (if executed first, before any `CALL`). -| - -* **The** ``pre`` **and** ``post`` **sections each have the same format of a mapping between addresses and accounts. Each account has the format:** - -| ``balance`` -| The balance of the account. -| ``nonce`` -| The nonce of the account. -| ``code`` -| The body code of the account, given as an array of byte values. See $DATA_ARRAY. -| ``storage`` -| The account's storage, given as a mapping of keys to values. For key used notion of string as digital or hex number e.g: ``"1200"`` or ``"0x04B0"`` For values used $DATA_ARRAY. -| - -| The ``logs`` sections is a mapping between the blooms and their corresponding logentries. -| Each logentry has the format: -| ``address`` The address of the logentry. -| ``data`` The data of the logentry. -| ``topics`` The topics of the logentry, given as an array of values. -| - -Finally, there is one simple key ``output`` - -| ``output`` -| The data, given as an array of bytes, returned from the execution (using the ``RETURN`` instruction). See $DATA_ARRAY. In order to avoid big data files, there is one exception. If the output data is prefixed with ``#``, the following number represents the size of the output, and not the output directly. -| - - **$DATA_ARRAY** - type that intended to contain raw byte data - and for convenient of the users is populated with three - types of numbers, all of them should be converted and - concatenated to a byte array for VM execution. - - The types are: - - 1. number - (unsigned 64bit) - 2. "longnumber" - (any long number) - 3. "0xhex_num" - (hex format number) - - - e.g: ``````[1, 2, 10000, "0xabc345dFF", "199999999999999999999999999999999999999"]`````` \ No newline at end of file diff --git a/source/contracts-and-transactions/ethereum-tests/transaction_tests/index.rst b/source/contracts-and-transactions/ethereum-tests/transaction_tests/index.rst deleted file mode 100644 index a9638e0..0000000 --- a/source/contracts-and-transactions/ethereum-tests/transaction_tests/index.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. _transaction_tests: - -################################################################################ -Transaction Tests -################################################################################ - -Describes a complete transaction and its `RLP `_ representation using the .json file. -The client should read the rlp and check whether the transaction is valid, has the correct sender and corresponds to the transaction parameters. -If it is an invalid transaction, the transaction and the sender object will be missing. - -Basic structure --------------------------------------------------------------------------------- -:: - - { - "transactionTest1": { - "rlp" : "bytearray", - "sender" : "address", - "blocknumber" : "1000000" - "transaction" : { - "nonce" : "int", - "gasPrice" : "int", - "gasLimit" : "int", - "to" : "address", - "value" : "int", - "v" : "byte", - "r" : "256 bit unsigned int", - "s" : "256 bit unsigned int", - "data" : "byte array" - } - }, - - "invalidTransactionTest": { - "rlp" : "bytearray", - }, - ... - } - -Sections --------------------------------------------------------------------------------- - -* ``rlp`` - RLP encoded data of this transaction -* ``transaction`` - transaction described by fields -* ``nonce`` - A scalar value equal to the number of transactions sent by the sender. -* ``gasPrice`` - A scalar value equal to the number of Wei to be paid per unit of gas. -* ``gasLimit`` - A scalar value equal to the maximum amount of gas that should be used in executing this transaction. -* ``to`` - The 160-bit address of the message call's recipient or empty for a contract creation transaction. -* ``value`` - A scalar value equal to the number of Wei to be transferred to the message call's recipient or, in the case of contract creation, as an endowment to the newly created account. -* ``v, r, s`` - Values corresponding to the signature of the transaction and used to determine the sender of the transaction. -* ``sender`` - the address of the sender, derived from the v,r,s values. -* ``blocknumber`` - indicates network rules for the transaction. Since blocknumber = **1000000** Homestead rules are applied to transaction. (see https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2.mediawiki) \ No newline at end of file diff --git a/source/contracts-and-transactions/ethereum-tests/using-testeth.rst b/source/contracts-and-transactions/ethereum-tests/using-testeth.rst deleted file mode 100644 index 15f790f..0000000 --- a/source/contracts-and-transactions/ethereum-tests/using-testeth.rst +++ /dev/null @@ -1,67 +0,0 @@ - -***************************************************** -Using Testeth -***************************************************** -Ethereum cpp-client testeth tool for creation and execution of ethereum tests. - -To run tests you should open folder (see also `Installing and building <../../ethereum-clients/cpp-ethereum/index.html#installing-and-building>`_) - - ``/build/libethereum/test`` - -and execute a command ``./testeth`` This will run all test cases automatically. -To run a specific test case you could use parameter ``-t`` in the command line option: - - ``./testeth -t /`` - -Or just the test suite: - - ``./testeth -t `` - -You could also use ``--filltests`` option to rerun test creation from .json files which are located at ``../cpp-ethereum/test/.json`` - - ``./testeth -t / --filltests`` - -By default using ``--filltests`` option ``testeth`` recreate tests to the ``ETHEREUM_TEST_PATH`` folder. You might want to set this variable globally on your system like: - -| ``nano /etc/environment`` -| ``ETHEREUM_TEST_PATH="/home/user/ethereum/tests"`` -| - -Filler files are test templates which are used to fill initial parameters defined at test specification `Ethereum Tests <../ethereum-tests/index.html>`_ and then create a complete test ``.json`` file. You might find filler files very useful when creating your own tests. - -The ``--checkstate`` option adds a BOOST error if the post state of filled test differs from it's ``expected`` section. - -To specify a concrete test in a TEST_CASE file for filling/running procedure use ``--singletest`` option: - - ``./testeth -t / --singletest `` - -If you want to debug (note: testeth should be build with VMTRACE=1) a single test within a result test ``.json`` file, you might use the following command: - -| ``./testeth --log_level=test_suite --run_test=/ --singletest .json`` -| `` --vmtrace --verbosity 12`` -| or -| ``./testeth -t / --singletest --vmtrace --verbosity 12`` -| - -Some tests may use excessive resources when running, so by default they are disabled. Such tests require specific flag to be set in order to be executed. Like ``--performance``, ``--inputLimits``, ``--memory``, ``--quadratic``. You may also enable all of the tests by setting ``--all`` flag. Be careful. Enabled memory tests may stress your system to use 4GB of RAM and more. - -That's it for test execution. To read more about command line options you may run ``testeth`` with ``--help`` option. - -Now let's see what test cases are available. - -Test Cases --------------------------------------------------------------------------------- - -Almost each test case has it's filler file available at ``/webthree-umbrella/libethereum/test`` - -TEST_SUITE = BlockTests -TEST_CASES = blValidBlockTest blInvalidTransactionRLP blTransactionTest blInvalidHeaderTest userDefinedFile - -TEST_SUITE = TransactionTests -TEST_CASES = ttTransactionTest ttWrongRLPTransaction tt10mbDataField userDefinedFile - -TEST_SUITE = StateTests -TEST_CASES = stExample stSystemOperationsTest stPreCompiledContracts stLogTests stRecursiveCreate stTransactionTest stInitCodeTest stSpecialTest stRefundTest stBlockHashTest stQuadraticComplexityTest stSolidityTest stMemoryTest stCreateTest userDefinedFileState - -TEST_SUITE = VMTests -TEST_CASES = vm_tests vmArithmeticTest vmBitwiseLogicOperationTest vmSha3Test vmEnvironmentalInfoTest vmBlockInfoTest vmIOandFlowOperationsTest vmPushDupSwapTest vmLogTest vmSystemOperationsTest vmPerformanceTest vmInputLimitsTest1 vmInputLimitsTest2 vmRandom userDefinedFile diff --git a/source/contracts-and-transactions/ethereum-tests/vm_tests/index.rst b/source/contracts-and-transactions/ethereum-tests/vm_tests/index.rst deleted file mode 100644 index 732c4d0..0000000 --- a/source/contracts-and-transactions/ethereum-tests/vm_tests/index.rst +++ /dev/null @@ -1,107 +0,0 @@ -.. _vm_tests: - -################################################################################ -VM Tests -################################################################################ - -Found in ``/VMTest``, the VM tests aim is to test the basic workings of the VM in isolation. This is specifically not meant to cover transaction, creation or call processing, or management of the state trie. Indeed at least one implementation tests the VM without calling into any Trie code at all. - -It is based around the notion of executing a single piece of code as part of a transaction, described by the ``exec`` portion of the test. The overarching environment in which it is executed is described by the ``env`` portion of the test and includes attributes of the current and previous blocks. A set of pre-existing accounts are detailed in the ``pre`` portion and form the world state prior to execution. Similarly, a set of accounts are detailed in the ``post`` portion to specify the end world state. - -The gas remaining (``gas``), the log entries (``logs``) as well as any output returned from the code (``output``) is also detailed. - -Because the data of the blockchain is not given, the opcode BLOCKHASH could not return the hashes of the corresponding blocks. Therefore we define the hash of block number n to be SHA3-256("n"). - -Since these tests are meant only as a basic test of VM operation, the ``CALL`` and ``CREATE`` instructions are not actually executed. To provide the possibility of testing to guarantee they were actually run at all, a separate portion ``callcreates`` details each ``CALL`` or ``CREATE`` operation in the order they would have been executed. Furthermore, gas required is simply that of the VM execution: the gas cost for transaction processing is excluded. - -It is generally expected that the test implementer will read ``env``, ``exec`` and ``pre`` then check their results against ``gas``, ``logs``, ``out``, ``post`` and ``callcreates``. If an exception is expected, then latter sections are absent in the test. Since the reverting of the state is not part of the VM tests. - -Basic structure --------------------------------------------------------------------------------- - -:: - - { - "test name 1": { - "env": { ... }, - "pre": { ... }, - "exec": { ... }, - "gas": { ... }, - "logs": { ... }, - "out": { ... }, - "post": { ... }, - "callcreates": { ... } - }, - "test name 2": { - "env": { ... }, - "pre": { ... }, - "exec": { ... }, - "gas": { ... }, - "logs": { ... }, - "out": { ... }, - "post": { ... }, - "callcreates": { ... } - }, - ... - } - -Sections --------------------------------------------------------------------------------- - -The ``env`` section: - -* ``currentCoinbase``: The current block's coinbase address, to be returned by the ``COINBASE`` instruction. -* ``currentDifficulty``: The current block's difficulty, to be returned by the ``DIFFICULTY`` instruction. -* ``currentGasLimit``: The current block's gas limit. -* ``currentNumber``: The current block's number. -* ``currentTimestamp``: The current block's timestamp. -* ``previousHash``: The previous block's hash. - -The ``exec`` section: - -* ``address``: The address of the account under which the code is executing, to be returned by the ``ADDRESS`` instruction. -* ``origin``: The address of the execution's origin, to be returned by the ``ORIGIN`` instruction. -* ``caller``: The address of the execution's caller, to be returned by the ``CALLER`` instruction. -* ``value``: The value of the call (or the endowment of the create), to be returned by the ``CALLVALUE`` instruction. -* ``data``: The input data passed to the execution, as used by the ``CALLDATA``... instructions. Given as an array of byte values. See $DATA_ARRAY. -* ``code``: The actual code that should be executed on the VM (not the one stored in the state(address)) . See $DATA_ARRAY. -* ``gasPrice``: The price of gas for the transaction, as used by the ``GASPRICE`` instruction. -* ``gas``: The total amount of gas available for the execution, as would be returned by the ``GAS`` instruction were it be executed first. - -The ``pre`` and ``post`` sections each have the same format of a mapping between addresses and accounts. Each account has the format: - -* ``balance``: The balance of the account. -* ``nonce``: The nonce of the account. -* ``code``: The body code of the account, given as an array of byte values. See $DATA_ARRAY. -* ``storage``: The account's storage, given as a mapping of keys to values. For key used notion of string as digital or hex number e.g: ``"1200"`` or ``"0x04B0"`` For values used $DATA_ARRAY. - -The ``callcreates`` section details each ``CALL`` or ``CREATE`` instruction that has been executed. It is an array of maps with keys: - -* ``data``: An array of bytes specifying the data with which the ``CALL`` or ``CREATE`` operation was made. In the case of ``CREATE``, this would be the (initialisation) code. See $DATA_ARRAY. -* ``destination``: The receipt address to which the ``CALL`` was made, or the null address (``"0000..."``) if the corresponding operation was ``CREATE``. -* ``gasLimit``: The amount of gas with which the operation was made. -* ``value``: The value or endowment with which the operation was made. - -The ``logs`` sections is a mapping between the blooms and their corresponding logentries. Each logentry has the format: - -* ``address``: The address of the logentry. -* ``data``: The data of the logentry. -* ``topics``: The topics of the logentry, given as an array of values. - -Finally, there are two simple keys, ``gas`` and ``output``: - -* ``gas``: The amount of gas remaining after execution. -* ``output``: The data, given as an array of bytes, returned from the execution (using the ``RETURN`` instruction). See $DATA_ARRAY. - - **$DATA_ARRAY** - type that intended to contain raw byte data - and for convenient of the users is populated with three - types of numbers, all of them should be converted and - concatenated to a byte array for VM execution. - -* The types are: - 1. number - (unsigned 64bit) - 2. "longnumber" - (any long number) - 3. "0xhex_num" - (hex format number) - - - e.g: ``````[1, 2, 10000, "0xabc345dFF", "199999999999999999999999999999999999999"]`````` \ No newline at end of file diff --git a/source/contracts-and-transactions/index.rst b/source/contracts-and-transactions/index.rst deleted file mode 100644 index f615486..0000000 --- a/source/contracts-and-transactions/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -################################################################################ -Contracts and Transactions -################################################################################ - -.. toctree:: - :maxdepth: 2 - - account-types-gas-and-transactions.rst - contracts.rst - accessing-contracts-and-transactions.rst - mix.rst - developer-tools.rst - ethereum-tests/index.rst - web3-base-layer-services.rst diff --git a/source/contracts-and-transactions/mix.rst b/source/contracts-and-transactions/mix.rst deleted file mode 100644 index 3f34812..0000000 --- a/source/contracts-and-transactions/mix.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. _sec:mix: - -################################################################################ -Mix -################################################################################ - - -The IDE Mix is intended to help you as a developer to create, debug and -deploy contracts and dapps (both contracts backend and frontend). - -**WARNING - There are numerous reports of crash-at-boot issues for Mix on -OS X. The issue is a** `Heisenbug `_ -**which we have been chasing for a month or two. The best workaround we have -for right now is to use the Debug configuration, like so:** :: - - cmake -DCMAKE_BUILD_TYPE=Debug .. - -**WARNING - A replacement for Mix called** `Remix `_ -**is being worked on, so if you are experiencing issues with Mix, you might be better -to look for alternatives until Remix is more mature.** - -Start by creating a new project that consists of - -- contracts -- html files -- JavaScript files -- style files -- image files - -.. toctree:: - :maxdepth: 2 - - mix/project-editor.rst - mix/scenario-editor.rst - mix/state-viewer.rst - mix/transaction-explorer.rst - mix/javascript-console.rst - mix/transaction-debugger.rst - mix/dapp-deployment.rst - mix/codeeditor.rst - - diff --git a/source/contracts-and-transactions/mix/codeeditor.rst b/source/contracts-and-transactions/mix/codeeditor.rst deleted file mode 100644 index a63a4a5..0000000 --- a/source/contracts-and-transactions/mix/codeeditor.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. _sec:codeeditor: - -Code Editor -=========== - -This editor provides basic functionalities of a code editor. - -- In Solidity or JavaScript mode, an autocompletion plugin is available - (Ctrl + Space). - -- Increasing/decreasing the font size (Ctrl +, Ctrl -) - -- In Solidity mode, you can display the gas estimation (Tools -> - Display Gas Estimation). This will highlight all statements which - requires a minimum amount of gas. Color turns to red if the gas - required becomes important. - It will also display the max execution cost of a transaction (for - each function). diff --git a/source/contracts-and-transactions/mix/dapp-deployment.rst b/source/contracts-and-transactions/mix/dapp-deployment.rst deleted file mode 100644 index 355053a..0000000 --- a/source/contracts-and-transactions/mix/dapp-deployment.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. _sec:dapp-deployment: - -Dapps deployment -================ - -| This feature allows users to deploy the current project as a Dapp in - the main blockchain. -| This will deploy contracts and register frontend resources. - -The deployment process includes three steps: - -- | **Deploy contract**: - | This step will deploy contracts in the main blockchain. - -- | **Package dapp**: - | This step is used to package and upload frontend resources. - -- | **Register**: - | To render the Dapp, the Ethereum browser (Mist or AlethZero) needs - to access this package. This step will register the URL where the - resources are stored. - -To Deploy your Dapp, Please follow these instructions: - -| Click on ``Deploy``, ``Deploy to Network``. -| This modal dialog displays three parts (see above): - -- **Deploy contract** - -- *Select Scenario* - -“Ethereum node URL” is the location where a node is running, there must -be a node running in order to initiate deployment. - -“Pick Scenario to deploy” is a mandatory step. Mix will execute -transactions that are in the selected scenario (all transactions except -transactions that are not related to contract creation or contract -call). Mix will display all the transactions in the panel below with all -associated input parameters. - -“Gas Used”: depending on the selected scenario, Mix will display the -total gas used. - -- *Deploy Scenario* - -“Deployment account” allow selecting the account that Mix will use to -execute transactions. - -“Gas Price” shows the default gas price of the network. You can also -specify a different value. - -“Deployment cost”: depending on the value of the gas price that you want -to use and the selected scenario. this will display the amount ether -that the deployment need. - -“Deployed Contract”: before any deployment this part is empty. This will -be filled once the deployment is finished by all contract addresses that -have been created. - -“Verifications”. This will shows the number of verifications (number of -blocks generated on top of the last block which contains the last -deployed transactions). Mix keep track of all the transactions. If one -is missing (unvalidated) it will be displayed in this panel. - -- *Package dapp* - -The action “Generate Package” will create a new folder named 'www', this -folder will contain all the resources and scripts will be mapped -to the current deployed contract. -In order to publish your dapp, you need to host the www folder in a webserver (to -be replace soon by IPFS and SWARM). by default the library web3.js is not included. -If you want to be able to use the dapp in a standard web browser, you wiil need to -include this library. - - diff --git a/source/contracts-and-transactions/mix/dapp-deployment.rst~ b/source/contracts-and-transactions/mix/dapp-deployment.rst~ deleted file mode 100644 index e0b9698..0000000 --- a/source/contracts-and-transactions/mix/dapp-deployment.rst~ +++ /dev/null @@ -1,77 +0,0 @@ -.. _sec:dapp-deployment: - -Dapps deployment -================ - -| This feature allows users to deploy the current project as a Dapp in - the main blockchain. -| This will deploy contracts and register frontend resources. - -The deployment process includes three steps: - -- | **Deploy contract**: - | This step will deploy contracts in the main blockchain. - -- | **Package dapp**: - | This step is used to package and upload frontend resources. - -- | **Register**: - | To render the Dapp, the Ethereum browser (Mist or AlethZero) needs - to access this package. This step will register the URL where the - resources are stored. - -To Deploy your Dapp, Please follow these instructions: - -| Click on ``Deploy``, ``Deploy to Network``. -| This modal dialog displays three parts (see above): - -- **Deploy contract** - -- *Select Scenario* - -“Ethereum node URL” is the location where a node is running, there must -be a node running in order to initiate deployment. - -“Pick Scenario to deploy” is a mandatory step. Mix will execute -transactions that are in the selected scenario (all transactions except -transactions that are not related to contract creation or contract -call). Mix will display all the transactions in the panel below with all -associated input parameters. - -“Gas Used”: depending on the selected scenario, Mix will display the -total gas used. - -- *Deploy Scenario* - -“Deployment account” allow selecting the account that Mix will use to -execute transactions. - -“Gas Price” shows the default gas price of the network. You can also -specify a different value. - -“Deployment cost”: depending on the value of the gas price that you want -to use and the selected scenario. this will display the amount ether -that the deployment need. - -“Deployed Contract”: before any deployment this part is empty. This will -be filled once the deployment is finished by all contract addresses that -have been created. - -“Verifications”. This will shows the number of verifications (number of -blocks generated on top of the last block which contains the last -deployed transactions). Mix keep track of all the transactions. If one -is missing (unvalidated) it will be displayed in this panel. - -- **Package dapp** - -- *Generate local package* - -The action “Generate Package” will create a new folder named 'www', this -folder will contain all the resources and scripts will be mapped -to the current deployed contract. -In order to publish your dapp, you need to host the www folder in a webserver (to -be replace soon by IPFS and SWARM). by default the library web3.js is not included. -If you want to be able to use the dapp in a standard web browser, you wiil need to -include this library. - - diff --git a/source/contracts-and-transactions/mix/javascript-console.rst b/source/contracts-and-transactions/mix/javascript-console.rst deleted file mode 100644 index 1aba410..0000000 --- a/source/contracts-and-transactions/mix/javascript-console.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. _sec:javascript-console: - -JavaScript console -================== - -Mix exposes the following objects into the global window context - -web3 - Ethereum JavaScript API - -contracts: A collection of contract objects. keys represents contracts name. values are is an objects containing the following properties: - - * contract: contract object instance (created as in web3.eth.contract) - - * address: contract address from the last deployed state (see below) - - * interface: contract ABI - -Check the JavaScript API Reference for further information. - -Using the JS console to add transactions and local calls -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In case the name of the contract is “Sample” with a function named -“set”, it is possible to make a transaction to call “set” by writing: - -:: - - contracts["Sample"].contract.set(14) - -If a call can be made this will be done by writing: - -:: - - contracts["Sample"].contract.get.call() - -| It is also possible to use all properties and functions of the web3 - object: -| https://github.com/ethereum/wiki/wiki/JavaScript-API diff --git a/source/contracts-and-transactions/mix/mix_bc.png b/source/contracts-and-transactions/mix/mix_bc.png deleted file mode 100644 index 532ae6c..0000000 Binary files a/source/contracts-and-transactions/mix/mix_bc.png and /dev/null differ diff --git a/source/contracts-and-transactions/mix/project-editor.rst b/source/contracts-and-transactions/mix/project-editor.rst deleted file mode 100644 index de14ce8..0000000 --- a/source/contracts-and-transactions/mix/project-editor.rst +++ /dev/null @@ -1,88 +0,0 @@ -.. _sec:project-editor: - -Project Editor -============== - -You can use projects to manage the creation and testing of a dapp. The -project will contain data related to both backend and frontend as well -as the data related to your scenarios (blockchain interaction) for -debugging and testing. The related files will be created and saved -automatically in the project directory. - -Creating a new project ----------------------- - -The development of a dapp start with the creation of a new project. -Create a new project in the “edit” menu. Enter the project name, e.g. -“Ratings” and select a path for the project file. - -Editing backend contract file ------------------------------ - -By default, a new project contains a contract “Contract” for backend -development on the blockchain using the Solidity language and the -“index.html” for the frontend. Check the Solidity tutorial for -references. - -Edit the empty default contract “Contract”, e.g. - -:: - - contract Rating { - function setRating(bytes32 _key, uint256 _value) { - ratings[_key] = _value; - } - mapping (bytes32 => uint256) public ratings; - } - -Check the Solidity tutorial for help getting started with the solidity -programming language. - -Save changes - -Editing frontend html files -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Select default index.html file and enter the following code - -:: - - .... - - -

Ratings

-
- Store: - - - -
-
- Query: - -
-
- - - - - - - - -Then it is possible to add many contract files as well as many HTML, -JavaScript, css files diff --git a/source/contracts-and-transactions/mix/scenario-editor.rst b/source/contracts-and-transactions/mix/scenario-editor.rst deleted file mode 100644 index 7f48ea0..0000000 --- a/source/contracts-and-transactions/mix/scenario-editor.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. _sec:scenario-editor: - -Scenarios Editor -================ - -Scenarios can be used to test and debug contracts. - -A scenario is effectively a local blockchain where blocks can be mined -without PoW – otherwise testing would be quite slow ;). - -A scenario consists of a sequence of transactions. Usually, a scenario -would start with the contract creation scenarios of the dapp. In -addition, further transactions can be added to test and debug the dapp. -Scenarios can be modified, i.e. transactions can be removed. Note that a -scenario needs to be rebuilt for modifications to become effective. -Further testing can be done using local JS calls via the JS API. - -In case it’s not open, access the scenario and debugger pane by pressing -F7 or Windows > Show right or the debug button in the upper right corner -of the main window. - - -Creating and setting up a new scenario -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When you launch Mix for the first time, an empty scenario, i.e. not -containing any transactions, will be created. -Add an account named “MyAccount” and set it’s initial balance to 1 -ether. Click OK. -Rename the scenario to “Deploy”. - - -Modifying initial ether balance of an account -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Actually, we want to do a lot of tests -Edit the Genesis block parameters and set your initial account balance -to 1000 ether. -Rebuild the scenario for the change to become effective. - - -Rebuilding a scenario -~~~~~~~~~~~~~~~~~~~~~ - -Each time a transaction is modified or an account added, the scenario -has to be rebuilt for modifications to become effective. -Note that if a scenario is rebuilt the web frontend (local storage) -may also need to be reset (this is not done automatically be Mix). - - -Creating a transaction -~~~~~~~~~~~~~~~~~~~~~~ - -Let’s get some ether sent to Bob. -Create another account named “Bob” with zero ether balance. -Create a new transaction in the scenario pane. Click “Add Tx…” and -send 300 ether to Bob. -Add a block. - - -Altering and reusing scenarios -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Create a new scenario or start from a scenario with several transactions -that you duplicate first - -Rename the scenario - -Modify scenario by specifying transactions that shall be removed - -Rebuild the scenario - -Display calls -~~~~~~~~~~~~~ - -A contract call is a function invokation. This is not a transaction as -a contract call cannot change the state. -A contract call is not part of the blockchain but for practical and ux -design reason, it is convenient to display calls at the same -functional level as a transaction. The JS icon warn you that this is -not a transaction but a call. -To show/hide call, click on the menu Scenario -> Display calls. diff --git a/source/contracts-and-transactions/mix/state-viewer.rst b/source/contracts-and-transactions/mix/state-viewer.rst deleted file mode 100644 index add61a2..0000000 --- a/source/contracts-and-transactions/mix/state-viewer.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _sec:state-viewer: - -State Viewer -============ - -This panel is located below the block chain panel, in the scenario -view. -Once the blockchain has been run, this panel shows the state of the -blockchain. - -By state we mean all accounts balance (including contract and normal -account), and the storage (global variable of all deployed contract). -The content of this panel is not static, it depends on the selected -transaction on the blockchain panel. -The state shown here is the state resulting of the execution of the -selected transaction. - - -|image0| - -In that case, 2 contracts are deployed, the selected transaction -(deployment of testCtr) is the last one. so the state view shows the -storage of both TestCtr and BasicContract. - -.. |image0| image:: state_mix.png diff --git a/source/contracts-and-transactions/mix/state_mix.png b/source/contracts-and-transactions/mix/state_mix.png deleted file mode 100644 index 0cc718a..0000000 Binary files a/source/contracts-and-transactions/mix/state_mix.png and /dev/null differ diff --git a/source/contracts-and-transactions/mix/transaction-debugger.rst b/source/contracts-and-transactions/mix/transaction-debugger.rst deleted file mode 100644 index 22023ed..0000000 --- a/source/contracts-and-transactions/mix/transaction-debugger.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. _sec:transaction-debugger: - -Transaction debugger -==================== - -Mix supports both Solidity and assembly level contract code debugging. -You can toggle between the two modes to retrieve the relevant -information you need. - -At any execution point the following information is available: - -VM stack – See Yellow Paper for VM instruction description - -Call stack – Grows when contract is calling into another contract. -Double click a stack frame to view the machine state in that frame - -Storage – Storage data associated with the contract - -Memory – Machine memory allocated up to this execution point - -Call data – Transaction or call parameters - -Accessing the debug mode ------------------------- - -When transaction details are expanded, you can switch to the debugger -view by clicking on the “Debug Transaction” button - -Toggling between debug modes and stepping through transactions --------------------------------------------------------------- - -This opens the Solidity debugging mode. Switch between Solidity and EVM -debugging mode using the Menu button (Debug -> Show VM code) - -- Step through a transaction in solidity debugging mode - -- Step through a transaction in EVM debugging mode diff --git a/source/contracts-and-transactions/mix/transaction-explorer.rst b/source/contracts-and-transactions/mix/transaction-explorer.rst deleted file mode 100644 index c188189..0000000 --- a/source/contracts-and-transactions/mix/transaction-explorer.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. _sec:transaction-explorer: - -Transaction Explorer -==================== - -Using the transaction pane - -The transaction pane enables you to explore transactions receipts, -including - - * Input parameters - - * Return parameters - - * Event logs - -To display the transaction explorer, click on the down triangle icon -which is on the right of each transaction, this will expand -transaction details: - - -|image0| - -Then you can either copy the content of this transaction in the -clipboard, Edit the current transaction (you will have to rerun the -blockchain then), or debug the transaction. - -.. |image0| image:: mix_bc.png diff --git a/source/contracts-and-transactions/web3-base-layer-services.rst b/source/contracts-and-transactions/web3-base-layer-services.rst deleted file mode 100644 index f2664ba..0000000 --- a/source/contracts-and-transactions/web3-base-layer-services.rst +++ /dev/null @@ -1,40 +0,0 @@ -******************************************************************************** -Web3 Base Layer Services -******************************************************************************** - -In addition to the Ethereum blockchain, more components are being developed that decentralise other important aspects of web applications. - -.. image:: ../img/ethereum-protocols.png - -Swarm - Decentralised data storage and distribution -================================================================================ - -Swarm is a peer to peer data sharing network in which files are addressed by the hash of their content. Similar to Bittorrent, it is possible to fetch the data from many nodes at once and as long as a single node hosts a piece of data, it will remain accessible everywhere. This approach makes it possible to distribute data without having to host any kind of server - data accessibility is location independent. - -Other nodes in the network can be incentivised to replicate and store the data themselves, obviating the need for hosting services when the original nodes are not connected to the network. - - -Whisper - Decentralised messaging -================================================================================ - -A protocol for private, secure communication directly between nodes. - --------- - -Furthermore, standard contracts are being created to make the development and usage of distributed applications easier: - -Name registry -================================================================================ - -Because dapps can be stored anywhere, including the Swarm network, the name registry maps names to their content or location. This is a decentralised alternative to the Domain Name System (DNS). - -See https://github.com/ethereum/EIPs/issues/26 - -Contract registry -================================================================================ - -To publish the source code of a specific contract, its address has to be mapped to it. The contract registry stores this mapping. Users can then look up this mapping and verify the contract byte code. - -See -* global registrar code -* namereg API diff --git a/source/ether.rst b/source/ether.rst deleted file mode 100644 index f2cc6c2..0000000 --- a/source/ether.rst +++ /dev/null @@ -1,194 +0,0 @@ -******************************************************************************** -Ether -******************************************************************************** - -What is ether? -================================================================================ - -Ether is the name of the currency used within Ethereum. It is used to pay for -computation within the EVM. This is done indirectly by purchasing gas for ether as explained in _`gas`. - -Denominations --------------------------------------------------------- - -Ethereum has a metric system of denominations used as units of Ether. Each denomination has its own unique name (some bear the family name of seminal figures playing a role in evolution of computer science and cryptoeconomics). The smallest denomination aka *base unit* of Ether is called Wei. Below is a list of the named denominations and -their value in Wei. Following a common (although somewhat ambiguous) pattern, Ether also designates a unit (of 1e18 or one quintillion Wei) of the currency. Note that the currency is not called Ethereum as many mistakenly think, nor is Ethereum a unit. - - -+-------------------------+-----------+-------------------------------------------+ -| Unit | Wei Value | Wei | -+=========================+===========+===========================================+ -| **wei** | 1 wei | 1 | -+-------------------------+-----------+-------------------------------------------+ -| **Kwei (babbage)** | 1e3 wei | 1,000 | -+-------------------------+-----------+-------------------------------------------+ -| **Mwei (lovelace)** | 1e6 wei | 1,000,000 | -+-------------------------+-----------+-------------------------------------------+ -| **Gwei (shannon)** | 1e9 wei | 1,000,000,000 | -+-------------------------+-----------+-------------------------------------------+ -| **microether (szabo)** | 1e12 wei | 1,000,000,000,000 | -+-------------------------+-----------+-------------------------------------------+ -| **milliether (finney)** | 1e15 wei | 1,000,000,000,000,000 | -+-------------------------+-----------+-------------------------------------------+ -| **ether** | 1e18 wei | 1,000,000,000,000,000,000 | -+-------------------------+-----------+-------------------------------------------+ - - -Ether supply -========================= - -* https://blog.ethereum.org/2014/04/10/the-issuance-model-in-ethereum/ -* https://www.reddit.com/r/ethereum/comments/44zy88/clarification_on_ether_supply_and_cost_of_gas/ -* https://www.reddit.com/r/ethereum/comments/45vj4g/question_about_scarcity_of_ethereum_and_its/ -* https://www.reddit.com/r/ethtrader/comments/48yqg6/is_there_a_cap_like_with_btc_with_how_many_ether/ - - -Getting ether -================================================================================ - -In order to obtain Ether, you need to either - -* become an Ethereum miner (see _`Mining`) or -* trade other currencies for Ether using centralised or trustless services -* use the user friendly `Mist Ethereum GUI Wallet `_ that as of Beta 6 introduced the ability to purchase ether using the http://shapeshift.io/ API. - -Trustless services --------------------------------------------------------------------------------- - -Note that the Ethereum platform is special in that the smart contracts enable trustless services that obviate the need for trusted third parties in a currency exchange transaction, ie. disintermediate currency exchange businesses. - -Such projects (alpha/prelaunch status at the time of writing) are: - -* `BTCrelay `_ - * `More information `_ (about ETH/BTC 2-way peg without modifying bitcoin code). - * `BTCrelay audit `_ -* `EtherEx decentralised exchange `_. - -List of centralised exchange marketplaces --------------------------------------------------------------------------------- - -========================== ============================ -Exchange Currencies -========================== ============================ -Poloniex BTC -Kraken BTC, USD, EUR, CAD, GBP -Gatecoin BTC, EUR -Bitfinex BTC, USD -Bittrex BTC -Bluetrade BTC, LTC, DOGE -HitBTC BTC -Livecoin BTC -Coinsquare BTC -Bittylicious GBP -BTER CNY -Yunbi CNY -Metaexchange BTC -========================== ============================ - - -Centralised fixed rate exchanges ------------------------------------ - - -========================== ============================ -Exchange Currencies -========================== ============================ -`Shapeshift`_ BTC, LTC, DOGE, Other -`Bity`_ BTC, USD, EUR, CHF -========================== ============================ - -.. _Bity: https://bity.com -.. _Shapeshift: shapeshift.io - - -Trading and price analytics --------------------------------------------------------------------------------- - -* `ETH markets exhaustive listing by volume on coinmarketcap `_ -* Aggregating realtime stats of major ETH markets: - - * `Tradeblock `_ - * `EthereumWisdom `_ - * `Cryptocompare `_ - * `Coinmarketcap `_ - - -.. _online-wallets-and-storage-solutions: - -Online wallets, paper wallets, and cold storage -================================================================================ - -.. todo:: - This is here just a dumping ground of links and notes - Please move this over in a listing form to ecosystem - - Keep examples here, maybe explain paranoid practices, list dangers - -* Mist Ethereum Wallet - * `Releases to download `_ - * `Mist Ethereum Wallet developer preview `_ - foundation blog post - * `How to easily set up the Ethereum Mist wallet! `_ - Tutorial by Tommy Economics -* Kryptokit Jaxx - * `Jaxx main site `_ - * `Mobile release `_ -* Etherwall - * `Etherwall website `_ - * `Etherwall source `_ -* MyEtherWallet - * `MyEtherWallet website `_ - * `MyEtherWallet source `_ - * `Chrome extension `_ -* Cold storage - * `Icebox `_ by `ConsenSys `_ - Cold storage based on lightwallet with HD wallet library integrated. - * `Reddit discussion 1 `_ - * `How to setup a cold storage wallet `_ -* Hardware wallet - * `reddit discussion 2 `_ - * `reddit discussion 3 `_ -* Brain wallet - * brain wallets are not safe, do not use them. https://www.reddit.com/r/ethereum/comments/45y8m7/brain_wallets_are_now_generally_shunned_by/ - * Extreme caution with brain wallets. Read the recent controversy: https://reddit.com/r/ethereum/comments/43fhb5/brainwallets vs http://blog.ether.camp/post/138376049438/why-brain-wallet-is-the-best -* Misc - * `Kraken Wallet Sweeper Tool `_ - Pre-sale wallet import - * `Recommended ways to safely store ether `_ - * `How to buy and store ether `_ - * `A laymen's intro into brute forcing and why not to use brain wallets `_ - * `Pyethsaletool `_ - * `Account vs wallet `_ - -Sending ether -================================================================================ - -The `Ethereum Wallet `_ supports sending ether via a graphical interface. - -Ether can also be transferred using the **geth console**. - -.. code-block:: console - - > var sender = eth.accounts[0]; - > var receiver = eth.accounts[1]; - > var amount = web3.toWei(0.01, "ether") - > eth.sendTransaction({from:sender, to:receiver, value: amount}) - -For more information of Ether transfer transactions, see :ref:`account-types-gas-and-transactions`. - -Ethereum is unique in the realm of cryptocurrencies in that ether has utility value as a cryptofuel, commonly referred to as "gas". Beyond transaction fees, gas is a central part of every network request and requires the sender to pay for the computing resources consumed. The gas cost is dynamically calculated, based on the volume and complexity of the request and multiplied by the current gas price. Its value as a cryptofuel has the effect of increasing the stability and long-term demand for ether and Ethereum as a whole. For more information, see :ref:`account-types-gas-and-transactions`. - -Gas and ether -============================= - -* https://www.reddit.com/r/ethereum/comments/271qdz/can_someone_explain_the_concept_of_gas_in_ethereum/ -* https://www.reddit.com/r/ethereum/comments/3fnpr1/can_someone_possibly_explain_the_concept_of/ -* https://www.reddit.com/r/ethereum/comments/49gol3/can_ether_be_used_as_a_currency_eli5_ether_gas/ - - -Gas is supposed to be the constant cost of network resources/utilisation. You want the real cost of sending a transaction to always be the same, so you can't really expect Gas to be issued, currencies in general are volatile. - -So instead, we issue Ether whose value is supposed to vary, but also implement a Gas Price in terms of Ether. If the price of Ether goes up, the Gas Price in terms of Ether should go down to keep the real cost of Gas the same. - -Gas has multiple associated terms with it: Gas Prices, Gas Cost, Gas Limit, and Gas Fees. The principle behind Gas is to have a stable value for how much a transaction or computation costs on the Ethereum network. - -* Gas Cost is a static value for how much a computation costs in terms of Gas, and the intent is that the real value of the Gas never changes, so this cost should always stay stable over time. -* Gas Price is how much Gas costs in terms of another currency or token like Ether. To stabilise the value of gas, the Gas Price is a floating value such that if the cost of tokens or currency fluctuates, the Gas Price changes to keep the same real value. The Gas Price is set by the equilibrium price of how much users are willing to spend, and how much processing nodes are willing to accept. -* Gas Limit is the maximum amount of Gas that can be used per block, it is considered the maximum computational load, transaction volume, or block size of a block, and miners can slowly change this value over time. -* Gas Fee is effectively the amount of Gas needed to be paid to run a particular transaction or program (called a contract). The Gas Fees of a block can be used to imply the computational load, transaction volume, or size of a block. The gas fees are paid to the miners (or bonded contractors in PoS). diff --git a/source/ethereum-clients/choosing-a-client.rst b/source/ethereum-clients/choosing-a-client.rst deleted file mode 100644 index c7e2c13..0000000 --- a/source/ethereum-clients/choosing-a-client.rst +++ /dev/null @@ -1,151 +0,0 @@ -.. _sec:clients: - -***************************************************** -Choosing a client -***************************************************** - -Why are there multiple Ethereum clients? -===================================================================== - - -The Ethereum clients are very analogous to a Java VM or .NET runtime. - -They enable you to execute "Ethereum programs" on your computer. They are -implemented to a written specification (the -`Yellow Paper `_) and by design -are interoperable and somewhat "commodity". - -From the earlier days of the project there have been multiple interoperable -client implementations across a range of different operating systems. That -client diversity is a huge win for the ecosystem as a whole. -It lets us verify that the protocol is unambiguous. It keeps the door -open for new innovation. It keeps us all honest. However, it can be -very confusing for end-users, because there is no universal -"Ethereum Installer" for them to use. - -As we enter the Homestead phase, the Go client is very, very dominant, but -it hasn't always been that way, and won't necessarily be that way in the -future. All of the clients except ethereumH have Homestead-compatible -releases. The table below contains links to the latest release. - -+------------------------+------------+------------------------+-------------------------------------+ -| Client | Language | Developers | Latest release | -+========================+============+========================+=====================================+ -| :ref:`go-ethereum` | Go | `Ethereum Foundation`_ | `go-ethereum-v1.4.10`_ | -+------------------------+------------+------------------------+-------------------------------------+ -| :ref:`Parity` | Rust | `Ethcore`_ | `Parity-v1.2.2`_ | -+------------------------+------------+------------------------+-------------------------------------+ -| :ref:`cpp-ethereum` | C++ | `Ethereum Foundation`_ | `cpp-ethereum-v1.3.0`_ | -+------------------------+------------+------------------------+-------------------------------------+ -| :ref:`pyethapp` | Python | `Ethereum Foundation`_ | `pyethapp-v1.3.2`_ | -+------------------------+------------+------------------------+-------------------------------------+ -| :ref:`ethereumjs-lib` | Javascript | `Ethereum Foundation`_ | `ethereumjs-lib-v3.0.0`_ | -+------------------------+------------+------------------------+-------------------------------------+ -| :ref:`Ethereum\(J\)` | Java | `\`_ | `ethereumJ-v1.3.0-RC5-DaoHardFork`_ | -+------------------------+------------+------------------------+-------------------------------------+ -| :ref:`ruby-ethereum` | Ruby | `Jan Xie`_ | `ruby-ethereum-v0.9.3`_ | -+------------------------+------------+------------------------+-------------------------------------+ -| :ref:`ethereumH` | Haskell | `BlockApps`_ | no Homestead release yet | -+------------------------+------------+------------------------+-------------------------------------+ - -.. _Ethereum Foundation: https://ethereum.org/foundation -.. _\: http://www.ether.camp -.. _BlockApps: http://www.blockapps.net/ -.. _Ethcore: https://ethcore.io/ -.. _Jan Xie: https://github.com/janx/ - -.. _go-ethereum-v1.4.10: https://github.com/ethereum/go-ethereum/releases/tag/v1.4.10 -.. _cpp-ethereum-v1.3.0: https://github.com/bobsummerwill/cpp-ethereum/releases/tag/v1.3.0 -.. _ethereumjs-lib-v3.0.0: https://github.com/ethereumjs/ethereumjs-lib/releases/tag/v3.0.0 -.. _ethereumJ-v1.3.0-RC5-DaoHardFork: https://github.com/ethereum/ethereumj/releases/tag/1.3.0-RC5-DaoHardFork -.. _Parity-v1.2.2: https://github.com/ethcore/parity/releases/tag/v1.2.2 -.. _pyethapp-v1.3.2: https://github.com/ethereum/pyethapp/releases/tag/v1.3.2 -.. _ruby-ethereum-v0.9.3: https://rubygems.org/gems/ruby-ethereum/versions/0.9.3 - -******************************************************************************** -Installing a Client -******************************************************************************** - -There are a number of "official" clients whose development has been funded -from the resources administered by the Ethereum Foundation. There are also -various other clients which have been built by the community or by other -commercial entities. - -Read more about the specific clients in the specific client sections in this chapter. - -What should I install on my desktop/laptop? -================================================================================ - -If you have a laptop or desktop machine, you should probably just install -the `Ethereum Wallet `_ and you are done. - -- Download the latest `Ethereum Wallet ZIP `_ from Github. -- Unzip wherever you like -- Click on the executable (**Ethereum-Wallet, Ethereum-Wallet** or **Ethereum-Wallet.app**) -- The block-chain will be downloaded - -The Ethereum Wallet is a "single dapp" deployment of the **Mist Browser** -which will be the centerpiece of the Metropolis phase of development, which -comes after Homestead. - -Mist comes with bundled :ref:`go-ethereum` and :ref:`cpp-ethereum` binaries -and if you are not running a command-line Ethereum client when Mist starts -then it will start running one of the bundles clients for you. - -If you want to interact with Ethereum on the command-line, and to take -advantage of the Javascript console then you will want to install one of -the client applications directly, as well as Mist. - -:ref:`go-ethereum` and :ref:`cpp-ethereum` are the best place to start, -because they have both been under development since the start of the project, -have passed security audits, work for all platforms and have -:ref:`foundation` resources assigned to their ongoing maintenance and -support. - -- Follow the :ref:`Installing binaries` instructions for **cpp-ethereum** -- For **go-ethereum**, just unzip the `released binaries `_ - -Parity is gaining in popularity fast. - -Beyond that, of course, it is all a matter of personal preference. Try them all :-) - -If you want to do mining then Mist will not be sufficient. Check out -the :ref:`mining` section. - - -What should I install on my mobile/tablet? -================================================================================ - -We are at the very beginning of our support for mobile devices. The Go -team are publishing experimental iOS and Android libraries, which some -developers are using to start bootstrapping mobile applications, but there -are not yet any mobile Ethereum clients available. - -The main hinderance to the use of Ethereum on mobile devices is that the -Light Client support is still incomplete. The work which has been done is -off in a private branch, and is only available for the Go client. -doublethinkco will be starting development of Light Client for the C++ client -in the coming months, following grant funding. - -Check out `Syng.im `_, who were initially using -`ethereumj-personal `_ based -on :ref:`Ethereum(J)`, but have recently flipped to Geth cross-builds with -Light Client. - - -What should I install on my SBC? -================================================================================ - -You have some choice here depending on your skill level, and what you are looking to do. - -* Download a fully prepared image(link to page with detailed download & install instructions) - - * If you are new to Ethereum AND SBC boards such as the Raspberry Pi then this is for you! Simply download the image specific to the dev board you are working with, burn it to an SD card, boot your device, and run Ethereum! - -* Download a pre-compiled application(link to page with detailed download & install instructions) - - * If you already have an SBC running and have a specific, preferred OS or setup that you want to keep, then this is your best option! Depending on the platform, you can simply download the apropriate executable, and with minimal linking of libraries and setting of PATH you can have Ethereum running in your existing environment! - -* Build from source using customizable scripts(link to page with more detail and individual SBC links to https://github.com/ethembedded) - - * Looking to perform a custom install? We have scripts available to compile from source "on device". Our scripts contain auto-install of dependencies as well as the client itself. This will allow you to install a specific version of the Ethereum client(i.e.-"develop", "master", etc.), compile your own forked version of a client, and generally play around with the intracacies of the build process. diff --git a/source/ethereum-clients/cpp-ethereum/automation.rst b/source/ethereum-clients/cpp-ethereum/automation.rst deleted file mode 100644 index cedd790..0000000 --- a/source/ethereum-clients/cpp-ethereum/automation.rst +++ /dev/null @@ -1,134 +0,0 @@ -.. _cpp-ethereum-automation: - -################################################################################ -Automation setup for cpp-ethereum -################################################################################ - -At the time of writing all of the automation for cpp-ethereum is driven using -a Jenkins instance hosted at http://52.28.164.97. - -There is a "pretty alias" to the setup at http://ethbuilds.com, but that is -owned by -`Bob Summerwill `_ personally, not by the -:ref:`Ethereum Foundation `, and might end up pointing to something else at a later date. - -.. image:: ../../img/jenkins.png - :height: 256px - :width: 256px - - -It runs in parallel with the `Ethereum buildbot instance `_ -which is used for Go and Python builds. - -The fact that we have two different automation systems is not ideal, and is for -historical reasons. It would make sense for us to consolidate all -:ref:`Ethereum Foundation ` projects into a single, consistent -automation setup, but that is a non-trivial amount of work. We're talking about -that. It will be much easier to assess that when we have completed the -`repo reorg `_ -for the C++ codebase. - -The current Jenkins setup is `missing a canonical continuous integration target `_, -which is a major weakness. There is no single URL which you can visit to find -out whether the C++ builds are working or broken at HEAD. There is not even -a URL which you can visit per repository, to find if the individual repositories -are working or broken. - -We are also missing automation for `webthree-umbrella `_ as a whole, to know -whether the set of repositories which we are publishing is working or broken. - -What we **do have** is automation of our pull-requests. Those are built against -the develop branches of the repositories which they depend on. There is a -mechanism for specifying alternative branches for those dependencies, when testing -changes which span multiple repositories. But `it is broken `_. - -Here are the Jenkins projects for the PR automation. These are triggered -automatically via Github webhooks whenever new PRs are created, or when the content -of the branches for existing PRs is updated: - -* `alethzero-prs `_ - PR testing for alethzero -* `libethereum-prs `_ - PR testing for libethereum -* `libweb3core-prs `_ - PR testing for libweb3core -* `mix-prs `_ - PR testing for mix -* `solidity-prs `_ - PR testing for solidity -* `webthree-helpers-prs `_ - PR testing for webthree-helpers -* `webthree-prs `_ - PR testing for webthree - -Here are the other Jenkins projects we have: - -* `ethbinaries-develop `_ and `ethbinaries-release `_ - Projects for generating Windows and OS X binaries for the develop and release branches of the webthree-umbrella. The develop project is run nightly at midnight, UTC. The release project is run manually. -* `ppa-build-develop `_ and `ppa-build-release `_ - Projects for packaging source and build steps which are then pushing to `Launchpad `_ where they will be built, and the binaries pushed to the world if they are successful. The develop project is run nightly at midnight, UTC. The release project is run manually. -* `solidity-emscripten `_ - Solidity builds for the Emscripten architecture. This is the build target, which calls the publish target detailed below. It is run nightly at midnight, UTC. -* `update-umbrella `_ - Utility project which can be run manually to update the submodules in the webthree-umbrella project. It will soon be obsolete. It is run manually, and also nightly. - -The following projects are effectively "libraries" which are used to build the "user-facing" -projects above. - -* `ethbinaries-build `_ - Used in ethbinaries-develop and ethbinaries-release. -* `project-build `_ - Used in all the PR projects. -* `project-test `_ - Used in all the PR projects. -* `pullrequest_parser `_ - Used in all the PR projects. -* `solidity-emscripten-publisher `_ - Used in solidity-emscripten. - -Bob does not know what these Jenkins targets are. They may be obsolete. - -* `code-coverage-run `_ - -We have been making a conscious effort to `move our automation scripts into Git from Jenkins `_ -to reduce the "voodoo factor" in our automation. It is still a work in progress, but here are -some key scripts which our automation uses: - -* `homebrew/prepare_receipt.sh `_ - Build for Homebrew -* `scripts/build_emscripten.sh `_ - Build Emscripten binaries (for browser-solidity) -* `scripts/ethbinaries.sh `_ - Build Windows and OS X binaries -* `scripts/ethbuild.sh `_ - Build code (all platforms) -* `scripts/ethtests.sh `_ - Run tests (all platforms) -* `scripts/ppabuild.sh `_ - Build bundle for PPAs - -But we still have some scripts which are orphaned within Jenkins: - -* `Create ZIP of Eth in Windows powershell `_ - Used to make win_eth.zip -* `github_issue_mover.py `_ - Script used to match move issues from cpp-ethereum to webthree-umbrella repo - - -Setting up a new Jenkins slave -------------------------------------------------------------------------------- - -This is a nightmare process. Here's how to add an OS X slave. The process -for other platforms will vary, but we've not had to do it yet. - -- Install appropriate operating system (Bob had to use his own Apple login) -- Install the latest xcode from the Mac Store -- Install Homebrew - - say yes to xcode select license - - brew update - - brew upgrade - - install pre-requisites (http://www.ethdocs.org/en/latest/ethereum-clients/cpp-ethereum/building-from-source/osx.html) - - install Ruby - - See https://github.com/rbenv/rbenv#homebrew-on-mac-os-x - - brew install rbenv - - rbenv init - - rbenv install 1.9.3-p551 - - Add `eval "$(rbenv init -)"` to ~/.bash_profile: - - Connect the slave using Java web-start (have to lower security settings) - - Cut-and-paste PATH from the machine into the Configure field for the node in Jenkins: - - Example: /Users/administrator/.rbenv/shims:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin - - -Known issues -------------------------------------------------------------------------------- - -- Lack of canonical build -- Lack of webthree-umbrella builds -- No automated Windows tests -- Broken cross-repo PRs -- Hanging tests -- Incomplete test suits -- Do we run "ethereum/tests" at all? -- Do we run "ethereum/rpc-tests" at all? -- Windows box is running Windows 7 home edition. No RDC access. -- Running Visual Studio 2013. -- Should be running Windows 10 with VS2015 targeting Windows7 -- We still don't have working El Capitan binaries -- Nothing doing Homebrew/PPA updates per cycle -- No clean builds ever? diff --git a/source/ethereum-clients/cpp-ethereum/building-from-source/android.rst b/source/ethereum-clients/cpp-ethereum/building-from-source/android.rst deleted file mode 100644 index 3e4514b..0000000 --- a/source/ethereum-clients/cpp-ethereum/building-from-source/android.rst +++ /dev/null @@ -1,11 +0,0 @@ - -Building for Android --------------------------------------------------------------------------------- - -We don't currently have a working Android build, though that is -`on the roadmap `_ -for `doublethinkco `_. Android uses the Linux kernel, -but has a `different API `_ -than the ARM Linux cross-builds, meaning that specific binaries will be required. - -ARM Linux distros use the GLIBC runtime library, where Android uses bionic. \ No newline at end of file diff --git a/source/ethereum-clients/cpp-ethereum/building-from-source/beaglebone.rst b/source/ethereum-clients/cpp-ethereum/building-from-source/beaglebone.rst deleted file mode 100644 index 345229e..0000000 --- a/source/ethereum-clients/cpp-ethereum/building-from-source/beaglebone.rst +++ /dev/null @@ -1,7 +0,0 @@ - -Building for BeagleBone Black --------------------------------------------------------------------------------- -`EthEmbedded `_ -maintain build scripts for BBB on Github in the -`BBB-Eth-Install `_ repository. -It is also possible to cross-build for this platform. diff --git a/source/ethereum-clients/cpp-ethereum/building-from-source/freebsd.rst b/source/ethereum-clients/cpp-ethereum/building-from-source/freebsd.rst deleted file mode 100644 index 01f02d4..0000000 --- a/source/ethereum-clients/cpp-ethereum/building-from-source/freebsd.rst +++ /dev/null @@ -1,38 +0,0 @@ - -################################################################################ -Building for FreeBSD -################################################################################ - -NOTE - Once the packages are in the FreeBSD main ports this guide should be -changed to something much more simple - -Install the ports manually -================================================================================ -For some of this steps you must require a root access to modify the ports directory. - -The webthree-umbrella depends on [libjson-rpc-cpp.shar](https://raw.githubusercontent.com/enriquefynn/webthree-umbrella-port/master/libjson-rpc-cpp.shar) that is also not in the ports system. - -First you need to download the shar file and place it on your ports directory under the "devel" session, usually -/usr/ports/devel :: - - curl https://raw.githubusercontent.com/enriquefynn/webthree-umbrella-port/master/libjson-rpc-cpp.shar > /usr/ports/devel/libjson-rpc-cpp.shar - -Now we execute the script with: :: - - cd /usr/ports/devel - sh libjson-rpc-cpp.shar - -This will create the libjson-rpc-cpp port. Now you should do the same for the webthree-umbrella port, we should get the [webthree-umbrella](https://raw.githubusercontent.com/enriquefynn/webthree-umbrella-port/master/webthree-umbrella.shar) file and create the port under "net-p2p" directory. :: - - curl https://raw.githubusercontent.com/enriquefynn/webthree-umbrella-port/master/webthree-umbrella.shar> /usr/ports/net-p2p/webthree-umbrella.shar - cd /usr/ports/net-p2p - sh webthree-umbrella.shar - - -Build and Install -================================================================================ - -Now you can navigate to the webthree-umbrella directory and install the port: :: - - cd /usr/ports/net-p2p/webthree-umbrella - make install clean diff --git a/source/ethereum-clients/cpp-ethereum/building-from-source/index.rst b/source/ethereum-clients/cpp-ethereum/building-from-source/index.rst deleted file mode 100644 index f9de142..0000000 --- a/source/ethereum-clients/cpp-ethereum/building-from-source/index.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. _Building from source: - -Building from source -================================================================================ - -Overview --------------------------------------------------------------------------------- - -The **cpp-ethereum** codebase is is mid-transition from several -Git repositories which are all grouped as sub-modules under the -`webthree-umbrella `_ repo -on Github back to `cpp-ethereum `_. - -As of right now (only for the v1.3.0 release), the canonical mainline is at: - -https://github.com/bobsummerwill/cpp-ethereum/tree/merge_repos - -We use a common `CMake `_ build system to generate -platform-specific build files, meaning that the workflow is very similar -whatever operating system you use: - -* Install build tools and external packages (these are platform dependent) -* Clone the source code from the **webthree-umbrella** git repository -* Run CMake to generate a build file (makefile, Visual Studio solution, etc) -* Build it - - -Platform-specific instructions --------------------------------------------------------------------------------- - -.. toctree:: - :maxdepth: 2 - - linux.rst - windows.rst - macos.rst - freebsd.rst - android.rst - ios.rst - rpi.rst - odroid.rst - beaglebone.rst - wandboard.rst - linux-arm.rst - diff --git a/source/ethereum-clients/cpp-ethereum/building-from-source/ios.rst b/source/ethereum-clients/cpp-ethereum/building-from-source/ios.rst deleted file mode 100644 index 755ed49..0000000 --- a/source/ethereum-clients/cpp-ethereum/building-from-source/ios.rst +++ /dev/null @@ -1,10 +0,0 @@ - -Building for iOS --------------------------------------------------------------------------------- - -We don't currently have a working iOS build, though that is -`on the roadmap `_ -for `doublethinkco `_. iOS is a UNIX-like operating -system based on Darwin (BSD) using ARM chips. This is a -`different API `_ -than the ARM Linux cross-builds, meaning that specific binaries will be required. diff --git a/source/ethereum-clients/cpp-ethereum/building-from-source/linux-arch.rst b/source/ethereum-clients/cpp-ethereum/building-from-source/linux-arch.rst deleted file mode 100644 index 06faec9..0000000 --- a/source/ethereum-clients/cpp-ethereum/building-from-source/linux-arch.rst +++ /dev/null @@ -1,68 +0,0 @@ - -################################################################################ -Installing dependencies for Arch Linux -################################################################################ - -Compiling webthree-umbrella on Arch Linux requires dependencies from both the `official repositories `_ -and the `Arch User Repository (AUR) `_. To install packages from the official repositories `pacman `_ is used. -For installation of packages from the AUR, a number of AUR helpers is `available `_. For this guide, `yaourt `_ AUR helper is used. - -Installing dependencies -================================================================================ - - # from official repositories - sudo pacman -Sy git base-devel cmake boost crypto++ leveldb llvm miniupnpc libcl opencl-headers libmicrohttpd qt5-base qt5-webengine - - # from AUR - yaourt -Sy libjson-rpc-cpp - - -Compiling the source code -================================================================================ - -During this step, an installation folder for the Ethereum can be specified. -Specification of the folder is optional though. If not given, the -binary files will be located in the build folder. However, for this guide, -it is assumed that the Ethereum files will be installed under `/opt/eth`. The reason for -using `/opt` is that it makes much easier to delete the Ethereum files later on, -as compared to having them installed under, e.g., `/usr`. Also `/opt` is commonly used -to install software that is not managed by packaging systems, such as manually -compiled programs. :: - - # enter webthree-umbrella folder after cloning its github repository - cd webthree-umbrella - - # make a build folder and enter into it - mkdir -p build && cd build - - # create build files and specify Ethereum installation folder - cmake .. -DCMAKE_INSTALL_PREFIX=/opt/eth - - # compile the source code - make - - # alternatively it is possible to specify number of compilation threads - # for example to use 4 threads execute make as follows: - # make -j 4 - - # install the resulting binaries, shared libraries and header files into /opt - sudo make install - - -After successful compilation and installation, Ethereum binaries can be found in `/opt/eth/bin`, -shared libraries in `/opt/eth/lib`, and header files in `/opt/eth/include`. - - -Specifying Ethereum libraries path -================================================================================ - -Since Ethereum was installed in `/opt/eth`, executing its binaries can result in linker error due to not being -able to find the Ethereum shared libraries. To rectify this issue, it is needed to add the folder containing -Ethereum shared libraries into `LD_LIBRARY_PATH` environmental variable: :: - - # update ~/.bashrc - echo "export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/eth/lib" >> ~/.bashrc - - # reload ~/.bashrc - source ~/.bashrc - diff --git a/source/ethereum-clients/cpp-ethereum/building-from-source/linux-arm.rst b/source/ethereum-clients/cpp-ethereum/building-from-source/linux-arm.rst deleted file mode 100644 index 8b38cd3..0000000 --- a/source/ethereum-clients/cpp-ethereum/building-from-source/linux-arm.rst +++ /dev/null @@ -1,27 +0,0 @@ - -Building for Linux for ARM (cross builds) --------------------------------------------------------------------------------- -`doublethinkco `_ -maintain a Docker-based cross-build infrastructure which is -hosted on Github in the -`cpp-ethereum-cross -`_ -repository. - -At the time of writing, these cross-built binaries have been successfully used -on the following devices: - -- Jolla Phone (Sailfish OS) -- Nexus 5 (Sailfish OS) -- Meizu MX4 Ubuntu Edition (Ubuntu Phone) -- Raspberry Pi Model B+, Rpi2 (Raspbian) -- Odroid XU3 (Ubuntu MATE) -- BeagleBone Black (Debian) -- Wandboard Quad (Debian) -- C.H.I.P. (Debian) - -Still TODO: - -- Tizen -- Android -- iOS \ No newline at end of file diff --git a/source/ethereum-clients/cpp-ethereum/building-from-source/linux-debian.rst b/source/ethereum-clients/cpp-ethereum/building-from-source/linux-debian.rst deleted file mode 100644 index 1a26e0b..0000000 --- a/source/ethereum-clients/cpp-ethereum/building-from-source/linux-debian.rst +++ /dev/null @@ -1,103 +0,0 @@ - -################################################################################ -Installing dependencies for Debian -################################################################################ - -Debian Jessie (8.5) --------------------------------------------------------------------------------- - -.. warning:: - - GUI applications haven't been tried on Debian. So, to build without GUI applications use: :: - - cmake .. -DGUI=0 - -Steps: :: - - sudo apt-get -y install gcc - sudo apt-get -y install g++ - sudo apt-get -y install unzip - sudo apt-get -y install cmake -Make sure you installed the cmake version 3.5.2. If apt-get installed an older version, compile it from source following the instructions in this `link `_ :: - - sudo apt-get -y install libboost-all-dev - sudo apt-get -y install libgmp-dev - sudo apt-get -y install libjsoncpp-dev - sudo apt-get -y install libleveldb-dev - -To install cryptopp it's necessary build from source: :: - - mkdir ~/download - cd ~/download - wget https://www.cryptopp.com/cryptopp563.zip - - mkdir cryptopp - mv cryptopp563.zip cryptopp - cd cryptopp - unzip -a cryptopp563.zip - - make static dynamic cryptest.exe - -Testing installation: :: - - ./cryptest.exe v - -Verify results, and do another test: :: - - ./cryptest.exe tv - -Testing ok? Let's continue: :: - - make libcryptopp.a libcryptopp.so cryptest.exe - sudo make install PREFIX=/usr/local - -CryptoPP installed!: :: - - sudo apt-get -y install libminiupnpc-dev - -Now, install LLVM building from source: :: - - sudo apt-get -y install build-essential - mkdir ~/download/llvm - cd ~/download/llvm - wget -c http://llvm.org/releases/3.8.0/llvm-3.8.0.src.tar.xz - wget -c http://llvm.org/releases/3.8.0/cfe-3.8.0.src.tar.xz - wget -c http://llvm.org/releases/3.8.0/compiler-rt-3.8.0.src.tar.xz - - tar -xf llvm-3.8.0.src.tar.xz - tar -xf cfe-3.8.0.src.tar.xz - tar -xf compiler-rt-3.8.0.src.tar.xz - - mv llvm-3.8.0.src llvm-3.8.0 - mv cfe-3.8.0.src cfe - mv compiler-rt-3.8.0.src compiler-rt - - mv cfe llvm-3.8.0/tools - mv compiler-rt llvm-3.8.0/projects/ - - mkdir build - cd build - - cmake ../llvm-3.8.0 - make - sudo make install - sudo ldconfig - -Coming back to apt-get: :: - - sudo apt-get -y install opencl-dev - sudo apt-get -y install libcurl4-openssl-dev - -Install json-rpc-cpp building from source: :: - - sudo apt-get source libmicrohttpd-dev - sudo apt-get -y install libargtable2-dev - sudo apt-get -y install libmicrohttpd-dev - - git clone git://github.com/cinemast/libjson-rpc-cpp.git - mkdir -p libjson-rpc-cpp/build - cd libjson-rpc-cpp/build - cmake - make - sudo make install - sudo ldconfig diff --git a/source/ethereum-clients/cpp-ethereum/building-from-source/linux-fedora.rst b/source/ethereum-clients/cpp-ethereum/building-from-source/linux-fedora.rst deleted file mode 100644 index 9ae3467..0000000 --- a/source/ethereum-clients/cpp-ethereum/building-from-source/linux-fedora.rst +++ /dev/null @@ -1,119 +0,0 @@ - -################################################################################ -Installing dependencies for Fedora -################################################################################ - -Fedora 20 --------------------------------------------------------------------------------- -Steps: :: - - yum install git automake autoconf libtool cmake gcc gcc-c++ xkeyboard-config \ - leveldb-devel boost-devel gmp-devel cryptopp-devel miniupnpc-devel \ - qt5-qtbase-devel qt5-qtdeclarative-devel qt5-qtquick1-devel qt5-qtwebkit-devel \ - mesa-dri-drivers snappy-devel ncurses-devel readline-devel curl-devel \ - python-devel - -Fedora 21 --------------------------------------------------------------------------------- -Steps: :: - - yum install git automake autoconf libtool cmake gcc gcc-c++ xkeyboard-config \ - leveldb-devel boost-devel gmp-devel cryptopp-devel miniupnpc-devel \ - qt5-qtbase-devel qt5-qtdeclarative-devel qt5-qtquick1-devel qt5-qtwebkit-devel \ - mesa-dri-drivers snappy-devel ncurses-devel readline-devel curl-devel \ - python-devel jsoncpp-devel argtable-devel - -Build json-rpc from github as per https://github.com/ethereum/cpp-ethereum/issues/617: :: - - git clone https://github.com/cinemast/libjson-rpc-cpp - cd libjson-rpc-cpp - git checkout tags/v0.3.2 - mkdir -p build - cd build - cmake .. && make - sudo make install - sudo ldconfig - -Fedora 22 --------------------------------------------------------------------------------- - -Fedora 22 dependencies there may be more depends what you have already installed: :: - - dnf install git automake autoconf libtool cmake gcc gcc-c++ xkeyboard-config \ - leveldb-devel boost-devel gmp-devel cryptopp-devel miniupnpc-devel \ - mesa-dri-drivers snappy-devel ncurses-devel readline-devel curl-devel \ - python-devel jsoncpp-devel argtable-devel - -Install gcc version 4.9! Fedora 22 comes with a different compiler (CC v5.3). -This one wont compile webthree-umbrella 4 me so i installed gcc version 4.9 from SRC! - -Check that you have a working gcc4.9 install in /usr/local i installed it in -/home/app/gcc49 its your choice read manual how to compile gcc in google! After that -you have to compile everything you need 4 webthree-umbrella with gcc4.9 so before -every cmake: :: - - export CXX=/home/app/gcc49/bin/g++ - export CC=/home/app/gcc49/bin/gcc - -With this you use gcc4.9 to compile instead of the one that comes with the -distro F22. Its not recommended to uninstall the compiler that comes with your -distro! You can also work with symlinking. - -Install from Fedora COPR REPO LLVM3.7 with: :: - - dnf copr enable alonid/llvm-3.7 - dnf install llvm-3.7 llvm-3.7-devel llvm-3.7-static llvm-3.7-libs - -I had to do this because Fedora 22 comes with llvm-3.5 from stock repos! There -may be other solutions but this one worked 4 me - -Install CryptoPP from SRC https://github.com/weidai11/cryptopp CRYPTOPP_5_6_2: :: - - git clone https://github.com/weidai11/cryptopp - cd cryptopp - git checkout release/CRYPTOPP_5_6_2 - mkdir build - cd build - export CXX=/home/app/gcc49/bin/g++ <- be sure to compile with gcc4.9 - export CC=/home/app/gcc49/bin/gcc <- be sure to compile with gcc4.9 - cmake .. - make - make install - -Install QT5 from COPR "dnf copr enable @kdesig/Qt5" newer QT5 version: :: - - dnf install qt5-* - -this should install QT5 version 5.6.0 in COPR repo are other QT5. Packages from other users i didnt test them - -Install qtwebengine from https://github.com/qtproject/qtwebengine i installed -version 5.6.0 others may also work find it out :D :: - - git clone https://github.com/qtproject/qtwebengine - cd qtwebengine - git checkout release/v5.6.0 - qmake-qt5 <- in other distros its just called qmake in fedora 22 qmake-qt5 - make - make install - -Install json-rpc from github https://github.com/ethereum/cpp-ethereum/issues/617: :: - - git clone https://github.com/cinemast/libjson-rpc-cpp - cd libjson-rpc-cpp - git checkout tags/v0.4.2 - mkdir -p build - cd build - export CXX=/home/app/gcc49/bin/g++ <- be sure to compile with gcc4.9 - export CC=/home/app/gcc49/bin/gcc <- be sure to compile with gcc4.9 - cmake .. && make - sudo make install - sudo ldconfig - -Be sure to check if jsonrpcstub works in console enter "jsonrpcstub" and look if its responding. -If it answers No Argument or s-l-t it works but if you get no such file to blabla.so you have to -symlinking the missing ones to your libs dir /usr/local/lib64 or usr/local/lib depends where the -file blabla.so is try to find it with "updatedb" and than "locate blabla.so" - -Try to compile now it should work if not there a missing symlinks cause of no such file easyfix -or there are some missing Packages try to find them with dnf like this "dnf search packname*" or -"dnf list packname*" all i can say its not a 5 min compile of webthree-umbrella enjoy Tflux99. diff --git a/source/ethereum-clients/cpp-ethereum/building-from-source/linux-opensuse.rst b/source/ethereum-clients/cpp-ethereum/building-from-source/linux-opensuse.rst deleted file mode 100644 index 7779e9c..0000000 --- a/source/ethereum-clients/cpp-ethereum/building-from-source/linux-opensuse.rst +++ /dev/null @@ -1,31 +0,0 @@ - -################################################################################ -Installing dependencies for openSUSE -################################################################################ - -Here is how to get the dependencies needed to build the latest -webthree-umbrella on OpenSUSE. This was done on Leap 42.1, but there should be equivalent packages available for Tumbleweed and 13.x. - -First install dependencies provided by the main repos: :: - - zypper in git automake autoconf libtool cmake gcc gcc-c++ \ - xkeyboard-config leveldb-devel boost-devel gmp-devel \ - cryptopp-devel libminiupnpc-devel libqt5-qtbase-common-devel \ - libqt5-qtdeclarative-devel libQTWebKit-devel libqt5-qtwebengine-devel \ - libQt5Concurrent-devel Mesa ncurses-devel readline-devel libcurl-devel \ - llvm llvm-clang llvm-clang-devel llvm-devel libLLVM binutils \ - libmicrohttp-devel jsoncpp-devel opencl-headers-1.2 zlib-devel - -It may be possible to use the generic `libOpenCL1`, but I have only tested with the -AMD proprietary package from the AMD drivers repo `fglrx64_opencl_SUSE421` - -These packages are not in the standard repos but can be found using the OpenSUSE -build service package search and YaST 1-Click Install: - -- libargtable2-devel -- libv8-3 -- v8-devel - -If you also have v8 from the chromium repo installed the devel package will -default to the 4.x branch which will not work. Use YaST or zypper to downgrade -this package to 3.x diff --git a/source/ethereum-clients/cpp-ethereum/building-from-source/linux-ubuntu.rst b/source/ethereum-clients/cpp-ethereum/building-from-source/linux-ubuntu.rst deleted file mode 100644 index 34dc100..0000000 --- a/source/ethereum-clients/cpp-ethereum/building-from-source/linux-ubuntu.rst +++ /dev/null @@ -1,155 +0,0 @@ - -################################################################################ -Installing dependencies for Ubuntu -################################################################################ - -Ubuntu Trusty Tahr (14.04) --------------------------------------------------------------------------------- -Steps: :: - - sudo apt-add-repository ppa:george-edison55/cmake-3.x - - sudo apt-get -y update - sudo apt-get -y install language-pack-en-base - sudo dpkg-reconfigure locales - sudo apt-get -y install software-properties-common - - sudo add-apt-repository "deb http://llvm.org/apt/trusty/ llvm-toolchain-trusty-3.7 main" - wget -O - http://llvm.org/apt/llvm-snapshot.gpg.key | sudo apt-key add - - sudo apt-get -y update - sudo apt-get -y install llvm-3.7-dev - - sudo add-apt-repository -y ppa:ethereum/ethereum-qt - sudo add-apt-repository -y ppa:ethereum/ethereum - sudo add-apt-repository -y ppa:ethereum/ethereum-dev - sudo apt-get -y update - sudo apt-get -y upgrade - - sudo apt-get -y install build-essential git cmake libboost-all-dev libgmp-dev \ - libleveldb-dev libminiupnpc-dev libreadline-dev libncurses5-dev \ - libcurl4-openssl-dev libcryptopp-dev libmicrohttpd-dev libjsoncpp-dev \ - libargtable2-dev libedit-dev mesa-common-dev ocl-icd-libopencl1 opencl-headers \ - libgoogle-perftools-dev qtbase5-dev qt5-default qtdeclarative5-dev \ - libqt5webkit5-dev libqt5webengine5-dev ocl-icd-dev libv8-dev libz-dev - - sudo apt-get -y install libjson-rpc-cpp-dev - sudo apt-get -y install qml-module-qtquick-controls qml-module-qtwebengine - -Ubuntu Utopic Unicorn (14.10) --------------------------------------------------------------------------------- -Steps: :: - - sudo apt-get -y update - sudo apt-get -y install language-pack-en-base - sudo dpkg-reconfigure locales - sudo apt-get -y install software-properties-common - - sudo add-apt-repository "deb http://llvm.org/apt/utopic/ llvm-toolchain-utopic-3.7 main" - wget -O - http://llvm.org/apt/llvm-snapshot.gpg.key | sudo apt-key add - - sudo apt-get -y update - sudo apt-get -y install llvm-3.7-dev - - sudo add-apt-repository -y ppa:ethereum/ethereum-qt - sudo add-apt-repository -y ppa:ethereum/ethereum - sudo add-apt-repository -y ppa:ethereum/ethereum-dev - sudo apt-get -y update - sudo apt-get -y upgrade - - sudo apt-get -y install build-essential git cmake libboost-all-dev libgmp-dev \ - libleveldb-dev libminiupnpc-dev libreadline-dev libncurses5-dev \ - libcurl4-openssl-dev libcryptopp-dev libmicrohttpd-dev libjsoncpp-dev \ - libargtable2-dev libedit-dev mesa-common-dev ocl-icd-libopencl1 opencl-headers \ - libgoogle-perftools-dev qtbase5-dev qt5-default qtdeclarative5-dev \ - libqt5webkit5-dev libqt5webengine5-dev ocl-icd-dev libv8-dev libz-dev - - sudo apt-get -y install libjson-rpc-cpp-dev - sudo apt-get -y install qml-module-qtquick-controls qml-module-qtwebengine - -Ubuntu Vivid Vervet (15.04) --------------------------------------------------------------------------------- -Steps: :: - - sudo apt-get -y update - sudo apt-get -y install language-pack-en-base - sudo dpkg-reconfigure locales - sudo apt-get -y install software-properties-common - - sudo add-apt-repository "deb http://llvm.org/apt/vivid/ llvm-toolchain-vivid-3.7 main" - wget -O - http://llvm.org/apt/llvm-snapshot.gpg.key | sudo apt-key add - - sudo apt-get -y update - sudo apt-get -y install llvm-3.7-dev - - sudo add-apt-repository -y ppa:ethereum/ethereum-qt - sudo add-apt-repository -y ppa:ethereum/ethereum - sudo add-apt-repository -y ppa:ethereum/ethereum-dev - sudo apt-get -y update - sudo apt-get -y upgrade - - sudo apt-get -y install build-essential git cmake libboost-all-dev libgmp-dev \ - libleveldb-dev libminiupnpc-dev libreadline-dev libncurses5-dev \ - libcurl4-openssl-dev libcryptopp-dev libmicrohttpd-dev libjsoncpp-dev \ - libargtable2-dev libedit-dev mesa-common-dev ocl-icd-libopencl1 opencl-headers \ - libgoogle-perftools-dev qtbase5-dev qt5-default qtdeclarative5-dev \ - libqt5webkit5-dev libqt5webengine5-dev ocl-icd-dev libv8-dev libz-dev - - sudo apt-get -y install libjson-rpc-cpp-dev - sudo apt-get -y install qml-module-qtquick-controls qml-module-qtwebengine - -Ubuntu Wily Werewolf (15.10) --------------------------------------------------------------------------------- -Steps: :: - - sudo apt-get -y update - sudo apt-get -y install language-pack-en-base - sudo dpkg-reconfigure locales - sudo apt-get -y install software-properties-common - - sudo add-apt-repository "deb http://llvm.org/apt/wily/ llvm-toolchain-wily-3.7 main" - wget -O - http://llvm.org/apt/llvm-snapshot.gpg.key | sudo apt-key add - - sudo apt-get -y update - sudo apt-get -y install llvm-3.7-dev - - sudo add-apt-repository -y ppa:ethereum/ethereum-qt - sudo add-apt-repository -y ppa:ethereum/ethereum - sudo add-apt-repository -y ppa:ethereum/ethereum-dev - sudo apt-get -y update - sudo apt-get -y upgrade - - sudo apt-get -y install build-essential git cmake libboost-all-dev libgmp-dev \ - libleveldb-dev libminiupnpc-dev libreadline-dev libncurses5-dev \ - libcurl4-openssl-dev libcryptopp-dev libmicrohttpd-dev libjsoncpp-dev \ - libargtable2-dev libedit-dev mesa-common-dev ocl-icd-libopencl1 opencl-headers \ - libgoogle-perftools-dev qtbase5-dev qt5-default qtdeclarative5-dev \ - libqt5webkit5-dev libqt5webengine5-dev ocl-icd-dev libv8-dev libz-dev - - sudo apt-get -y install libjsonrpccpp-dev - sudo apt-get -y install qml-module-qtquick-controls qml-module-qtwebengine - -Ubuntu Xenial Xerus (16.04) --------------------------------------------------------------------------------- -Steps: :: - - sudo apt-get -y update - sudo apt-get -y install language-pack-en-base - sudo dpkg-reconfigure locales - sudo apt-get -y install software-properties-common - - sudo apt-get -y install llvm-3.7-dev - - sudo add-apt-repository -y ppa:ethereum/ethereum-qt - sudo add-apt-repository -y ppa:ethereum/ethereum - sudo add-apt-repository -y ppa:ethereum/ethereum-dev - sudo apt-get -y update - sudo apt-get -y upgrade - - sudo apt-get -y install build-essential git cmake libboost-all-dev libgmp-dev \ - libleveldb-dev libminiupnpc-dev libreadline-dev libncurses5-dev \ - libcurl4-openssl-dev libcryptopp-dev libmicrohttpd-dev libjsoncpp-dev \ - libargtable2-dev libedit-dev mesa-common-dev ocl-icd-libopencl1 opencl-headers \ - libgoogle-perftools-dev qtbase5-dev qt5-default qtdeclarative5-dev \ - libqt5webkit5-dev libqt5webengine5-dev ocl-icd-dev libv8-dev libz-dev - - sudo apt-get -y install libjsonrpccpp-dev - sudo apt-get -y install qml-module-qtquick-controls qml-module-qtwebengine \ - qml-module-qtquick-privatewidgets qml-module-qtquick-dialogs \ - qml-module-qt-labs-settings qml-module-qtgraphicaleffects diff --git a/source/ethereum-clients/cpp-ethereum/building-from-source/linux.rst b/source/ethereum-clients/cpp-ethereum/building-from-source/linux.rst deleted file mode 100644 index 2524aae..0000000 --- a/source/ethereum-clients/cpp-ethereum/building-from-source/linux.rst +++ /dev/null @@ -1,62 +0,0 @@ - -################################################################################ -Building for Linux -################################################################################ - -NOTE - It may be possible to get the client working for Linux 32-bit, by -disabling EVMJIT and maybe other features too. We might accept -pull-requests to add such support, but we will not put any of our -own development time into supporting Linux 32-bit builds. - -Linux has a horror-show of distro-specific packaging system steps which are -the first thing which we need to do before we can start on -:ref:`Building from source`. The sections below attempt to capture those -steps. If you are using as different distro and hit issues, please -`let us know `_. - - -Clone the repository -================================================================================ - -To clone the source code, execute the following command: :: - - git clone --recursive https://github.com/bobsummerwill/cpp-ethereum.git - cd cpp-ethereum - git checkout merge_repos - git submodule update --init - -Installing dependencies (the easy way!) -================================================================================ - -For the "Homecoming" release (v1.3.0) in July 2016 we added a new "one-button" -script for installing external dependencies, which identifies your distro and -installs the packages which you need. This script is new and incomplete, but -is a way easier experience than the manual steps described in the next section -of this document. Give it a go! It works for Ubuntu and macOS and a few -other distros already. If you try it, and it doesn't work for you, please let -us know and we will prioritize fixing your distro!:: - - ./install_deps.sh - - -Installing dependencies (distro-specific) -================================================================================ - -.. toctree:: - linux-ubuntu.rst - linux-fedora.rst - linux-opensuse.rst - linux-arch.rst - linux-debian.rst - -Build on the command-line -================================================================================ - -**ONLY** after you have installed your dependencies (the rest of this doc!): :: - - mkdir build Make a directory for the build output - cd build Switch into that directory - - cmake .. To generate a makefile. - make To build that makefile on the command-line - make -j (or) Execute makefile with multiple cores in parallel diff --git a/source/ethereum-clients/cpp-ethereum/building-from-source/macos.rst b/source/ethereum-clients/cpp-ethereum/building-from-source/macos.rst deleted file mode 100644 index d46766e..0000000 --- a/source/ethereum-clients/cpp-ethereum/building-from-source/macos.rst +++ /dev/null @@ -1,112 +0,0 @@ - -Building for OS X -================================================================================ - -Overview - Here be dragons! --------------------------------------------------------------------------------- - -It is impossible for us to avoid OS X build breaks because `Homebrew is a "rolling -release" package manager -`_ -which means that the ground will forever be moving underneath us unless we add -all external dependencies to our -`Homebrew tap `_, or add them as -git sub-modules within the umbrella projects. End-user results vary depending -on when they are build the project. Building yesterday may have worked for -you, but that doesn't guarantee that your friend will have the same result -today on their machine. Needless to say, this isn't a happy situation. - -If you hit build breaks for OS X please look through the `Github issues -`_ to see whether the -issue you are experiencing has already been reported. If so, please comment -on that existing issue. If you don't see anything which looks similar, -please create a new issue, detailing your OS X version, cpp-ethereum version, -hardware and any other details you think might be relevant. Please add -verbose log files via `gist.github.com `_ or a -similar service. - -The `cpp-ethereum-development -`_ gitter channel is where we hang out, and try -to work together to get known issues resolved. - -We only support the following OS X versions: - -- `OS X Mavericks (10.9) `_ -- `OS X Yosemite (10.10) `_ -- `OS X El Capitan (10.11) `_ - -The cpp-ethereum code base does not build on older OS X versions and this -is not something which we will ever support. If you are using an older -OS X version, we recommend that you update to the latest release, not -just so that you can build cpp-ethereum, but for your own security. - - -Clone the repository --------------------------------------------------------------------------------- - -To clone the source code, execute the following command: :: - - git clone --recursive https://github.com/bobsummerwill/cpp-ethereum.git - cd cpp-ethereum - git checkout merge_repos - git submodule update --init - - -Pre-requisites and external dependencies --------------------------------------------------------------------------------- - -Ensure that you have the latest version of -`xcode installed `_. -This contains the `Clang C++ compiler `_, the -`xcode IDE `_ and other Apple development -tools which are required for building C++ applications on OS X. -If you are installing xcode for the first time, or have just installed a new -version then you will need to agree to the license before you can do -command-line builds: :: - - sudo xcodebuild -license accept - -Our OS X builds require you to `install the Homebrew `_ -package manager for installing external dependencies. -Here's how to `uninstall Homebrew -`_, -if you ever want to start again from scratch. - -We now have a "one button" script which installs all required external dependencies -on macOS and on numerous Linux distros. This used to a multi-step manual process: :: - - ./install_dep.sh - - -Command-line build --------------------------------------------------------------------------------- - -From the project root: :: - - mkdir build - cd build - cmake .. - make -j4 (or different value, depending on your number of CPU cores) - - -Install your own build --------------------------------------------------------------------------------- - -You can also use the same Makefile to install your own build globally on your machine: :: - - make install - -This will install binaries into **/usr/local/** and **/usr/bin/**. - - -Generate xcode project --------------------------------------------------------------------------------- - -From the project root: :: - - mkdir build_xc - cd build_xc - cmake -G Xcode .. - -This will generate an Xcode project file called **cpp-ethereum.xcodeproj**, -which you can then open with xcode and build/debug/run. diff --git a/source/ethereum-clients/cpp-ethereum/building-from-source/odroid.rst b/source/ethereum-clients/cpp-ethereum/building-from-source/odroid.rst deleted file mode 100644 index 96c17ed..0000000 --- a/source/ethereum-clients/cpp-ethereum/building-from-source/odroid.rst +++ /dev/null @@ -1,9 +0,0 @@ - -Building for Odroid XU3/XU4 --------------------------------------------------------------------------------- -`EthEmbedded `_ -maintain build scripts for both of these Odroid models. Support -for a broader range of Odroid devices is likely in the future. -They are on Github in the -`OdroidXU3-Eth-Install `_ repository. -It is also possible to cross-build for these platforms. diff --git a/source/ethereum-clients/cpp-ethereum/building-from-source/rpi.rst b/source/ethereum-clients/cpp-ethereum/building-from-source/rpi.rst deleted file mode 100644 index 2367fe4..0000000 --- a/source/ethereum-clients/cpp-ethereum/building-from-source/rpi.rst +++ /dev/null @@ -1,8 +0,0 @@ - -Building for Raspberry Pi Model A, B+, Zero, 2 and 3 --------------------------------------------------------------------------------- -`EthEmbedded `_ -maintain build scripts for all Raspberry Mi models. -They are on Github in the -`Raspi-Eth-Install `_ repository. -It is also possible to cross-build for these platforms. diff --git a/source/ethereum-clients/cpp-ethereum/building-from-source/wandboard.rst b/source/ethereum-clients/cpp-ethereum/building-from-source/wandboard.rst deleted file mode 100644 index 2509b8e..0000000 --- a/source/ethereum-clients/cpp-ethereum/building-from-source/wandboard.rst +++ /dev/null @@ -1,7 +0,0 @@ - -Building for WandBoard --------------------------------------------------------------------------------- -`EthEmbedded `_ -maintain build scripts for the WandBoard on Github in the -`WandBoard-Eth-Install `_ repository. -It is also possible to cross-build for this platform. diff --git a/source/ethereum-clients/cpp-ethereum/building-from-source/windows.rst b/source/ethereum-clients/cpp-ethereum/building-from-source/windows.rst deleted file mode 100644 index b86c7ee..0000000 --- a/source/ethereum-clients/cpp-ethereum/building-from-source/windows.rst +++ /dev/null @@ -1,80 +0,0 @@ - -Building for Windows -================================================================================ - -We support **only 64-bit** builds and only for the following versions of Windows: - -- `Windows 7 `_ -- `Windows 8/8.1 `_ -- `Windows 10 `_ -- `Windows Server 2012 R2 `_ - -It may be possible to get the client working for Windows 32-bit, by -disabling EVMJIT and maybe other features too. We might accept -pull-requests to add such support, but we will not put any of our -own development time into supporting Windows 32-bit builds. - - -Pre-requisites --------------------------------------------------------------------------------- - -You will need to install the following dependencies - -+------------------------------+-------------------------------------------------------+ -| Software | Notes | -+==============================+=======================================================+ -| `Git for Windows`_ | Command-line tool for retrieving source from Github. | -+------------------------------+-------------------------------------------------------+ -| `CMake`_ | Cross-platform build file generator. | -+------------------------------+-------------------------------------------------------+ -| `Visual Studio 2015`_ | C++ compiler and dev environment. | -+------------------------------+-------------------------------------------------------+ - -.. _Git for Windows: https://git-scm.com/download/win -.. _CMake: https://cmake.org/download/ -.. _Visual Studio 2015: https://www.visualstudio.com/products/vs-2015-product-editions - - -Get the source --------------------------------------------------------------------------------- - -Clone the git repository containing all the source code by executing the following command: :: - - git clone --recursive https://github.com/bobsummerwill/cpp-ethereum.git - cd cpp-ethereum - git checkout merge_repos - git submodule update --init - - -Get the external dependencies --------------------------------------------------------------------------------- - -Execute the CMake script that downloads and unpacks pre-built external libraries -needed to build the project: :: - - install_deps.bat - - -Generate Visual Studio project files --------------------------------------------------------------------------------- -Then execute the following commands, which will generate a Visual Studio -solution file using CMake: :: - - mkdir build - cd build - cmake -G "Visual Studio 14 2015 Win64" .. - -Which should result in the creation of **cpp-ethereum.sln** in that build directory. - -**NOTE: We only support Visual Studio 2015 as of cpp-ethereum-v.1.3.0.** - -Double-clicking on that file should result in Visual Studio firing up. We suggest -building **RelWithDebugInfo** configuration, but all others work. - - -Build on the command-line --------------------------------------------------------------------------------- - -Alternatively, you can build the project on the command-line, like so: :: - - cmake --build . --config RelWithDebInfo diff --git a/source/ethereum-clients/cpp-ethereum/history-of-the-code.rst b/source/ethereum-clients/cpp-ethereum/history-of-the-code.rst deleted file mode 100644 index e642e49..0000000 --- a/source/ethereum-clients/cpp-ethereum/history-of-the-code.rst +++ /dev/null @@ -1,22 +0,0 @@ -################################################################################ -History of the code -################################################################################ - -The `C++ Ethereum project `_ was -initiated by `Gavin Wood `_, the -`former CTO `_ of the -Ethereum Foundation, in December 2013. It is the second most popular of the -clients, trailing a long way behind the dominant `geth `_ client, -also built by the Ethereum Foundation. - -Many of the original C++ developers moved on to roles at -`Slock.it `_ and `Ethcore `_ in -late 2015 and early 2016 following a -`75% cut in funding `_ for C++ -development. Those cuts were part of a broader effort to bring Foundation -costs under control, and they happened prior to the recent spike in ETH -value which has put the Foundation in a much more comfortable financial -position. - -See `Contributors `_ -for the full list of everybody who has worked on the code. diff --git a/source/ethereum-clients/cpp-ethereum/index.rst b/source/ethereum-clients/cpp-ethereum/index.rst deleted file mode 100644 index 4eed812..0000000 --- a/source/ethereum-clients/cpp-ethereum/index.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. _cpp-ethereum: - -################################################################################ -cpp-ethereum -################################################################################ - -.. image:: ../../img/cpp_35k9.png - :height: 200px - :width: 200px - -.. image:: ../../img/ETHEREUM-ICON_Black.png - :height: 200px - :width: 200px - - -Quick Start -================================================================================ - -- The Github project for the Ethereum C++ client is https://github.com/ethereum/cpp-ethereum/ -- As of right now, though (only for the v1.3.0 release), the canonical mainline is at https://github.com/bobsummerwill/cpp-ethereum/tree/merge_repos -- Prior to the v1.3.0 release and for several months before, the canonical mainline was at https://github.com/ethereum/webthree-umbrella -- If you just want to install binaries then head to :ref:`Installing binaries`. -- If you want to build from source then head to :ref:`Building from source`. -- You can chat with the community and developers at `cpp-ethereum-gitter`_ -- The developers have their in-depth conversations at `cpp-ethereum-development-gitter`_ -- Please log any issues using the `Github issue tracker `_. -- cpp-ethereum is extremely portable and is used on a :ref:`very broad range of platforms `. - -.. _cpp-ethereum-gitter: https://gitter.im/ethereum/cpp-ethereum -.. _cpp-ethereum-development-gitter: https://gitter.im/ethereum/cpp-ethereum-development - - -Details -================================================================================ - -.. toctree:: - :maxdepth: 2 - - project-reboot.rst - history-of-the-code.rst - portability.rst - installing-binaries/index.rst - building-from-source/index.rst - running.rst - what-are-the-modules.rst - ./automation.rst diff --git a/source/ethereum-clients/cpp-ethereum/installing-binaries/index.rst b/source/ethereum-clients/cpp-ethereum/installing-binaries/index.rst deleted file mode 100644 index c0a07d8..0000000 --- a/source/ethereum-clients/cpp-ethereum/installing-binaries/index.rst +++ /dev/null @@ -1,25 +0,0 @@ - -.. _Installing binaries: - -Installing binaries -================================================================================ - -The cpp-ethereum development team and the broader Ethereum community publish -binary releases in many different forms for a variety of platforms. This -aims to be a complete list of those releases. - -If you are aware of other third-party packaging efforts, please let us know on -the `cpp-ethereum gitter channel `_, -and we will add them to this list. - -.. toctree:: - :maxdepth: 2 - - linux-ubuntu-ppa.rst - windows-installer.rst - windows-chocolatey.rst - osx-dmg.rst - osx-homebrew.rst - linux-sbcs.rst - linux-cross-builds.rst - linux-arch-aur.rst diff --git a/source/ethereum-clients/cpp-ethereum/installing-binaries/linux-arch-aur.rst b/source/ethereum-clients/cpp-ethereum/installing-binaries/linux-arch-aur.rst deleted file mode 100644 index 408d764..0000000 --- a/source/ethereum-clients/cpp-ethereum/installing-binaries/linux-arch-aur.rst +++ /dev/null @@ -1,23 +0,0 @@ - -ArchLinux User Repository (AUR) --------------------------------------------------------------------------------- - -Arch Linux packages are community maintained by -`Afri Schoedon `_. - -Check out the following packages -on `aur.archlinux.org `_. - -- `ethereum `_ (stable, latest release) -- `ethereum-git `_ (unstable, latest develop) - -To build and install the package, follow the `AUR installing package `_ instructions: - -- Acquire the tarball which contains the PKGBUILD -- Extract the tarball -- Run :code:`makepkg -sri` as simple user in the directory where the files are saved -- Install the resulting package with :code:`pacman -U` as superuser - -You can also use `AUR helpers `_ -like :code:`yaourt` or :code:`pacaur` to install the packages directly on your system. - diff --git a/source/ethereum-clients/cpp-ethereum/installing-binaries/linux-cross-builds.rst b/source/ethereum-clients/cpp-ethereum/installing-binaries/linux-cross-builds.rst deleted file mode 100644 index 98e9936..0000000 --- a/source/ethereum-clients/cpp-ethereum/installing-binaries/linux-cross-builds.rst +++ /dev/null @@ -1,22 +0,0 @@ - -Linux ARM cross-builds for mobile, wearables, SBCs --------------------------------------------------------------------------------- - -`Bob Summerwill `_, of -`doublethinkco `_ cross-builds -`ARM binaries `_ -which work on a very broad variety of hardware, from mobile and wearables -Linux distros (Sailfish OS, Tizen OS, Ubuntu Touch) to the same SBCs which -`EthEmbedded `_ target - and more. -doublethinkco was a -`BlockGrantX recipient -`_ in Feb 2016. - -See the -`cpp-ethereum-cross README -`_ -for a full matrix of platforms and known status. - -Here are the cross-build binaries from doublethinkco: -`RELEASED – Cross-build eth binaries for Homestead -`_. diff --git a/source/ethereum-clients/cpp-ethereum/installing-binaries/linux-sbcs.rst b/source/ethereum-clients/cpp-ethereum/installing-binaries/linux-sbcs.rst deleted file mode 100644 index 856f186..0000000 --- a/source/ethereum-clients/cpp-ethereum/installing-binaries/linux-sbcs.rst +++ /dev/null @@ -1,13 +0,0 @@ - -Raspberry Pi, Odroid, BeagleBone Black, Wandboard --------------------------------------------------------------------------------- - -`John Gerryts `_ of -`EthEmbedded `_ builds binary images for a variety of -SBCs at major milestones, in addition to testing and maintaining build scripts -for these devices. EthEmbedded was a `devgrant recipient -`_ in May 2015. -He builds binaries for both eth and geth. - -Here are the `Homestead binaries `_ -from `EthEmbedded `_ diff --git a/source/ethereum-clients/cpp-ethereum/installing-binaries/linux-ubuntu-ppa.rst b/source/ethereum-clients/cpp-ethereum/installing-binaries/linux-ubuntu-ppa.rst deleted file mode 100644 index 1754fa8..0000000 --- a/source/ethereum-clients/cpp-ethereum/installing-binaries/linux-ubuntu-ppa.rst +++ /dev/null @@ -1,49 +0,0 @@ - -Ubuntu PPA (Personal Package Archive) -================================================================================ - -We have set up PPA instances for the following Ubuntu versions: - -- `Ubuntu Trusty Tahr (14.04) `_ -- `Ubuntu Utopic Unicorn (14.10) `_ -- `Ubuntu Vivid Vervet (15.04) `_ -- `Ubuntu Wily Werewolf (15.10) `_ -- `Ubuntu Xenial Xerus (16.04) `_ - -**We only support 64-bit builds.** It may be possible to get the -client working for Ubuntu 32-bit, by building from source and disabling -EVMJIT and maybe other features too. We might accept pull-requests to -add such support, but we will not put any of our development time into -supporting Ubuntu 32-bit builds. - -Installing the "eth" command-line tool --------------------------------------------------------------------------------- - -WARNING: The **ethereum-qt** PPA will upgrade your system-wide Qt5 -installation, from 5.2 on Trusty and 5.3 on Utopic, to 5.5. - -For the latest stable version: :: - - sudo add-apt-repository ppa:ethereum/ethereum-qt - sudo add-apt-repository ppa:ethereum/ethereum - sudo apt-get update - sudo apt-get install cpp-ethereum - -If you want to use the cutting edge developer version: :: - - sudo add-apt-repository ppa:ethereum/ethereum-qt - sudo add-apt-repository ppa:ethereum/ethereum - sudo add-apt-repository ppa:ethereum/ethereum-dev - sudo apt-get update - sudo apt-get install cpp-ethereum - - -Installing the Mix IDE --------------------------------------------------------------------------------- - -The `Mix IDE `_ is shipped on -Ubuntu as part of the developer PPA (above). So follow the steps -directly above, and then also do: :: - - sudo apt-get install mix-ide - mix-ide diff --git a/source/ethereum-clients/cpp-ethereum/installing-binaries/osx-dmg.rst b/source/ethereum-clients/cpp-ethereum/installing-binaries/osx-dmg.rst deleted file mode 100644 index f57e351..0000000 --- a/source/ethereum-clients/cpp-ethereum/installing-binaries/osx-dmg.rst +++ /dev/null @@ -1,16 +0,0 @@ - -OS X DMG (disk image) --------------------------------------------------------------------------------- - -We generate OS X disk images -`for each release `_. - -We **only** support the two most recent OS X versions: - -- `OS X Yosemite (10.10) `_ -- `OS X El Capitan (10.11) `_ - -**We only support 64-bit builds.** - -If your system does not support either of these OS X versions then you -are out of luck. Sorry! diff --git a/source/ethereum-clients/cpp-ethereum/installing-binaries/osx-homebrew.rst b/source/ethereum-clients/cpp-ethereum/installing-binaries/osx-homebrew.rst deleted file mode 100644 index 4fa8635..0000000 --- a/source/ethereum-clients/cpp-ethereum/installing-binaries/osx-homebrew.rst +++ /dev/null @@ -1,46 +0,0 @@ - -OS X Homebrew packages --------------------------------------------------------------------------------- - -We generate Homebrew packages within our automated build system. - -We **only** support the two most recent OS X versions: - -- `OS X Yosemite (10.10) `_ -- `OS X El Capitan (10.11) `_ - -**We only support 64-bit builds.** - -If your system does not support either of these OS X versions then you -are out of luck. Sorry! - -All OS X builds require you to `install the Homebrew `_ -package manager before doing anything else. Here's how to `uninstall Homebrew -`_, -if you ever want to start again from scratch. - -To install the Ethereum C++ components from Homebrew, execute these commands: :: - - brew update - brew upgrade - brew tap ethereum/ethereum - brew install cpp-ethereum - brew linkapps cpp-ethereum - -Or ... :: - - brew install cpp-ethereum --with-gui - -... if you want to build -`AlethZero `_ and -the `Mix IDE `_ too. - -To start the applications, type one of these commands in a Terminal window: :: - - open /Applications/AlethZero.app - open /Applications/Mix.app - eth - -Here is the `Homebrew Formula -`_ -which details all the supported command-line options. diff --git a/source/ethereum-clients/cpp-ethereum/installing-binaries/windows-chocolatey.rst b/source/ethereum-clients/cpp-ethereum/installing-binaries/windows-chocolatey.rst deleted file mode 100644 index 4778882..0000000 --- a/source/ethereum-clients/cpp-ethereum/installing-binaries/windows-chocolatey.rst +++ /dev/null @@ -1,18 +0,0 @@ - -Windows Chocolatey NuGet packages --------------------------------------------------------------------------------- - -We aren't generating `Chocolatey `_ packages at -the time of writing, though we have done so in the past. - -For anybody who isn't already familiar with the technology, this is essentially -`apt-get for Windows` - a global silent installer for tools. - -We would like to -`support Chocolatey `_ -again in the near future for all the same reasons we support Homebrew on OS X -and have PPAs for Ubuntu. For technically competent users, doing -command-line operations like so would be very convenient: :: - - choco install cpp-ethereum - choco update cpp-ethereum diff --git a/source/ethereum-clients/cpp-ethereum/installing-binaries/windows-installer.rst b/source/ethereum-clients/cpp-ethereum/installing-binaries/windows-installer.rst deleted file mode 100644 index 2faff2b..0000000 --- a/source/ethereum-clients/cpp-ethereum/installing-binaries/windows-installer.rst +++ /dev/null @@ -1,24 +0,0 @@ - -Windows installer --------------------------------------------------------------------------------- - -We generate Windows installers -`for each release `_. - -These should work on Windows 7, Windows 8/8.1, Windows 10 and Windows Server -2012 R2, though our `automated builds `_ are all built -on a Windows 8.1 host machine. - -If you hit runtime errors complaining about missing **msvcr120.dll** or -**msvcp120.dll** files then please install the -`Visual C++ Redistributable Packages for Visual Studio 2013 `_ -from Microsoft. - -**We only support 64-bit builds.** - -It may be possible to get the client working for Windows 32-bit, by building -from source and disabling EVMJIT and maybe other features too. We might accept -pull-requests to add such support, but we will not put any of our development -time into supporting Windows 32-bit builds. - -The vast majority of individuals using Windows have 64-bit hardware now. diff --git a/source/ethereum-clients/cpp-ethereum/portability.rst b/source/ethereum-clients/cpp-ethereum/portability.rst deleted file mode 100644 index 71220a9..0000000 --- a/source/ethereum-clients/cpp-ethereum/portability.rst +++ /dev/null @@ -1,125 +0,0 @@ -.. _cpp-ethereum-portability: - -################################################################################ -Portability -################################################################################ - -The Ethereum C++ client code is exceedingly portable, and is being successfully -used on a huge range of different operating systems and devices. - -We continue to expand our range and are very open to pull-requests which add -support for additional operating systems, compilers or devices. - - -Operating systems verified as working --------------------------------------------------------------------------------- - -- Linux - - Alpine Linux - - Arch Linux - - Debian 8 (Jessie) - - Fedora 20 - - Fedora 21 - - Fedora 22 - - openSUSE Leap 42.1 - - Raspbian - - Sailfish OS 2.0 - - Ubuntu 14.04 (Trusty) - - Ubuntu 14.10 (Utopic) - - Ubuntu 15.04 (Vivid) - - Ubuntu 15.10 (Wily) - - Ubuntu 16.04 (Xenial) - - Ubuntu Touch - - Ubuntu 15.04 MATE -- BSD - - FreeBSD -- OS X - - OS X Yosemite (10.10) - - OS X El Capitan (10.11) - - OS X 10.10 (Yosemite Server 4.0) - - OS X 10.11 (Yosemite Server 5.0) - - OS X 10.11 (Yosemite Server 5.1) -- Windows - - Windows 7 - - Windows 8 - - Windows 8.1 - - Windows 10 - - Windows Server 2012 R2 - - -Operating systems - work in progress --------------------------------------------------------------------------------- - -- Linux - - Maemo - - MeeGo - - Tizen -- BSD - - iOS - - tvOS - - WatchOS -- Android - - -Devices verified as working --------------------------------------------------------------------------------- - -- All varieties of desktop and laptop devices (Windows, OS X, Desktop Linux) - - 64-bit (with rebuilt binaries) - - 32-bit (not official supported, but they work) -- Smartphones - - Linux - - Jolla Phone - - Meizu MX4 Ubuntu Edition - - Nexus 5 (SailfishOS 2.0) -- SBCs - - Linux - - BeagleBone Black - - Odroid XU3 - - Project C.H.I.P. - - Raspberry Pi Model A - - Raspberry Pi Model B+ - - Raspberry Pi Zero - - Raspberry Pi 2 - - Raspberry Pi 3 - - Wandboard Quad - - -Devices - work in progress --------------------------------------------------------------------------------- -- Smartwatches - - Linux - - Samsung Gear S2 - - BSD - - Apple Watch -- Smartphones - - Linux - - Nokia N9 (MeeGo) - - Nokia N900 (Meemo) - - Samsung Z1 - - Samsung Z3 - - Android - - Samsung Galaxy S3 - - Samsung Galaxy S4 - - BSD - - iPhone 3GS - - iPhone 5 -- Developer phones - - Linux - - Samsung RD-210 - - Samsung RD-PQ - - Samsung TM1 -- Tablets - - Android - - Samsung Galaxy Tab S 10.5 - - Nexus 7 - - BSD - - iPad Air 2 -- SBCs - - Linux - - DragonBoard 410c - - Intel Curie - - Intel Edison - - Intel NUC - - Minnowboard Max - - Odroid XU4 diff --git a/source/ethereum-clients/cpp-ethereum/project-reboot.rst b/source/ethereum-clients/cpp-ethereum/project-reboot.rst deleted file mode 100644 index 94afcfe..0000000 --- a/source/ethereum-clients/cpp-ethereum/project-reboot.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. _project-reboot: - -################################################################################ -Project reboot -################################################################################ - -The project is going through a `reboot under new leadership -`_. At -the time of writing, we have a number of moving parts. Please bear with us! - -We `simplified the project naming -`_ at Homestead, -although some naming shadows of the past still linger. There was a further -`C++ development update `_ -from Christian in May 2016. - - -The next big step is our pending `git repository reorganization `_, -which will move our code back into the -`cpp-ethereum `_ repository. - -We are also -`working toward `_ -re-licensing the codebase as `Apache 2.0 `_, -which would be the culmination of a very long-term plan to -`liberalize the core `_. An effort was -begun in 2015 to re-license the cpp-ethereum core as MIT, but it was never completed. This -is a revival of that effort, especially with a view towards the potential for collaboration -with the `Linux Foundation `_'s -`Hyperledger `_ project. - -Current reality (squares are applications, circles are libraries): - -.. image:: ../../img/dependency_graph.svg - -Target refactoring: - -.. image:: ../../img/target_dependency_graph.svg diff --git a/source/ethereum-clients/cpp-ethereum/running.rst b/source/ethereum-clients/cpp-ethereum/running.rst deleted file mode 100644 index 44d22db..0000000 --- a/source/ethereum-clients/cpp-ethereum/running.rst +++ /dev/null @@ -1,36 +0,0 @@ -################################################################################ -Running -################################################################################ - -Running eth without any argument will synchronise your node to the public blockchain. -It is also possible to create or synchronise to another blockchain (see :ref:`custom blockchain using eth `). - -Interacting with your node can be done using either geth or the ethereum console: - -**Using geth** - -.. code:: Console - - > geth attach //attach geth to a running eth node. - -**Using the ethereum console** - -The ethereum console is a node.js application which connect to a running eth/geth node and provide access to the web3 object. - -.. note:: https://github.com/ethereum/ethereum-console - -It can be installed using npm: - -.. note:: | > npm install -g ethereum-console - | > ethconsole - -.. note:: | **Usage:** - | ethconsole [javascript file] [ipc socket] - | Connects to an ethereum node via ipc in order to control it remotely - | through global variable web3 (web3.admin is also present). - | If no arguments are given, connects to the default ipc socket - | and drops into interactive mode. - | Arguments: - | connect to the given ipc socket (use ipc:// if it does not end with .ipc) - | execute the given javascript file that has to end in .js non-interactively. - | The script has to call process.exit() in order to terminate the console. diff --git a/source/ethereum-clients/cpp-ethereum/what-are-the-modules.rst b/source/ethereum-clients/cpp-ethereum/what-are-the-modules.rst deleted file mode 100644 index 5999264..0000000 --- a/source/ethereum-clients/cpp-ethereum/what-are-the-modules.rst +++ /dev/null @@ -1,74 +0,0 @@ - -################################################################################ -What are the modules? -################################################################################ - - -What are the primary executables? -================================================================================ - -- **eth** A command-line Ethereum full-node that can be controlled via RPC. -- **mix** An IDE for contract and user interface development, testing and deployment to the blockchain. -- **solc** The solidity command line compiler -- **lllc** The LLL command-line compiler. - - -Deprecated executables, to be retired soon -================================================================================ - -- **AlethZero** A Qt-based all-encompassing GUI for interacting with Ethereum (receives minimal support). -- **EthKey** Key management CLI. - - -What are the various modules? -================================================================================ - -- **AlethZero** - A Qt-based GUI for interacting with Ethereum. Receives minimal support. -- **libethereum** - Modules related to the Ethereum part of web3, i.e. consensus engine, blockchain download, virtual machine. - - **ethkey**: stand-alone key management - - **ethminer**: stand-alone ethash miner - - ethvm: stand-alone EVM execution utility - - evmjit: library for the EVM just-in-time compiler - - libethash: ethash mining POW algorithm implementation - - libethash-cl: ethash mining code for GPU mining (OpenCL) - - libethashseal: generic wrapper around the POW block seal engine. Also contains the genesis states for all ethash-based chains. - - libethcore: collection of core data structures and concepts - - libethereum: main consensus engine (minus EVM). Includes the State and BlockChain classes. - - libevm: Ethereum Virtual Machine implementation (interpreter). - - libevmasm: EVM assembly tools, also contains the optimizer. - - libevmcore: elementary data structures of the EVM, opcodes, gas costs, ... - - liblll: Low-level LISP-like Language compiler & assembler. - - libnatspec: natspec script evaluator (confirmation messages) - - libtestutils: utilities for testing code - - lllc: LLL compiler commandline interface -- **libweb3core** - Web3 core libraries, networking, encoding, decoding, basic data structures. - - bench: trie benchmarking - - libdevcore: data structures, utilities, rlp, trie, memory db - - libdevcrypto: crypto primitives. Depends on libsecp256k1 and libcrypto++. - - libp2p: core peer to peer networking implementation (excluding specific sub-protocols) - - rlp: stand-alone rlp en-/decoder -- **mix** - Dapp IDE -- **solidity** - Solidity compiler - - docs: documentation, appears at http://solidity.readthedocs.org/ - - libsolidity: actual implementation - - analysis: reference resolution, type checking, ... (builds up the annotations for the AST) - - ast: abstract syntax tree and type system - - codegen: assembly code generation from annotated AST - - formal: formal verification - - interface: external interface for users of libsolidity - - parsing: parser (creates the non-annotated AST) - - solc: commandline compiler -- **web3.js** - JavaScript Dapp framework library (connects to backend via RPC / IPC) -- **webthree** - actual client / node implementation ("eth") - - eth: commandline client / node - - libjsconsole: JavaScript console for access to eth - deprecated, to be replaced by nodejs application - - libjsengine: underlying engine for libjsconsole, to be removed - - libweb3jsonrpc: json-rpc server-side endpoint, provides http and IPC (unix socket, windows pipe) connectors - - libwebthree: service connectors for ethereum, swarm/ipfs and whisper. - - libwhisper: whisper implementation -- **webthree-helpers** - build system and some external dependencies - - cmake: cmake files for build system, contains specification of inter-dependencies - - utils: external dependencies - - json_spirit: JSON parser written for Boost's Spirit library. - - libscrypt: scrypt implementation - - secp256k1: implementation of the SECP 256k1 ECDSA signing algorithm. diff --git a/source/ethereum-clients/ethereumh/index.rst b/source/ethereum-clients/ethereumh/index.rst deleted file mode 100644 index cb47b18..0000000 --- a/source/ethereum-clients/ethereumh/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _ethereumH: - -################################################################################ -ethereumH -################################################################################ - -This package provides a tool written in Haskell to allow you to connect to -the Ethereum blockchain - -Links: - -* Github: https://github.com/blockapps/ethereumH -* BlockApps: http://www.blockapps.net/ \ No newline at end of file diff --git a/source/ethereum-clients/ethereumj/index.rst b/source/ethereum-clients/ethereumj/index.rst deleted file mode 100644 index 3614833..0000000 --- a/source/ethereum-clients/ethereumj/index.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. _Ethereum\(J\): - -################################################################################ -Ethereum(J) -################################################################################ - -**Ethereum(J)** is a pure-Java implementation of the Ethereum protocol. -It is provided as a library that can be embedded in any Java/Scala project and -to provide full support for Ethereum protocol and sub-services. -Ethereum(J) was first developed by -`Roman Mandeleil `_ and is now sponsored -by ` `_. - -Ethereum(J) supports CPU mining. It is currently implemented in pure Java -and can be used in private and test networks. You may even mine on the -live Ethereum network, even though it is not economically feasible. - -Links: - -* Blog: http://ethereumj.io/ -* Github: https://github.com/ethereum/ethereumj -* Gitter chat: https://gitter.im/ethereum/ethereumj diff --git a/source/ethereum-clients/ethereumjs-lib/index.rst b/source/ethereum-clients/ethereumjs-lib/index.rst deleted file mode 100644 index 88e6b13..0000000 --- a/source/ethereum-clients/ethereumjs-lib/index.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _ethereumjs-lib: - -################################################################################ -ethereumjs-lib -################################################################################ - -**ethereumjs-lib** is the javascript library of core `Ethereum `_ functions as described in the `Yellow Paper `_. This is a simple meta-module that provides the following modules. Most JS modules are tracked in `ethereumjs `_ - -* `VM `_ - The Ethereum virtual machine and state processing functions -* `Blockchain `_ - Blockchain managment -* `Block `_ - Block Schema definition and validation -* `Transaction `_ - Transaction Schema definition and validation -* `Account `_ - Account Schema definition and validation -* `rlp `_ - Recursive Length Prefix serialization -* `Trie `_ - Modified Merkle Patricia Tree -* `Ethash `_ - Ethereum's Proof of Work algorithm -* `utils `_ - Miscellaneous helper functions -* `devp2p `_ - The networking protocol -* `devp2p-dpt `_ - The disputed peer table - -Links: - -* Github: https://github.com/ethereumjs/ethereumjs-lib -* Join the Gitter chat: https://gitter.im/ethereum/ethereumjs-lib - diff --git a/source/ethereum-clients/go-ethereum/index.rst b/source/ethereum-clients/go-ethereum/index.rst deleted file mode 100644 index 9cef0bc..0000000 --- a/source/ethereum-clients/go-ethereum/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _go-ethereum: - -################################################################################ -go-ethereum -################################################################################ - -The go-ethereum client is commonly referred to as **geth**, which is the the command line interface for running a full ethereum node implemented in Go. By installing and running geth, you can take part in the ethereum frontier live network and: - -* mine real ether -* transfer funds between addresses -* create contracts and send transactions -* explore block history -* and much much more - -Links: - -* Website: http://ethereum.github.io/go-ethereum/ -* Github: https://github.com/ethereum/go-ethereum -* Wiki: https://github.com/ethereum/go-ethereum/wiki/geth -* Gitter: https://gitter.im/ethereum/go-ethereum \ No newline at end of file diff --git a/source/ethereum-clients/index.rst b/source/ethereum-clients/index.rst deleted file mode 100644 index 43a0736..0000000 --- a/source/ethereum-clients/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. _Ethereum Clients: - -################################################################################ -Ethereum Clients -################################################################################ - -.. toctree:: - :maxdepth: 2 - - choosing-a-client.rst - cpp-ethereum/index.rst - go-ethereum/index.rst - pyethapp/index.rst - ethereumjs-lib/index.rst - ethereumj/index.rst - ethereumh/index.rst - parity/index.rst - ruby-ethereum/index.rst diff --git a/source/ethereum-clients/parity/index.rst b/source/ethereum-clients/parity/index.rst deleted file mode 100644 index d6ac0f1..0000000 --- a/source/ethereum-clients/parity/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. _Parity: - -################################################################################ -Parity -################################################################################ - -**Parity** claims to be the world's fastest and lightest Ethereum client. It is written in the Rust language, which offers improved reliability, performance, and code clarity. Parity is being developed by `Ethcore `_, which was founded by several members of the Ethereum Foundation. - -* Website: https://ethcore.io/parity.html -* Github: https://github.com/ethcore/parity -* Gitter chat: https://gitter.im/ethcore/parity - -Arch Linux packages are community maintained by `Afri Schoedon `_ and quininer. - -* https://aur.archlinux.org/packages/parity/ (stable, latest release) -* https://aur.archlinux.org/packages/parity-git/ (unstable, latest develop) - -Some people have reported success with Parity on Raspberry Pi 2. diff --git a/source/ethereum-clients/pyethapp/index.rst b/source/ethereum-clients/pyethapp/index.rst deleted file mode 100644 index d8f77f4..0000000 --- a/source/ethereum-clients/pyethapp/index.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. _pyethapp: - -################################################################################ -pyethapp -################################################################################ - -**pyethapp** is the python-based client implementing the Ethereum cryptoeconomic state machine. The python implementation aims to provide an easily hackable and extendable codebase. - -pyethapp leverages two ethereum core components to implement the client: - -* `pyethereum `_ - the core library, featuring the blockchain, the ethereum virtual machine, mining -* `pydevp2p `_ - the p2p networking library, featuring node discovery for and transport of multiple services over multiplexed and encrypted connections - -Links: - -* Github: https://github.com/ethereum/pyethapp -* Wiki: https://github.com/ethereum/pyethapp/wiki/Getting-Started -* Gitter chat: https://gitter.im/ethereum/pyethapp - diff --git a/source/ethereum-clients/ruby-ethereum/index.rst b/source/ethereum-clients/ruby-ethereum/index.rst deleted file mode 100644 index 209dd8c..0000000 --- a/source/ethereum-clients/ruby-ethereum/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _ruby-ethereum: - -################################################################################ -ruby-ethereum -################################################################################ - -**ruby-ethereum** is an implementation of the :ref:`Ethereum Virtual Machine ` written in Ruby. - - -Links: - -* Github: https://github.com/janx/ruby-ethereum -* Gem: https://rubygems.org/gems/ruby-ethereum - - -Related: - -* `ruby-serpent `_: Ruby binding to the `Ethereum Serpent `_ compiler. -* `ethereum-ruby `_: a pure-Ruby JSON-RPC wrapper for communicating with an Ethereum node. To use this library you will need to have a running Ethereum node with IPC support enabled (default). Currently, the :ref:`go-ethereum` client is supported. - diff --git a/source/frequently-asked-questions/frequently-asked-questions.rst b/source/frequently-asked-questions/frequently-asked-questions.rst deleted file mode 100644 index ca53ef4..0000000 --- a/source/frequently-asked-questions/frequently-asked-questions.rst +++ /dev/null @@ -1,113 +0,0 @@ -################################################################################ -Frequently Asked Questions -################################################################################ - -.. contents:: - :local: - :depth: 2 - -Questions -============================================================================================== - -What is Ethereum? ----------------------------------------------------------------------------------------------- -Ethereum is a decentralized smart contracts platform that is powered by a cryptocurrency called Ether. A good starting point to learn more about it's workings would be the ":ref:`what-is-ethereum`" page. - -I have heard of Ethereum, but what are Geth, Mist, Ethminer, Mix? ----------------------------------------------------------------------------------------------- - -* **Geth**: This is the Go implementation of an Ethereum node, and is the basis for any interactions with the Ethereum blockchain. Running this locally will allow you to easily interact with the Ethereum blockchain. Read the `go-ethereum installation instructions `_. - -* **Mist**: This is the equivalent of a web browser, but for the Ethereum platform. It acts as a GUI to display the accounts and contracts that you interact with. It also allows you to create and interact with contracts in a graphical user interface without ever touching the command line. If you are not a developer and just want to store Ether and interact with Ethereum contracts, then Mist is the program to use. Downloads can be found on the `Mist releases page `_. - -* **Ethminer**: A standalone miner. This can be used to mine or benchmark a mining set-up. It is compatible with eth, geth, and pyethereum. Check out the :ref: `mining` page for more information. - -* **Mix**: The integrated development environment for DApp authoring. Quickly prototype and debug decentralised applications on the Ethereum platform. More information can be found at the `Mix GitHub Page `_. - -How can I store big files on the blockchain? ----------------------------------------------------------------------------------------------- -In general you do not want to store large files or pieces of data in the Ethereum blockchain because of the high cost of storage. You will need to use a third party storage solution, such as Swarm or IPFS. Swarm is an Ethereum-specific project for distributed file storage. IPFS is an non-Ethereum project which has close ties to Ethereum; it will be used independently and may be used as an added layer underlying Swarm in the future. See `this Ethereum StackExchange post on the topic `_ for more information. - -Is Ethereum based on Bitcoin? ----------------------------------------------------------------------------------------------- -Only in the sense that it uses a blockchain, which Bitcoin pioneered. Ethereum has a separate blockchain that has several significant technical differences from Bitcoin's blockchain. See `this Ethereum StackExchange answer `_ for a detailed explanation. - -What's the future of Ethereum? ----------------------------------------------------------------------------------------------- -Ethereum developers are planning a switch from a Proof-of-Work consensus model to a Proof-of-Stake consensus model in the future. They are also investigating scalability solutions and how to store secrets on the blockchain. - -What's the difference between account and "wallet contract"? ----------------------------------------------------------------------------------------------- -An account is your public / private key pair file that serves as your identity on the blockchain. See "account" in the glossary. A "wallet contract" is an Ethereum contract that secures your ether and identity with features such as multisignature signing and programmed deposit/withdrawal limits. A wallet contract can be easily created in the Mist Ethereum Wallet GUI client. - -Are keyfiles only accessible from the computer you downloaded the client on? ----------------------------------------------------------------------------------------------- -No, you are welcome to export or move the keyfile, but always remember to backup your keyfiles and be aware of which computers you store your keyfile on. - -How long should it take to download the blockchain? ----------------------------------------------------------------------------------------------- -The Ethereum blockchain is constantly growing, and is nearing 10GB as of March 2016. The amount of time it will take to download depends on the amount of peers you are able to connect to, your internet connection speed, and other factors. See the :ref: `download-the-blockchain-faster` section for tips on syncing the blockchain more quickly. - -How do I get a list of transactions into/out of an address? ----------------------------------------------------------------------------------------------- -You would have to pull the transactions manually out of the blockchain to achieve this. Alternatively, you can rely on third party explorers' API's like `Etherchain `_. For contract execution transactions however, you can filter the contract logs to achieve this. - -Can a contract pay for its execution? ----------------------------------------------------------------------------------------------- -No this is not possible. The gas for the execution must be provided by the address submitting the execution request. - -Can a contract call another contract? ----------------------------------------------------------------------------------------------- -Yes, this is possible, read `about interactions between contracts `_. - -Can a transaction be signed offline and then submitted on another online device? ----------------------------------------------------------------------------------------------- -Yes, you can refer to the solution from `Icebox `_. - -How to get testnet Ether? ----------------------------------------------------------------------------------------------- -See :ref: `test-networks`. - -Can a transaction be sent by a third party? i.e can transaction broadcasting be outsourced ----------------------------------------------------------------------------------------------- -Technically yes, but there is an important restriction as opposed to bitcoin signed transactions: in ethereum the transaction has a nonce (more precisely, each account increases a counter when sending a transaction based on how many transactions total have been sent. If 3 transactions have ever been sent from the account, the account nonce would be 3). - -Can Ethereum contracts pull data using third-party APIs? ----------------------------------------------------------------------------------------------- -No, Ethereum contracts cannot pull data from external information sources in this way. It is however possible to push data from external sites (e.g. weather sites, stock prices) to Ethereum contracts through transactions. There are "oracle" services that are compatible with the Ethereum network that will pull/push data to the Ethereum network for a fee. - -Is the content of the data and contracts sent over the Ethereum network encrypted? ----------------------------------------------------------------------------------------------- -Data and contracts on the Ethereum network are encoded, but not encrypted. Everyone can audit the behavior of the contracts and the data sent to them. However, you are always free to encrypt data locally before broadcasting it to the network. - -Can I store secrets or passwords on the Ethereum network? ----------------------------------------------------------------------------------------------- -All data on Ethereum is public. It is not possible to store secrets or passwords in Ethereum contracts without it being seen by all. There is work being done to make this a possibility through code obfuscation and other techniques. A good read would be this article by `Vitalik Buterin `_. - -How will Ethereum combat centralisation of mining pools? ----------------------------------------------------------------------------------------------- -There are two primary ways that the Ethereum PoW based consensus algorithm combats mining centralisation (`Source `_). - -* The first is by reducing losses due to orphaned blocks, which independent miners are more likely to experience. - - * This portion of the Ethereum mining algorithm, a technique referred to as GHOST, includes the headers only of recently orphaned blocks in return for a reduced reward to both the block producer and the includer of the (otherwise orphaned) block. These included orphans from "grandparent" or earlier blocks are frequently referred to as "uncle" blocks because the gender neutral term "ommer" isn't widely known or understood. - -* The second way that the Ethereum PoW consensus algorithm combats mining centralisation is by its use of a Proof of Work function that is ASIC resistant. - - * By preventing mining from becoming dominated by specially designed and produced hardware, independent miners are kept competitive or even given an advantage in terms of their profits and/or levels of hardware investment, because they can make use of readily available commodity hardware (i.e. consumer graphics cards). - -How will Ethereum deal with ever increasing blockchain size? ----------------------------------------------------------------------------------------------- -There are many discussions around blockchain scalability. This questioned has been partially answered on `this Ethereum StackExchange post `_ and `this blog post from Vitalik Buterin `_. - -How will Ethereum ensure the network is capable of making 10,000+ transactions-per-second? ----------------------------------------------------------------------------------------------- -Ethereum is planning on implementing a proof-of-stake consensus protocol change during the Serenity phase of their development roadmap. More information on the likely Ethereum PoS candidate and how it may increase transactions-per-second can be `found here `_. - -Where do the contracts reside? ----------------------------------------------------------------------------------------------- -TODO - -Your question is still not answered? ----------------------------------------------------------------------------------------------- -Ask the community on `Ethereum StackExchange `_. diff --git a/source/glossary.rst b/source/glossary.rst deleted file mode 100644 index 19e9bd4..0000000 --- a/source/glossary.rst +++ /dev/null @@ -1,439 +0,0 @@ -******************************************************************************** -Glossary -******************************************************************************** - -.. glossary:: - :sorted: - -.. _geth-letter: - - Đ - Đ, `D with stroke `_, is used in Old English, Middle English, Icelandic, and Faroese to stand for an uppercase letter "Eth". It is used in words like ĐEV or Đapp (decentralized application), where the Đ is the Norse letter "eth". The uppercase eth (Ð) is also used to symbolize the cryptocurrency Dogecoin. - -.. _dec-app: - - decentralized application (= dapp_) - Service that operates without a central trusted party. An application that enables direct interaction/agreements/communication between end users and/or resources without a middleman. See :ref:`dapps`. - - DAO - decentralized autonomous organization - DAO is type of contract on the blockchain (or a suite of contracts) that is supposed to codify, enforce or automate the workings of an organization including governance, fund-raising, operations, spending and expansion. - - identity - A set of cryptographically verifiable interactions that have the property that they were all created by the same person. - - digital identity - The set of cryptographically verifiable transactions signed by the same public key define the digital identity's behavior. In many real world scenarios (voting) it is desireable that digital identities coincide with real world identities. Ensuring this without violence is an unsolved problem. - - unique identity - A set of cryptographically verifiable interactions that have the property that they were all created by the same person, with the added constraint that one person cannot have multiple unique identities. - - reputation - The property of an identity that other entities believe that identity to be either (1) competent at some specific task, or (2) trustworthy in some context, i.e., not likely to betray others even if short-term profitable. - - escrow - If two mutually-untrusting entities are engaged in commerce, they may wish to pass funds through a mutually trusted third party and instruct that party to send the funds to the payee only when evidence of product delivery has been shown. This reduces the risk of the payer or payee committing fraud. Both this construction and the third party is called escrow. - - deposit - Digital property placed into a contract involving another party such that if certain conditions are not satisfied that property is automatically forfeited and either credited to a counterparty as insurance against the conditions, or destroyed (= burnt = equally distributed) or donated to some charitable funds. - - web of trust - The idea that if A highly rates B, and B highly rates C, then A is likely to trust C. Complicated and powerful mechanisms for determining the reliability of specific individuals in specific concepts can theoretically be gathered from this principle. - - incentive compatibility - A protocol is incentive-compatible if everyone is better off "following the rules" than attempting to cheat, at least unless a very large number of people agree to cheat together at the same time (collusion). - - collusion - In an incentivized protocol scenario, when a number of participants *play together* (conspire) to game the rules to their own benefit. - - token system - A fungible virtual good that can be traded. More formally, a token system is a database mapping addresses to numbers with the property that the primary allowed operation is a transfer of N tokens from A to B, with the conditions that N is non-negative, N is not greater than A's current balance, and a document authorizing the transfer is digitally signed by A. Secondary "issuance" and "consumption" operations may also exist, transaction fees may also be collected, and simultaneous multi-transfers with many parties may be possible. Typical use cases include currencies, cryptographic tokens inside of networks, company shares and digital gift cards. - - block - A block is a package of data that contains zero or more transactions, the hash of the previous block ("parent"), and optionally other data. The total set of blocks, with every block except for the initial "genesis block" containing the hash of its parent, is called the blockchain and contains the entire transaction history of a network. Note that some blockchain-based cryptocurrencies use the word "ledger" instead of blockchain; the two are roughly equivalent, although in systems that use the term "ledger" each block generally contains a full copy of the current state (e.g. currency balances, partially fulfilled contracts, registrations) of every account allowing users to discard outdated historical data. - -.. _dapp: - - dapp - Đapp - Stands for "decentralized application". Some say it is pronounced Ethapp due to the use of the `uppercase eth letter Ð `_. - - address - An Ethereum address represents an account. For EOA_, the address is derived as the last 20 bytes of the public key controlling the account, e.g., ``cd2a3d9f938e13cd947ec05abc7fe734df8dd826``. This is a hexadecimal_ format (base 16 notation), which is often indicated explicitly by appending ``0x`` to the address. Web3.js and console functions accept addresses with or without this prefix but for transparency we encourage their use. Since each byte of the address is represented by 2 hex characters, a prefixed address is 42 characters long. Several apps and APIs are also meant to implement the new `checksum-enabled address scheme `_ introduced in the Mist Ethereum wallet as of version 0.5.0. - -.. _hexadecimal: - - hexadecimal - Common representation format for byte sequencing. Its advantage is that values are represented in a compact format using two characters per byte (the characters ``[0-9][a-f]``). - - ether - Ether is the name of the currency used within Ethereum. It is used to pay for computations within the EVM. Ambiguously, ether is also the name of a unit in the system; - -.. _EOA: - - EOA - Externally Owned Account. An account controlled by a private key. If you own the private key associated with the EOA you have the ability to send ether and messages from it. Contract accounts also have an address, see :ref:`Accounts`. EOAs and contract accounts may be combined into a single account type during Serenity. - -.. _gas: - - gas - Name for the `cryptofuel` that is consumed when code is executed by the EVM. The gas is paid for execution fee for every operation made on an Ethereum blockchain. - - -.. _gas limit: - - gas limit - Gas limit can apply to both individual transactions, see `transaction gas limit `_ and to blocks, `block-gas-limit`. For individual transactions, the gas limit represents the maximum amount of gas you indicate you are willing to pay for a contract execution transaction. It is meant to protect users from getting their ether depleted when trying to execute buggy or malicious contracts. The block gas limit represents the maximum cumulative gas used for all the transactions in a block. With the launch of Homestead, the block gas limit floor will increase from 3,141,592 gas to 4,712,388 gas (~50% increase). - -.. _transaction-gas-limit: - - gas price - Price in ether of one unit of gas specified in a transaction. With the launch of Homestead, the default gas price reduces from 50 shannon to 20 shannon (~60% reduction). - - transaction - The signed data package that stores a message to be sent from an externally owned account. Simply put, a transaction describes a transfer of information from an EOA to another EOA or a contract account. - - message - A data transfer mechanism contracts use to communicate with other contracts. Messages can also be described as virtual objects that are never serialized and exist only in the Ethereum execution environment. - - Web3 - The exact definition of the Web3 paradigm is still taking form, but it generally refers to the phenomenon of increased connectedness between all kinds of devices, decentralization of services and applications, semantic storage of information online and application of artificial intelligence to the web. - - DAO - See Decentralized Autonomous Organization. - - epoch - Epoch is the interval between each regeneration of the DAG used as seed by the PoW algorithm Ethash. The epoch in specified as 30000 blocks. - - elliptic curve (cryptography) - Refers to an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields. See `elliptic curve cryptography `_. - - wallet - A wallet, in the most generic sense, refers to anything that can store ether or any other crypto token. In the crypto space in general, the term wallet is used to mean anything from a single private/public key pair (like a single paper wallet) all the way to applications that manage multiple key pairs, like the Mist Ethereum wallet. - - contract - A persistent piece of code on the Ethereum blockchain that encompasses a set of data and executable functions. These functions execute when Ethereum transactions are made to them with certain input parameters. Based on the input parameters, the functions will execute and interact with data within and outside of the contract. - - suicide - See self-destruct. ``selfdestruct`` acts as an alias to the deprecated ``suicide`` terminology in accordance with `EIP 6 \- Renaming SUICIDE OPCODE `_. - - selfdestruct - A global variable in the Solidity language that allows you to `\"destroy the current contract, sending its funds to the given address\" `_. ``selfdestruct`` acts as an alias to the deprecated ``suicide`` terminology in accordance with `EIP 6 \- Renaming SUICIDE OPCODE `_. It frees up space on the blockchain and prevents future execution of the contract. The contract's address will still persist, but ether sent to it will be lost forever. The possibility to kill a contract has to be implemented by the contract creator him/herself using the Solidity ``selfdestruct`` function. - - transaction fee - Also known as gas cost, it is the amount of ether that the miners will charge for the execution of your transaction. - - mining - The process of verifying transactions and contract execution on the Ethereum blockchain in exchange for a reward in ether with the mining of every block. - - mining pool - The pooling of resources by miners, who share their processing power over a network, to split the reward equally, according to the amount of work they contributed to solving a block. - - mining reward - The amount of cryptographic tokens (in this case ether) that is given to the miner who mined a new block. - - state - Refers to a snapshot of all balances and data at a particular point in time on the blockchain, normally referring to the condition at a particular block. - - blockchain - An ever-extending series of data blocks that grows as new transactions are confirmed as part of a new block. Each new block is chained to the existing blockchain by a cryptographic proof-of-work. - - peer - Other computers on the network also running an Ethereum node (Geth) with an exact copy of the blockchain that you have. - - signing - Producing a piece of data from the data to be signed using your private key, to prove that the data originates from you. - - discovery (peer) - The process of 'gossiping' with other nodes in the network to find out the state of other nodes on the network. - - gas price oracle - A helper function of the Geth client that tries to find an appropriate default gas price when sending transactions. - - light client - A client program that allows users in low-capacity environments to still be able to execute and check the execution of transactions without needing to run a full Ethereum node (Geth). - - etherbase - It is the default name of the account on your node that acts as your primary account. If you do mining, mining rewards will be credited to this account. - - coinbase - Coinbase is analogous to etherbase, but is a more generic term for all cryptocurrency platforms. - - balance - The amount of cryptocurrency (in this case) belonging to an account. - - solidity - Solidity is a high-level language whose syntax is similar to that of JavaScript and it is designed to compile to code for the Ethereum Virtual Machine. - - serpent - Serpent is a high-level language whose syntax is similar to that of Python and it is designed to compile to code for the Ethereum Virtual Machine. - - EVM - Ethereum Virtual Machine, the decentralized computing platform which forms the core of the Ethereum platform. - - virtual machine - In computing, it refers to an emulation of a particular computer system. - - peer to peer network - A network of computers that are collectively able to perform functionalities normally only possible with centralized, server-based services. - - decentralization - The concept of moving the control and execution of computational processes away from a central entity. - - distributed hash table - A distributed hash table (DHT) is a class of a decentralized distributed system that provides a lookup service similar to a hash table: (key, value) pairs are stored in a DHT, and any participating node can efficiently retrieve the value associated with a given key. - - NAT - Network address translation (NAT) is a methodology of remapping one IP address space into another by modifying network address information in Internet Protocol (IP) datagram packet headers while they are in transit across a traffic routing device. - - nonce - Number Used Once or Number Once. A nonce, in information technology, is a number generated for a specific use, such as session authentication. Typically, a nonce is some value that varies with time, although a very large random number is sometimes used. In general usage, nonce means “for the immediate occasion” or “for now.” - In the case of Blockchain Proof of Work scenarios, the hash value, found by a Miner, matching the network's Difficulty thus proving the Block Validity is called Nonce as well. - - proof-of-work - Often seen in its abbreviated form "PoW", it refers to a mathematical value that can act as the proof of having solved a resource and time consuming computational problem. - - proof-of-stake - An alternative method of mining blocks that require miners to demonstrate their possession of a certain amount of the currency of the network in question. This works on the principle that miners will be disincentivized to try to undermine a network in which they have a stake. PoS is less wasteful than PoW, but is still often used together with it to provide added security to the network. - - CASPER - Casper is a security-deposit based economic consensus protocol. This means that nodes, so called “bonded validators”, have to place a security deposit (an action we call “bonding”) in order to serve the consensus by producing blocks. If a validator produces anything that Casper considers “invalid”, the deposit is forfeited along with the privilege of participating in the consensus process. - - consensus - The agreement among all nodes in the network about the state of the Ethereum network. - - homestead - Homestead is the second major version release of the Ethereum platform. Homestead includes several protocol changes and a networking change that makes possible further network upgrades: `EIP\-2 Main homestead hardfork changes `_; `EIP\-7 Hardfork EVM update (DELEGATECALL) `_; `EIP\-8 devp2p forward compatibility `_. Homestead will launch when block 1,150,000 is reached on the Mainnet. On the Testnet, Homestead will launch at block 494,000. - - metropolis - The third stage of Ethereum's release. This is the stage when the user interfaces come out (e.g. Mist), including a dapp store, and non-technical users should feel comfortable joining at this point. - - serenity - The fourth stage of Ethereum's release. This is when things are going to get fancy: the network is going to change its mining process from Proof-of-Work to Proof-of-Stake. - - frontier - Ethereum was planned to be released in four major steps with Frontier being the name for the first phase. The Frontier release went live on July 30th, 2015. The command line Frontier phase was mainly meant to get mining operations going with the full reward of 5 ether per block and also to promote the emergence of ether exchanges. Frontier surpassed earlier modest expectations and has nurtured tremendous growth of the ecosystem. - - olympic - The Frontier pre-release, which launched on May 9th 2015. It was meant for developers to help test the limits of the Ethereum blockchain. - - morden - Morden is the first Ethereum alternative testnet. It is expected to continue throughout the Frontier and Homestead era. - - testnet - A mirror network of the production Ethereum network that is meant for testing. See Morden. - - private chain - A fully private blockchain is a blockchain where write permissions are kept centralized to one organization. - - consortium chain - A blockchain where the consensus process is controlled by a pre-selected set of nodes. - - micropayment - A micropayment is a financial transaction involving a very small sum of money (<1 USD) and usually one that occurs online. - - sharding - The splitting of the space of possible accounts (contracts are accounts too) into subspaces, for example, based on first digits of their numerical addresses. This allows for contract executions to be executed within 'shards' instead of network wide, allowing for faster transactions and greater scalability. - - hash - A cryptographic function which takes an input (or 'message') and returns a fixed-size alphanumeric string, which is called the hash value (sometimes called a message digest, a digital fingerprint, a digest or a checksum). A hash function (or hash algorithm) is a process by which a document (i.e. a piece of data or file) is processed into a small piece of data (usually 32 bytes) which looks completely random, and from which no meaningful data can be recovered about the document, but which has the important property that the result of hashing one particular document is always the same. Additionally, it is crucially important that it is computationally infeasible to find two documents that have the same hash. Generally, changing even one letter in a document will completely randomize the hash; for example, the SHA3 hash of "Saturday" is ``c38bbc8e93c09f6ed3fe39b5135da91ad1a99d397ef16948606cdcbd14929f9d``, whereas the SHA3 hash of "Caturday" is ``b4013c0eed56d5a0b448b02ec1d10dd18c1b3832068fbbdc65b98fa9b14b6dbf``. Hashes are usually used as a way of creating a globally agreed-upon identifier for a particular document that cannot be forged. - - crypto-fuel - Similar to 'gas', referring to the amount of cryptocurrency required to power a transaction. - - cryptoeconomics - The economics of cryptocurrencies. - - protocol - A standard used to define a method of exchanging data over a computer network. - - block validation - The checking of the coherence of the cryptographic signature of the block with the history stored in the entire blockchain. - - blocktime - The average time interval between the mining of two blocks. - - network hashrate - The number of hash calculations the network can make per second collectively. - - hashrate - The number of hash calculations made per second. - - serialization - The process of converting a data structure into a sequence of bytes. Ethereum internally uses an encoding format called recursive-length prefix encoding (RLP), described in the `RLP section of the wiki `_. - - double spend - A deliberate blockchain fork, where a user with a large amount of mining power sends a transaction to purchase some produce, then after receiving the product creates another transaction sending the same coins to themselves. The attacker then creates a block, at the same level as the block containing the original transaction but containing the second transaction instead, and starts mining on the fork. If the attacker has more than 50% of all mining power, the double spend is guaranteed to succeed eventually at any block depth. Below 50%, there is some probability of success, but it is usually only substantial at a depth up to about 2-5; for this reason, most cryptocurrency exchanges, gambling sites and financial services wait until six blocks have been produced ("six confirmations") before accepting a payment. - - SPV client - A client that downloads only a small part of the blockchain, allowing users of low-power or low-storage hardware like smartphones and laptops to maintain almost the same guarantee of security by sometimes selectively downloading small parts of the state without needing to spend megabytes of bandwidth and gigabytes of storage on full blockchain validation and maintenance. See light client. - - uncle - Uncles are blockchain blocks found by a miner, when a different miner has already found another block for the corresponding place in the blockchain. They are called “stale blocks”. The parent of an Uncle is an ancestor of the inserting block, located at the tip of the blockchain. In contrast to the Bitcoin network, Ethereum rewards stale blocks as well in order to avoid to penalize miners with a bad connection to the network. This is less critical in the Bitcoin network, because the Block Time there is much higher (~10 minutes) than on the Ethereum network (aimed to ~15 seconds). - - GHOST - Greedy Heaviest-Observed Sub-Tree is an alternative chain-selection method that is designed to incentivize stale blocks (uncles) as well, thus reducing the incentive for pool mining. In GHOST, even the confirmation given by stale blocks to previous blocks are considered valid, and the miners of the stale blocks are also rewarded with a mining reward. - - merkle patricia tree - Merkle Patricia trees provide a cryptographically authenticated data structure that can be used to store all (key, value) bindings. They are fully deterministic, meaning that a Patricia tree with the same (key,value) bindings is guaranteed to be exactly the same down to the last byte and therefore have the same root hash, provide O(log(n)) efficiency for inserts, lookups and deletes, and are much easier to understand and code than more complex comparison-based alternatives like red-black trees. - - DAG - DAG stands for Directed Acyclic Graph. It is a graph, a set of nodes and links between nodes, that has very special properties. Ethereum uses a DAG in Ethash, the Ethereum Proof of Work (POW) algorithm.The Ethash DAG takes a long time to be generated, which is done by a Miner node into a cache file for each Epoch. The file data is then used when a value from this graph is required by the algorithm. - - uncle rate - The number of uncles produced per block. - - issuance - The minting and granting of new cryptocurrency to a miner who has found a new block. - - presale - Sale of cryptocurrency before the actual launch of the network. - - static node - A feature supported by Geth, the Golang Ethereum client, which makes it possible to always connect to specific peers. Static nodes are re-connected on disconnects. For details, see the :ref:`section on static nodes `. - - bootnode - The nodes which can be used to initiate the discovery process when running a node. The endpoints of these nodes are recorded in the Ethereum source code. - - exchange - An online marketplace which facilitates the exchange of crypto or fiat currencies based on the market exchange rate. - - compiler - A program that translates pieces of code written in high level languages into low level executable code. - - genesis block - The first block in a blockchain. - - network id - A number which identifies a particular version of the Ethereum network. - - block header - The data in a block which is unique to its content and the circumstances in which it was created. It includes the hash of the previous block's header, the version of the software the block is mined with, the timestamp and the merkle root hash of the contents of the block. - - pending transaction - A transaction that is not yet confirmed by the Ethereum network. - - block propagation - The process of transmitting a confirmed block to all other nodes in the network. - - sidechain - A blockchain that branches off a main blockchain and checks in periodically with the main blockchain. Besides that it runs independently from the main chain, and any security compromises in the sidechain will not affect the main chain. - - pegging - Locking down the exchange rate of the coins/tokens in two chains (usually a main and a side chain) in a certain direction. - - 2-way pegging - Locking down the exchange rate of the coins/tokens in two chains (usually a main and a side chain) in both directions. - - trustless - Refers to the ability of a network to trustworthily mediate transactions without any of the involved parties needing to trust anyone else. - - faucet - A website that dispenses (normally testnet) cryptocurrencies for free. - - checksum - A count of the number of bits in a transmission that is included with the unit so that the receiving end can verify that the entirety of the message has been transmitted. - - ICAP - Interexchange Client Address Protocol, an IBAN-compatible system for referencing and transacting to client accounts aimed to streamline the process of transferring funds, worry-free between exchanges and, ultimately, making KYC and AML concerns a thing of the past. - - private key - A private key is a string of characters known only to the owner, that is paired with a public key to set off algorithms for text encryption and decryption. - - public key - A string of characters derived from a private key that can be made public. The public key can be used to verify the authenticity of any signature created using the private key. - - encryption - Encryption is the conversion of electronic data into a form unreadable by anyone except the owner of the correct decryption key. It can further be described as a process by which a document (plaintext) is combined with a shorter string of data, called a key (e.g. ``c85ef7d79691fe79573b1a7064c19c1a9819ebdbd1faaab1a8ec92344438aaf4``), to produce an output (ciphertext) which can be "decrypted" back into the original plaintext by someone else who has the key, but which is incomprehensible and computationally infeasible to decrypt for anyone who does not have the key. - - digital signature - A mathematical scheme for demonstrating the authenticity of a digital message or documents. - - port - A network port is a communication endpoint used by a one of the existing standards of establishing a network conversation (e.g. TCP, UDP). - - RPC - Remote Procedure Call, a protocol that a program uses to request a service from a program located in another computer in a network without having to understand the network details. - - IPC - Interprocess communication (IPC) is a set of programming interfaces that allow a programmer to coordinate activities among different program processes that can run concurrently in an operating system. - - attach - The command used to initiate the Ethereum Javascript console. - - daemon - A computer program that runs as a background process instead of in direct control by an interactive user. - - system service - See base layer service - - base layer service - Services such as SWARM and Whisper which are built into the Ethereum platform. - - js - Javascript. - - syncing - The process of downloading the entire blockchain. - - fast sync - Instead of processing the entire block-chain one link at a time, and replay all transactions that ever happened in history, fast syncing downloads the transaction receipts along the blocks, and pulls an entire recent state database. - - ASIC - Application-specific integrated circuit, in this case referring to an integrated circuit custom built for cryptocurrency mining. - - memory-hard - Memory hard functions are processes that experience a drastic decrease in speed or feasibility when the amount of available memory even slightly decreases. - - keyfile - Every account's private key/address pair exists as a single keyfile. These are JSON text files which contains the encrypted private key of the account, which can only be decrypted with the password entered during account creation. - - ICAP format - The format of the IBANs defined using the `Inter-exchange Client Address Protocol `_. - - block(chain) explorer - A website that allows easy searching and extraction of data from the blockchain. - - geth - Ethereum client implemented in the Golang programming language, based on the protocol as defined in the Ethereum Yellow Paper. - - eth - Ethereum client implemented in the C++ programming language, based on the protocol as defined in the Ethereum Yellow Paper. - - ethereumjs - Ethereum client implemented in the Javascript/Node programming language, based on the protocol as defined in the Ethereum Yellow Paper. - - pyethereum - Ethereum client implemented in the Python programming language, based on the protocol as defined in the Ethereum Yellow Paper. - - ethereumj - Ethereum client implemented in the Java programming language, based on the protocol as defined in the Ethereum Yellow Paper. - - ethereumh - Ethereum client implemented in the Haskell programming language, based on the protocol as defined in the Ethereum Yellow Paper. - - parity - Ethereum client implemented in the Rust programming language, based on the protocol as defined in the Ethereum Yellow Paper. - - difficulty - In very general terms, the amount of effort required to mine a new block. With the launch of Homestead, the `difficulty adjustment algorithm will change `_. - - account - Accounts are a central part of the Ethereum network and are an essential part of any transaction or contract. In Ethereum, there are two types of accounts: Externally Owned accounts (EOA) and Contract accounts. - - HLL (obsolete) - Acronym for Higher Level Language, which is what Serpent and Solidity are. HLL is what early Ðapp developers called Ethereum programming languages that did not touch the low level elements. This phrase has been phased out. - - CLL (obsolete) - Acronym for C Like Language, which Mutan was. This acronym has been phased out. - - ES1, ES2, and ES3 (obsolete) - "Ethereum Script" versions 1,2 and 3. There were early versions of what would become the Ethereum Virtual Machine (EVM). - - log event - Contracts are triggered by transactions executed as part of the block verification. If conceived of as a function call, contract execution is asynchronous, and therefore they have no return value. Instead contracts communicate to the outside world with log events. The log events are part of the transaction receipt which is produced when the transaction is executed. - The receipts are stored in the receipt trie, the integrity of which is guaranteed by the fact that the current root of the receipt trie is part of the block header alongside the roots of state and state-trie. In a broad sense from the external perspective receipts are part of the Ethereum system state except that they are not readable contracts internally. - - .. hardware wallet - .. brain wallet - .. cold storage diff --git a/source/img/51Downloading.png b/source/img/51Downloading.png deleted file mode 100644 index b7f6765..0000000 Binary files a/source/img/51Downloading.png and /dev/null differ diff --git a/source/img/51OpeningScreen.png b/source/img/51OpeningScreen.png deleted file mode 100644 index 35f6443..0000000 Binary files a/source/img/51OpeningScreen.png and /dev/null differ diff --git a/source/img/51PresaleImportInstall.png b/source/img/51PresaleImportInstall.png deleted file mode 100644 index 215a9db..0000000 Binary files a/source/img/51PresaleImportInstall.png and /dev/null differ diff --git a/source/img/ETHEREUM-ICON_Black.png b/source/img/ETHEREUM-ICON_Black.png deleted file mode 100644 index 6433738..0000000 Binary files a/source/img/ETHEREUM-ICON_Black.png and /dev/null differ diff --git a/source/img/ETHEREUM-classic-ICON_green.png b/source/img/ETHEREUM-classic-ICON_green.png deleted file mode 100644 index 66dcb13..0000000 Binary files a/source/img/ETHEREUM-classic-ICON_green.png and /dev/null differ diff --git a/source/img/Feels-Good-Man-Frog-02.png b/source/img/Feels-Good-Man-Frog-02.png deleted file mode 100644 index 3725600..0000000 Binary files a/source/img/Feels-Good-Man-Frog-02.png and /dev/null differ diff --git a/source/img/classic-guide.svg b/source/img/classic-guide.svg deleted file mode 100644 index 9fef98f..0000000 --- a/source/img/classic-guide.svg +++ /dev/null @@ -1 +0,0 @@ -chatchaton gitteron gitter diff --git a/source/img/contract_relationship.png b/source/img/contract_relationship.png deleted file mode 100644 index f6506e6..0000000 Binary files a/source/img/contract_relationship.png and /dev/null differ diff --git a/source/img/contract_relationship2.png b/source/img/contract_relationship2.png deleted file mode 100644 index cdfaef2..0000000 Binary files a/source/img/contract_relationship2.png and /dev/null differ diff --git a/source/img/cpp_35k9.png b/source/img/cpp_35k9.png deleted file mode 100644 index b80d657..0000000 Binary files a/source/img/cpp_35k9.png and /dev/null differ diff --git a/source/img/dependency_graph.svg b/source/img/dependency_graph.svg deleted file mode 100644 index 895d50b..0000000 --- a/source/img/dependency_graph.svg +++ /dev/null @@ -1,652 +0,0 @@ - - - - - - -webthree - -webthree dependencies -cluster_webthree_helpers - -webthree-helpers dependencies - -cluster_alethzero - -alethzero dependencies - -cluster_libethereum - -libethereum dependencies - -cluster_libweb3core - -libweb3core dependencies - -cluster_mix - -mix dependencies - -cluster_solidity - -solidity dependencies - -cluster_webthree - -webthree dependencies - - -buildinfo - -buildinfo - - -base - -base - - -json_spirit - -json_spirit - - -base->json_spirit - - - - -boost - -boost - - -base->boost - - - - -Jsoncpp - -Jsoncpp - - -base->Jsoncpp - - - - -LevelDB - -LevelDB - - -base->LevelDB - - - - -pthreads - -pthreads - - -base->pthreads - - - - -scrypt - -scrypt - - -secp256k1 - -secp256k1 - - -gmp - -gmp - - -secp256k1->gmp - - - - -AlethZero - -AlethZero - - -aleth - -aleth - - -AlethZero->aleth - - - - -natspec - -natspec - - -aleth->natspec - - - - -web3jsonrpc - -web3jsonrpc - - -aleth->web3jsonrpc - - - - -Qt* - -Qt* - - -aleth->Qt* - - - - -AlethOne - -AlethOne - - -AlethOne->aleth - - - - -ethereum - -ethereum - - -evm - -evm - - -ethereum->evm - - - - -lll - -lll - - -ethereum->lll - - - - -p2p - -p2p - - -ethereum->p2p - - - - -ethashseal - -ethashseal - - -ethashseal->ethereum - - - - -ethash-cl - -ethash-cl - - -ethashseal->ethash-cl - - - - -Cpuid - -Cpuid - - -ethashseal->Cpuid - - - - -ethcore - -ethcore - - -ethcore->buildinfo - - - - -devcrypto - -devcrypto - - -ethcore->devcrypto - - - - -ethkey - -ethkey - - -ethkey->ethcore - - - - -ethminer - -ethminer - - -ethminer->ethashseal - - - - -JsonRpc* - -JsonRpc* - - -ethminer->JsonRpc* - - - - -ethvm - -ethvm - - -ethvm->ethashseal - - - - -evmjit - -evmjit - - -ethash - -ethash - - -ethash-cl->ethash - - - - -OpenCL - -OpenCL - - -ethash-cl->OpenCL - - - - -evm->ethcore - - - - -evm->evmjit - - - - -evmcore - -evmcore - - -evm->evmcore - - - - -evmasm - -evmasm - - -evmasm->evmcore - - - - -devcore - -devcore - - -evmcore->devcore - - - - -lll->evmasm - - - - -testutils - -testutils - - -testutils->ethashseal - - - - -lllc - -lllc - - -lllc->buildinfo - - - - -lllc->lll - - - - -testeth - -testeth - - -testeth->testutils - - - - -p2p->devcrypto - - - - -Miniupnpc - -Miniupnpc - - -p2p->Miniupnpc - - - - -devcrypto->scrypt - - - - -devcrypto->secp256k1 - - - - -devcrypto->devcore - - - - -Cryptopp - -Cryptopp - - -devcrypto->Cryptopp - - - - -devcore->base - - - - -bench - -bench - - -bench->devcrypto - - - - -rlp - -rlp - - -rlp->devcrypto - - - - -testweb3core - -testweb3core - - -testweb3core->p2p - - - - -Mix - -Mix - - -Mix->web3jsonrpc - - - - -Mix->Qt* - - - - -soljson - -soljson - - -solidity - -solidity - - -soljson->solidity - - - - -solidity->evmasm - - - - -solc - -solc - - -solc->solidity - - - - -soltest - -soltest - - -soltest->ethereum - - - - -soltest->solidity - - - - -web3jsonrpc->solidity - - - - -webthree - -webthree - - -web3jsonrpc->webthree - - - - -web3jsonrpc->JsonRpc* - - - - -webthree->ethashseal - - - - -whisper - -whisper - - -webthree->whisper - - - - -eth - -eth - - -eth->web3jsonrpc - - - - -jsconsole - -jsconsole - - -eth->jsconsole - - - - -jsconsole->devcore - - - - -jsengine - -jsengine - - -jsconsole->jsengine - - - - -jsconsole->JsonRpc* - - - - -Readline - -Readline - - -jsconsole->Readline - - - - -V8 - -V8 - - -jsengine->V8 - - - - -whisper->p2p - - - - -ethrpctest - -ethrpctest - - -ethrpctest->web3jsonrpc - - - - - diff --git a/source/img/eth_miner_setup.png b/source/img/eth_miner_setup.png deleted file mode 100644 index 29819b5..0000000 Binary files a/source/img/eth_miner_setup.png and /dev/null differ diff --git a/source/img/ethereum-classic-documentation-logo.png b/source/img/ethereum-classic-documentation-logo.png deleted file mode 100644 index e63116e..0000000 Binary files a/source/img/ethereum-classic-documentation-logo.png and /dev/null differ diff --git a/source/img/ethereum-homestead-documentation-logo.png b/source/img/ethereum-homestead-documentation-logo.png deleted file mode 100644 index bcd4f4f..0000000 Binary files a/source/img/ethereum-homestead-documentation-logo.png and /dev/null differ diff --git a/source/img/ethereum-protocols.png b/source/img/ethereum-protocols.png deleted file mode 100644 index 00d9297..0000000 Binary files a/source/img/ethereum-protocols.png and /dev/null differ diff --git a/source/img/jenkins.png b/source/img/jenkins.png deleted file mode 100644 index 70231fc..0000000 Binary files a/source/img/jenkins.png and /dev/null differ diff --git a/source/img/target_dependency_graph.svg b/source/img/target_dependency_graph.svg deleted file mode 100644 index 42627bd..0000000 --- a/source/img/target_dependency_graph.svg +++ /dev/null @@ -1,580 +0,0 @@ - - - - - - -webthree - -webthree dependencies -cluster_cpp_ethereum - -cpp_ethereum dependencies - -cluster_solidity - -solidity dependencies - -cluster_alethzero - -alethzero dependencies - -cluster_mix - -mix dependencies - - -buildinfo - -buildinfo - - -base - -base - - -json_spirit - -json_spirit - - -base->json_spirit - - - - -boost - -boost - - -base->boost - - - - -Jsoncpp - -Jsoncpp - - -base->Jsoncpp - - - - -LevelDB - -LevelDB - - -base->LevelDB - - - - -pthreads - -pthreads - - -base->pthreads - - - - -scrypt - -scrypt - - -secp256k1 - -secp256k1 - - -gmp - -gmp - - -secp256k1->gmp - - - - -testeth - -testeth - - -testutils - -testutils - - -testeth->testutils - - - - -evmcore - -evmcore - - -devcore - -devcore - - -evmcore->devcore - - - - -ethereum - -ethereum - - -p2p - -p2p - - -ethereum->p2p - - - - -evm - -evm - - -ethereum->evm - - - - -ethashseal - -ethashseal - - -ethashseal->ethereum - - - - -ethash-cl - -ethash-cl - - -ethashseal->ethash-cl - - - - -Cpuid - -Cpuid - - -ethashseal->Cpuid - - - - -web3jsonrpc - -web3jsonrpc - - -webthree - -webthree - - -web3jsonrpc->webthree - - - - -JsonRpc* - -JsonRpc* - - -web3jsonrpc->JsonRpc* - - - - -webthree->ethashseal - - - - -whisper - -whisper - - -webthree->whisper - - - - -ethcore - -ethcore - - -ethcore->buildinfo - - - - -devcrypto - -devcrypto - - -ethcore->devcrypto - - - - -p2p->devcrypto - - - - -Miniupnpc - -Miniupnpc - - -p2p->Miniupnpc - - - - -devcrypto->scrypt - - - - -devcrypto->secp256k1 - - - - -devcrypto->devcore - - - - -Cryptopp - -Cryptopp - - -devcrypto->Cryptopp - - - - -ethkey - -ethkey - - -ethkey->ethcore - - - - -ethminer - -ethminer - - -ethminer->ethashseal - - - - -ethminer->JsonRpc* - - - - -ethvm - -ethvm - - -ethvm->ethashseal - - - - -evmjit - -evmjit - - -ethash - -ethash - - -ethash-cl->ethash - - - - -OpenCL - -OpenCL - - -ethash-cl->OpenCL - - - - -evm->evmcore - - - - -evm->ethcore - - - - -evm->evmjit - - - - -testutils->ethashseal - - - - -devcore->base - - - - -bench - -bench - - -bench->devcrypto - - - - -rlp - -rlp - - -rlp->devcrypto - - - - -testweb3core - -testweb3core - - -testweb3core->p2p - - - - -eth - -eth - - -eth->web3jsonrpc - - - - -whisper->p2p - - - - -testweb3 - -testweb3 - - -testweb3->web3jsonrpc - - - - -lllc - -lllc - - -lll - -lll - - -lllc->lll - - - - -evmasm - -evmasm - - -lll->evmasm - - - - -evmcore_solidity - -evmcore_solidity - - -evmasm->evmcore_solidity - - - - -solidity - -solidity - - -solidity->evmasm - - - - -soljson - -soljson - - -soljson->solidity - - - - -solc - -solc - - -solc->solidity - - - - -soltest - -soltest - - -soltest->ethereum - - - - -soltest->solidity - - - - -AlethZero - -AlethZero - - -AlethZero->solidity - - - - -aleth - -aleth - - -AlethZero->aleth - - - - -aleth->web3jsonrpc - - - - -Qt* - -Qt* - - -aleth->Qt* - - - - -AlethOne - -AlethOne - - -AlethOne->aleth - - - - -Mix - -Mix - - -Mix->web3jsonrpc - - - - -Mix->solidity - - - - -Mix->Qt* - - - - - diff --git a/source/index.rst b/source/index.rst deleted file mode 100644 index 7d05cc0..0000000 --- a/source/index.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. Homestead guide documentation master file, created by - sphinx-quickstart on Tue Jan 5 17:30:05 2016. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. Modification to classic began on Sat Jul 30 07:00:00 2016 - -Ethereum Classic Documentation -=============================================================================== - -.. image:: img/ethereum-classic-documentation-logo.png -.. :height: 500px -.. :width: 394 px - :scale: 50 % - :alt: ethereum-logo - :align: center - -This documentation is the result of an ongoing collaborative effort by -volunteers from the Ethereum :ref:`community`. Although it has not been -authorized by the :ref:`foundation`, we hope you will find it useful, -and welcome new :ref:`contributors`. - - -Contents -=============================================================================== - -.. toctree:: - :maxdepth: 4 - - introduction/index.rst - ethereum-clients/index.rst - account-management.rst - ether.rst - network/index.rst - mining.rst - contracts-and-transactions/index.rst - frequently-asked-questions/frequently-asked-questions.rst - glossary.rst - about.rst - - -Improve the Documentation -=============================================================================== - -See `this page `__ to help us improve the documentation. diff --git a/source/introduction/The-Classic-release.rst b/source/introduction/The-Classic-release.rst deleted file mode 100644 index 04ef11f..0000000 --- a/source/introduction/The-Classic-release.rst +++ /dev/null @@ -1,67 +0,0 @@ -******************************************************************************** -The Classic 'Release' -******************************************************************************** - -Ethereum 'Classic' is the original unmolested Ethereum block chain of the Ethereum platform. We believe in decentralized, censorship-resistant, permissionless blockchains. We believe in the original vision of Ethereum as a world computer you can't shut down, running irreversible smart contracts. We believe in a strong separation of concerns, where system forks are only possible in order to correct actual platform bugs, not to bail out failed contracts and special interests. We believe in censorship-resistant platform that can be actually trusted - by anyone. - -.. _Motivation: - -Motivation ------------------------------------------------ - -Ethereum Foundation responded to DAO debacle in the worst way possible. Special interests controlling the Foundation are ramming through DAO bailout hardfork against principled opposition of a significant economic minority of Ethereum stakeholders. According to (diligently hidden, pro-fork) coin vote on Carbonvote, 13% of ETH holders oppose this hardfork. Also, about 22% of Ethereum miners voted against the previous 'DAO softfork' and would logically oppose hardfork as well. Such a significant minority of stakeholders should not be silenced or intimidated into submission - they should be given a clear choice. - -If we want to continue to move forward and guarantee survival of the original Ethereum vision, we must fork Ethereum. This will lay the foundation to build secure decentralized applications that are actually censorship resistant. - -More: http://github.com/ethereumclassic/freeworldcomputer-project - -.. _Goals: - -Goals ----------------------------------- - -The main goal of the project is to ensure survival of the original Ethereum blockchain. We will strive to provide alternative for people who strongly disagree with DAO bailout and the direction Ethereum Foundation is taking their project. Anyone opting to remain on the original chain should have such opportunity. - -.. _A Crypto-Decentralist Manifesto: - -A Crypto-Decentralist Manifesto ----------------------------------- - -by: Bit Novosti - -Blockchains are going to rule the world, providing a mechanism for scaling social and economic cooperation to an unprecedented level — a truly global -scale. Such cooperation will involve not only human beings, groups and -associations but also a growing multitude of increasingly independent -artificial agents. - -* Every blockchain creates a social network around its applications, with network value growing exponentially with the number of participants in accordance with Reed’s Law. This value isn’t extracted by intermediaries or controllers, as with previous centralized models. Instead, it’s shared among participants, providing economic incentives for cooperation without coercion. - -* Not all blockchains are created equal. There are three key characteristics that make scalable blockchain-enabled cooperation possible: openness, neutrality and immutability. - -* Openness is necessary. It goes without saying that the rules of the game should be open for anyone to see and understand. Anyone should be able to participate in any layer of the system without asking for any permission whatsoever. Anyone should be able to use the network in accordance with its rules. Anyone should be able to create their own client implementing the open protocol. Anyone should be able to contribute to network security, and so on. No registration, identification or other preconditions should limit participation. All such limitations prevent the network from scaling and their enforcement creates centralization risks. - -* Neutrality is necessary. It’s important for anyone participating in blockchain-enabled cooperation to be on an equal footing with everyone else. It doesn’t matter if you wield huge economic power or only a tiny amount. It doesn’t matter whether you’re a saintly Mother Theresa or a vicious drug dealer. It doesn’t matter whether you’re a human or a refrigerator. It doesn’t matter what you believe in, what political theory you subscribe to, or whether you’re a moral or immoral person. A participant’s ethnicity, age, sex, profession, social standing, friends or affiliations, make or model, goals, purposes or intentions — none of this matters to the blockchain even a bit. The rules of the game are exactly the same for everyone, period. Without neutrality, the system is skewed towards one set of participants at the expense of others. In that case, it’s less likely to gain universal acceptance and maximize network value for everyone. - -* Immutability is necessary. The blockchain is a truth machine preserving one universally accepted version of history, one immutable sequence of events. What’s true once is always true, regardless of political or business interests, and no amount of lobbying can change that. If it’s simply not possible to change history, then no resources are wasted on the effort. If there are any loopholes at all, then sufficiently motivated and determined interest groups will exploit them at the expense of others, diminishing network value for everyone. - -* The rules governing the blockchain network are known in advance. They’re exactly the same for everyone and not subject to change other than with 100% consensus. Yes, it must be 100%. Because any change to the system’s rules that not all participants freely agree to creates a network split, diminishing network value for everyone. - -It’s impossible to achieve these blockchain characteristics without the system -being truly decentralized. If any aspect of the blockchain system becomes -subject to centralized control, this introduces an attack vector enabling the -violation of one or more of the key blockchain characteristics. It may be -possible to limit participation (such as by enforcing AML/KYC rules), thus -violating openness. It may be possible to enforce discriminatory policies (such as by filtering “illegal” transactions), thus violating neutrality. It may be possible to rewrite the history of events (such as by confiscating or -“redistributing” funds), thus violating immutability. Introducing centralized -chokepoints creates a precondition for the introduction of “blockchain -intermediaries or controllers” who can siphon value out of the system at other participants’ expense. - -So decentralization is the most important feature of blockchain systems, the one everything else depends on. With decentralization, blockchains will come to rule the world. Without it, they’ll be “contained” and railroaded into niche applications. - -We decentralists are committed to keeping blockchains open, neutral and -immutable. We’re committed to keeping blockchain systems decentralized. This informs all our actions and positions towards any developments in the crypto world and beyond. All attempts to violate any of the key blockchain -characteristics should be fought. All changes to a blockchain’s rules that -introduce new centralization risks or strengthen existing ones should be fought. Only developments that are clearly beneficial to decentralization or strengthen the three key blockchain characteristics should be supported and encouraged. -The blockchain revolution won’t be centralized. Let’s make sure of it. - -Onward. diff --git a/source/introduction/community.rst b/source/introduction/community.rst deleted file mode 100644 index d62204d..0000000 --- a/source/introduction/community.rst +++ /dev/null @@ -1,161 +0,0 @@ -.. _community: - -******************************************************************************** -Community -******************************************************************************** - -Please choose your forum wisely when starting a discussion or asking a question, help keep our various forums clean and tidy. - -Reddit -================================================================================ -The `Ethereum classic subreddit`_ is the most inclusive Ethereum classic forum, where most of the community discussion is happening and where core devs are also active. This is your forum of choice for generic discussion of news, media coverage, announcements, brainstorming. In general all things Ethereum relevant to the wider community. - -Strictly no price discussion. - -Also, this is not the ideal place to ask for hands-on help or post questions you expect there are clear immediate answers to (use :ref:`gitter-rooms` and :ref:`stack-exchange` for these, respectively). - -Read the `Ethereum classic subreddit rules`_ before posting. - -Further specialised subreddits: - -* `/r/Ethereum `_- Ether hard-fork discussion -* `/r/EthTrader `_ - Ether trading, price and market -* `/r/EtherMining `_ - Ether mining discussion -* `/r/Ethmarket `_ - Marketplace for individuals looking to exchange goods and services for Ether -* `/r/Ethinvestor `_ - News and prospects for Ethereum investors. Following the long term trends in the Ethereum marketplace. -* `/r/ethereumism/ `_ - a bit more ism, ostic, ical, ist and tinfoil hats, pyramids and crystal ball type of views - the ethereal side of Ethereum - - -.. _Ethereum classic subreddit: https://www.reddit.com/r/ethereumclassic/ -.. _Ethereum classic subreddit rules: http://www.reddit.com/r/ethereumclassic/comments/3auc97/ethereum_subreddit_rules/ - -.. _wiki: - -Ethereum Classic Wiki -================================================================================ - -* Ethereum Classic Wiki: `ETHC wiki `_ - - -.. _Telegram: - -Telegram -================================================================================ - -* Ethereum Classic (general discussion): @ethclassic -* Ethereum Classic Dev: @etcdev - - -.. _slack: - -Slack -================================================================================ -* `https://ethereumclassic.slack.com/ `_ - -.. _Ethereum Improvement Proposals: - -Ethereum Improvement Proposals (EIPs) -================================================================================ - -The EIP scheme aims to be a framework and largely informal business process coordinating improvements to the protocols. People should first propose their idea as an issue or pull request to the EIPs repository. After basic filtering, the proposal will receive a number and is published in draft form. For an EIP to become Active it will require the mutual consent of the community. Those proposing changes should consider that ultimately consent may rest with the consensus of the Ethereum users. -For discussion of EIPs, use the `gitter channel for EIP discussions`_. - -* `EIP guidelines and sample EIP `_ -* `EIP template `_ -* `EIP repository and README `_ - - -.. _Chinese Community: - -Chinese Community -================================================================================ - -* WeChat group: ETC以太坊Classic -* QQ group: 361470220 -* Weibo Group: `http://weibo.com/ethereumclassic/ `_ -* Chinese Wiki: `http://assembly.io/ `_ -* 8btc: `http://8bct.com/forum-126-1.html `_ -.. _Russian Community: - -Russian Community -================================================================================ -* `https://bitcointalk.org/index.php?topic=1563268 `_ -* `https://bitcointalk.org/index.php?topic=1563328 `_ -* `https://ethclassic.ru `_ - -.. _Indonesian Community: - -Indonesian Community -================================================================================ -* `https://bitcointalk.org/index.php?topic=1563400 <`https://bitcointalk.org/index.php?topic=1563400>`_ - - - - -.. _gitter-rooms: - -Gitter Rooms (old) -================================================================================ - -Gitter is our forum of choice for daily chat. It is the virtual coworking space where devs hang out, so it is where you can get quick help and a bit of handholding if needed. - -Gitter uses Github accounts, offers Github integration (notification of pull requests etc), private channels, provides markdown formatting, and more. - -Most Gitter channels are organised around particular repositories, or generic topics like research or governance. Please choose the appropriate room and keep discussions on topic. - -See `the full list of gitter rooms for the Ethereum organisation`_. Below is the list of active public channels: - -* `go-ethereum`_ - about geth (and tools related to the go implementation) -* `cpp-ethereum`_ - about eth (and tools related to the C++ implementation) -* `web3.js`_ - about web3.js, Ethereum JavaScript API library -* `Solidity`_ - The Solidity Contract-Oriented Programming Language -* `serpent`_ - The Serpent language for contract development -* `mist`_ - GUI dapp browser, official wallet app -* `light-client`_ - about light client and the LES protocol -* `research`_ - Ethereum research -* `governance`_ - about dev governance -* `whisper`_ - anonymous datagram publishing -* `swarm`_ - decentralised content storage and distribution network -* `EIPs`_ - discussion of _`Ethereum Improvement Proposals (EIPs)` -* `ethereumjs-lib`_ - a JavaScript library of core Ethereum functions -* `devp2p`_ - ÐΞV's p2p network protocol & framework - -.. _the full list of gitter rooms for the Ethereum organisation: https://gitter.im/orgs/ethereum/rooms - -.. _go-ethereum: https://gitter.im/ethereum/go-ethereum -.. _cpp-ethereum: https://gitter.im/ethereum/cpp-ethereum -.. _web3.js: https://gitter.im/ethereum/web3.js -.. _Solidity: https://gitter.im/ethereum/Solidity -.. _serpent: https://gitter.im/ethereum/serpent -.. _mist: https://gitter.im/ethereum/mist -.. _light-client: https://gitter.im/ethereum/light-client -.. _research: https://gitter.im/ethereum/research -.. _governance: https://gitter.im/ethereum/governance -.. _whisper: https://gitter.im/ethereum/whisper -.. _swarm: https://gitter.im/ethereum/swarm -.. _EIPs: https://gitter.im/ethereum/EIPs -.. _ethereumjs-lib: https://gitter.im/ethereum/ethereumjs-lib -.. _devp2p: https://gitter.im/ethereum/devp2p - - -.. _stack-exchange: - -Stack Exchange (old) -================================================================================ - -The `Ethereum Classic Stack Exchange `_ is part of the StackExchange network of Q&A communities. StackExchange is a free Q&A site where all the questions and answers are preserved for posterity. - -This is the best place to ask technical questions. Help your fellow etherians by answering questions and collect reputation points. - - - - -Obsolete -=================== -Skype -------- -Some community discussion fora still use skype rooms, but we would like to move away from that and encourage people to use `gitter `_ or `slack `_. - -Ethereum Forum --------------------- -Stephan Tual's legendary `Ethereum Forum `_ is no longer maintained and likely to be decommissioned soon. We encourage people to use one of the recommended alternatives listed above. diff --git a/source/introduction/contributors.rst b/source/introduction/contributors.rst deleted file mode 100644 index ca5184d..0000000 --- a/source/introduction/contributors.rst +++ /dev/null @@ -1,85 +0,0 @@ -.. _contributors: - -******************************************************************************** -Contributors -******************************************************************************** - -This documentation was built collectively by the Ethereum and the Ethereum classic community originally as part of -a project called the -`Homestead Documentation Initiative `_ -which was coordinated by: - -- `Viktor Trón ("zelig") `_ -- `Hudson Jameson ("Souptacular") `_ - -It was subsequently modified to fit the needs of the classic community with an initiative called the `Classic Documentation Initiative `_ -which was coordinated by: - -- `Cody Burns ("dontpanicburns") `_ - -We would like to thank everybody who helped in this effort for `their contributions `_: - -.. image:: ../img/Feels-Good-Man-Frog-02.png - -- `Ricardo de Azevedo Brandao `_ -- `Santanu Barai `_ -- `Brooks Boyd `_ -- `RJ Catalano `_ -- `Joseph Chow `_ -- `Keri Clowes `_ -- `François Deppierraz `_ -- `Bertie Dinneen `_ -- `Erik Edrosa `_ -- `Andrey Fedorov `_ -- `Rocky Fikki `_ -- `Alex Fisher `_ -- `Enrique Fynn `_ -- `Arno Gaboury `_ -- `Taylor Gerring `_ -- `Dave Hoover `_ -- `Joël Hubert `_ -- `Makoto Inoue `_ -- `Keith Irwin `_ -- `Matthias Käppler `_ -- `Bas van Kervel `_ -- `Michael Kilday `_ -- `Chandra Kumar `_ -- `Guangmian Kung `_ -- `Hugh Lang `_ -- `Yann Levreau `_ -- `Roman Mandeleil `_ -- `Kévin Maschtaler `_ -- `Andrew Mazzola `_ -- `Dominik Miszkiewicz `_ -- `John Mooney `_ -- `Chris Peel `_ -- `Craig Polley `_ -- `Colm Ragu `_ -- `Laurent Raufaste `_ -- `Christian Reitwiessner `_ -- `Josh Stark `_ -- `Scott Stevenson `_ -- `Bob Summerwill `_ -- `Alex van de Sande `_ -- `Paul Schmitzer `_ -- `Afri Schoedon `_ -- `Sudeep Singh `_ -- `Giacomo Tazzari `_ -- `Ben Tannenbaum `_ -- `Dean Alain Vernon `_ -- `Paul Worrall `_ -- `Luca Zeug `_ -- `Weiyang Zhu `_ -- `Will Zeng `_ - -And these pseudonymous contributors: - -- `12v `_ -- `c0d3inj3cT `_ -- `ijcoe6ru `_ -- `LucaTony `_ -- `madhancr `_ -- `mWo `_ -- `Omkara `_ -- `tflux99 `_ -- `xyzether `_ diff --git a/source/introduction/foundation.rst b/source/introduction/foundation.rst deleted file mode 100644 index 877e4d9..0000000 --- a/source/introduction/foundation.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. _foundation: - -*************************************************** -The Ethereum Foundation -*************************************************** -The Ethereum Foundation is a non-profit organization registered in Switzerland, and has the purpose of managing the funds that were raised from the Ether Sale in order to best serve the Ethereum and decentralized technology ecosystem. - -Founded July 2014 in Switzerland, Stiftung Ethereum’s mission is the promotion of developments of new technologies and applications, especially in the fields of new open and decentralized software architectures. - -It is the aim that decentralized and open technologies will be developed, nurtured, promoted and maintained. A dominating, but not exclusive, focus is set on the promotion of the development of the Ethereum Protocol and the relevant technology to it as well as the promotion and support of applications using the Ethereum technology or protocol. Stiftung Ethereum will additionally support and advocate for a decentralized Internet in a variety of forms. - -Find out about more about the `Foundation Management Team on the website `_ - -Ethereum Foundation's faces to the community ---------------------------------------------------- -* `Official Homestead website `_ - main entrypoint -* `Reddit `_ - see :ref:`community` -* `Blog `_ -* `Twitter `_ -* `Youtube `_ -* `Facebook `_ - largely unused -* `Email `_ - use if you must - -Official communication from the Ethereum foundation most often comes in the form of a comprehensive blogpost on the `Ethereum blog `_. Some of the posts there are technical, some organisational, some personal. All blog posts are announced on -`Twitter `_ and -`Reddit `_. - -The foundation `Youtube channel `_ hosts our videos, including all talks of the developers conferences DEVCON0 and DEVCON1. - -For community discussion forums, see :ref:`community`. diff --git a/source/introduction/history-of-ethereum.rst b/source/introduction/history-of-ethereum.rst deleted file mode 100644 index e02f595..0000000 --- a/source/introduction/history-of-ethereum.rst +++ /dev/null @@ -1,98 +0,0 @@ -******************************************************************************** -History of Ethereum -******************************************************************************** - -For a recent historical account, see `Taylor Gerring's blogpost `_ - -Inception -================================================================================ -Ethereum was initially described by Vitalik Buterin in late 2013 as a result of his research and work in the Bitcoin community. Shortly thereafter, Vitalik published the `Ethereum white paper `_, where he describes in detail the technical design and rationale for the Ethereum protocol and smart contracts architecture. In January 2014, Ethereum was formally announced by Vitalik at the The North American Bitcoin Conference in Miami, Florida, USA. - -Around that time, Vitalik also started working with Dr. Gavin Wood and together co-founded Ethereum. By April 2014, Gavin published the `Ethereum Yellow Paper `_ that would serve as the technical specification for the Ethereum Virtual Machine (EVM). By following the detailed specification in the Yellow Paper, the Ethereum client has been implemented in seven programming languages (C++, Go, Python, Java, JavaScript, Haskell, Rust), and has resulted in better software overall. - -* `Ethereum launches Cryptocurrency 2.0 network `_ - Coindesk article of 2014 Jan on the beginnings -* `Ethereum announcement on bitcointalk `_ Vitalik's original announcement to the bitcoin community. Forum thread with 5000 replies. - -The Ethereum Foundation and the ether presale -================================================================================ -In addition to developing the software for Ethereum, the ability to launch a new cryptocurrency and blockchain requires a massive bootstrapping effort in order to assemble the resources needed to get it up and running. To kickstart a large network of developers, miners, investors, and other stakeholders, Ethereum announced its plan to conduct a presale of ether tokens, the currency unit of Ethereum. The legal and financial complexities of raising funds through a presale led to the creation of several legal entities, including the :ref:`Ethereum Foundation (Stiftung Ethereum) ` established June 2014 in Zug, Switzerland. - -Beginning in July 2014, Ethereum distributed the initial allocation of ether via a 42-day public ether presale, netting 31,591 bitcoins, worth $18,439,086 at that time, in exchange for about 60,102,216 ether. The results of the sale were initially used to pay back mounting legal debts and also for the months of developer effort that had yet to be compensated, and to finance the ongoing development of the Ethereum. - -* `Launching the ether sale `_ - original official announcement on the Ethereum blog -* `Concise information-rich stats page about the presale `_ by (since then inactive) `Ether.Fund `_ -* `Overview: Ethereum’s initial public sale `_ - Blogpost by slacknation - all stats about the ether presale -* `Terms and Conditions of the Presale `_ - - -ETH/DEV and Ethereum development -================================================================================ -Following the successful ether presale, Ethereum development was formalized under a non-for-profit organization called ETH DEV, which manages the development of Ethereum under contract from Ethereum Suisse – with Vitalik Buterin, Gavin Wood, and Jeffrey Wilcke as the 3 directors of the organization. Developer interest in Ethereum grew steadily throughout 2014 and the ETH DEV team delivered a series of proof-of-concept (PoC) releases for the development community to evaluate. Frequent posts by ETH DEV team on the `the Ethereum blog `_ also kept the excitement and momentum around Ethereum going. Increasing traffic and growing user-base on both the Ethereum forum and the ethereum subreddit testified that the platform is attracting a fast-growing and devoted developer community. This trend has been continuing to this very day. - -DEVCON-0 --------------------------------------------------------------------------------- -In November 2014, ETH DEV organized the `DEVCON-0 event `_, which brought together Ethereum developers from around the world to Berlin to meet and discuss a diverse range of Ethereum technology topics. Several of the presentations and sessions at DEVcon-0 would later drive important initiatives to make Ethereum more reliable, more secure, and more scalable. Overall, the event galvanized developers as they continued to work towards the launch of Ethereum. - -* `DEVCON-0 talks youtube playlist `_ -* `DEVCON-0 reddit post `_ -* `Gav's DEV update mentioning DEVCON-0 `_ -* `DEVcon-0 recap blog post `_ - - -DEVgrants program --------------------------------------------------------------------------------- - -In April 2015, `the DEVgrants program `_ was announced, which is a program that offers funding for contributions both to the Ethereum platform, and to projects based on Ethereum. Hundreds of developers were already contributing their time and thinking to Ethereum projects and in open source projects. This program served to reward and support those developers for their contributions. The DEVgrants program continues to operate today and funding of the program was recently renewed in January 2016. - -* `DEVgrants initial announcement `_ -* `Announcement of new funding at DEVCON-1 `_ -* `DEVgrants public gitter room `_ -* `DEVgrants talk at DEVCON-1 by Wendell Davis on YouTube `_ - -.. _olympic-testnet: - -Olympic testnet, bug bounty and security audit --------------------------------------------------------------------------------- - -Throughout 2014 and 2015 development went through a series of proof of concept releases leading to the 9th POC open testnet, called Olympic. The developer community was `invited to test the limits of the network `_ and a substantial prize fund was allocated to award those holding various records or having success in breaking the system in some way or other. The `rewards were announced `_ officially a month after the live release. - -In early 2015, an `Ethereum Bounty Program `_ was launched, offering BTC rewards for finding vulnerabilities in any part of the Ethereum software stack. This has undoubtedly contributed to the reliability and security of Ethereum and the confidence of the Ethereum community in the technology. The bounty program is currently still active and there is no end date planned. - -The Ethereum security audit began at the end of 2014 and continued through the first half of 2015. Ethereum engaged multiple third party software security firms to conduct an end-to-end audit of all protocol-critical components (Ethereum VM, networking, Proof of Work). The audits uncovered security issues that were addressed and tested again and as a result ultimately led to a more secure platform. - -* `Olympic testnet prerelease `_ - Vitalik's blogpost detailing olympic rewards -* `Olympic rewards announced `_ - Vitalik's blogpost detailing the winners and prizes -* `Bug bounty program launch `_ -* `Ethereum Bounty Program website `_ -* `Least Authority audit blogpost `_ - with links to the audit report -* `Deja Vu audit blogpost `_ - -.. _frontier-launch: - -The Ethereum Frontier launch -======================================================================= - -The Ethereum Frontier network launched on July 30th, 2015, and developers began writing smart contracts and decentralized apps to deploy on the live Ethereum network. In addition, miners began to join the Ethereum network to help secure the Ethereum blockchain and earn ether from mining blocks. Even though the Frontier release is the first milestone in the Ethereum project and was intended for use by developers as a beta version, it turned out to be more capable and reliable than anyone expected, and developers have rushed in to build solutions and improve the Ethereum ecosystem. - -See also: - -* `Original announcement of the release scheme `__ by Vinay Gupta -* `Frontier is coming `_ - Frontier launch announcement by Stephan Tual -* `Frontier launch final steps `_ - Follow-up post to announcement -* `Ethereum goes live with Frontier launch `_ -* `The frontier website `_ - -DEVCON-1 --------------------------------------------------------------------------------- -The second developers' conference `DEVCON-1 `_ took place in the city of London at the beginning of November 2015. The 5-day event featured more than 100 presentations, panel discussions and lightning talks, attracted more than 400 participants, a mix of developers, entrepreneurs, thinkers, and business executives. -The talks were all recorded and are `freely available `_ - -The presence of large companies like UBS, IBM and Microsoft clearly indicated enterprise interest in the technology. Microsoft announced that it would offer `Ethereum on its new Blockchain as a Service `_ offering on the Microsoft Azure cloud platform. In conjunction with DEVCON-1, this announcement will be remembered as the moment when blockchain technology became mainstream, with Ethereum at the center of it. - -* `DEVCON-1 talks Youtube playlist `_ -* `DEVCON-1 website `_ full listing of presentations with links to the slides if available. - -History resources ----------------------------------------- - -* `a simple graphical timeline `_ diff --git a/source/introduction/how-to-use-this-guide.rst b/source/introduction/how-to-use-this-guide.rst deleted file mode 100644 index 1d7c541..0000000 --- a/source/introduction/how-to-use-this-guide.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _how-to-use-this-guide: - -******************************************************************************** -How to use this guide? -******************************************************************************** - -Using Ethereum: The Basics -======================================================================================== - -This section captures the basic ways in which a user would want to participate in the Ethereum project. First, in order to become a node in the Ethereum network you must run an Ethereum client. Multiple implementations are listed in the :ref:`sec:clients` section along with advice on which client to choose for various setups. In :ref:`sec:connecting-to-the-network`, new users can find basic information about networks, connectivity, troubleshooting and blockchain synchronization. Advanced network topics such as setting up private chains are found in :ref:`test-networks`. diff --git a/source/introduction/index.rst b/source/introduction/index.rst deleted file mode 100644 index 0ba7100..0000000 --- a/source/introduction/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -################################################################################ -Introduction -################################################################################ - -.. toctree:: - :maxdepth: 2 - - what-is-ethereum.rst - how-to-use-this-guide.rst - The-Classic-release.rst - - web3.rst - history-of-ethereum.rst - community.rst - foundation.rst - contributors.rst diff --git a/source/introduction/the-homestead-release.rst b/source/introduction/the-homestead-release.rst deleted file mode 100644 index 36f2da9..0000000 --- a/source/introduction/the-homestead-release.rst +++ /dev/null @@ -1,56 +0,0 @@ -******************************************************************************** -The Homestead Release -******************************************************************************** - -Homestead is the second major version of the Ethereum platform and is the first production release of Ethereum. It includes several protocol changes and a networking change that provides the ability to do further network upgrades. The first version of Ethereum, called the Frontier release, was essentially a beta release that allowed developers to learn, experiment, and begin building Ethereum decentralized apps and tools. - -Milestones of the Ethereum development roadmap ------------------------------------------------ - -The `original development roadmap `_ laid out before Ethereum went live specified the following milestones: - -* Prerelease Step 0: Olympic testnet - launched May 2015 -* Release Step One: Frontier - launched 30 July 2015 -* Release Step Two: Homestead - launches 14 March 2016 (Pi Day) -* Release Step Three: Metropolis - TBA -* Release Step Four: Serenity - TBA - - -While still valid, the substance behind it has changed somewhat. -The `Olympic testnet `_ phase (before the `Frontier release `_) saw a lot of major improvements, followed by Frontier which was launched immediately after. Homestead marks the exit from a beta product to a stable release. -Homestead is introduced automatically at block number 1,150,000 which should occur roughly around March 14th, 2016, Pi Day. - -If you are running a node connected to the live network, it is important that you upgrade to a Homestead-compatible client. Such clients with their versions are listed under :ref:`Ethereum Clients`. Otherwise you will end up on the wrong fork and will no longer be in sync with the rest of the network. - -Once the Ethereum blockchain reaches block 1,150,000, the Ethereum network will undergo a hardfork enabling a few major changes such as explained in the following section. - -.. _homestead-hard-fork-changes: - -Homestead hard fork changes ----------------------------------- -Ethereum in the narrow formal sense is a suite of protocols. -Homestead comes with a few backward-incompatible protocol changes, and therefore will require a hard fork. These changes that made their way through the process for :ref:`Ethereum Improvement Proposals ` and included are: - -* `EIP 2: `_ - - * cost for creating contracts via a transaction is increased from 21000 to 53000. Contract creation from a contract using the ``CREATE`` opcode is unaffected. - * transaction signatures whose s-value is greater than ``secp256k1n/2`` are now considered invalid - * If contract creation does not have enough gas to pay for the final gas fee for adding the contract code to the state, the contract creation fails (ie. goes out-of-gas) rather than leaving an empty contract. - * Change the difficulty adjustment algorithm -* `EIP 7: DELEGATECALL `_: Add a new opcode, ``DELEGATECALL`` at ``0xf4``, which is similar in idea to ``CALLCODE``, except that it propagates the sender and value from the parent scope to the child scope, ie. the call created has the same sender and value as the original call. This means contracts can store pass through information while following msg.sender and ``msg.value`` from its parent contract. Great for contracts which create contracts but don’t repeat additional information which saves gas. See `comments on EIP 7 `_ -* `EIP 8: devp2p Forward Compatibility compliance with the Robustness Principle `_ Changes to the RLPx Discovery Protocol and RLPx TCP transfer protocol to ensure that all client software in use on the Ethereum network can cope with future network protocol upgrades. For older versions of an Ethereum client, updates to the network protocol weren’t being accepted by older clients and would refuse communication if the hello packets didn’t meet expectations. This update means all future versions of the client will accept incoming network upgrades and handshakes. - -The changes have the following benefits: - -* EIP-2/1 eliminates the excess incentive to create contracts via transactions, where the cost is 21000, rather than contracts, where the cost is 32000. -* EIP-2/1 also fixes the protocol "bug" that with the help of suicide refunds, it is currently possible to make a simple ether value transfer using only 11664 gas. -* EIP-2/2 fixes a transaction malleability concern (not a security flaw, but a UI incovenience). -* EIP-2/3 creates a more intuitive "success or fail" distinction in the result of a contract creation process, rather than the current "success, fail, or empty contract" trichotomy -* EIP-2/4 eliminates the excess incentive to set the timestamp difference to exactly 1 in order to create a block that has slightly higher difficulty and that will thus be guaranteed to beat out any possible forks. This guarantees to keep block time in the 10-20 range and according to simulations restores the target 15 second blocktime (instead of the current effective 17s). -* EIP-7 makes it much easier for a contract to store another address as a mutable source of code and ''pass through'' calls to it, as the child code would execute in essentially the same environment (except for reduced gas and increased callstack depth) as the parent. -* EIP-8 makes sure that all client software in use on the Ethereum network can cope with future network protocol upgrades. - - -Additional resources: -- `Reddit discussion on Homestead Release `_ -- :ref:`Ethereum Improvement Proposals` diff --git a/source/introduction/web3.rst b/source/introduction/web3.rst deleted file mode 100644 index 0d15c45..0000000 --- a/source/introduction/web3.rst +++ /dev/null @@ -1,43 +0,0 @@ - -Web 3: A platform for decentralized apps -******************************************************************************** - - - -Many have come to believe that an open, trustless blockchain platform like Ethereum is perfectly suited to serve as the shared "back end" to a decentralized, secure internet - Web 3.0. An internet where core services like DNS and digital identity are decentralized, and where individuals can engage in economic interactions with each other. - -As intended by the Ethereum developers, Ethereum is a blank canvas and you have the freedom to build whatever you want with it. The Ethereum protocol is meant to be generalized so that the core features can be combined in arbitrary ways. Ideally, dapp projects on Ethereum will leverage the Ethereum blockchain to build solutions that rely on decentralized consensus to provide new products and services that were not previously possible. - -Ethereum is perhaps best described as an ecosystem: the core protocol is supported by various pieces of infrastructure, code, and community that together make up the Ethereum project. Ethereum can also be understood by looking at the projects that use Ethereum. Already, there are a number of high-profile projects built on Ethereum such as Augur, Digix, Maker, and many more (see :ref:`dapps`). In addition, there are development teams that build open source components that anyone can use. While each of these organizations are separate from the Ethereum Foundation and have their own goals, they undoubtedly benefit the overall Ethereum ecosystem. - -Further Watching/Reading: - -* Vitalik Buterin - TNABC 2015: https://www.youtube.com/watch?v=Fjhe0MVRHO4 - -* Gavin Wood - DEVCON 1 - Ethereum for Dummies: https://www.youtube.com/watch?v=U_LK0t_qaPo - -* Ethereum London Meetup (best detailed here): https://www.youtube.com/watch?v=GJGIeSCgskc - -Smart contracts -================================================================================ - -by Alex: - -Would you enter in a contract with someone you've never met? Would you agree to lend money to some farmer in Ethiopia? Would you become an investor in a minority-run newspaper in a war zone? Would you go to the hassle of writing up a legal binding contract for a $5 dollar purchase over the internet? - -The answer is no for most of these questions, the reason being that a contract requires a large infrastructure: sometimes you need a working trust relationship between the two parties, sometimes you rely on a working legal system, police force and lawyer costs. - -In Ethereum you don't need any of that: if all the requisites to the contract can be put in the blockchain then they will, in a trustless environment for almost no cost. - -Instead of thinking of moving your current contracts to the blockchain, think of all the thousand little contracts that you would never agree to simply because they weren't economically feasible or there was not enough legal protection.. - - -DAO -================================================================================ - -Here is just one example: imagine you own a small business with your friends. Lawyers and accountants are expensive, and trusting a single partner to oversee the books can be a source of tension (even an opportunity for fraud). Complying strictly with a system in which more than one partner oversees the books can be trying and is subject to fraud whenever the protocol isn't followed exactly. - -Using a smart contract, ownership in your company and terms for the disbursal of funds can be specified at the outset. The smart contract can be written such that it is only changeable given the approval of a majority of owners. Smart contracts like these will likely be available as open source software, so you won't even need to hire your own programmer instead of an accountant/lawyer. - -A smart contract like this scales instantly. A couple of teenagers can split revenue from a lemonade stand just as transparently as a sovereign wealth fund can disburse funds to the hundred million citizens who are entitled to it. In both cases the price of this transparency is likely to be fractions of a penny per dollar. - diff --git a/source/introduction/what-is-ethereum.rst b/source/introduction/what-is-ethereum.rst deleted file mode 100644 index 1601dd6..0000000 --- a/source/introduction/what-is-ethereum.rst +++ /dev/null @@ -1,115 +0,0 @@ -.. _what-is-ethereum: - -################################################################################ -What is Ethereum? -################################################################################ - -Ethereum is an open blockchain platform that lets anyone build and use decentralized applications that run on blockchain technology. Like Bitcoin, no one controls or owns Ethereum – it is an open-source project built by many people around the world. But unlike the Bitcoin protocol, Ethereum was designed to be adaptable and flexible. It is easy to create new applications on the Ethereum platform, and with the Homestead release, it is now safe for anyone to use those applications. - -================================================================================ -A next generation blockchain -================================================================================ - -Blockchain technology is the technological basis of Bitcoin, first described by its mysterious author Satoshi Nakamoto in his white paper "Bitcoin: A Peer-to-Peer Electronic Cash System", published in 2008. While the use of blockchains for more general uses was already discussed in the original paper, it was not until a few years later that blockchain technology emerged as a generic term. A blockchain is a distributed computing architecture where every network node executes and records the same transactions, which are grouped into blocks. Only one block can be added at a time, and every block contains a mathematical proof that verifies that it follows in sequence from the previous block. In this way, the blockchain’s "distributed database" is kept in consensus across the whole network. Individual user interactions with the ledger (transactions) are secured by strong cryptography. Nodes that maintain and verify the network are incentivized by mathematically enforced economic incentives coded into the protocol. - -In Bitcoin's case the distributed database is conceived of as a table of account balances, a ledger, and transactions are transfers of the bitcoin token to facilitate trustless finance between individuals. But as bitcoin began attracting greater attention from developers and technologists, novel projects began to use the bitcoin network for purposes other than transfers of value tokens. Many of these took the form of "alt coins" - separate blockchains with cryptocurrencies of their own which improved on the original bitcoin protocol to add new features or capabilities. In late 2013, Ethereum's inventor Vitalik Buterin proposed that a single blockchain with the capability to be reprogrammed to perform any arbitrarily complex computation could subsume these many other projects. - -In 2014, Ethereum founders Vitalik Buterin, Gavin Wood and Jeffrey Wilcke began work on a next-generation blockchain that had the ambitions to implement a general, fully trustless smart contract platform. - -================================================================================ -Ethereum Virtual Machine -================================================================================ - -Ethereum is a programmable blockchain. Rather than give users a set of pre-defined operations (e.g. bitcoin transactions), Ethereum allows users to create their own operations of any complexity they wish. In this way, it serves as a platform for many different types of decentralized blockchain applications, including but not limited to cryptocurrencies. - -Ethereum in the narrow sense refers to a suite of protocols that define a platform for decentralised applications. At the heart of it is the :ref:`Ethereum Virtual Machine ("EVM") `, which can execute code of arbitrary algorithmic complexity. In computer science terms, Ethereum is "Turing complete". Developers can create applications that run on the EVM using friendly programming languages modelled on existing languages like JavaScript and Python. - -Like any blockchain, Ethereum also includes a peer-to-peer network protocol. The Ethereum blockchain database is maintained and updated by many nodes connected to the network. Each and every node of the network runs the EVM and executes the same instructions. For this reason, Ethereum is sometimes described evocatively as a "world computer". - -This massive parallelisation of computing across the entire Ethereum network is not done to make computation more efficient. In fact, this process makes computation on Ethereum far slower and more expensive than on a traditional "computer". Rather, every Ethereum node runs the EVM in order to maintain consensus across the blockchain. Decentralized consensus gives Ethereum extreme levels of fault tolerance, ensures zero downtime, and makes data stored on the blockchain forever unchangeable and censorship-resistant. - -The Ethereum platform itself is featureless or value-agnostic. Similar to programming languages, it is up to entrepreneurs and developers to decide what it should be used for. However, it is clear that certain application types benefit more than others from Ethereum's capabilities. Specifically, Ethereum is **suited for applications that automate direct interaction between peers or facilitate coordinated group action across a network**. For instance, applications for coordinating peer-to-peer marketplaces, or the automation of complex financial contracts. Bitcoin allows for individuals to exchange cash without involving any middlemen like financial institutions, banks, or governments. Ethereum’s impact may be more far-reaching. In theory, financial interactions or exchanges of any complexity could be carried out automatically and reliably using code running on Ethereum. Beyond financial applications, any environments where trust, security, and permanence are important – for instance, asset-registries, voting, governance, and the internet of things – could be massively impacted by the Ethereum platform. - -================================================================================ -How does Ethereum work? -================================================================================ - -Ethereum incorporates many features and technologies that will be familiar to users of Bitcoin while also introducing many modifications and innovations of its own. - -Whereas the Bitcoin blockchain was purely a list of transactions, :ref:`Ethereum's basic unit is the account `. The Ethereum blockchain tracks the state of every account, and all state transitions on the Ethereum blockchain are transfers of value and information between accounts. There are two types of accounts: - -- Externally Owned Accounts (EOAs), which are controlled by private keys -- Contract Accounts, which are controlled by their contract code and can only be "activated" by an EOA - -For most users, the basic difference between these is that human users control EOAs - because they can control the private keys which give control over an EOA. Contract accounts, on the other hand, are governed by their internal code. If they are "controlled" by a human user, it is because they are *programmed* to be controlled by an EOA with a certain address, which is in turn controlled by whomever holds the private keys that control that EOA. The popular term "smart contracts" refers to code in a Contract Account – programs that execute when a transaction is sent to that account. Users can create new contracts by deploying code to the blockchain. - -Contract accounts only perform an operation when instructed to do so by an EOA. So it is not possible for a Contract account to be performing native operations like random number generation or API calls – it can do these things only if prompted by an EOA. This is because Ethereum requires nodes to be able to agree on the outcome of computation, which requires a guarantee of strictly deterministic execution. - -Like in Bitcoin, users must pay small transaction fees to the network. This protects the Ethereum blockchain from frivolous or malicious computational tasks, like DDoS attacks or infinite loops. The sender of a transaction must pay for each step of the "program" they activated, including computation and memory storage. These fees are paid in amounts of Ethereum's native value-token, ether. - -These transaction fees are collected by the nodes that validate the network. These "miners" are nodes in the Ethereum network that receive, propogate, verify, and execute transactions. The miners then group the transactions – which include many updates to the "state" of accounts in the Ethereum blockchain – into what are called "blocks", and miners then compete with one another for *their* block to be the next one to be added to the blockchain. Miners are rewarded with ether for each successful block they mine. This provides the economic incentive for people to dedicate hardware and electricity to the Ethereum network. - -Just as in the Bitcoin network, miners are tasked with solving a complex mathematical problem in order to successfully "mine" a block. This is known as a "Proof of Work". Any computational problem that requires orders of magnitude more resources to solve algorithmically than it takes to verify the solution is a good candidate for proof of work. In order to discourage centralisation due to the use of specialised hardware (e.g. ASICs), as has occurred in the Bitcoin network, Ethereum chose a memory-hard computational problem. If the problem requires memory as well as CPU, the ideal hardware is in fact the general computer. This makes Ethereum's Proof of Work ASIC-resistant, allowing a more decentralized distribution of security than blockchains whose mining is dominated by specialized hardware like Bitcoin. - - -Learn about Ethereum -============================== - -[to be extended] - -PR videos with some pathos: ---------------------------------- - -* `Ethereum: the World Computer `_ -* `Ethereum -- your turn `_ - - -Blockchain and Ethereum 101 ----------------------------------- - -* `Explain bitcoin like I'm five `_ - an excellent introduction to blockchain technology and bitcoin to the mildly techsavvy layperson. -* https://medium.com/@creole/7-a-simple-view-of-ethereum-e276f76c980b -* http://blog.chain.com/post/92660909216/explaining-ethereum - -* `Explain Ethereum to non-technical people Q&A on stackexchange `_ -* Reddit threads on ELI5-ing Ethereum: - -`[1] `_ -`[2] `_ -`[3] `_ -`[4] `_ -`[5] `_ -`[6] `_ -`[7] `_ -`[8] `_ -`[9] `_ -`[10] `_ -`[11] `_ -`[12] `_ -`[13] `_ -`[14] `_ -`[15] `_ -`[16] `_ -`[17] `_ -`[18] `_ -`[19] `_ - - -Videos ----------------------- - -* http://change.is/video/ethereum-the-world-computer-featuring-dr-gavin-wood - -Infographics --------------------------------- - -* `Ethereum explained...[to your mother] `_ -* http://decentral.ca/wp-content/uploads/2016/03/infographic.jpg -* https://medium.com/@angelomilan/ethereum-explained-to-my-mom-infographic-673e32054c1c#.n9kzhme6v - - -Comparison to alternatives ---------------------------------- - -* `NXT `_ -* `MaidSafe `_ diff --git a/source/mining.rst b/source/mining.rst deleted file mode 100644 index d4d66a6..0000000 --- a/source/mining.rst +++ /dev/null @@ -1,436 +0,0 @@ -.. _mining: - -******************************************************************************** -Mining -******************************************************************************** - -Introduction -================================================================================ - -The word mining originates in the context of the gold analogy for crypto currencies. Gold or precious metals are scarce, so are digital tokens, and the only way to increase the total volume is through mining. This is appropriate to the extent that in Ethereum too, the only mode of issuance post launch is via mining. Unlike these examples however, mining is also the way to secure the network by creating, verifying, publishing and propagating blocks in the blockchain. - -- Mining Ether = Securing the Network = Verifying Computation - -What is mining? --------------------------------------------------------------------------------- - -Ethereum, like all blockchain technologies, uses an incentive-driven model of security. Consensus is based on choosing the block with the highest total difficulty. Miners produce blocks which the others check for validity. Among other well-formedness criteria, a block is only valid if it contains *proof of work* (PoW) of a given *difficulty*. Note that in the Ethereum Serenity milestone, this is likely going to be replaced by a (see :ref:`proof of stake model ` ). - -The Ethereum blockchain is in many ways similar to the Bitcoin blockchain, although it does have some differences. The main difference between Ethereum and Bitcoin with regard to the blockchain architecture is that, unlike Bitcoin, Ethereum blocks contain a copy of both the transaction list and the most recent state (the root hash of the merkle patricia trie encoding the state to be more precise). Aside from that, two other values, the block number and the difficulty, are also stored in the block. - -The proof of work algorithm used is called `Ethash `_ (a modified version of `the Dagger-Hashimoto algorithm `_) and involves finding a *nonce* input to the algorithm so that the result is below a certain difficulty threshold. The point in PoW algorithms is that there is no better strategy to find such a nonce than enumerating the possibilities, while verification of a solution is trivial and cheap. Since outputs have a uniform distribution (as they are the result of the application of a hash function), we can guarantee that, on average, the time needed to find such a nonce depends on the difficulty threshold. This makes it possible to control the time of finding a new block just by manipulating the difficulty. - -As dictated by the protocol, the difficulty dynamically adjusts in such a way that on average one block is produced by the entire network every 15 seconds. We say that the network produces a blockchain with a *15 second block time*. -This "heartbeat" basically punctuates the synchronisation of system state -and guarantees that maintaining a fork (to allow double spend) or -rewriting history by malicious actors are impossible unless the attacker possesses more than half of the network mining power (this is the so called *51% attack*). - -Any node participating in the network can be a miner and their expected revenue from mining will be directly proportional to their (relative) mining power or *hashrate*, i.e., the number of nonces tried per second normalised by the total hashrate of the network. - -Ethash PoW is *memory hard*, making it *ASIC resistant*. Memory hardness is achieved with a proof of work algorithm that requires choosing subsets of a fixed resource dependent on the nonce and block header. This resource (a few gigabyte size data) is called a **DAG**. The `DAG `_ is totally different every 30000 blocks, a 125-hour window called *epoch* (roughly 5.2 days) and takes a while to generate. Since the DAG only depends on block height, it can be pregenerated but if its not, the client needs to wait until the end of this process to produce a block. If clients do not pregenerate and cache DAGs ahead of time the network may experience massive block delay on each epoch transition. Note that the DAG does not need to be generated for verifying the PoW essentially allowing for verification with both low CPU and small memory. - -As a special case, when you start up your node from scratch, mining will only start once the DAG is built for the current epoch. - -Mining rewards --------------------------------------------------------------------------------- - -The successful PoW miner of the winning block receives: - -* a *static block reward* for the 'winning' block, consisting of exactly 5.0 Ether -* cost of the gas expended within the block – an amount of ether that depends on the current gas price -* an extra reward for including uncles as part of the block, in the form of an extra 1/32 per uncle included - -All the gas consumed by the execution of all the transactions in the block submitted by the winning miner is paid by the senders of each transaction. The gas cost incurred is credited to the miner's account as part of the consensus protocol. Over time, it is expected these will dwarf the static block reward. - -*Uncles* are stale blocks i.e. with parents that are ancestors (max 6 blocks back) of the including block. Valid uncles are rewarded in order to neutralise the effect of network lag on the dispersion of mining rewards, thereby increasing security (this is called the GHOST protocol). Uncles included in a block formed by the successful PoW miner receive 7/8 of the static block reward (=4.375 ether). A maximum of 2 uncles are allowed per block. - - * `Uncles ELI5 on reddit `_ - * `Forum thread explaining uncles `_ - - -Mining success depends on the set block difficulty. Block difficulty dynamically adjusts each block in order to regulate the network hashing power to produce a 12 second blocktime. Your chances of finding a block therefore follows from your hashrate relative to difficulty. - -Ethash DAG --------------------------------------------------------------------------------- - -Ethash uses a *DAG* (directed acyclic graph) for the proof of work algorithm, this is generated for each *epoch*, i.e., every 30000 blocks (125 hours, ca. 5.2 days). The DAG takes a long time to generate. If clients only generate it on demand, you may see a long wait at each epoch transition before the first block of the new epoch is found. However, the DAG only depends on the block number, so it can and should be calculated in advance to avoid long wait times at each epoch transition. Both ``geth`` and ``ethminer`` implement automatic DAG generation and maintains two DAGs at a time for smooth epoch transitions. Automatic DAG generation is turned on and off when mining is controlled from the console. It is also turned on by default if ``geth`` is launched with the ``--mine`` option. Note that clients share a DAG resource, so if you are running multiple instances of any client, make sure automatic dag generation is switched off in all but one instance. - -To generate the DAG for an arbitrary epoch: - -.. code-block:: bash - - geth makedag - -For instance ``geth makedag 360000 ~/.ethash``. Note that ethash uses -``~/.ethash`` (Mac/Linux) or ``~/AppData/Ethash`` (Windows) for the DAG -so that it can shared between different client implementations as well as multiple running instances. - -The algorithm -================================================================================ - -Our algorithm, `Ethash `__ (previously known as Dagger-Hashimoto), is based around the provision of a large, transient, randomly generated dataset which forms a DAG (the Dagger-part), and attempting to solve a particular constraint on it, partly determined through a block's header-hash. - -It is designed to hash a fast verifiability time within a slow CPU-only environment, yet provide vast speed-ups for mining when provided with a large amount of memory with high-bandwidth. The large memory requirements mean that large-scale miners get comparatively little super-linear benefit. The high bandwidth requirement means that a speed-up from piling on many super-fast processing units sharing the same memory gives little benefit over a single unit. This is important in that pool mining have no benefit for nodes doing verification, thus discourageing centralisation. - -Communication between the external mining application and the Ethereum daemon for work provision and submission happens through the JSON-RPC API. Two RPC functions are provided; ``eth_getWork`` and ``eth_submitWork``. - -These are formally documented on the `JSON-RPC API `_ wiki article under `miner `_. - - -In order to mine you need a fully synced Ethereum client that is enabled for mining and at least one ethereum account. This account is used to send the mining rewards to and is often referred to as *coinbase* or *etherbase*. Visit the ":ref:`creating_an_account`" section of this guide to learn how to create an account. - -.. warning:: Ensure your blockchain is fully synchronised with the main chain before starting to mine, otherwise you will not be mining on the main chain. - -CPU mining -================================================================================ - -You can use your computer's central processing unit (CPU) to mine ether. This is no longer profitable, since GPU miners are roughly two orders of magnitude more efficient. However, you can use CPU mining to mine on the Morden testnet or a private chain for the purposes of creating the ether you need to test contracts and transactions without spending your real ether on the live network. - -.. note:: The testnet ether has no value other than using it for testing purposes (see :ref:`test-networks`). - -Using geth -------------------------------- -When you start up your ethereum node with ``geth`` it is not mining by -default. To start it in CPU mining mode, you use the ``--mine`` `command line option `__. -The ``-minerthreads`` parameter can be used to set the number parallel mining threads (defaulting to the total number of processor cores). - -``geth --mine --minerthreads=4`` - -You can also start and stop CPU mining at runtime using the `console `__. ``miner.start`` takes an optional parameter for the number of miner threads. - -.. code-block:: Javascript - - > miner.start(8) - true - > miner.stop() - true - -Note that mining for real ether only makes sense if you are in sync with the network (since you mine on top of the consensus block). Therefore the eth blockchain downloader/synchroniser will delay mining until syncing is complete, and after that mining automatically starts unless you cancel your intention with ``miner.stop()``. - -In order to earn ether you must have your **etherbase** (or **coinbase**) address set. This etherbase defaults to your primary account. If you don't have an etherbase address, then ``geth --mine`` will not start up. - -You can set your etherbase on the command line: - -.. code-block:: bash - - geth --etherbase 1 --mine 2>> geth.log // 1 is index: second account by creation order OR - geth --etherbase '0xa4d8e9cae4d04b093aac82e6cd355b6b963fb7ff' --mine 2>> geth.log - -You can reset your etherbase on the console too: - -.. code-block:: javascript - - miner.setEtherbase(eth.accounts[2]) - -Note that your etherbase does not need to be an address of a local account, just an existing one. - -There is an option `to add extra Data `__ (32 bytes only) to your mined blocks. By convention this is interpreted as a unicode string, so you can set your short vanity tag. - -.. code-block:: javascript - - miner.setExtra("ΞTHΞЯSPHΞЯΞ") - ... - debug.printBlock(131805) - BLOCK(be465b020fdbedc4063756f0912b5a89bbb4735bd1d1df84363e05ade0195cb1): Size: 531.00 B TD: 643485290485 { - NoNonce: ee48752c3a0bfe3d85339451a5f3f411c21c8170353e450985e1faab0a9ac4cc - Header: - [ - ... - Coinbase: a4d8e9cae4d04b093aac82e6cd355b6b963fb7ff - Number: 131805 - Extra: ΞTHΞЯSPHΞЯΞ - ... - } - -You can check your hashrate with `miner.hashrate `_, the result is in H/s (Hash operations per second). - -.. code-block:: javascript - - > miner.hashrate - 712000 - -After you successfully mined some blocks, you can check the ether balance of your etherbase account. Now assuming your etherbase is a local account: - -.. code-block:: javascript - - > eth.getBalance(eth.coinbase).toNumber(); - '34698870000000' - -In order to spend your earnings on gas to transact, you will need to have this account unlocked. - -.. code-block:: javascript - - > personal.unlockAccount(eth.coinbase) - Password - true - -You can check which blocks are mined by a particular miner (address) with the following code snippet on the console: - -.. code-block:: javascript - - function minedBlocks(lastn, addr) { - addrs = []; - if (!addr) { - addr = eth.coinbase - } - limit = eth.blockNumber - lastn - for (i = eth.blockNumber; i >= limit; i--) { - if (eth.getBlock(i).miner == addr) { - addrs.push(i) - } - } - return addrs - } - // scans the last 1000 blocks and returns the blocknumbers of blocks mined by your coinbase - // (more precisely blocks the mining reward for which is sent to your coinbase). - minedBlocks(1000, eth.coinbase); - //[352708, 352655, 352559] - -Note that it will happen often that you find a block yet it never makes it to the canonical chain. This means when you locally include your mined block, the current state will show the mining reward credited to your account, however, after a while, the better chain is discovered and we switch to a chain in which your block is not included and therefore no mining reward is credited. Therefore it is quite possible that as a miner monitoring their coinbase balance will find that it may fluctuate quite a bit. - -GPU mining -================================================================================ - -Hardware -------------------------------- - -The algorithm is memory hard and in order to fit the DAG into memory, it needs 1-2GB of RAM on each GPU. If you get ``Error GPU mining. GPU memory fragmentation?`` you do not have enough memory. -The GPU miner is implemented in OpenCL, so AMD GPUs will be 'faster' than same-category NVIDIA GPUs. -ASICs and FPGAs are relatively inefficient and therefore discouraged. -To get openCL for your chipset and platform, try: - -- `AMD SDK openCL `_ -- `NVIDIA CUDA openCL `_ - -Ubuntu Linux set-up -------------------------- - -For this quick guide, you'll need Ubuntu 14.04 or 15.04 and the fglrx graphics drivers. You can use NVidia drivers and other platforms, too, but you'll have to find your own way to getting a working OpenCL install with them, such as `Genoil's ethminer fork `_. - -If you're on 15.04, Go to "Software and Updates > Additional Drivers" and set it to "Using video drivers for the AMD graphics accelerator from fglrx". - -If you're on 14.04, go to "Software and Updates > Additional Drivers" and set it to "Using video drivers for the AMD graphics accelerator from fglrx". Unfortunately, for some of you this will not work due to a known bug in Ubuntu 14.04.02 preventing you from switching to the proprietary graphics drivers required to GPU mine. - -So, if you encounter this bug, and before you do anything else, go to "Software and updates > Updates" and select "Pre-released updates trusty proposed". Then, go back to "Software and Updates > Additional Drivers" and set it to "Using video drivers for the AMD graphics accelerator from fglrx"). After rebooting, it's well worth having a check that the drivers have now indeed been installed correctly (For example by going to "Additional Drivers" again). - -Whatever you do, if you are on 14.04.02 do not alter the drivers or the drivers configuration once set. For example, the usage of aticonfig --initial (especially with the -f, --force option) can 'break' your setup. If you accidentally alter their configuration, you'll need to de-install the drivers, reboot, reinstall the drivers and reboot. - -Mac set-up -------------------------------- - -.. code-block:: bash - - wget http://developer.download.nvidia.com/compute/cuda/7_0/Prod/local_installers/cuda_7.0.29_mac.pkg - sudo installer -pkg ~/Desktop/cuda_7.0.29_mac.pkg -target / - brew update - brew tap ethereum/ethereum - brew reinstall cpp-ethereum --with-gpu-mining --devel --headless --build-from-source - -You check your cooling status: - -.. code-block:: bash - - aticonfig --adapter=0 --od-gettemperature - -Windows set-up -------------------------------- -`Download the latest Eth\+\+ installation `_ and choose ethminer at the "Choose Components" screen of the installation screen. - -.. image:: img/eth_miner_setup.png -.. :height: 513px -.. :width: 399 px - :alt: ethereum-ethminer-set-upfdg - -Using ethminer with geth -------------------------------- - -.. code-block:: bash - - geth account new // Set-up ethereum account if you do not have one - geth --rpc --rpccorsdomain localhost 2>> geth.log & - ethminer -G // -G for GPU, -M for benchmark - tail -f geth.log - -``ethminer`` communicates with geth on port 8545 (the default RPC port in geth). You can change this by giving the ``--rpcport`` option to ``geth``. Ethminer will find geth on any port. Note that you need to set the CORS header with ``--rpccorsdomain localhost``. You can also set port on ``ethminer`` with ``-F http://127.0.0.1:3301``. Setting the ports is necessary if you want several instances mining on the same computer, although this is somewhat pointless. If you are testing on a private chain, we recommend you use CPU mining instead. - -.. note:: You do **not** need to give ``geth`` the ``--mine`` option or start the miner in the console unless you want to do CPU mining on TOP of GPU mining. - -If the default for ``ethminer`` does not work try to specify the OpenCL device with: ``--opencl-device X`` where X is {0, 1, 2,...}. When running ``ethminer`` with ``-M`` (benchmark), you should see something like: - -.. code-block:: bash - - Benchmarking on platform: { "platform": "NVIDIA CUDA", "device": "GeForce GTX 750 Ti", "version": "OpenCL 1.1 CUDA" } - - - Benchmarking on platform: { "platform": "Apple", "device": "Intel(R) Xeon(R) CPU E5-1620 v2 @ 3.70GHz", "version": "OpenCL 1.2 " } - -To debug ``geth``: - -.. code-block:: bash - - geth --rpccorsdomain "localhost" --verbosity 6 2>> geth.log - -To debug the miner: - -.. code-block:: bash - - make -DCMAKE_BUILD_TYPE=Debug -DETHASHCL=1 -DGUI=0 - gdb --args ethminer -G -M - -.. note:: hashrate info is not available in ``geth`` when GPU mining. - -Check your hashrate with ``ethminer``, ``miner.hashrate`` will always report 0. - -Using ethminer with eth -------------------------------- - -Mining on a single GPU -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In order to mine on a single GPU all that needs to be done is to run eth with the following arguments: - -.. code-block:: bash - - eth -v 1 -a 0xcadb3223d4eebcaa7b40ec5722967ced01cfc8f2 --client-name "OPTIONALNAMEHERE" -x 50 -m on -G - -- ``-v 1`` Set verbosity to 1. Let's not get spammed by messages. -- ``-a YOURWALLETADDRESS`` Set the coinbase, where the mining rewards will go to. The above address is just an example. This argument is really important, make sure to not make a mistake in your wallet address or you will receive no ether payout. -- ``--client-name "OPTIONAL"`` Set an optional client name to identify you on the network -- ``-x 50`` Request a high amount of peers. Helps with finding peers in the beginning. -- ``-m on`` Actually launch with mining on. -- ``-G`` set GPU mining on. - -While the client is running you can interact with it using either -geth attach` or [ethconsole](https://github.com/ethereum/ethereum-console). - -Mining on a multiple GPUs -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Mining with multiple GPUs and eth is very similar to mining with geth and multiple GPUs. -Ensure that an eth node is running with your coinbase address properly set: - -.. code-block:: bash - - eth -v 1 -a 0xcadb3223d4eebcaa7b40ec5722967ced01cfc8f2 --client-name "OPTIONALNAMEHERE" -x 50 -j - -Notice that we also added the -j argument so that the client can have the JSON-RPC server enabled to communicate with the ethminer instances. Additionally we removed the mining related arguments since ethminer will now do the mining for us. -For each of your GPUs execute a different ethminer instance: - -.. code-block:: bash - - ethminer --no-precompute -G --opencl-device X - -Where X is the index number corresponding to the openCL device you want the ethminer to use {0, 1, 2,...}. -In order to easily get a list of OpenCL devices you can execute ``ethminer --list-devices`` which will provide a list of all devices OpenCL can detect, with also some additional information per device. - -Below is a sample output: - -.. code-block:: console - - [0] GeForce GTX 770 - CL_DEVICE_TYPE: GPU - CL_DEVICE_GLOBAL_MEM_SIZE: 4286345216 - CL_DEVICE_MAX_MEM_ALLOC_SIZE: 1071586304 - CL_DEVICE_MAX_WORK_GROUP_SIZE: 1024 - -Finally the ``--no-precompute`` argument requests that the ethminers don't create the DAG of the next epoch ahead of time. Although this is not recommended since you'll have a mining interruption every time when there's an epoch transition. - -Benchmarking -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Mining power tends to scale with memory bandwidth. Our implementation is written in OpenCL, which is typically supported better by AMD GPUs over NVidia. Empirical evidence confirms that AMD GPUs offer a better mining performance in terms of price than their NVidia counterparts. - -To benchmark a single-device setup you can use ethminer in benchmarking mode through the -M option: - -.. code-block:: bash - - ethminer -G -M - -If you have many devices and you'll like to benchmark each individually, you can use the --opencl-device option similarly to the previous section: - -.. code-block:: bash - - ethminer -G -M --opencl-device X - -Use ethminer ``--list-devices`` to list possible numbers to substitute for the X {0, 1, 2,...}. - - - -To start mining on Windows, first `download the geth windows binary `_. - -* Unzip Geth (right-click and select unpack) and launch Command Prompt. Use `cd` to navigate to the location of the Geth data folder. (e.g. ``cd /`` to go to the ``C:`` drive) -* Start geth by typing ``geth --rpc``. - -As soon as you enter this, the Ethereum blockchain will start downloading. Sometimes your firewall may block the synchronisation process (it will prompt you when doing so). If this is the case, click "Allow access". - -* First `download and install ethminer `_, the C++ mining software (your firewall or Windows itself may act up, allow access) -* Open up another Command Prompt (leave the first one running!), change directory by typing ``cd /Program\ Files/Ethereum(++)/release`` -* Now make sure `geth` has finished syncing the blockchain. If it is not syncing any longer, you can start the mining process by typing ``ethminer -G`` at the command prompt - -At this point some problems may appear. If you get an error, you can abort the miner by pressing ``Ctrl+C``. If the error says -"Insufficient Memory", your GPU does not have enough memory to mine ether. - -Pool mining -================================================================================ - -Mining pools are cooperatives that aim to smooth out expected revenue by pooling the mining power of participating miners. In return, they usually charge you 0-5% of your mining rewards. The mining pool submits blocks with proof of work from a central account and redistributes the reward to participants in proportion to their contributed mining power. - -.. warning:: Most mining pools involve third party, central components which means they are not trustless. In other words, pool operators can run away with your earnings. Act with caution. There are a number of trustless, decentralised pools with open source codebase. - -.. warning:: Mining pools only outsource proof of work calculation, they do not validate blocks or run the VM to check state transitions brought about by executing the transactions. This effectively make pools behave like single nodes in terms of security, so their growth poses a centralisation risk of a `51% attack `_. Make sure you follow the network capacity distribution and do not allow pools to grow too large. - -Mining pools --------------------------------------------------------------------- - -* `coinotron`_ -* `nanopool`_ -* `ethpool`_ - Predictable solo mining, unconventional payout scheme, affiliated with `etherchain\.org`_. -* `supernova`_ -* `coinmine.pl`_ -* `eth.pp.ua`_ -* `talkether`_ - Unconventional payout scheme, partially decentralized -* `weipool`_ -* `ethereumpool`_ -* `pooleum`_ -* `alphapool`_ -* `cryptopool`_ -* `unitedminers`_ -* `dwarfpool`_ - Try to avoid this (currently over 50% of the network) -* `laintimes `_ - Discontinued - -.. _Ethpool: https://github.com/etherchain-org/ethpool-core -.. _Ethpool source: https://github.com/etherchain-org/ethpool-core -.. _ethereumpool: https://ethereumpool.co/ -.. _nanopool: http://eth.nanopool.org/ -.. _pooleum: http://www.pooleum.com -.. _alphapool: http://www.alphapool.xyz/ -.. _dwarfpool: http://dwarfpool.com/eth -.. _talkether: http://talkether.org/ -.. _weipool: http://weipool.org/ -.. _supernova: https://eth.suprnova.cc/ -.. _coinmine.pl: https://www2.coinmine.pl/eth/ -.. _eth.pp.ua: https://eth.pp.ua/ -.. _coinotron: https://www.coinotron.com/ -.. _etherchain.org: https://etherchain.org/ -.. _unitedminers: http://eth.unitedminers.cloud/ -.. _cryptopool: http://ethereum.cryptopool.online/ - - -Mining resources -======================================================= - -* `Top miners of last 24h on etherchain `_ -* `pool hashrate distribution for august 2015 `_ -* `Unmaintained list of pools on Forum `_ -* `Mining profitability calculator on cryptocompare `_ -* `Mining profitability calculator on cryptowizzard `_ -* `Mining profitability calculator on etherscan `_ -* `Mining profitability calculator on In The Ether `_ -* `Mining difficulty chart on etherscan `_ - - -.. _POS vs POW: - -POS vs POW ------------------------------ - -* https://www.reddit.com/r/ethereum/comments/38db1z/eli5_the_difference_between_pos_and_pow/ -* https://blog.ethereum.org/2014/11/25/proof-stake-learned-love-weak-subjectivity/ -* https://www.reddit.com/r/ethereum/comments/42o8oy/can_someone_explain_the_switch_to_pos_how_and_when/ diff --git a/source/network/connecting-to-the-network.rst b/source/network/connecting-to-the-network.rst deleted file mode 100644 index fece85f..0000000 --- a/source/network/connecting-to-the-network.rst +++ /dev/null @@ -1,177 +0,0 @@ -.. _sec:connecting-to-the-network: - -******************************************************************************** -Connecting to the Network -******************************************************************************** - -This section - -The Ethereum network -================================================================================ - -The basis for decentralised consensus is the peer-to-peer network of participating nodes which maintain and secure the blockchain. See :ref:`mining`. - -Ethereum network stats --------------------------------------------------- - -`EthStats\.net `_ is a dashboard of live statistics of the Ethereum network. This dashboard displays important information such as the current block, hash difficulty, gas price, and gas spending. The nodes shown on the page are only a selection of actual nodes on the network. -Anyone is allowed to add their node to the EthStats dashboard. The `Eth\-Netstats README on Github `_ describes how to connect. - -`EtherNodes\.com `_ displays current and historical data on node count and other information on both the Ethereum mainnet and Morden testnet. - -`Distribution of client implementations on the current live network `_ - Realtime stats on EtherChain. - -Public, private, and consortium blockchains ------------------------------------------------- - -Most Ethereum projects today rely on Ethereum as a public blockchain, which grants access to a larger audience of users, network nodes, currency, and markets. However, there are often reasons to prefer a private blockchain or consortium blockchain (among a group of trusted participants). For example, a number of companies in verticals, like banking, are looking to Ethereum as a platform for their own private blockchains. - -Below is an excerpt from the blog post `On Public and Private Blockchains `_ that explains the difference between the three types of blockchains based on permissioning: - -- **Public blockchains**: a public blockchain is a blockchain that anyone in the world can read, anyone in the world can send transactions to and expect to see them included if they are valid, and anyone in the world can participate in the consensus process – the process for determining what blocks get added to the chain and what the current state is. As a substitute for centralized or quasi-centralized trust, public blockchains are secured by cryptoeconomics – the combination of economic incentives and cryptographic verification using mechanisms such as proof of work or proof of stake, following a general principle that the degree to which someone can have an influence in the consensus process is proportional to the quantity of economic resources that they can bring to bear. These blockchains are generally considered to be “fully decentralized”. - -- **Consortium blockchains**: a consortium blockchain is a blockchain where the consensus process is controlled by a pre-selected set of nodes; for example, one might imagine a consortium of 15 financial institutions, each of which operates a node and of which 10 must sign every block in order for the block to be valid. The right to read the blockchain may be public, or restricted to the participants, and there are also hybrid routes such as the root hashes of the blocks being public together with an API that allows members of the public to make a limited number of queries and get back cryptographic proofs of some parts of the blockchain state. These blockchains may be considered “partially decentralized”. - -- **Private blockchains**: a fully private blockchain is a blockchain where write permissions are kept centralized to one organization. Read permissions may be public or restricted to an arbitrary extent. Likely applications include database management, auditing, etc internal to a single company, and so public readability may not be necessary in many cases at all, though in other cases public auditability is desired. - -While these private/consortium blockchains may not have any connection to the public blockchain, they still contribute to the overall Ethereum ecosystem by investing in Ethereum software development. Over time, this translates into software improvements, shared knowledge, and job opportunities. - - -How to connect -================================================================================ - -Geth continuously attempts to connect to other nodes on the network until it has peers. If you have UPnP enabled on your router or run Ethereum on an Internet-facing server, it will also accept connections from other nodes. - -Geth finds peers through something called the *discovery protocol*. In the discovery protocol, nodes are gossipping with each other to find out about other nodes on the network. In order to get going initially, geth uses a set of bootstrap nodes whose endpoints are recorded in the source code. - -Checking connectivity and ENODE IDs --------------------------------------------------------------------------------- - -To check how many peers the client is connected to in the interactive console, the ``net`` module has two attributes that give you info about the number of peers and whether you are a listening node. - -.. code-block:: Javascript - - > net.listening - true - - > net.peerCount - 4 - -To get more information about the connected peers, such as IP address and port number, supported protocols, use the ``peers()`` function of the ``admin`` object. ``admin.peers()`` returns the list of currently connected peers. - -.. code-block:: Javascript - - > admin.peers - [{ - ID: 'a4de274d3a159e10c2c9a68c326511236381b84c9ec52e72ad732eb0b2b1a2277938f78593cdbe734e6002bf23114d434a085d260514ab336d4acdc312db671b', - Name: 'Geth/v0.9.14/linux/go1.4.2', - Caps: 'eth/60', - RemoteAddress: '5.9.150.40:30301', - LocalAddress: '192.168.0.28:39219' - }, { - ID: 'a979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c', - Name: 'Geth/v0.9.15/linux/go1.4.2', - Caps: 'eth/60', - RemoteAddress: '52.16.188.185:30303', - LocalAddress: '192.168.0.28:50995' - }, { - ID: 'f6ba1f1d9241d48138136ccf5baa6c2c8b008435a1c2bd009ca52fb8edbbc991eba36376beaee9d45f16d5dcbf2ed0bc23006c505d57ffcf70921bd94aa7a172', - Name: 'pyethapp_dd52/v0.9.13/linux2/py2.7.9', - Caps: 'eth/60, p2p/3', - RemoteAddress: '144.76.62.101:30303', - LocalAddress: '192.168.0.28:40454' - }, { - ID: 'f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0', - Name: '++eth/Zeppelin/Rascal/v0.9.14/Release/Darwin/clang/int', - Caps: 'eth/60, shh/2', - RemoteAddress: '129.16.191.64:30303', - LocalAddress: '192.168.0.28:39705' - } ] - - -To check the ports used by geth and also find your enode URI run: - -.. code-block:: Javascript - - > admin.nodeInfo - { - Name: 'Geth/v0.9.14/darwin/go1.4.2', - NodeUrl: 'enode://3414c01c19aa75a34f2dbd2f8d0898dc79d6b219ad77f8155abf1a287ce2ba60f14998a3a98c0cf14915eabfdacf914a92b27a01769de18fa2d049dbf4c17694@[::]:30303', - NodeID: '3414c01c19aa75a34f2dbd2f8d0898dc79d6b219ad77f8155abf1a287ce2ba60f14998a3a98c0cf14915eabfdacf914a92b27a01769de18fa2d049dbf4c17694', - IP: '::', - DiscPort: 30303, - TCPPort: 30303, - Td: '2044952618444', - ListenAddr: '[::]:30303' - } - -Download the blockchain faster -================================================================================ - -When you start an Ethereum client, the Ethereum blockchain is automatically downloaded. The time it takes to download the Ethereum blockchain can vary based on client, client settings, connection speed, and number of peers available. Below are some options for more quickly obtaining the Ethereum blockchain. - -Using geth --------------------------------------------------------------------------------- - -If you are using the geth client, there are some things you can do to speed up the time it takes to download the Ethereum blockchain. If you choose to use the ``--fast`` flag to perform an Ethereum fast sync, you will not retain past transaction data. - -.. note:: You cannot use this flag after performing all or part of a normal sync operation, meaning you should not have any portion of the Ethereum blockchain downloaded before using this command. `See this Ethereum Stack\.Exchange answer for more information `_. - -Below are some flags to use when you want to sync your client more quickly. - -``--fast`` - -This flag enables fast syncing through state downloads rather than downloading the full block data. This will also reduce the size of your blockchain dramatically. -NOTE: ``--fast`` can only be run if you are syncing your blockchain from scratch and only the first time you download the blockchain for security reasons. `See this Reddit post for more information `_. - -``--cache=1024`` - -Megabytes of memory allocated to internal caching (min 16MB / database forced). Default is 16MB, so increasing this to 256, 512, 1024 (1GB), or 2048 (2GB) depending on how much RAM your computer has should make a difference. - -``--jitvm`` - -This flag enables the JIT VM. - -Full example command with console: - -.. code-block:: Bash - - geth --fast --cache=1024 --jitvm console - -For more discussion on fast syncing and blockchain download times, `see this Reddit post `_. - -Exporting/Importing the blockchain --------------------------------------------------------------------------------- - -If you already have a full Ethereum node synced, you can export the blockchain data from the fully synced node and import it into your new node. You can accomplish this in geth by exporting your full node with the command ``geth export filename`` and importing the blockchain into your node using ``geth import filename``. -see `this link `_ - -.. _cr-static-nodes: - -Static Nodes, Trusted Nodes, and Boot Nodes -================================================================================ - -Geth supports a feature called static nodes if you have certain peers you always want to connect to. Static nodes are re-connected on disconnects. You can configure permanent static nodes by putting something like the following into ``/static-nodes.json`` (this should be the same folder that your ``chaindata`` and ``keystore`` folders are in) - -.. code-block:: Javascript - - [ - "enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303", - "enode://pubkey@ip:port" - ] - -You can also add static nodes at runtime via the Javascript console using ``admin.addPeer()`` - -.. code-block:: Console - - > admin.addPeer("enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303") - -Common problems with connectivity --------------------------------------------------------------------------------- - -Sometimes you just can't get connected. The most common reasons are: - -* Your local time might be incorrect. An accurate clock is required to participate in the Ethereum network. Check your OS for how to resync your clock (example ``sudo ntpdate -s time.nist.gov``) because even 12 seconds too fast can lead to 0 peers. -* Some firewall configurations can prevent UDP traffic from flowing. You can use the static nodes feature or ``admin.addPeer()`` on the console to configure connections by hand. - -To start geth without the discovery protocol, you can use the ``--nodiscover`` parameter. You only want this if you are running a test node or an experimental test network with fixed nodes. diff --git a/source/network/index.rst b/source/network/index.rst deleted file mode 100644 index 4880ab9..0000000 --- a/source/network/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -################################################################################ -The Ethereum network -################################################################################ - -Network info. - -.. toctree:: - connecting-to-the-network.rst - test-networks.rst \ No newline at end of file diff --git a/source/network/test-networks.rst b/source/network/test-networks.rst deleted file mode 100644 index f386c1a..0000000 --- a/source/network/test-networks.rst +++ /dev/null @@ -1,362 +0,0 @@ -.. _test-networks: - -******************************************************************************** -Test Networks -******************************************************************************** - -Morden testnet -================================================================================ -Morden is a public Ethereum alternative testnet. It is expected to -continue throughout the Frontier and Homestead milestones of the software. - -Usage --------------------------------------------------------------------------------- - -eth (C++ client) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This is supported natively on 0.9.93 and above. Pass the ``--morden`` argument in when starting any of the clients. e.g.: - -.. code:: Console - - > eth --morden - -PyEthApp (Python client) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -PyEthApp supports the morden network from v1.0.5 onwards: - -.. code:: Console - - > pyethapp --profile morden run - -geth (Go client) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code:: Console - - > geth --testnet - -Details --------------------------------------------------------------------------------- -All parameters are the same as the main Ethereum network except: - -- Network Name: **Morden** -- Network Identity: 2 -- genesis.json (given below); -- Initial Account Nonce (``IAN``) is 2^20 (instead of 0 in all previous - networks). - - - All accounts in the state trie have nonce >= ``IAN``. - - Whenever an account is inserted into the state trie it is - initialised with nonce = ``IAN``. - -- Genesis generic block hash: - ``0cd786a2425d16f152c658316c423e6ce1181e15c3295826d7c9904cba9ce303`` -- Genesis generic state root: - ``f3f4696bbf3b3b07775128eb7a3763279a394e382130f27c21e70233e04946a9`` - -Morden's genesis.json -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code:: JSON - - { - "nonce": "0x00006d6f7264656e", - "difficulty": "0x20000", - "mixhash": "0x00000000000000000000000000000000000000647572616c65787365646c6578", - "coinbase": "0x0000000000000000000000000000000000000000", - "timestamp": "0x00", - "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000", - "extraData": "0x", - "gasLimit": "0x2FEFD8", - "alloc": { - "0000000000000000000000000000000000000001": { "balance": "1" }, - "0000000000000000000000000000000000000002": { "balance": "1" }, - "0000000000000000000000000000000000000003": { "balance": "1" }, - "0000000000000000000000000000000000000004": { "balance": "1" }, - "102e61f5d8f9bc71d0ad4a084df4e65e05ce0e1c": { "balance": "1606938044258990275541962092341162602522202993782792835301376" } - } - } - -Getting Morden testnet ether --------------------------------------------------------------------------------- - -Two ways to obtain Morden testnet ether: - -- Mine using your CPU/GPU, (see :ref:`mining`). -- Use the `Ethereum wei faucet `__. - - -******************************************************************************** -Setting up a local private testnet -******************************************************************************** - -.. _custom-networks-eth: - -eth (C++ client) -================================================================================ - - -It is possible to connect to or create a new network by using the --genesis and --config. - -.. code:: Console - - > eth --private "customChain" --config config.json --genesis genesis.json - -It is possible to use both --config and --genesis. - -In that case, the genesis block description provided by --config will be overwritten by the --genesis option. - -.. code:: Console - - --private //defines the name of the custom chain (optional). - -.. code:: Console - - --config - -.. note:: contains a JSON description of the network: - - - sealEngine (engine use to mine block) - - "Ethash" is the Ethereum proof of work engine (used by the live network). - - "NoProof" no proof of work is needed to mine a block. - - - params (general network information like minGasLimit, minimumDifficulty, blockReward, networkID) - - - genesis (genesis block description) - - - accounts (setup an original state that contains accounts/contracts) - -Here is a Config sample (used by the Olympic network): - -.. code:: JSON - - { - "sealEngine": "Ethash", - "params": { - "accountStartNonce": "0x00", - "frontierCompatibilityModeLimit": "0xffffffff", - "maximumExtraDataSize": "0x0400", - "tieBreakingGas": false, - "minGasLimit": "125000", - "gasLimitBoundDivisor": "0x0400", - "minimumDifficulty": "0x020000", - "difficultyBoundDivisor": "0x0800", - "durationLimit": "0x08", - "blockReward": "0x14D1120D7B160000", - "registrar": "5e70c0bbcd5636e0f9f9316e9f8633feb64d4050", - "networkID" : "0x0" - }, - "genesis": { - "nonce": "0x000000000000002a", - "difficulty": "0x20000", - "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000", - "author": "0x0000000000000000000000000000000000000000", - "timestamp": "0x00", - "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000", - "extraData": "0x", - "gasLimit": "0x2fefd8" - }, - "accounts": { - "0000000000000000000000000000000000000001": { "wei": "1", "precompiled": { "name": "ecrecover", "linear": { "base": 3000, "word": 0 } } }, - "0000000000000000000000000000000000000002": { "wei": "1", "precompiled": { "name": "sha256", "linear": { "base": 60, "word": 12 } } }, - "0000000000000000000000000000000000000003": { "wei": "1", "precompiled": { "name": "ripemd160", "linear": { "base": 600, "word": 120 } } }, - "0000000000000000000000000000000000000004": { "wei": "1", "precompiled": { "name": "identity", "linear": { "base": 15, "word": 3 } } }, - "dbdbdb2cbd23b783741e8d7fcf51e459b497e4a6": { "wei": "1606938044258990275541962092341162602522202993782792835301376" }, - "e6716f9544a56c530d868e4bfbacb172315bdead": { "wei": "1606938044258990275541962092341162602522202993782792835301376" }, - "b9c015918bdaba24b4ff057a92a3873d6eb201be": { "wei": "1606938044258990275541962092341162602522202993782792835301376" }, - "1a26338f0d905e295fccb71fa9ea849ffa12aaf4": { "wei": "1606938044258990275541962092341162602522202993782792835301376" }, - "2ef47100e0787b915105fd5e3f4ff6752079d5cb": { "wei": "1606938044258990275541962092341162602522202993782792835301376" }, - "cd2a3d9f938e13cd947ec05abc7fe734df8dd826": { "wei": "1606938044258990275541962092341162602522202993782792835301376" }, - "6c386a4b26f73c802f34673f7248bb118f97424a": { "wei": "1606938044258990275541962092341162602522202993782792835301376" }, - "e4157b34ea9615cfbde6b4fda419828124b70c78": { "wei": "1606938044258990275541962092341162602522202993782792835301376" } - } - } - - -.. code:: Console - - --genesis (optional if the config option is provided and contains the genesis description). - -.. note:: contains a JSON description of the genesis block: - -The content is the same as the genesis field provided by the 'config' parameter: - -.. code:: JavaScript - - { - "nonce": "0x000000000000002a", - "difficulty": "0x20000", - "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000", - "author": "0x0000000000000000000000000000000000000000", - "timestamp": "0x00", - "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000", - "extraData": "0x", - "gasLimit": "0x2fefd8" - } - - - - -geth (Go client) -================================================================================ - - -You either pre-generate or mine your own Ether on a private -testnet. It is a much more cost effective way of trying out -Ethereum and you can avoid having to mine or find Morden test ether. - -The things that are required to specify in a private chain are: - - Custom Genesis File - - Custom Data Directory - - Custom NetworkID - - (Recommended) Disable Node Discovery - -The genesis file --------------------------------------------------------------------------------- - -The genesis block is the start of the blockchain - the first -block, block 0, and the only block that does not point to a predecessor -block. The protocol ensures that no other node will agree with your version of the -blockchain unless they have the same genesis block, so you can make as many private testnet blockchains as you'd like! - -:file:`CustomGenesis.json` - -.. code-block:: JSON - - { - "nonce": "0x0000000000000042", "timestamp": "0x0", - "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000", - "extraData": "0x0", "gasLimit": "0x8000000", "difficulty": "0x400", - "mixhash": "0x0000000000000000000000000000000000000000000000000000000000000000", - "coinbase": "0x3333333333333333333333333333333333333333", "alloc": { } - } - -Save a file called :file:`CustomGenesis.json`. -You will reference this when starting your geth node using the following flag: - -``--genesis /path/to/CustomGenesis.json`` - -Command line parameters for private network --------------------------------------------------------------------------------- - -There are some command line options (also called “flags”) that are -necessary in order to make sure that your network is private. We already covered the genesis flag, but we need a few more. Note that all of the commands below are to be used in the geth Ethereum client. - -``--nodiscover`` - -Use this to make sure that your node is not discoverable by people who do not manually add you. Otherwise, there is a chance that your node may be inadvertently added to a stranger's blockchain if they have the same genesis file and network id. - -``--maxpeers 0`` - -Use maxpeers 0 if you do not want anyone else connecting to your test chain. Alternatively, you can adjust this number if you know exactly how many peers you want connecting to your node. - -``--rpc`` - -This will enable RPC interface on your node. This is generally enabled by default in Geth. - - -``--rpcapi "db,eth,net,web3"`` - -This dictates what APIs that are allowed to be accessed over RPC. By default, Geth enables the web3 interface over RPC. - -**IMPORTANT: Please note that offering an API over the RPC/IPC interface will give everyone access to the API who can access this interface (e.g. dapp's). Be careful which API's you enable. By default geth enables all API's over the IPC interface and only the db,eth,net and web3 API's over the RPC interface.** - -``--rpcport "8080"`` - -Change 8000 to any port that is open on your network. The default for geth is 8080. - -``--rpccorsdomain "http://chriseth.github.io/browser-solidity/"`` - -This dictates what URLs can connect to your node in order to perform RPC client tasks. Be very careful with this and type a specific URL rather than the wildcard (*) which would allow any URL to connect to your RPC instance. - -``--datadir "/home/TestChain1"`` - -This is the data directory that your private chain data will be stored in (under the :file:`nubits` . Choose a location that is separate from your public Ethereum chain folder. - - -``--port "30303"`` - -This is the "network listening port", which you will use to connect with other peers manually. - - -``--identity "TestnetMainNode"`` - -This will set up an identity for your node so it can be identified more easily in a list of peers. -Here is an example of how these identities show up on the network. - -Launching ``geth`` --------------------------------------------------------------------------------- - -After you have created your custom genesis block JSON file and created a directory for your blockchain data, type the following command into your console that has access to geth: - -.. code-block:: Console - - geth --identity "MyNodeName" --genesis /path/to/CustomGenesis.json --rpc --rpcport "8080" --rpccorsdomain "*" --datadir "C:\chains\TestChain1" --port "30303" --nodiscover --rpcapi "db,eth,net,web3" --networkid 1999 console - -.. note:: Please change the flags to match your custom settings. - -You will need to start your geth instance with your custom chain command every time you want to access your custom chain. If you just type "geth" in your console, it will not remember all of the flags you have set. - -Pre-allocating ether to your account --------------------------------------------------------------------------------- - -A difficulty of "0x400" allows you to mine Ether very quickly on your private testnet chain. If you create your chain and start mining, you should have hundreds of Ether in a matter of minutes which is way more than enough to test transactions on your network. If you would still like to pre-allocate Ether to your account, you will need to: - -1. Create a new Ethereum account after you create your private chain -2. Copy your new account address -3. Add the following command to your Custom_Genesis.json file: - -.. code-block:: Javascript - - "alloc": - { - "": - { "balance": "20000000000000000000" } - } - -.. note:: Replace ``0x1fb891f92eb557f4d688463d0d7c560552263b5a`` with your account address. - -Save your genesis file and rerun your private chain command. Once geth is fully loaded, close it by . - -We want to assign an address to the variable ``primary`` and check its balance. - -Run the command ``geth account list`` in your terminal to see what account # your new address was assigned. - -.. code-block:: Console - - > geth account list - Account #0: {d1ade25ccd3d550a7eb532ac759cac7be09c2719} - Account #1: {da65665fc30803cb1fb7e6d86691e20b1826dee0} - Account #2: {e470b1a7d2c9c5c6f03bbaa8fa20db6d404a0c32} - Account #3: {f4dd5c3794f1fd0cdc0327a83aa472609c806e99} - -Take note of which account # is the one that you pre-allocated Ether to. -Alternatively, you can launch the console with ``geth console`` (keep the same parameters as when you launched ``geth`` first). Once the prompt appears, type - -.. code-block:: Console - - > eth.accounts - -This will return the array of account addresses you possess. - -.. code-block:: Console - - > primary = eth.accounts[0] - -.. note:: Replace ``0`` with your account's index. This console command should return your primary Ethereum address. - -Type the following command: - -.. code-block:: Console - - > balance = web3.fromWei(eth.getBalance(primary), "ether"); - -This should return ``7.5`` indicating you have that much Ether in your account. The reason we had to put such a large number in the alloc section of your genesis file is because the "balance" field takes a number in wei which is the smallest denomination of the Ethereum currency Ether (see _`Ether`). - - -* https://www.reddit.com/r/ethereum/comments/3kdnus/question_about_private_chain_mining_dont_upvote/ -* http://adeduke.com/2015/08/how-to-create-a-private-ethereum-chain/ diff --git a/tox.ini b/tox.ini deleted file mode 100644 index 2922aef..0000000 --- a/tox.ini +++ /dev/null @@ -1,13 +0,0 @@ -[tox] -skipsdist=true -envlist= - rst_lint - -[testenv] -commands=py.test --tb native {posargs:tests} -deps = - -r{toxinidir}/requirements.txt - -[testenv:rst_lint] -basepython=python -commands=python {toxinidir}/rst_lint.py